登录
目录
当前位置： 首页 > 文档资料 > Electron 中文文档 >

session

优质
小牛编辑
194浏览
2023-12-01

管理浏览器会话、cookie、缓存、代理设置等。

进程：主进程

session 模块可用于创建新的 session 对象。

你还可以使用WebContents的session属性或session模块访问现有页的session

const { BrowserWindow } = require('electron')
let win = new BrowserWindow({ width: 800, height: 600 })
win.loadURL('http://github.com')
const ses = win.webContents.session
console.log(ses.getUserAgent())

Manage browser sessions, cookies, cache, proxy settings, etc.

Process: Main

The session module can be used to create new Session objects.

You can also access the session of existing pages by using the session property of WebContents, or from the session module.

const { BrowserWindow } = require('electron')
let win = new BrowserWindow({ width: 800, height: 600 })
win.loadURL('http://github.com')
const ses = win.webContents.session
console.log(ses.getUserAgent())

方法

session 模块具有以下方法:

Methods

The session module has the following methods:

session.fromPartition(partition[, options])

  • partition String

  • 选项 Object (可选)

    • cache Boolean - 是否可以使用缓存.

Returns Session - 根据partition字符串产生的session实例。 当这里已存在一个Session具有相同的partition, 它将被返回; 否则一个新的Session实例将根据options被创建。

如果 partition 以 persist:开头, 该页面将使用持续的 session，并在所有页面生效，且使用同一个partition. 如果没有 persist: 前缀, 页面将使用 in-memory session. 如果没有设置partition，app 将返回默认的session。

要根据options创建Session，你需要确保Session的partition在之前从未被使用。 没有办法修改一个已存在的Session对象的options。

session.fromPartition(partition[, options])

  • partition String

  • options Object (optional)

    • cache Boolean - Whether to enable cache.

Returns Session - A session instance from partition string. When there is an existing Session with the same partition, it will be returned; otherwise a new Session instance will be created with options.

If partition starts with persist:, the page will use a persistent session available to all pages in the app with the same partition. if there is no persist: prefix, the page will use an in-memory session. If the partition is empty then default session of the app will be returned.

To create a Session with options, you have to ensure the Session with the partition has never been used before. There is no way to change the options of an existing Session object.

属性

session 模块具有以下方法:

Properties

The session module has the following properties:

session.defaultSession

一个Session对象，该应用程序的默认session对象。

session.defaultSession

A Session object, the default session object of the app.

类: Session

获取和设置Session的属性。

进程：主进程

你可以创建一个 Session对象在session模块中。

const { session } = require('electron')
const ses = session.fromPartition('persist:name')
console.log(ses.getUserAgent())

Class: Session

Get and set properties of a session.

Process: Main

You can create a Session object in the session module:

const { session } = require('electron')
const ses = session.fromPartition('persist:name')
console.log(ses.getUserAgent())

实例事件

以下事件会在Session实例触发。

Instance Events

The following events are available on instances of Session:

Instance Events

  • event Event
  • item DownloadItem
  • webContents WebContents

当 Electron 刚要在webContents中下载`item<0>的时候触发。

调用event.preventDefault()`方法，将会停止下载，并且在进程的next tick中，`item`将不再可用。

const { session } = require('electron')
session.defaultSession.on('will-download', (event, item, webContents) => {
  event.preventDefault()
  require('request')(item.getURL(), (data) => {
    require('fs').writeFileSync('/somewhere', data)
  })
})

Event: 'will-download'

  • event Event
  • item DownloadItem
  • webContents WebContents

Emitted when Electron is about to download item in webContents.

Calling event.preventDefault() will cancel the download and item will not be available from next tick of the process.

const { session } = require('electron')
session.defaultSession.on('will-download', (event, item, webContents) => {
  event.preventDefault()
  require('request')(item.getURL(), (data) => {
    require('fs').writeFileSync('/somewhere', data)
  })
})

实例方法

在Session实例对象中，有以下方法:

Instance Methods

The following methods are available on instances of Session:

ses.getCacheSize(callback)

  • callback Function - 回调函数

    • size Integer 缓存大小（单位：bytes）
    • error Integer - The error code corresponding to the failure.

Callback会被调用，参数是session的当前缓存大小。

即将弃用

ses.getCacheSize(callback)

  • callback Function

    • size Integer - Cache size used in bytes.
    • error Integer - The error code corresponding to the failure.

Callback is invoked with the session's current cache size.

Deprecated Soon

ses.getCacheSize()

Returns Promise<Integer> - the session's current cache size, in bytes.

ses.getCacheSize()

