会话 | session

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 串

返回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在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 功能

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

ses.clearCache(callback)

callback 功能 - 操作完成时调用

清除会话的 HTTP 缓存。

ses.clearStorageData([options, callback])

options 对象（可选）

清除网络存储的数据。

ses.flushStorageData()

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

ses.setProxy(config, callback)

config 目的

设置代理设置。

当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://网址。

proxyBypassRules是一个逗号分隔的规则列表，如下所述：

[ URL_SCHEME "://" ] HOSTNAME_PATTERN [ ":" <port> ] 匹配与模式 HOSTNAME_PATTERN 匹配的所有主机名。例如：“foobar.com”，“ foobar.com”，“ .foobar.com”，“ foobar.com:99”，“https：// x。.y.com：99”

ses.resolveProxy(url, callback)

url 网址

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

ses.setDownloadPath(path)

path 字符串 - 下载位置

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

ses.enableNetworkEmulation(options)

options 目的

使用给定的配置模拟网络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 功能

-  `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 功能

设置可用于响应该权限请求的处理程序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 串

覆盖userAgent和acceptLanguages本次会议。

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

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

ses.getUserAgent()

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

ses.getBlobData(identifier, callback)

identifier 字符串 - 有效的UUID。

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

ses.createInterruptedDownload(options)

options 目的

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

ses.clearAuthCache(options[, callback])

options （RemovePassword | RemoveClientCertificate）

清除会话的 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')
  })
})