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

<h2 id="methods">方法</h2>

session模块有以下方法：

<h3 id="session-fromPartition"><code>session.fromPartition(partition[, options])</code></h3>

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

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

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

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

<h2 id="properties">属性</h2>

session模块有以下属性：

<h3 id="session-defaultSession"><code>session.defaultSession</code></h3>

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

<h2 id="class-session">类：Session</h2>

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

进程：主进程

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

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

<h3 id="instance-events">实例的事件</h3>

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

<h4 id="event-will-download">事件：'will-download'</h4>

当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)
    })
})

<h3 id="instance-methods">实例的方法</h3>

以下方法在Session的实例中有效：

<h4 id="ses-getCacheSize"><code>ses.getCacheSize(callback)</code></h4>

  • callback Function类型
    • size Integer类型 - 使用的缓存大小，以字节为单位。

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

<h4 id="ses-clearCache"><code>ses.clearCache(callback)</code></h4>

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

清空会话的HTTP缓存。

<h4 id="ses-clearStorageData"><code>ses.clearStorageData([options, callback])</code></h4>

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

清除网络存储数据。

<h4 id="ses-flushStorageData"><code>ses.flushStorageData()</code></h4>

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

<h4 id="ses-setProxy"><code>ses.setProxy(config, callback)</code></h4>

  • config Object类型
    • pacScript String类型 - 与PAC文件相关的URL。
    • proxyRules String类型 - 规定要使用的代理的标志。
    • proxyBypassRules String类型 - 规定需要绕过代理设置的URL的标志。
  • 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>]

例如：

  • 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 [ ":" <port> ]

    匹配所有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".

  • <local>

    匹配本地地址。<local>的意思是匹配到这之中的任何一个："127.0.0.1"，"::1"，"localhost"。

<h4 id="ses-resolveProxy"><code>ses.resolveProxy(url, callback)</code></h4>

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

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

<h4 id="ses-setDownloadPath"><code>ses.setDownloadPath(path)</code></h4>

  • path String类型 - 下载位置

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

<h4 id="ses-enableNetworkEmulation"><code>ses.enableNetworkEmulation(options)</code></h4>

  • 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})

<h4 id="ses-disableNetworkEmulation"><code>ses.disableNetworkEmulation()</code></h4>

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

<h4 id="ses-setCertificateVerifyProc"><code>ses.setCertificateVerifyProc(proc)</code></h4>

  • 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)
    }
})

<h4 id="ses-setPermissionRequestHandler"><code>ses.setPermissionRequestHandler(handler)</code></h4>

  • 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)
})

<h4 id="ses-clearHostResolverCache"><code>ses.clearHostResolverCache([callback])</code></h4>

  • callback Function类型（可选参数）- 当操作完成时被调用。

清空主机解析器的缓存。

<h4 id="ses-allowNTLMCredentialsForDomains"><code>ses.allowNTLMCredentialsForDomains(domains)</code></h4>

  • 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('*')

<h4 id="ses-setUserAgent"><code>ses.setUserAgent(userAgent[, acceptLanguages])</code></h4>

  • userAgent String类型
  • acceptLanguages String类型（可选参数）

重写这个会话的userAgent和acceptLanguages。

acceptLanguages必须是一个逗号分隔的语言代码的命令列表，例如："en-US,fr,de,ko,zh-CN,ja"。

这个不能影响到当前存在的WebContents，每个WebContents可以使用webContents.setUserAgent来重写会话范围内的用户代理。

<h4 id="ses-getUserAgent"><code>ses.getUserAgent()</code></h4>

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

<h4 id="ses-getBlobData"><code>ses.getBlobData(identifier, callback)</code></h4>

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

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

<h4 id="ses-createInterruptedDownload"><code>ses.createInterruptedDownload(options)</code></h4>

  • 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接口时启动。

<h4 id="ses-clearAuthCache"><code>ses.clearAuthCache(options[, callback])</code></h4>

清空会话的HTTP验证缓存。

<h3 id="instance-properties">实例的属性</h3>

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

<h4 id="ses-cookies"><code>ses.cookies</code></h4>

这个会话的Cookie对象。

<h4 id="ses-webRequest"><code>ses.webRequest</code></h4>

这个会话的WebRequest对象。

<h4 id="ses-protocol"><code>ses.protocol</code></h4>