Returns Promise<Integer> - the session's current cache size, in bytes.

ses.clearCache(callback)

  • callback Function - Called when operation is done.

    • error Integer - The error code corresponding to the failure.

清除session的HTTP缓存。

即将弃用

ses.clearCache(callback)

  • callback Function - Called when operation is done.

    • error Integer - The error code corresponding to the failure.

Clears the session’s HTTP cache.

Deprecated Soon

ses.clearCache()

Returns Promise<void> - resolves when the cache clear operation is complete.

清除session的HTTP缓存。

ses.clearCache()

Returns Promise<void> - resolves when the cache clear operation is complete.

Clears the session’s HTTP cache.

ses.clearStorageData([options,] callback)

  • 选项 Object (可选)

    • origin String - (可选项) 这个值应该按照 window.location.origin 的形式: 协议://主机名:端口方式设置。
    • storages String - The types of storages to clear, can contain: appcache, cookies, filesystem, indexdb, localstorage, shadercache, websql, serviceworkers, cachestorage.
    • quotas String[] - (可选项) 要清除的配额类型, 包含: temporary, persistent, syncable。
  • callback Function (可选) - 会在操作完成后被调用.

Clears the storage data for the current session.

即将弃用

ses.clearStorageData([options,] callback)

  • options Object (optional)

    • origin String (optional) - Should follow window.location.origin’s representation scheme://host:port.
    • storages String - The types of storages to clear, can contain: appcache, cookies, filesystem, indexdb, localstorage, shadercache, websql, serviceworkers, cachestorage.
    • quotas String - The types of quotas to clear, can contain: temporary, persistent, syncable.
  • callback Function (optional) - Called when operation is done.

Clears the storage data for the current session.

Deprecated Soon

ses.clearStorageData([options])

  • options Object (可选)

    • origin String - (可选项) 这个值应该按照 window.location.origin 的形式: 协议://主机名:端口方式设置。
    • storages String - The types of storages to clear, can contain: appcache, cookies, filesystem, indexdb, localstorage, shadercache, websql, serviceworkers, cachestorage.
    • quotas String[] - (可选项) 要清除的配额类型, 包含: temporary, persistent, syncable。

Returns Promise<void> - resolves when the storage data has been cleared.

ses.clearStorageData([options])

  • options Object (optional)

    • origin String (optional) - Should follow window.location.origin’s representation scheme://host:port.
    • storages String - The types of storages to clear, can contain: appcache, cookies, filesystem, indexdb, localstorage, shadercache, websql, serviceworkers, cachestorage.
    • quotas String - The types of quotas to clear, can contain: temporary, persistent, syncable.

Returns Promise<void> - resolves when the storage data has been cleared.

ses.flushStorageData()

写入任何未写入DOMStorage数据到磁盘.

ses.flushStorageData()

Writes any unwritten DOMStorage data to disk.

ses.setProxy(config, callback)

  • config Object

    • pacScript String - 与 PAC 文件关联的 URL。
    • proxyRules String - 表明要使用的代理规则。
    • proxyBypassRules String - 表明哪些 url 应绕过代理设置的规则。
  • callback Function - 会在操作完成之后被调用。

代理设置

当pacScript和proxyRules一起提供时, proxyRules 选项会被忽略, 会使用pacScript配置。

proxyRules 要遵循以下规则:

proxyRules = schemeProxies[";"<schemeProxies>]
schemeProxies = [<urlScheme>"="]<proxyURIList>
urlScheme = "http" | "https" | "ftp" | "socks"
proxyURIList = <proxyURL>[","<proxyURIList>]
proxyURL = [<proxyScheme>"://"]<proxyHost>[":"<proxyPort>]

例如：

  • http=foopy:80;ftp=foopy2 - Use HTTP proxy foopy:80 for http:// URLs, and HTTP proxy foopy2:80 for ftp:// URLs.
  • foopy:80 - Use HTTP proxy foopy:80 for all URLs.
  • foopy:80,bar,direct:// - Use HTTP proxy foopy:80 for all URLs, failing over to bar if foopy:80 is unavailable, and after that using no proxy.
  • socks4://foopy - Use SOCKS v4 proxy foopy:1080 for all URLs.
  • http=foopy,socks5://bar.com - Use HTTP proxy foopy for http URLs, and fail over to the SOCKS5 proxy bar.com if foopy is unavailable.
  • http=foopy,direct:// - Use HTTP proxy foopy for http URLs, and use no proxy if foopy is unavailable.
  • http=foopy;socks=foopy2 - 对于http URL，用foopy作为HTTP协议代理，而其它所有URL则用socks4://foopy2 协议。

