14. session

原文：https://github.com/electron/electron/blob/master/docs/api/session.md
译者：Lin

管理浏览器会话、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())

方法

session模块有以下方法：

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

partition String类型
options Object类型
- cache Boolean类型 - 是否可以使用缓存。

返回值为Session类型 - 从partition字符串获取的会话。当这里存在一个拥有同样的partition的Session，它将会被返回；否则一个新的Session实例将会通过options被创建。

如果partition是以persist:开头的，这个页面将会使用一个在应用中对所有页面的相同partition永久有效的会话。如果没有persist:前缀，页面将会使用内存会话。如果partition是空的，那么应用的默认会话将会被返回。

使用options创建一个Session，你必须保证Session的partition在之前从来没有被使用过。这里没有方法改变一个存在的Session对象的options。

属性

session模块有以下属性：

`session.defaultSession`

一个Session对象，应用的默认会话对象。

类：Session

获取并设置一个会话的属性。

进程：主进程

你可以使用session模块来创建一个新的Session对象。

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

实例的事件

以下事件在Session的实例中有效：

事件：'will-download'

event Event类型
item DownloadItem类型
webContents WebContents类型

当Electron要下载webContents中的item的时候被分发。

调用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 Function类型
- size Integer类型 - 使用的缓存大小，以字节为单位。

回调会返回这个会话的当前缓存大小。

`ses.clearCache(callback)`

callback Function类型 - 当操作完成时被调用

清空会话的HTTP缓存。

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

options Object类型（可选参数）
- origin String类型 - 应该遵循window.location.origin的表述方式scheme://host:port。
- storages String[]类型 - 要清除的存储类型，可以包含：appcache、cookies、filesystem、indexdb、localstorage、shadercache、websql、serviceworkers
- quotas String[]类型 - 要清除的量的类型，可以包含：temporary、persistent、syncable。
callback Function类型（可选参数）- 当操作完成时被调用。

清除网络存储数据。

`ses.flushStorageData()`

将还没有写入的DOMStorage写入磁盘。

