session

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

进程：Main

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

你也可以通过使用webContents的属性session来使用一个已有页面的session，webContents是BrowserWindow的属性。

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

partitionString
optionsObject
- cacheBoolean - 是否启用缓存。

从字符串partition返回一个新的Session实例。

返回Session- 一个来自partition字符串的会话实例。当存在时Session与同一个partition，它会被返回；否则一个新Session实例将使用options创建。

如果partition以persist:开头，那么这个 page 将使用一个持久的 session，这个 session 将对应用的所有 page 可用。如果没前缀，这个 page 将使用一个历史 session。如果partition为空，那么将返回应用的默认 session。

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

属性

session模块有如下属性：

session.defaultSession

返回应用的默认Session对象。

Class: Session

获取和设置会话的属性。

进程:Main

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

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

实例事件

实例Session有以下事件:

Event: 'will-download'

eventEvent
itemDownloadItem
webContentsWebContents

当 Electron 将要从webContents下载item时触发.

调用event.preventDefault()可以取消下载，并且在进程的下个 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)
  })
})

实例方法

实例Session有以下方法：

`ses.cookies`

cookies赋予你全力来查询和修改 cookies. 例如:

// 查询所有 cookies.
session.defaultSession.cookies.get({}, function (error, cookies) {
  if (error) console.error(error)
  console.log(cookies)
})

// 查询与指定 url 相关的所有 cookies.
session.defaultSession.cookies.get({ url: 'http://www.github.com' }, function (error, cookies) {
  if (error) console.error(error)
  console.log(cookies)
})

// 设置 cookie;
// may overwrite equivalent cookies if they exist.
var cookie = { url: 'http://www.github.com', name: 'dummy_name', value: 'dummy' }
session.defaultSession.cookies.set(cookie, function (error) {
  if (error) console.error(error)
})

`ses.cookies.get(filter, callback)`

filterObject
- urlString (可选) - 与获取 cookies 相关的url.不设置的话就是从所有 url 获取 cookies .
- nameString (可选) - 通过 name 过滤 cookies.
- domainString (可选) - 获取对应域名或子域名的 cookies .
- pathString (可选) - 获取对应路径的 cookies .
- secureBoolean (可选) - 通过安全性过滤 cookies.
- sessionBoolean (可选) - 过滤掉 session 或持久的 cookies.
callbackFunction

发送一个请求，希望获得所有匹配details的 cookies, 在完成的时候，将通过callback(error, cookies)调用callback.

cookies是一个cookie对象.

cookieObject
- nameString - cookie 名.
- valueString - cookie值.
- domainString - cookie域名.
- hostOnlyString - 是否 cookie 是一个 host-only cookie.
- pathString - cookie路径.
- secureBoolean - 是否是安全 cookie.
- httpOnlyBoolean - 是否只是 HTTP cookie.
- sessionBoolean - cookie 是否是一个 session cookie 或一个带截至日期的持久 cookie .
- expirationDateDouble (可选) - cookie的截至日期，数值为UNIX纪元以来的秒数. 对session cookies 不提供.

`ses.cookies.set(details, callback)`

detailsObject
- urlString - 与获取 cookies 相关的url.
- nameString - cookie 名. 忽略默认为空.
- valueString - cookie 值. 忽略默认为空.
- domainString - cookie的域名. 忽略默认为空.
- pathString - cookie 的路径. 忽略默认为空.
- secureBoolean - 是否已经进行了安全性标识. 默认为 false.
- sessionBoolean - 是否已经 HttpOnly 标识. 默认为 false.
- expirationDateDouble - cookie的截至日期，数值为UNIX纪元以来的秒数. 如果忽略, cookie 变为 session cookie.
callbackFunction

使用details设置 cookie, 完成时使用callback(error)掉哟个callback.

`ses.cookies.remove(url, name, callback)`

urlString - 与 cookies 相关的url.
nameString - 需要删除的 cookie 名.
callbackFunction

删除匹配url和name的 cookie, 完成时使用callback()调用callback.

`ses.getCacheSize(callback)`

callbackFunction
- sizeInteger - 单位 bytes 的缓存 size.

返回 session 的当前缓存 size .

`ses.clearCache(callback)`

callbackFunction - 操作完成时调用

清空 session 的 HTTP 缓存.

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