proxyBypassRules是一个用逗号分隔的规则列表, 如下所述:

  • [ URL_SCHEME "://" ] HOSTNAME_PATTERN [ ":" <port> ]

    与 HOSTNAME_PATTERN 模式匹配的所有主机名。

    例如: "foobar.com", "foobar.com", ".foobar.com", "foobar.com:99", "https://x..y.com:99"

    • "." HOSTNAME_SUFFIX_PATTERN [ ":" PORT ]

      匹配特定域名后缀。

      例如： ".google.com", ".com", "http://.google.com"

  • [ SCHEME "://" ] IP_LITERAL [ ":" PORT ]

    匹配 IP 地址文本的 url。

    例如: "127.0.1", "[0:0::1]", "[::1]", "http://[::1]:99"

  • IP_LITERAL "/" PREFIX_LENGTH_IN_BITS

    匹配位于给定范围之间的 IP 文本的任何 URL。IP 范围是使用 CIDR 表示法指定的。

    例如: "192.168.1.1/16", "fefe:13::abc/33".

  • <local>

    匹配本地地址。local 的含义是，是否匹配其中一个: "127.0.0.1", "::1", "localhost".

即将弃用

ses.setProxy(config, callback)

  • config Object

    • pacScript String - The URL associated with the PAC file.
    • proxyRules String - Rules indicating which proxies to use.
    • proxyBypassRules String - Rules indicating which URLs should bypass the proxy settings.
  • callback Function - Called when operation is done.

Sets the proxy settings.

When pacScript and proxyRules are provided together, the proxyRules option is ignored and pacScript configuration is applied.

The proxyRules has to follow the rules below:

proxyRules = schemeProxies[";"<schemeProxies>]
schemeProxies = [<urlScheme>"="]<proxyURIList>
urlScheme = "http" | "https" | "ftp" | "socks"
proxyURIList = <proxyURL>[","<proxyURIList>]
proxyURL = [<proxyScheme>"://"]<proxyHost>[":"<proxyPort>]

For example:

  • http=foopy:80;ftp=foopy2 - Use HTTP proxy foopy:80 for http:// URLs, and HTTP proxy foopy2:80 for ftp:// URLs.
  • foopy:80 - Use HTTP proxy foopy:80 for all URLs.
  • foopy:80,bar,direct:// - Use HTTP proxy foopy:80 for all URLs, failing over to bar if foopy:80 is unavailable, and after that using no proxy.
  • socks4://foopy - Use SOCKS v4 proxy foopy:1080 for all URLs.
  • http=foopy,socks5://bar.com - Use HTTP proxy foopy for http URLs, and fail over to the SOCKS5 proxy bar.com if foopy is unavailable.
  • http=foopy,direct:// - Use HTTP proxy foopy for http URLs, and use no proxy if foopy is unavailable.
  • http=foopy;socks=foopy2 - Use HTTP proxy foopy for http URLs, and use socks4://foopy2 for all other URLs.

The proxyBypassRules is a comma separated list of rules described below:

  • [ URL_SCHEME "://" ] HOSTNAME_PATTERN [ ":" <port> ]

    Match all hostnames that match the pattern HOSTNAME_PATTERN.

    Examples: "foobar.com", "foobar.com", ".foobar.com", "foobar.com:99", "https://x..y.com:99"

  • "." HOSTNAME_SUFFIX_PATTERN [ ":" PORT ]

    Match a particular domain suffix.

    Examples: ".google.com", ".com", "http://.google.com"

  • [ SCHEME "://" ] IP_LITERAL [ ":" PORT ]

    Match URLs which are IP address literals.

    Examples: "127.0.1", "[0:0::1]", "[::1]", "http://[::1]:99"

  • IP_LITERAL "/" PREFIX_LENGTH_IN_BITS

    Match any URL that is to an IP literal that falls between the given range. IP range is specified using CIDR notation.

    Examples: "192.168.1.1/16", "fefe:13::abc/33".

  • <local>

    Match local addresses. The meaning of <local> is whether the host matches one of: "127.0.0.1", "::1", "localhost".

Deprecated Soon

ses.setProxy(config)

  • config Object

    • pacScript String - 与 PAC 文件关联的 URL。
    • proxyRules String - 表明要使用的代理规则。
    • proxyBypassRules String - 表明哪些 url 应绕过代理设置的规则。

Returns Promise<void> - Resolves when the proxy setting process is complete.

代理设置

当pacScript和proxyRules一起提供时, proxyRules 选项会被忽略, 会使用pacScript配置。

