会话 | session

管理浏览器会话，Cookie，缓存，代理设置等。

过程：主程序

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

您也可以session使用模块的session属性WebContents或从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())

方法

session模块具有以下方法：

`session.fromPartition(partition[, options])`

partition 串
options 目的
cache 布尔值 - 是否启用缓存。

返回Session- partition字符串中的会话实例。当存在一个Session相同的时候partition，它将被返回; 否则Session将创建一个新的实例options。

如果partition开头persist:，页面将使用持续会话可用于应用程序中的所有页面partition。如果没有persist:前缀，页面将使用内存中会话。如果它partition是空的，那么应用程序的默认会话将被返回。

要创建一个Session有options，你必须确保Session与partition之前从未被使用。没有办法改变options现有的Session对象。

属性

session模块具有以下属性：

`session.defaultSession`

Session对象，该应用程序的默认会话对象。

类：会话

获取和设置会话的属性。

过程：主程序

您可以Session在模块中创建一个session对象：

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

实例事件

以下事件可用于以下情况Session：

事件：‘will-download’

event 事件
item DownloadItem
webContents WebContents

当电子即将发出的下载item在webContents。

通话event.preventDefault()将取消下载，并且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)
  })
})

实例方法

以下方法适用于以下情况Session：

`ses.getCacheSize(callback)`

callback 功能
size 整数 - 用于字节的高速缓存大小。

使用会话的当前缓存大小调用回调。

`ses.clearCache(callback)`

callback 功能 - 操作完成时调用

清除会话的 HTTP 缓存。

`ses.clearStorageData([options, callback])`

options 对象（可选）
- origin字符串 - （可选）应该遵循window.location.origin'表示scheme://host:port。
- storages串[] - （可选）类型存储器的清除，可包含：appcache，cookies，filesystem，indexdb，localstorage，shadercache，websql，serviceworkers
- quotas串[] - （可选）类型的配额来清除，可以包含：temporary，persistent，syncable。
callback 功能（可选） - 操作完成时调用。

清除网络存储的数据。

`ses.flushStorageData()`

将任何未写入的 DOMStorage 数据写入磁盘。

`ses.setProxy(config, callback)`

config 目的
- pacScript 字符串 - 与 PAC 文件关联的 URL。
- proxyRules 字符串 - 指示使用哪个代理的规则。
- proxyBypassRules 字符串 - 指示哪些URL应绕过代理设置的规则。
callback 功能 - 操作完成时调用。

设置代理设置。

当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-使用 HTTP 代理服务器foopy:80的http://URL 和 HTTP 代理服务器foopy2:80的ftp://网址。
foopy:80- foopy:80对所有网址使用 HTTP 代理。
foopy:80,bar,direct://- foopy:80对所有 URL 使用HTTP代理，bar如果foopy:80不可用，则使用 HTTP 代理，然后使用无代理。
socks4://foopy- foopy:1080为所有网址使用 SOCKS v4代理。
http=foopy,socks5://bar.com- foopy对 HTTP URL 使用 HTTP 代理，bar.com如果foopy不可用，则故障切换到 SOCKS5 代理。
http=foopy,direct://- foopy对 HTTP URL 使用 HTTP 代理，如果foopy不可用，则不使用代理。
http=foopy;socks=foopy2- foopy对 HTTP URL 使用 HTTP 代理，并将其socks4://foopy2用于所有其他 URL。

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_LENGHT_IN_BITS 匹配任何落在给定范围内的IP文字的URL。IP 范围使用 CIDR 表示法指定。例如：“192.168.1.1/16”，“fefe：13 :: abc / 33”。
<local> 匹配本地地址。其含义<local>是主机是否匹配“127.0.0.1”，“:: 1”，“localhost”之一。

`ses.resolveProxy(url, callback)`

url 网址
callback 功能
- proxy 串

解析代理信息url。在callback将被用callback(proxy)在执行请求。

`ses.setDownloadPath(path)`

path 字符串 - 下载位置

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

`ses.enableNetworkEmulation(options)`

options 目的
- offline布尔（可选） - 是否模拟网络中断。默认为 false。
- latency双（可选） - RTT，单位为 ms。默认为0，这将禁用等待时间限制。
- downloadThroughput双（可选） - 以 Bps 下载速率。默认为0，这将禁用下载限制。
- uploadThroughput双倍（可选） - 以 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.disableNetworkEmulation()`

禁用任何已为其激活的网络仿真session。重置为原始网络配置。

`ses.setCertificateVerifyProc(proc)`

proc 功能
- request 目的
  - hostname 串
  - certificate 证书
  - error 字符串 - 来自铬的验证结果。

-  `callback` Function 
    -  `verificationResult` Integer - Value can be one of certificate error codes from [here](https://code.google.com/p/chromium/codesearch#chromium/src/net/base/net_error_list.h). Apart from the certificate error codes, the following special codes can be used. 
        -  `0` - Indicates success and disables Certificate Transperancy verification.
        -  `-2` - Indicates failure.
        -  `-3` - Uses the verification result from chromium.

设置证书验证过程，只要请求服务器证书验证session，proc就会调用proc(request, callback)证书验证过程。呼叫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.setPermissionRequestHandler(handler)`

handler 功能
- webContents WebContents - 请求权限的WebContents。
- permission String - “媒体”，“地理位置”，“通知”，“midiSysex”，“pointerLock”，“全屏”，“openExternal”的枚举。
- callback 功能
  - permissionGranted 布尔值 - 允许或拒绝权限

设置可用于响应该权限请求的处理程序session。调用callback(true)将允许该权限callback(false)并将拒绝它。

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.clearHostResolverCache([callback])`

callback 功能（可选） - 操作完成时调用。

清除主机解析程序缓存。

`ses.allowNTLMCredentialsForDomains(domains)`

domains 字符串 - 启用集成身份验证的服务器的逗号分隔列表。

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

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 串
acceptLanguages 字符串（可选）

覆盖userAgent和acceptLanguages本次会议。

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

这不会影响现有的WebContents，并且每个都WebContents可以webContents.setUserAgent用来覆盖会话范围的用户代理。

`ses.getUserAgent()`

返回String- 此会话的用户代理。

`ses.getBlobData(identifier, callback)`

identifier 字符串 - 有效的UUID。
callback 功能
- result 缓冲区 - Blob 数据。

返回Blob- 与该关联的 Blob 数据identifier。

`ses.createInterruptedDownload(options)`

options 目的
- path 字符串 - 下载的绝对路径。
- urlChain 字符串[] - 下载的完整URL链。
- mimeType 字符串（可选）
- offset 整数 - 下载的开始范围。
- length 整数 - 下载的总长度。
- lastModified 字符串 - 上次修改的标题值。
- eTag 字符串 - ETag标头值。
- startTime Double（可选） - 从 UNIX 纪元开始以秒为单位开始下载的时间。

允许从以前的恢复cancelled或interrupted下载Session。该API将生成一个可以通过will-download事件访问的DownloadItem。DownloadItem不会有任何WebContents关联，并且初始状态将会是interrupted。只有在resumeDownloadItem上调用API 时，下载才会开始。

`ses.clearAuthCache(options[, callback])`

options （RemovePassword | RemoveClientCertificate）
callback 功能（可选） - 操作完成时调用

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

实例属性

以下属性可用于以下实例Session：

`ses.cookies`

会话的 Cookies 对象。

`ses.webRequest`

会话的 WebRequest 对象。

`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')
  })
})

本文档系腾讯云开发者社区成员共同维护，如有问题请联系 cloudcommunity@tencent.com

最后更新于：2017-12-18