本文介绍:session(会话,缓存和代理等控制)
- 方法
  - session.fromPartition(partition[, options])
- 属性

本文介绍:session(会话,缓存和代理等控制)

管理浏览器 session ,Cookie,缓存,代理设置等。

session模块可以用来创建新的 Session对象,你也可以通过使用 webContents 的 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 对象 :

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

方法

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

用途:获取来自 partition字符串的 Session实例( Session)

partition String
options Object
- cache Boolean - 是否启用缓存

如果存在一个具有相同 partition的 Session时,它将被返回;否则将使用 options创建一个新的 Session实例。

如果 partition以 persist:前缀,该页面将使用一个持久会话,该会话可用于应用程序中具有相同 partition的所有页面。

如果 partition没有 persist:前缀,该页面将使用内存中会话。

如果 partition为空,那么将返回应用程序的默认会话。

要用 options创建一个 Session, 您必须确保带有 partition的 Session从来没有被使用过. 因为没有办法改变现有 Session 对象中的 options。

属性

`session.defaultSession`

属性:返回应用程序的默认 Session对象

事件

事件: ‘will-download’

触发:Electron 将要从 webContents 下载 item 时

event Event
item DownloadItem
webContents 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)
  })
})

实例方法

`ses.getCacheSize(callback)`

用途:获取当前缓存大小并调用 callback

callback Function
- size Integer - 缓存大小(字节)

`ses.clearCache(callback)`

用途:清除会话的HTTP缓存并调用 callback

callback Function

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

用途:清除Web存储的数据

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

用途:设置代理并调用 callback

config Object
- pacScript String - 与 PAC 文件相关的 URL.
- proxyRules String - 要使用的代理规则.
- proxyBypassRules String - 应绕过代理设置的网址规则。
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 - 为 http://使用HTTP代理 foopy:80 , 为 ftp://使用HTTP代理 foopy2:80 .
foopy:80 - 为所有 URL 使用HTTP代理 foopy:80 .
foopy:80,bar,direct:// - 为所有 URL 使用HTTP代理 foopy:80 , 如果 foopy:80 不可用,则切换使用 bar, 再往后就不使用代理了.
socks4://foopy - 为所有 URL 使用SOCKS4代理 foopy:1080.
http=foopy,socks5://bar.com - 为所有 URL 使用HTTP代理 foopy, 如果 foopy不可用,则切换到SOCKS5代理 bar.com.
http=foopy,direct:// - 为所有http url 使用 HTTP 代理,如果 foopy不可用,则不使用代理.
http=foopy;socks=foopy2 - 为所有http url 使用 foopy 代理,为所有其他 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地址文字的网址。如:”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> 匹配本地地址。即匹配”127.0.0.1”, “::1”, “localhost”之一。

`ses.resolveProxy(url, callback)`

用途:解析 url 的代理信息并调用 callback

url URL
callback Function
- proxy Object

`ses.setDownloadPath(path)`

用途:设置下载目录

path String - 下载地址

下载目录默认是应用所在目录里的 Downloads文件夹.

`ses.enableNetworkEmulation(options)`

用途:通过 session的给定配置模拟网络

options Object
- offline Boolean - 是否模拟网络中断。默认为 false
- latency Double (可选) -每毫秒的 RTT。默认为0,禁用延迟调节。
- downloadThroughput Double (可选) -下载速率(以Bps为单位)。默认值为0,禁用下载限制。
- uploadThroughput Double (可选) - 上传速率(以Bps为单位)。默认值为0,禁用上传限制。

//模拟具有50kbps吞吐量和500 ms延迟的GPRS连接
window.webContents.session.enableNetworkEmulation({
  latency: 500,
  downloadThroughput: 6400,
  uploadThroughput: 6400
})
//模拟网络中断
window.webContents.session.enableNetworkEmulation({offline: true})

`ses.disableNetworkEmulation()`

用途:重置为默认网络配置并停止所有已经使用 session 的活跃模拟网络

`ses.setCertificateVerifyProc(proc)`

用途:每当请求服务器证书验证时为session验证证书并调用 callback接收结果

proc Function
- request Object
  - hostname String
  - certificate Certificate
  - error String - 验证结果.
- callback Function
  - verificationResult Integer - 证书错误码.以下为常见错误代码:
    - 0 - 表示成功并禁用证书Transperancy验证
    - -2 - 表示失败
    - -3 - 使用chrome的验证结果。，
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)`

用途:设置可以用于响应 session权限请求的处理程序并通过 callback(true) 允许或 callback(false) 拒绝该权限

handler Function
- webContents WebContents - WebContents 请求权限.
- permission String -枚举了 'media', 'geolocation', 'notifications', 'midiSysex', 'pointerLock', 'fullscreen', 'openExternal'.
- callback Function
  - permissionGranted Boolean -允许或拒绝该权限

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

`ses.clearHostResolverCache([callback])`

用途:清除主机解析器缓存

callback Function (可选) - 操作完成时调用.

`ses.allowNTLMCredentialsForDomains(domains)`

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

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

const {session} = require('electron')
// 以 `example.com`,`foobar.com`,`baz`等结尾用于集成身份验证的网址
session.defaultSession.allowNTLMCredentialsForDomains('*example.com, *foobar.com, *baz')
//用于集成身份验证的所有网址
session.defaultSession.allowNTLMCredentialsForDomains('*')

`ses.setUserAgent(userAgent[, acceptLanguages])`

用途:覆盖此会话的 userAgent和 acceptLanguages

userAgent String
acceptLanguages String (可选) 以逗号分隔的语言列表,例如 en-US,fr,de,ko,zh-CN,ja。

该方法不会影响现有 WebContents,每个 WebContents可以使用 webContents.setUserAgent来覆盖会话范围的 userAgent。

`ses.getUserAgent()`

用途:获取此会话的 userAgent( String)

`ses.getBlobData(identifier, callback)`

用途:获取与 identifier相关联的 blob数据( Blob)

identifier String - Valid UUID.
callback Function
- result Buffer - Blob data.

`ses.createInterruptedDownload(options)`

用途:允许从以前的 Session 恢复 已取消或 已中断的下载

options Object
- path String - 下载的绝对路径
- urlChain String[] - 完整的下载链接
- mimeType String (可选)
- offset Integer - 下载的开始范围
- length Integer - 下载大小
- lastModified String - Last-Modified标头值
- eTag String - ETag头值。
- startTime Double (可选) - 秒级的下载时间

API将生成可以用will-download进行访问的DownloadItem事件。该事件没有任何可关联的 WebContents且它的初始状态将被 中断。

只有当在DownloadItem上调用 resume API时,下载将开始。

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

用途:清除会话的HTTP身份验证缓存

options (RemovePassword | RemoveClientCertificate)
callback Function (可选) - 操作完成时调用

实例属性

`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('无法注册协议')
  })
})