proxyRules 要遵循以下规则:

proxyRules = schemeProxies[";"<schemeProxies>]
schemeProxies = [<urlScheme>"="]<proxyURIList>
urlScheme = "http" | "https" | "ftp" | "socks"
proxyURIList = <proxyURL>[","<proxyURIList>]
proxyURL = [<proxyScheme>"://"]<proxyHost>[":"<proxyPort>]

例如：

  • http=foopy:80;ftp=foopy2 - Use HTTP proxy foopy:80 for http:// URLs, and HTTP proxy foopy2:80 for ftp:// URLs.
  • foopy:80 - Use HTTP proxy foopy:80 for all URLs.
  • foopy:80,bar,direct:// - Use HTTP proxy foopy:80 for all URLs, failing over to bar if foopy:80 is unavailable, and after that using no proxy.
  • socks4://foopy - Use SOCKS v4 proxy foopy:1080 for all URLs.
  • http=foopy,socks5://bar.com - Use HTTP proxy foopy for http URLs, and fail over to the SOCKS5 proxy bar.com if foopy is unavailable.
  • http=foopy,direct:// - Use HTTP proxy foopy for http URLs, and use no proxy if foopy is unavailable.
  • http=foopy;socks=foopy2 - 对于http URL，用foopy作为HTTP协议代理，而其它所有URL则用socks4://foopy2 协议。

proxyBypassRules是一个用逗号分隔的规则列表, 如下所述:

  • [ URL_SCHEME "://" ] HOSTNAME_PATTERN [ ":" <port> ]

    与 HOSTNAME_PATTERN 模式匹配的所有主机名。

    例如: "foobar.com", "foobar.com", ".foobar.com", "foobar.com:99", "https://x..y.com:99"

    • "." HOSTNAME_SUFFIX_PATTERN [ ":" PORT ]

      匹配特定域名后缀。

      例如： ".google.com", ".com", "http://.google.com"

  • [ SCHEME "://" ] IP_LITERAL [ ":" PORT ]

    匹配 IP 地址文本的 url。

    例如: "127.0.1", "[0:0::1]", "[::1]", "http://[::1]:99"

  • IP_LITERAL "/" PREFIX_LENGTH_IN_BITS

    匹配位于给定范围之间的 IP 文本的任何 URL。IP 范围是使用 CIDR 表示法指定的。

    例如: "192.168.1.1/16", "fefe:13::abc/33".

  • <local>

    匹配本地地址。local 的含义是，是否匹配其中一个: "127.0.0.1", "::1", "localhost".

ses.setProxy(config)

  • config Object

    • pacScript String - The URL associated with the PAC file.
    • proxyRules String - Rules indicating which proxies to use.
    • proxyBypassRules String - Rules indicating which URLs should bypass the proxy settings.

Returns Promise<void> - Resolves when the proxy setting process is complete.

Sets the proxy settings.

When pacScript and proxyRules are provided together, the proxyRules option is ignored and pacScript configuration is applied.

The proxyRules has to follow the rules below:

proxyRules = schemeProxies[";"<schemeProxies>]
schemeProxies = [<urlScheme>"="]<proxyURIList>
urlScheme = "http" | "https" | "ftp" | "socks"
proxyURIList = <proxyURL>[","<proxyURIList>]
proxyURL = [<proxyScheme>"://"]<proxyHost>[":"<proxyPort>]

For example:

  • http=foopy:80;ftp=foopy2 - Use HTTP proxy foopy:80 for http:// URLs, and HTTP proxy foopy2:80 for ftp:// URLs.
  • foopy:80 - Use HTTP proxy foopy:80 for all URLs.
  • foopy:80,bar,direct:// - Use HTTP proxy foopy:80 for all URLs, failing over to bar if foopy:80 is unavailable, and after that using no proxy.
  • socks4://foopy - Use SOCKS v4 proxy foopy:1080 for all URLs.
  • http=foopy,socks5://bar.com - Use HTTP proxy foopy for http URLs, and fail over to the SOCKS5 proxy bar.com if foopy is unavailable.
  • http=foopy,direct:// - Use HTTP proxy foopy for http URLs, and use no proxy if foopy is unavailable.
  • http=foopy;socks=foopy2 - Use HTTP proxy foopy for http URLs, and use socks4://foopy2 for all other URLs.