optionsObject (可选)
- originString - 应当遵循window.location.origin的格式scheme://host:port.
- storagesArray - 需要清理的 storages 类型, 可以包含 :appcache,cookies,filesystem,indexdb,local storage,shadercache,websql,serviceworkers
- quotasArray - 需要清理的类型指标, 可以包含:temporary,persistent,syncable.
callback Function - 操作完成时调用.

清除 web storages 的数据.

`ses.flushStorageData()`

将没有写入的 DOMStorage 写入磁盘.

`ses.setProxy(config, callback)`

configObject
- pacScriptString - 与 PAC 文件相关的 URL.
- proxyRulesString - 代理使用规则.
callbackFunction - 操作完成时调用.

设置 proxy settings.

当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://URL 使用 HTTP 代理foopy:80, 和为ftp://URL HTTP 代理foopy2:80.
foopy:80- 为所有 URL 使用 HTTP 代理foopy:80.
foopy:80,bar,direct://- 为所有 URL 使用 HTTP 代理foopy:80, 如果foopy:80不可用，则切换使用bar, 再往后就不使用代理了.
socks4://foopy- 为所有 URL 使用 SOCKS v4 代理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代理.

`ses.resolveProxy(url, callback)`

urlURL
callbackFunction

解析url的代理信息.当请求完成的时候使用callback(proxy)调用callback.

`ses.setDownloadPath(path)`

pathString - 下载地址

设置下载保存地址，默认保存地址为各自 app 应用的Downloads目录.

`ses.enableNetworkEmulation(options)`

optionsObject
- offlineBoolean - 是否模拟网络故障.
- latencyDouble - 每毫秒的 RTT
- downloadThroughputDouble - 每 Bps 的下载速率.
- uploadThroughputDouble - 每 Bps 的上载速率.

通过给定配置的session来模拟网络.

// 模拟 GPRS 连接，使用的 50kbps 流量，500 毫秒的 rtt.
window.webContents.session.enableNetworkEmulation({
  latency: 500,
  downloadThroughput: 6400,
  uploadThroughput: 6400
})

// 模拟网络故障.
window.webContents.session.enableNetworkEmulation({offline: true})

`ses.disableNetworkEmulation()`

停止所有已经使用session的活跃模拟网络. 重置为原始网络类型.

`ses.setCertificateVerifyProc(proc)`

procFunction

为session设置证书验证过程，当请求一个服务器的证书验证时，使用proc(hostname, certificate, callback)调用proc.调用callback(true)来接收证书，调用callback(false)来拒绝验证证书.

调用了setCertificateVerifyProc(null)，则将会回复到默认证书验证过程.

myWindow.webContents.session.setCertificateVerifyProc(function (hostname, cert, callback) {
  callback(hostname === 'github.com')
})

`ses.setPermissionRequestHandler(handler)`

handlerFunction
- webContentsObject -WebContents请求许可.
- permissionString - 枚举了 'media', 'geolocation', 'notifications', 'midiSysex', 'pointerLock', 'fullscreen'.
- callbackFunction - 允许或禁止许可.

为对应session许可请求设置响应句柄.调用callback(true)接收许可，调用callback(false)禁止许可.

session.fromPartition(partition).setPermissionRequestHandler(function (webContents, permission, callback) {
  if (webContents.getURL() === host) {
    if (permission === 'notifications') {
      callback(false) // denied.
      return
    }
  }

  callback(true)
})

`ses.clearHostResolverCache([callback])`

callbackFunction (可选) - 操作结束调用.

清除主机解析缓存.

`ses.webRequest`

在其生命周期的不同阶段，webRequestAPI 设置允许拦截并修改请求内容.

每个 API 接收一可选的filter和listener，当 API 事件发生的时候使用listener(details)调用listener，details是一个用来描述请求的对象.为listener使用null则会退定事件.

filter是一个拥有urls属性的对象，这是一个 url 模式数组，这用来过滤掉不匹配指定 url 模式的请求.如果忽略filter，那么所有请求都将可以成功匹配.

所有事件的listener都有一个回调事件，当listener完成它的工作的时候，它将使用一个response对象来调用.

// 将所有请求的代理都修改为下列 url.
var filter = {
  urls: ['https://*.github.com/*', '*://electron.github.io']
}

session.defaultSession.webRequest.onBeforeSendHeaders(filter, function (details, callback) {
  details.requestHeaders['User-Agent'] = 'MyAgent'
  callback({cancel: false, requestHeaders: details.requestHeaders})
})

`ses.webRequest.onBeforeRequest([filter, ]listener)`

filterObject
listenerFunction

当一个请求即将开始的时候，使用listener(details, callback)调用listener.