这个会话的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')
    })
})
最后编辑于 ：
©著作权归作者所有,转载或内容合作请联系作者
  • 人面猴
    序言：七十年代末，一起剥皮案震惊了整个滨河市，随后出现的几起案子，更是在滨河造成了极大的恐慌，老刑警刘岩，带你破解...
    沈念sama阅读 204,684评论 6赞 478
  • 死咒
    序言：滨河连续发生了三起死亡事件，死亡现场离奇诡异，居然都是意外死亡，警方通过查阅死者的电脑和手机，发现死者居然都...
    沈念sama阅读 87,143评论 2赞 381
  • 救了他两次的神仙让他今天三更去死
    文/潘晓璐 我一进店门，熙熙楼的掌柜王于贵愁眉苦脸地迎上来，“玉大人，你说我怎么就摊上这事。” “怎么了？”我有些...
    开封第一讲书人阅读 151,214评论 0赞 337
  • 道士缉凶录：失踪的卖姜人
    文/不坏的土叔 我叫张陵，是天一观的道长。 经常有香客问我，道长，这世上最难降的妖魔是什么？ 我笑而不...
    开封第一讲书人阅读 54,788评论 1赞 277
  • 港岛之恋（遗憾婚礼）
    正文 为了忘掉前任，我火速办了婚礼，结果婚礼上，老公的妹妹穿的比我还像新娘。我一直安慰自己，他们只是感情好，可当我...
    茶点故事阅读 63,796评论 5赞 368
  • 恶毒庶女顶嫁案：这布局不是一般人想出来的
    文/花漫 我一把揭开白布。 她就那样静静地躺着，像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上，一...
    开封第一讲书人阅读 48,665评论 1赞 281
  • 城市分裂传说
    那天，我揣着相机与录音，去河边找鬼。 笑死，一个胖子当着我的面吹牛，可吹牛的内容都是我干的。 我是一名探鬼主播，决...
    沈念sama阅读 38,027评论 3赞 399
  • 双鸳鸯连环套：你想象不到人心有多黑
    文/苍兰香墨 我猛地睁开眼，长吁一口气：“原来是场噩梦啊……” “哼！你这毒妇竟也来了？” 一声冷哼从身侧响起，我...
    开封第一讲书人阅读 36,679评论 0赞 258
  • 万荣杀人案实录
    序言：老挝万荣一对情侣失踪，失踪者是张志新（化名）和其女友刘颖，没想到半个月后，有当地人在树林里发现了一具尸体，经...
    沈念sama阅读 41,346评论 1赞 299
  • 护林员之死
    正文 独居荒郊野岭守林人离奇死亡，尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 35,664评论 2赞 321
  • 白月光启示录
    正文 我和宋清朗相恋三年，在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 37,766评论 1赞 331
  • 活死人
    序言：一个原本活蹦乱跳的男人离奇死亡，死状恐怖，灵堂内的尸体忽然破棺而出，到底是诈尸还是另有隐情，我是刑警宁泽，带...
    沈念sama阅读 33,412评论 4赞 321
  • 日本核电站爆炸内幕
    正文 年R本政府宣布，位于F岛的核电站，受9级特大地震影响，放射性物质发生泄漏。R本人自食恶果不足惜，却给世界环境...
    茶点故事阅读 39,015评论 3赞 307
  • 男人毒药：我在死后第九天来索命
    文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹，春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 29,974评论 0赞 19
  • 一桩弑父案，背后竟有这般阴谋
    文/苍兰香墨 我抬头看了看天上的太阳。三九已至，却和暖如春，着一层夹袄步出监牢的瞬间，已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 31,203评论 1赞 260
  • 情欲美人皮
    我被黑心中介骗来泰国打工， 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留，地道东北人。 一个月前我还...
    沈念sama阅读 45,073评论 2赞 350
  • 代替公主和亲
    正文 我出身青楼，却偏偏与公主长得像，于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子，可洞房花烛夜当晚...
    茶点故事阅读 42,501评论 2赞 343

推荐阅读更多精彩内容

  • 17. webContents
    原文：https://github.com/electron/electron/blob/master/docs/...
    Shmily落墨阅读 6,089评论 0赞 1
  • 3. BrowserWindow
    原文：https://github.com/electron/electron/blob/master/docs/...
    Shmily落墨阅读 18,992评论 1赞 5
  • Spring Cloud
    Spring Cloud为开发人员提供了快速构建分布式系统中一些常见模式的工具（例如配置管理，服务发现，断路器，智...
    卡卡罗2017阅读 134,596评论 18赞 139
  • NodeJS 官方文档v5.3.0 学习笔记
    https://nodejs.org/api/documentation.html 工具模块 Assert 测试 ...
    KeKeMars阅读 6,301评论 0赞 6
  • 抒怀
    发枯容颜素， 天高人自矮。 老来贫病消磨， 回忆多悲哀。 惭愧岁月蹉跎， 半世江湖义气， 无语诉情怀。 青春几万里...
    曹焕甫阅读 237评论 0赞 0