The proxyBypassRules is a comma separated list of rules described below:

  • [ URL_SCHEME "://" ] HOSTNAME_PATTERN [ ":" <port> ]

    Match all hostnames that match the pattern HOSTNAME_PATTERN.

    Examples: "foobar.com", "foobar.com", ".foobar.com", "foobar.com:99", "https://x..y.com:99"

  • "." HOSTNAME_SUFFIX_PATTERN [ ":" PORT ]

    Match a particular domain suffix.

    Examples: ".google.com", ".com", "http://.google.com"

  • [ SCHEME "://" ] IP_LITERAL [ ":" PORT ]

    Match URLs which are IP address literals.

    Examples: "127.0.1", "[0:0::1]", "[::1]", "http://[::1]:99"

  • IP_LITERAL "/" PREFIX_LENGTH_IN_BITS

    Match any URL that is to an IP literal that falls between the given range. IP range is specified using CIDR notation.

    Examples: "192.168.1.1/16", "fefe:13::abc/33".

  • <local>

    Match local addresses. The meaning of <local> is whether the host matches one of: "127.0.0.1", "::1", "localhost".

ses.resolveProxy(url, callback)

  • url URL

  • callback Function

    • proxy String

解析 url 的代理信息。执行被请求时, 将使用 callback(proxy) 来调用 callback。

即将弃用

ses.resolveProxy(url, callback)

  • url URL

  • callback Function

    • proxy String

Resolves the proxy information for url. The callback will be called with callback(proxy) when the request is performed.

Deprecated Soon

ses.resolveProxy(url)

  • url URL

Returns Promise<string> - Resolves with the proxy information for url.

ses.resolveProxy(url)

  • url URL

Returns Promise<string> - Resolves with the proxy information for url.

ses.setDownloadPath(path)

  • path String - 下载地址.

设置下载保存目录。默认情况下, 下载目录将是相应应用程序文件夹下的 Downloads。

ses.setDownloadPath(path)

  • path String - The download location.

Sets download saving directory. By default, the download directory will be the Downloads under the respective app folder.

ses.enableNetworkEmulation(options)

  • options Object

    • offline Boolean (可选) - 是否模拟网络中断、离线。默认 否。
    • latency Double (可选) - RTT时延毫秒值. 默认为0将禁用时延调节。
    • downloadThroughput Double (可选) - 指定下载Bps速率。默认为0将禁用下载限速。
    • uploadThroughput Double (可选) - 指定上传Bps速率. 默认0将禁用上传速率限制。

通过指定的配置为 session 模拟网络。

// To emulate a GPRS connection with 50kbps throughput and 500 ms latency.
window.webContents.session.enableNetworkEmulation({
  latency: 500,
  downloadThroughput: 6400,
  uploadThroughput: 6400
})
// To emulate a network outage.
window.webContents.session.enableNetworkEmulation({ offline: true })

ses.enableNetworkEmulation(options)

  • options Object

    • offline Boolean (optional) - Whether to emulate network outage. Defaults to false.
    • latency Double (optional) - RTT in ms. Defaults to 0 which will disable latency throttling.
    • downloadThroughput Double (optional) - Download rate in Bps. Defaults to 0 which will disable download throttling.
    • uploadThroughput Double (optional) - Upload rate in Bps. Defaults to 0 which will disable upload throttling.

Emulates network with the given configuration for the session.

// To emulate a GPRS connection with 50kbps throughput and 500 ms latency.
window.webContents.session.enableNetworkEmulation({
  latency: 500,
  downloadThroughput: 6400,
  uploadThroughput: 6400
})
// To emulate a network outage.
window.webContents.session.enableNetworkEmulation({ offline: true })

ses.disableNetworkEmulation()

禁用所有为 session 模拟的已激活网络。重置为原始网络配置。

ses.disableNetworkEmulation()

Disables any network emulation already active for the session. Resets to the original network configuration.

ses.setCertificateVerifyProc(proc)

  • proc Function

    • request Object

      • hostname String
      • certificate 证书
      • verificationResult String - chromium证书验证结果
      • errorCode Integer - 错误代码

    • callback Function

      • verificationResult Integer - 证书错误代码之一，来自 这里。 除了证书错误代码外，还可以使用以下特殊代码。

        • -0 - 表示成功并禁用证书透明度验证
        • -2 - 表示失败
        • -3 - 使用chromium的验证结果

每当一个服务器证书请求验证，proc 将被这样 proc(request, callback) 调用，为 session 设置证书验证过程。 回调函数 callback(0) 接受证书，callback(-2) 驳回证书。

调用 setCertificateVerifyProc（null）将恢复为默认证书验证过程。

const { BrowserWindow } = require('electron')
let win = new BrowserWindow()
win.webContents.session.setCertificateVerifyProc((request, callback) => {
  const { hostname } = request
  if (hostname === 'github.com') {
    callback(0)
  } else {
    callback(-2)
  }
})