detailsObject
- idInteger
- urlString
- methodString
- resourceTypeString
- timestampDouble
- uploadDataArray (可选)
callbackFunction

uploadData是一个data数组对象:

dataObject
- bytesBuffer - 被发送的内容.
- fileString - 上载文件路径.

callback必须使用一个response对象来调用:

responseObject
- cancelBoolean (可选)
- redirectURLString (可选) - 原始请求阻止发送或完成，而不是重定向.

`ses.webRequest.onBeforeSendHeaders([filter, ]listener)`

filterObject
listenerFunction

一旦请求报文头可用了,在发送 HTTP 请求的之前，使用listener(details, callback)调用listener.这也许会在服务器发起一个tcp 连接，但是在发送任何 http 数据之前发生.

detailsObject
- idInteger
- urlString
- methodString
- resourceTypeString
- timestampDouble
- requestHeadersObject
callbackFunction

必须使用一个response对象来调用callback:

responseObject
- cancelBoolean (可选)
- requestHeadersObject (可选) - 如果提供了,将使用这些 headers 来创建请求.

`ses.webRequest.onSendHeaders([filter, ]listener)`

filterObject
listenerFunction

在一个请求正在发送到服务器的时候，使用listener(details)来调用listener，之前onBeforeSendHeaders修改部分响应可用，同时取消监听.

detailsObject
- idInteger
- urlString
- methodString
- resourceTypeString
- timestampDouble
- requestHeadersObject

`ses.webRequest.onHeadersReceived([filter,] listener)`

filterObject
listenerFunction

当 HTTP 请求报文头已经到达的时候，使用listener(details, callback)调用listener.

detailsObject
- idString
- urlString
- methodString
- resourceTypeString
- timestampDouble
- statusLineString
- statusCodeInteger
- responseHeadersObject
callbackFunction

必须使用一个response对象来调用callback:

responseObject
- cancelBoolean
- responseHeadersObject (可选) - 如果提供, 服务器将假定使用这些头来响应.

`ses.webRequest.onResponseStarted([filter, ]listener)`

filterObject
listenerFunction

当响应body的首字节到达的时候，使用listener(details)调用listener.对 http 请求来说，这意味着状态线和响应头可用了.

detailsObject
- idInteger
- urlString
- methodString
- resourceTypeString
- timestampDouble
- responseHeadersObject
- fromCacheBoolean - 标识响应是否来自磁盘 cache.
- statusCodeInteger
- statusLineString

`ses.webRequest.onBeforeRedirect([filter, ]listener)`

filterObject
listenerFunction

当服务器的重定向初始化正要启动时，使用listener(details)调用listener.

detailsObject
- idString
- urlString
- methodString
- resourceTypeString
- timestampDouble
- redirectURLString
- statusCodeInteger
- ipString (可选) - 请求的真实服务器ip 地址
- fromCacheBoolean
- responseHeadersObject

`ses.webRequest.onCompleted([filter, ]listener)`

filterObject
listenerFunction

当请求完成的时候，使用listener(details)调用listener.

detailsObject
- idInteger
- urlString
- methodString
- resourceTypeString
- timestampDouble
- responseHeadersObject
- fromCacheBoolean
- statusCodeInteger
- statusLineString

`ses.webRequest.onErrorOccurred([filter, ]listener)`

filterObject
listenerFunction

当一个错误发生的时候，使用listener(details)调用listener.

detailsObject
- idInteger
- urlString
- methodString
- resourceTypeString
- timestampDouble
- fromCacheBoolean
- errorString - 错误描述.

session

session

方法

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

属性

session.defaultSession

Class: Session

实例事件

Event: 'will-download'

实例方法

`ses.cookies`

`ses.cookies.get(filter, callback)`

`ses.cookies.set(details, callback)`

`ses.cookies.remove(url, name, callback)`

`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.webRequest`

`ses.webRequest.onBeforeRequest([filter, ]listener)`

`ses.webRequest.onBeforeSendHeaders([filter, ]listener)`

`ses.webRequest.onSendHeaders([filter, ]listener)`

`ses.webRequest.onHeadersReceived([filter,] listener)`

`ses.webRequest.onResponseStarted([filter, ]listener)`

`ses.webRequest.onBeforeRedirect([filter, ]listener)`

`ses.webRequest.onCompleted([filter, ]listener)`

`ses.webRequest.onErrorOccurred([filter, ]listener)`

results matching ""

No results matching ""