`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 = ["="]
urlScheme = "http" | "https" | "ftp" | "socks"
proxyURIList = [","]
proxyURL = ["://"][":"]

例如：

ttp=foopy:80;ftp=foopy2 - 使用HTTP代理foopy:80的http://地址，使用HTTP代理foopy2:80的ftp://地址。
foopy:80 - 使用HTTP代理foopy:80的所有地址。
foopy:80,bar,direct:// - 使用HTTP代理foopy:80的所有地址，如果foopy:80不可用则换为bar，如果bar也不可用那就不使用代理。
socks4://foopy - 使用SOCKS v4代理foopy:1080的所有地址。
http=foopy,socks5://bar.com - 使用HTTP代理foopy的所有http地址，如果foopy不可用就换为使用SOCKS5代理bar.com。
http=foopy,direct:// - 使用HTTP代理foopy的所有http地址，如果foopy不可用就不使用代理。
http=foopy;socks=foopy2 - 使用HTTP代理foopy的所有http地址，并使用socks4://foopy2代理其他所有的地址。

proxyBypassRules是一个使用逗号分隔的列表，规则描述见下面：

[ URL_SCHEME "://" ] HOSTNAME_PATTERN [ ":" ]

匹配所有hostnames that match the pattern 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地址字面量的地址。

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

Match any URL that is to an IP literal that falls between the given range. IP范围使用CIDR符号指定。

例如："192.168.1.1/16", "fefe:13::abc/33".
匹配本地地址。的意思是匹配到这之中的任何一个："127.0.0.1"，"::1"，"localhost"。

`ses.resolveProxy(url, callback)`

url URL类型
callback Function类型
- proxy String类型

解析url的协议信息。当请求被执行的时候callback将要被callback(proxy)调用。

`ses.setDownloadPath(path)`

path String类型 - 下载位置

设置下载保存目录。默认情况下，下载目录将是在各自应用的文件夹中的Downloads文件夹下。

`ses.enableNetworkEmulation(options)`

options Object类型
- offline Boolean类型（可选参数）- 是否模拟网络断开。默认为false。
- latency Double类型（可选参数）- ms为单位的RTT。默认是0，即禁止限制延迟。
- downloadThroughput Double类型（可选参数）- Bps为单位的下载速度。默认是0，即禁止限制下载。
- uploadThroughput Double类型（可选参数）- Bps为单位的上传速度。默认是0，即禁止限制上传。

session中使用给定的配置模拟网络。

// 使用50kbps吞吐量和500ms延迟来模拟一个GPRS链接。
window.webContents.session.enableNetworkEmulation({
    latency: 500,
    downloadThroughput: 6400,
    uploadThroughput: 6400
})

// 模拟一个网络中断。
window.webContents.session.enableNetworkEmulation({offline: true})

`ses.disableNetworkEmulation()`

禁用session中已经开启的网络模拟。将重置为原来的网络配置。

`ses.setCertificateVerifyProc(proc)`

proc Function类型
- request Object类型
  - hostname String类型
  - certificate Certificate类型
  - error String类型 - 从chromium中验证结果。
- callback Function类型
  - verificationResult Integer类型 - 值可以是这里面的证书错误代码之一。除了证书错误代码之外还可以使用下面的特殊代码。
    - 0 - 表示成功，并且不允许Certificate Transperancy验证。
    - -2 - 表示失败。
    - -3 - 使用chromium的验证结果。

设置session的证书验证过程，当一个服务器证书验证被请求，proc将会被proc(request, callback)调用 whenever a server certificate verification is requested. 调用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 Function类型
- webContents Object类型 - WebContents请求许可。
- permission String类型 - 枚举值为'media'，'geolocation'，'notifications'，'midiSysex'，'pointerLock'，'fullscreen'，'openExternal'。
- callback Function类型
  - permissionGranted Boolean类型 - 允许或者拒绝这个许可。

设置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 Function类型（可选参数）- 当操作完成时被调用。

清空主机解析器的缓存。

`ses.allowNTLMCredentialsForDomains(domains)`

domains String类型 - A comma-seperated 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')
// 考虑到任何使用`example.com`, `foobar.com`, `baz`结尾的url的集成认证。
session.defaultSession.allowNTLMCredentialsForDomains('*example.com, *foobar.com, *baz')

// 考虑到所有的url的集成认证。
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来重写会话范围内的用户代理。

`ses.getUserAgent()`

返回值为String类型 - 这个会话的用户代理

`ses.getBlobData(identifier, callback)`

identifier String类型 - 有效的UUID。
callback Function类型
- result Buffer类型 - Blob数据。

返回值为Blob类型 - 与identifier相关的blob数据。

`ses.createInterruptedDownload(options)`

options Object类型
- path String类型 - 下载的绝对路径。
- urlChain String[]类型 - 完整的下载链接。
- mimeType String类型（可选参数）
- offset Integer类型 - 下载的起始范围。
- length Integer类型 - 下载的总长度。
- lastModified String类型 - 最后修改头的值。
- eTag String类型 - ETag头的值。
- startTime Double类型（可选参数）- Time when download was started in number of seconds since UNIX epoch.

允许在之前的Session中重新开始cancelled或interrupted下载。这个接口将生成一个可以被will-download事件使用的DownloadItemhttps://github.com/electron/electron/blob/master/docs/api/download-item.md。这个DownloadItem将没有任何和它相关的WebContents，并且最开始的状态将会被interrupted。这个下载将只在DownloadItem中调用resume接口时启动。

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

options (RemovePassword | RemoveClientCertificate)类型
callback Function类型（可选参数）- 当操作完成时被调用。

清空会话的HTTP验证缓存。

实例的属性

以下属性在Session的实例中有效：

`ses.cookies`

这个会话的Cookie对象。

`ses.webRequest`

这个会话的WebRequest对象。

`ses.protocol`

这个会话的Protocol对象（一个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')
    })
})

14. session

方法

session.fromPartition(partition[, options])

属性

session.defaultSession

类：Session

实例的事件

事件：'will-download'

实例的方法

ses.getCacheSize(callback)

ses.clearCache(callback)

ses.clearStorageData([options, callback])

ses.flushStorageData()

ses.setProxy(config, callback)

ses.resolveProxy(url, callback)

ses.setDownloadPath(path)

ses.enableNetworkEmulation(options)

ses.disableNetworkEmulation()

ses.setCertificateVerifyProc(proc)

ses.setPermissionRequestHandler(handler)

ses.clearHostResolverCache([callback])

ses.allowNTLMCredentialsForDomains(domains)

ses.setUserAgent(userAgent[, acceptLanguages])

ses.getUserAgent()

ses.getBlobData(identifier, callback)

ses.createInterruptedDownload(options)

ses.clearAuthCache(options[, callback])