ses.setCertificateVerifyProc(proc)

  • proc Function

    • request Object

      • hostname String
      • certificate Certificate
      • verificationResult String - Verification result from chromium.
      • errorCode Integer - Error code.

    • callback Function

      • verificationResult Integer - Value can be one of certificate error codes from here. Apart from the certificate error codes, the following special codes can be used.

        • 0 - Indicates success and disables Certificate Transparency verification.
        • -2 - Indicates failure.
        • -3 - Uses the verification result from chromium.

Sets the certificate verify proc for session, the proc will be called with proc(request, callback) whenever a server certificate verification is requested. Calling callback(0) accepts the certificate, calling callback(-2) rejects it.

Calling setCertificateVerifyProc(null) will revert back to default certificate verify proc.

const { BrowserWindow } = require('electron')
let win = new BrowserWindow()
win.webContents.session.setCertificateVerifyProc((request, callback) => {
  const { hostname } = request
  if (hostname === 'github.com') {
    callback(0)
  } else {
    callback(-2)
  }
})

ses.setPermissionRequestHandler(handler)

  • handler Function | null

    • webContents WebContents - 请求权限的WebContents。 Please note that if the request comes from a subframe you should use requestingUrl to check the request origin.
    • permission String - 枚举 'media', 'geolocation', 'notifications', 'midiSysex', 'pointerLock', 'fullscreen', 'openExternal'.

    • callback Function

      • permissionGranted Boolean - 允许或拒绝该权限.

    • details Object - 一些属性只有在某些授权状态下可用。

      • externalURL String (Optional) - The url of the openExternal request.
      • mediaTypes String - The types of media access being requested, elements can be video or audio
      • requestingUrl String - The last URL the requesting frame loaded
      • isMainFrame Boolean - Whether the frame making the request is the main frame

设置可用于响应 session 的权限请求的处理程序。 调用 callback(true) 将允许该权限, 调用 callback(false) 将拒绝它。 若要清除处理程序, 请调用 setPermissionRequestHandler (null)。

const { session } = require('electron')
session.fromPartition('some-partition').setPermissionRequestHandler((webContents, permission, callback) => {
  if (webContents.getURL() === 'some-host' && permission === 'notifications') {
    return callback(false) // denied.
  }
  callback(true)
})

ses.setPermissionRequestHandler(handler)

  • handler Function | null

    • webContents WebContents - WebContents requesting the permission. Please note that if the request comes from a subframe you should use requestingUrl to check the request origin.
    • permission String - Enum of 'media', 'geolocation', 'notifications', 'midiSysex', 'pointerLock', 'fullscreen', 'openExternal'.

    • callback Function

      • permissionGranted Boolean - Allow or deny the permission.

    • details Object - Some properties are only available on certain permission types.

      • externalURL String (Optional) - The url of the openExternal request.
      • mediaTypes String - The types of media access being requested, elements can be video or audio
      • requestingUrl String - The last URL the requesting frame loaded
      • isMainFrame Boolean - Whether the frame making the request is the main frame

Sets the handler which can be used to respond to permission requests for the session. Calling callback(true) will allow the permission and callback(false) will reject it. To clear the handler, call setPermissionRequestHandler(null).

const { session } = require('electron')
session.fromPartition('some-partition').setPermissionRequestHandler((webContents, permission, callback) => {
  if (webContents.getURL() === 'some-host' && permission === 'notifications') {
    return callback(false) // denied.
  }
  callback(true)
})

ses.setPermissionCheckHandler(handler)

  • handler Function | null

    • webContents WebContents - WebContents checking the permission. Please note that if the request comes from a subframe you should use requestingUrl to check the request origin.
    • permission String - Enum of 'media'.
    • requestingOrigin String - The origin URL of the permission check

    • details Object - 一些属性只有在某些授权状态下可用。

      • securityOrigin String - The security orign of the media check.
      • mediaType String - The type of media access being requested, can be video, audio or unknown
      • requestingUrl String - The last URL the requesting frame loaded
      • isMainFrame Boolean - Whether the frame making the request is the main frame

Sets the handler which can be used to respond to permission checks for the session. Returning true will allow the permission and false will reject it. To clear the handler, call setPermissionCheckHandler(null).

const { session } = require('electron')
session.fromPartition('some-partition').setPermissionCheckHandler((webContents, permission) => {
  if (webContents.getURL() === 'some-host' && permission === 'notifications') {
    return false // denied
  }
  return true
})

