session
管理浏览器会话、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
Stringoptions
Object (optional)cache
Boolean - 是否可以使用缓存.
Returns Session
- 根据partition
字符串产生的session实例。 当这里已存在一个Session
具有相同的partition
, 它将被返回; 否则一个新的Session
实例将根据options
被创建。
如果 partition
以 persist:
开头, 该页面将使用持续的 session,并在所有页面生效,且使用同一个partition
. 如果没有 persist:
前缀, 页面将使用 in-memory session. 如果没有设置partition
,app 将返回默认的session。
要根据options
创建Session
,你需要确保Session
的partition
在之前从未被使用。 没有办法修改一个已存在的Session
对象的options
。
属性
session
模块具有以下方法:
session.defaultSession
一个Session
对象,该应用程序的默认session对象。
类: Session
获取和设置Session的属性。
进程:主进程
你可以创建一个 Session
对象在session
模块中。
const { session } = require('electron')
const ses = session.fromPartition('persist:name')
console.log(ses.getUserAgent())
实例事件
以下事件会在Session
实例触发。
Instance Events
返回:
event
Eventitem
DownloadItemwebContents
WebContents
当 Electron 刚要在webContents
中下载`item<0>的时候触发。
调用event.preventDefault()
方法,将会停止下载,并且在进程的next tick中,
item将不再可用。
```javascript
const { session } = require('electron')
session.defaultSession.on('will-download', (event, item, webContents) => {
event.preventDefault()
require('request')(item.getURL(), (data) => {
require('fs').writeFileSync('/somewhere', data)
})
})
```
#### Event: 'preconnect'
返回:
*
eventEvent
*
preconnectUrlString - The URL being requested for preconnection by the renderer.
*
allowCredentialsBoolean - True if the renderer is requesting that the connection include credentials (see the [spec](https://w3c.github.io/resource-hints/#preconnect) for more details.)
Emitted when a render process requests preconnection to a URL, generally due to a [resource hint](https://w3c.github.io/resource-hints/).
#### Event: 'spellcheck-dictionary-initialized'
返回:
*
eventEvent
*
languageCodeString - The language code of the dictionary file
Emitted when a hunspell dictionary file has been successfully initialized. This occurs after the file has been downloaded.
#### Event: 'spellcheck-dictionary-download-begin'
返回:
*
eventEvent
*
languageCodeString - The language code of the dictionary file
Emitted when a hunspell dictionary file starts downloading
#### Event: 'spellcheck-dictionary-download-success'
返回:
*
eventEvent
*
languageCodeString - The language code of the dictionary file
Emitted when a hunspell dictionary file has been successfully downloaded
#### Event: 'spellcheck-dictionary-download-failure'
返回:
*
eventEvent
*
languageCodeString - The language code of the dictionary file
Emitted when a hunspell dictionary file download fails. For details on the failure you should collect a netlog and inspect the download request.
### 实例方法
在
Session实例对象中,有以下方法:
####
ses.getCacheSize()Returns
Promise- the session's current cache size, in bytes.
####
ses.clearCache()Returns
Promise- resolves when the cache clear operation is complete.
清除session的HTTP缓存。
####
ses.clearStorageData([options])*
optionsObject (optional)
*
originString - (可选项) 这个值应该按照
window.location.origin的形式:
协议://主机名:端口方式设置。
*
storagesString[] (optional) - The types of storages to clear, can contain:
appcache,
cookies,
filesystem,
indexdb,
localstorage,
shadercache,
websql,
serviceworkers,
cachestorage. If not specified, clear all storage types.
*
quotasString[] - (可选项) 要清除的配额类型, 包含:
temporary,
persistent,
syncable。 If not specified, clear all quotas.
Returns
Promise- resolves when the storage data has been cleared.
####
ses.flushStorageData()写入任何未写入DOMStorage数据到磁盘.
####
ses.setProxy(config)*
configObject
*
pacScriptString (optional) - The URL associated with the PAC file.
*
proxyRulesString (optional) - Rules indicating which proxies to use.
*
proxyBypassRulesString (optional) - Rules indicating which URLs should bypass the proxy settings.
Returns
Promise- Resolves when the proxy setting process is complete.
代理设置
当
pacScript和
proxyRules一起提供时,
proxyRules选项会被忽略, 会使用
pacScript配置。
proxyRules要遵循以下规则:
```sh
proxyRules = schemeProxies[";"<schemeProxies>]
schemeProxies = [<urlScheme>"="]<proxyURIList>
urlScheme = "http" | "https" | "ftp" | "socks"
proxyURIList = <proxyURL>[","<proxyURIList>]
proxyURL = [<proxyScheme>"://"]<proxyHost>[":"<proxyPort>]
```
例如:
*
http=foopy:80;ftp=foopy2- Use HTTP proxy
foopy:80for
http://URLs, and HTTP proxy
foopy2:80for
ftp://URLs.
*
foopy:80- Use HTTP proxy
foopy:80for all URLs.
*
foopy:80,bar,direct://- Use HTTP proxy
foopy:80for all URLs, failing over to
barif
foopy:80is unavailable, and after that using no proxy.
*
socks4://foopy- Use SOCKS v4 proxy
foopy:1080for all URLs.
*
http=foopy,socks5://bar.com- Use HTTP proxy
foopyfor http URLs, and fail over to the SOCKS5 proxy
bar.comif
foopyis unavailable.
*
http=foopy,direct://- Use HTTP proxy
foopyfor http URLs, and use no proxy if
foopyis unavailable.
*
http=foopy;socks=foopy2- 对于http URL,用
foopy作为HTTP协议代理,而其它所有URL则用
socks4://foopy2协议。
proxyBypassRules是一个用逗号分隔的规则列表, 如下所述:
*
[ URL_SCHEME “://“ ] HOSTNAME_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 地址文本的 url。
例如: "127.0.1", "[0:0::1]", "[::1]", "http://[::1]:99"
*
IP_LITERAL “/“ PREFIX_LENGTH_IN_BITSMatch any URL that is to an IP literal that falls between the given range. IP range is specified using CIDR notation.
例如: "192.168.1.1/16", "fefe:13::abc/33".
*
Match local addresses. The meaning of
is whether the host matches one of: "127.0.0.1", "::1", "localhost".
####
ses.resolveProxy(url)*
urlURL
Returns
Promise- Resolves with the proxy information for
url.
####
ses.setDownloadPath(path)*
pathString - 下载地址.
Sets download saving directory. By default, the download directory will be the
Downloadsunder the respective app folder.
####
ses.enableNetworkEmulation(options)*
optionsObject
*
offlineBoolean (optional) - Whether to emulate network outage. 默认值为 false.
*
latencyDouble (optional) - RTT in ms. Defaults to 0 which will disable latency throttling.
*
downloadThroughputDouble (optional) - Download rate in Bps. Defaults to 0 which will disable download throttling.
*
uploadThroughputDouble (optional) - Upload rate in Bps. Defaults to 0 which will disable upload throttling.
通过指定的配置为
session模拟网络。
```javascript
// 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.preconnect(options)*
optionsObject
*
urlString - URL for preconnect. Only the origin is relevant for opening the socket.
*
numSocketsNumber (optional) - number of sockets to preconnect. Must be between 1 and 6. Defaults to 1.
Preconnects the given number of sockets to an origin.
####
ses.disableNetworkEmulation()Disables any network emulation already active for the
session. Resets to the original network configuration.
####
ses.setCertificateVerifyProc(proc)*
procFunction | null
*
requestObject
*
hostnameString
*
certificate[证书](structures/certificate.md)
*
validatedCertificate[Certificate](structures/certificate.md)
*
verificationResultString - chromium证书验证结果
*
errorCodeInteger - 错误代码
*
callbackFunction
*
verificationResultInteger - 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- 表示成功并禁用证书透明度验证
*
-2- 表示失败
*
-3- 使用chromium的验证结果
每当一个服务器证书请求验证,
proc将被这样
proc(request, callback)调用,为
session设置证书验证过程。 回调函数
callback(0)接受证书,
callback(-2)驳回证书。
调用
setCertificateVerifyProc(null)将恢复为默认证书验证过程。
```javascript
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)*
handlerFunction | null
*
webContents[WebContents]($api-web-contents.md) - 请求权限的WebContents。 Please note that if the request comes from a subframe you should use
requestingUrlto check the request origin.
*
permissionString - 枚举 'media', 'geolocation', 'notifications', 'midiSysex', 'pointerLock', 'fullscreen', 'openExternal'.
*
callbackFunction
*
permissionGrantedBoolean - 允许或拒绝该权限.
*
detailsObject - Some properties are only available on certain permission types.
*
externalURLString (optional) - The url of the
openExternalrequest.
*
mediaTypesString[] (optional) - The types of media access being requested, elements can be
videoor
audio*
requestingUrlString - The last URL the requesting frame loaded
*
isMainFrameBoolean - Whether the frame making the request is the main frame
设置可用于响应
session 的权限请求的处理程序。 调用
callback(true)将允许该权限, 调用
callback(false)将拒绝它。 若要清除处理程序, 请调用
setPermissionRequestHandler (null) 。
```javascript
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.setPermissionCheckHandler(handler)*
handlerFunction<Boolean> | null
*
webContents[WebContents]($api-web-contents.md) - WebContents checking the permission. Please note that if the request comes from a subframe you should use
requestingUrlto check the request origin.
*
permissionString - Enum of 'media'.
*
requestingOriginString - The origin URL of the permission check
*
detailsObject - Some properties are only available on certain permission types.
*
securityOriginString - The security orign of the
mediacheck.
*
mediaTypeString - The type of media access being requested, can be
video,
audioor
unknown*
requestingUrlString - The last URL the requesting frame loaded
*
isMainFrameBoolean - Whether the frame making the request is the main frame
Sets the handler which can be used to respond to permission checks for the
session. Returning
truewill allow the permission and
falsewill reject it. To clear the handler, call
setPermissionCheckHandler(null).
```javascript
const { session } = require('electron')
session.fromPartition('some-partition').setPermissionCheckHandler((webContents, permission) => {
if (webContents.getURL() === 'some-host' && permission === 'notifications') {
return false // denied
}
return true
})
```
####
ses.clearHostResolverCache()Returns
Promise- Resolves when the operation is complete.
清除主机解析程序的缓存。
####
ses.allowNTLMCredentialsForDomains(domains)*
domainsString - 一个逗号分隔的服务器列表, 用于收集已经启用身份验证的服务器。
动态设置是否始终为 HTTP NTLM 发送凭据或协商身份验证。
```javascript
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])*
userAgentString
*
acceptLanguagesString (可选)
覆盖当前会话的
userAgent和
acceptLanguages.
acceptLanguages必须是用逗号分隔的语言代码列表,例如
“en-US,fr,de,ko,zh-CN,ja”.
这不会影响现有的
WebContents, 并且每个
WebContents都可以使用
webContents.setUserAgent重写会话范围的user agent。
####
ses.isPersistent()Returns
Boolean- Whether or not this session is a persistent one. The default
webContentssession of a
BrowserWindowis persistent. When creating a session from a partition, session prefixed with
persist:will be persistent, while others will be temporary.
####
ses.getUserAgent()返回
String- 当前会话的 user agent.
####
ses.getBlobData(identifier)*
identifierString - 有效的 UUID.
Returns
Promise- resolves with blob data.
####
ses.downloadURL(url)*
urlString
Initiates a download of the resource at
url. The API will generate a [DownloadItem]($api-download-item.md) that can be accessed with the [will-download](#event-will-download) event.
**Note:** This does not perform any security checks that relate to a page's origin, unlike [
webContents.downloadURL]($api-web-contents.md#contentsdownloadurlurl).
####
ses.createInterruptedDownload(options)*
optionsObject
*
pathString - 下载的绝对路径.
*
urlChainString[] - 完整的 url 下载地址.
*
mimeTypeString (可选)
*
offsetInteger - 下载的开始范围.
*
lengthInteger - 下载的总长度。
*
lastModifiedString (optional) - Last-Modified header value.
*
eTagString (optional) - ETag header value.
*
startTimeDouble (optional) - 下载的时间是从 UNIX 时代以来的秒数开始的。
允许从上一个
Session恢复
cancelled 或
interrupted 下载。 该 API 将生成一个 [ DownloadItem ]($api-download-item.md), 可使用 [ will-download ](#event-will-download) 事件进行访问。 [ DownloadItem ]($api-download-item.md) 将不具有与之关联的任何
WebContents , 并且初始状态将为
interrupted 。 只有在 [ DownloadItem ]($api-download-item.md) 上调用
resume API 时, 才会启动下载。
####
ses.clearAuthCache()Returns
Promise- resolves when the session’s HTTP authentication cache has been cleared.
####
ses.setPreloads(preloads)*
preloadsString[] - 数组,该数组由所有需要进行预加载的脚本的绝对路径组成。
Adds scripts that will be executed on ALL web contents that are associated with this session just before normal
preloadscripts run.
####
ses.getPreloads()返回
String[]返回一个数组,这个数组由已经注册过的预加载脚本的路径组成。
####
ses.setSpellCheckerLanguages(languages)*
languagesString[] - An array of language codes to enable the spellchecker for.
The built in spellchecker does not automatically detect what language a user is typing in. In order for the spell checker to correctly check their words you must call this API with an array of language codes. You can get the list of supported language codes with the
ses.availableSpellCheckerLanguagesproperty.
**Note:** On macOS the OS spellchecker is used and will detect your language automatically. This API is a no-op on macOS.
####
ses.getSpellCheckerLanguages()Returns
String[]- An array of language codes the spellchecker is enabled for. If this list is empty the spellchecker will fallback to using
en-US. By default on launch if this setting is an empty list Electron will try to populate this setting with the current OS locale. This setting is persisted across restarts.
**Note:** On macOS the OS spellchecker is used and has it's own list of languages. This API is a no-op on macOS.
####
ses.setSpellCheckerDictionaryDownloadURL(url)*
urlString - A base URL for Electron to download hunspell dictionaries from.
By default Electron will download hunspell dictionaries from the Chromium CDN. If you want to override this behavior you can use this API to point the dictionary downloader at your own hosted version of the hunspell dictionaries. We publish a
hunspell_dictionaries.zipfile with each release which contains the files you need to host here, the file server must be **case insensitive** you must upload each file twice, once with the case it has in the ZIP file and once with the filename as all lower case.
If the files present in
hunspell_dictionaries.zipare available at
https://example.com/dictionaries/language-code.bdic` then you should call this api with ses.setSpellCheckerDictionaryDownloadURL('https://example.com/dictionaries/')
. Please note the trailing slash. The URL to the dictionaries is formed as ${url}${filename}
.
Note: On macOS the OS spellchecker is used and therefore we do not download any dictionary files. This API is a no-op on macOS.
#### ses.listWordsInSpellCheckerDictionary()
Returns Promise<String[]>
- An array of all words in app’s custom dictionary. Resolves when the full dictionary is loaded from disk.
#### ses.addWordToSpellCheckerDictionary(word)
word
String - The word you want to add to the dictionary
Returns Boolean
- Whether the word was successfully written to the custom dictionary. This API will not work on non-persistent (in-memory) sessions.
Note: On macOS and Windows 10 this word will be written to the OS custom dictionary as well
#### ses.removeWordFromSpellCheckerDictionary(word)
word
String - The word you want to remove from the dictionary
Returns Boolean
- Whether the word was successfully removed from the custom dictionary. This API will not work on non-persistent (in-memory) sessions.
Note: On macOS and Windows 10 this word will be removed from the OS custom dictionary as well
#### ses.loadExtension(path)
path
String - Path to a directory containing an unpacked Chrome extension
Returns Promise<Extension>
- resolves when the extension is loaded.
This method will raise an exception if the extension could not be loaded. If there are warnings when installing the extension (e.g. if the extension requests an API that Electron does not support) then they will be logged to the console.
Note that Electron does not support the full range of Chrome extensions APIs. See Supported Extensions APIs for more details on what is supported.
Note that in previous versions of Electron, extensions that were loaded would be remembered for future runs of the application. This is no longer the case: loadExtension
must be called on every boot of your app if you want the extension to be loaded.
js
const { app, session } = require('electron')
const path = require('path')
app.on('ready', async () => {
await session.defaultSession.loadExtension(path.join(__dirname, 'react-devtools'))
// Note that in order to use the React DevTools extension, you'll need to
// download and unzip a copy of the extension.
})
This API does not support loading packed (.crx) extensions.
注意: 该 API 不能在 app
模块的 ready
事件之前调用.
Note: Loading extensions into in-memory (non-persistent) sessions is not supported and will throw an error.
#### ses.removeExtension(extensionId)
extensionId
String - ID of extension to remove
Unloads an extension.
注意: 该 API 不能在 app
模块的 ready
事件之前调用.
#### ses.getExtension(extensionId)
extensionId
String - ID of extension to query
Returns Extension
| null
- The loaded extension with the given ID.
注意: 该 API 不能在 app
模块的 ready
事件之前调用.
#### ses.getAllExtensions()
Returns Extension[]
- A list of all loaded extensions.
*注意: 该 API 不能在 app
模块的 ready
事件之前调用.
### 实例属性
以下属性在` Session </ 0>实例上可用:
ses.availableSpellCheckerLanguages` Readonly
A String[]
array which consists of all the known available spell checker languages. Providing a language code to the setSpellCheckerLanaguages
API that isn’t in this array will result in an error.
ses.cookies
Readonly
A Cookies
object for this session.
ses.serviceWorkers
Readonly
A ServiceWorkers
object for this session.
ses.webRequest
Readonly
A WebRequest
object for this session.
ses.protocol
Readonly
A Protocol
object for this session.
const { app, session } = require('electron')
const path = require('path')
app.whenReady().then(() => {
const protocol = session.fromPartition('some-partition').protocol
protocol.registerFileProtocol('atom', (request, callback) => {
let url = request.url.substr(7)
callback({ path: path.normalize(`${__dirname}/${url}`) })
}, (error) => {
if (error) console.error('Failed to register protocol')
})
})
ses.netLog
Readonly
A NetLog
object for this session.
const { app, session } = require('electron')
app.whenReady().then(async () => {
const netLog = session.fromPartition('some-partition').netLog
netLog.startLogging('/path/to/net-log')
// After some network events
const path = await netLog.stopLogging()
console.log('Net-logs written to', path)
})