ses.setPermissionCheckHandler(handler)

  • handler Function | null

    • webContents WebContents - WebContents checking the permission. Please note that if the request comes from a subframe you should use requestingUrl to check the request origin.
    • permission String - Enum of 'media'.
    • requestingOrigin String - The origin URL of the permission check

    • details Object - Some properties are only available on certain permission types.

      • securityOrigin String - The security orign of the media check.
      • mediaType String - The type of media access being requested, can be video, audio or unknown
      • requestingUrl String - The last URL the requesting frame loaded
      • isMainFrame Boolean - Whether the frame making the request is the main frame

Sets the handler which can be used to respond to permission checks for the session. Returning true will allow the permission and false will reject it. To clear the handler, call setPermissionCheckHandler(null).

const { session } = require('electron')
session.fromPartition('some-partition').setPermissionCheckHandler((webContents, permission) => {
  if (webContents.getURL() === 'some-host' && permission === 'notifications') {
    return false // denied
  }
  return true
})

ses.clearHostResolverCache(callback)

  • callback Function (optional) - 会在操作完成后被调用.

清除主机解析程序的缓存。

即将弃用

ses.clearHostResolverCache(callback)

  • callback Function (optional) - Called when operation is done.

Clears the host resolver cache.

Deprecated Soon

ses.clearHostResolverCache()

Returns Promise<void> - Resolves when the operation is complete.

清除主机解析程序的缓存。

ses.clearHostResolverCache()

Returns Promise<void> - Resolves when the operation is complete.

Clears the host resolver cache.

ses.allowNTLMCredentialsForDomains(domains)

  • domains String - 一个逗号分隔的服务器列表, 用于收集已经启用身份验证的服务器。

动态设置是否始终为 HTTP NTLM 发送凭据或协商身份验证。

const { session } = require('electron')
// 以 "example.com"、"foobar.com"、"baz" 结尾的 url 用于身份验证。
session.defaultSession.allowNTLMCredentialsForDomains('*example.com, *foobar.com, *baz')
// 所有的 url 都可以用作身份验证
session.defaultSession.allowNTLMCredentialsForDomains('*')

ses.allowNTLMCredentialsForDomains(domains)

  • domains String - A comma-separated list of servers for which integrated authentication is enabled.

Dynamically sets whether to always send credentials for HTTP NTLM or Negotiate authentication.

const { session } = require('electron')
// consider any url ending with `example.com`, `foobar.com`, `baz`
// for integrated authentication.
session.defaultSession.allowNTLMCredentialsForDomains('*example.com, *foobar.com, *baz')
// consider all urls for integrated authentication.
session.defaultSession.allowNTLMCredentialsForDomains('*')

ses.setUserAgent(userAgent[, acceptLanguages])

  • userAgent String
  • acceptLanguages String (可选)

覆盖当前会话的 userAgent 和 acceptLanguages.

acceptLanguages 必须是用逗号分隔的语言代码列表，例如 "en-US,fr,de,ko,zh-CN,ja".

这不会影响现有的WebContents, 并且每个WebContents都可以使用 webContents.setUserAgent重写会话范围的user agent。

ses.setUserAgent(userAgent[, acceptLanguages])

  • userAgent String
  • acceptLanguages String (optional)

Overrides the userAgent and acceptLanguages for this session.

The acceptLanguages must a comma separated ordered list of language codes, for example "en-US,fr,de,ko,zh-CN,ja".

This doesn't affect existing WebContents, and each WebContents can use webContents.setUserAgent to override the session-wide user agent.

ses.getUserAgent()

返回 String - 当前会话的 user agent.

ses.getUserAgent()

Returns String - The user agent for this session.

ses.getBlobData(identifier, callback)

  • identifier String - 有效的 UUID.

  • callback Function

    • result Buffer - Blob 数据.

即将弃用

ses.getBlobData(identifier, callback)

  • identifier String - Valid UUID.

  • callback Function

    • result Buffer - Blob data.

Deprecated Soon

ses.getBlobData(identifier)

  • identifier String - 有效的 UUID.

Returns Promise<Buffer> - resolves with blob data.

ses.getBlobData(identifier)

  • identifier String - Valid UUID.

Returns Promise<Buffer> - resolves with blob data.

ses.createInterruptedDownload(options)

  • options Object

    • path String - 下载的绝对路径.
    • urlChain String[] - 完整的 url 下载地址.
    • mimeType String (可选)
    • offset Integer - 下载的开始范围.
    • length Integer - 下载的总长度。
    • lastModified String - 上次修改的标头值。
    • eTag String - ETag 标头值。
    • startTime Double (optional) - 下载的时间是从 UNIX 时代以来的秒数开始的。

允许从上一个 Session 恢复 cancelled 或 interrupted 下载。 该 API 将生成一个 DownloadItem , 可使用 will-download 事件进行访问。 DownloadItem 将不具有与之关联的任何 WebContents, 并且初始状态将为 interrupted。 只有在 DownloadItem 上调用 resume API 时, 才会启动下载。

ses.createInterruptedDownload(options)

  • options Object

    • path String - Absolute path of the download.
    • urlChain String[] - Complete URL chain for the download.
    • mimeType String (optional)
    • offset Integer - Start range for the download.
    • length Integer - Total length of the download.
    • lastModified String - Last-Modified header value.
    • eTag String - ETag header value.
    • startTime Double (optional) - Time when download was started in number of seconds since UNIX epoch.

Allows resuming cancelled or interrupted downloads from previous Session. The API will generate a DownloadItem that can be accessed with the will-download event. The DownloadItem will not have any WebContents associated with it and the initial state will be interrupted. The download will start only when the resume API is called on the DownloadItem.

ses.clearAuthCache(options, callback)

  • options (RemovePassword | RemoveClientCertificate)
  • callback Function - 会在操作完成之后被调用。

清除会话的 HTTP 身份验证缓存。

即将弃用

ses.clearAuthCache(options, callback)

  • options (RemovePassword | RemoveClientCertificate)
  • callback Function - Called when operation is done.

Clears the session’s HTTP authentication cache.

Deprecated Soon

ses.clearAuthCache(options) (deprecated)

  • options (RemovePassword | RemoveClientCertificate)

Returns Promise<void> - resolves when the session’s HTTP authentication cache has been cleared.

ses.clearAuthCache(options) (deprecated)

  • options (RemovePassword | RemoveClientCertificate)

Returns Promise<void> - resolves when the session’s HTTP authentication cache has been cleared.

ses.clearAuthCache()

Returns Promise<void> - resolves when the session’s HTTP authentication cache has been cleared.

ses.clearAuthCache()

Returns Promise<void> - resolves when the session’s HTTP authentication cache has been cleared.

ses.setPreloads(preloads)

  • preloads String[] - 数组，该数组由所有需要进行预加载的脚本的绝对路径组成。

Adds scripts that will be executed on ALL web contents that are associated with this session just before normal preload scripts run.

ses.setPreloads(preloads)

  • preloads String[] - An array of absolute path to preload scripts

Adds scripts that will be executed on ALL web contents that are associated with this session just before normal preload scripts run.

ses.getPreloads()

返回 String[] 返回一个数组，这个数组由已经注册过的预加载脚本的路径组成。

ses.getPreloads()

Returns String[] an array of paths to preload scripts that have been registered.

实例属性

以下属性在` Session </ 0>实例上可用：

ses.cookies`

此会话的 cookie 对象。

Instance Properties

The following properties are available on instances of Session:

ses.webRequest

此会话的 WebRequest 对象。

ses.cookies

A Cookies object for this session.

ses.protocol

此会话的 协议 对象。

const { app, session } = require('electron')
const path = require('path')
app.on('ready', function () {
  const protocol = session.fromPartition('some-partition').protocol
  protocol.registerFileProtocol('atom', function (request, callback) {
    var url = request.url.substr(7)
    callback({ path: path.normalize(`${__dirname}/${url}`) })
  }, function (error) {
    if (error) console.error('Failed to register protocol')
  })
})

ses.webRequest

A WebRequest object for this session.

ses.netLog

A NetLog object for this session.

const { app, session } = require('electron')
app.on('ready', async function () {
  const netLog = session.fromPartition('some-partition').netLog
  netLog.startLogging('/path/to/net-log')
  // After some network events
  const path = await netLog.stopLogging()
  console.log('Net-logs written to', path)
})

ses.protocol

A Protocol object for this session.

const { app, session } = require('electron')
const path = require('path')
app.on('ready', function () {
  const protocol = session.fromPartition('some-partition').protocol
  protocol.registerFileProtocol('atom', function (request, callback) {
    var url = request.url.substr(7)
    callback({ path: path.normalize(`${__dirname}/${url}`) })
  }, function (error) {
    if (error) console.error('Failed to register protocol')
  })
})
免责声明： 以上内容版权归原作者所有，如有侵犯您的原创版权请告知，我们将尽快删除相关内容。感谢每一位辛勤著写的作者，感谢每一位的分享。
@小牛知识库 xnip.cn