session

管理浏览器会话、cookie、缓存、代理设置等。

进程：主进程

session 模块可用于创建新的 session 对象。

你还可以使用WebContents的session属性或 session模块访问现有页的session

const { BrowserWindow } = require('electron')
const 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 - 是否启用缓存。

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的属性。

Process: Main
此类不从 'electron' 模块导出. 它只能作为 Electron API 中其他方法的返回值。

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

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

实例事件

以下事件会在Session实例触发。

Event: ‘will-download’

返回:

• event Event
• item DownloadItem
• webContents WebContents

当 Electron 刚要在webContents中下载item的时候触发。

调用event.preventDefault()方法，将会停止下载，并且在进程的next tick中，item将不再可用。

const { session } = require('electron')
session.defaultSession.on('will-download', (event, item, webContents) => {
  event.preventDefault()
  require('got')(item.getURL()).then((response) => {
    require('fs').writeFileSync('/somewhere', response.body)
  })
})

Event: ‘extension-loaded’

返回:

• event Event
• extension 扩展插件

在扩展插件加载完成后触发。 当一个扩展插件被添加到 “enabled” 的扩展插件集合内部时， 将自动触发 这包括：

• 扩展插件正在从 Session.loadExtension 中被加载
• 扩展插件正在被重新加载：
  • 由于崩溃
  • 扩展插件被请求重新载入 (chrome.runtime.reload()).

Event: ‘extension-unloaded’

返回:

• event Event
• extension 扩展插件

当一个扩展插件被卸载后触发。 当 Session.removeExtension 被调用时也会触发。

Event: ‘extension-ready’

返回:

• event Event
• extension 扩展插件

当一个扩展插件加载完成，同时所有必要的浏览器状态也初始化完毕，允许启动插件背景页面时， 将触发此事件。

Event: ‘preconnect’

返回:

• event Event
• preconnectUrl string - 渲染进程进行预连接时请求的 URL
• allowCredentials boolean - 为 true 代表渲染进程要求此连接包含 credentials 信息（详见此 规范）

当渲染进程已经预链接到 URL 后将触发此事件, 通常用于 资源加载 提醒

Event: ‘spellcheck-dictionary-initialized’

返回:

• event Event
• languageCode string - 字典文件的语言代码

当一个hunspell字典初始化成功时触发。 这个事件在文件被下载之后触发。

Event: ‘spellcheck-dictionary-download-begin’

返回:

• event Event
• languageCode string - 字典文件的语言代码

当 hunspell 字典文件开始下载时触发

Event: ‘spellcheck-dictionary-download-success’

返回:

• event Event
• languageCode string - 字典文件的语言代码

当 hunspell 字典文件下载成功触发

Event: ‘spellcheck-dictionary-download-failure’

返回:

• event Event
• languageCode string - 字典文件的语言代码

当hunspell字典下载失败时触发。 如果需要详细信息，你应当查看网络日志并且检查下载请求。

Event: ‘select-hid-device’

返回:

• event Event
• details Object
  • deviceList HIDDevice[]
  • frame WebFrameMain
• callback Function
  • deviceId string | null (optional)

调用 navigator.hid.requestDevice 并要求选择一个输入设备时，会触发此事件。 需在选中 deviceId 后调用 callback 函数；不向 callback 传参代表取消此次请求。 此外，还可通过 ses.setPermissionCheckHandler(handler) 和 ses.setDevicePermissionHandler(handler) 来进一步管理对 navigator.hid 的授权。

const { app, BrowserWindow } = require('electron')
let win = null
app.whenReady().then(() => {
  win = new BrowserWindow()
  win.webContents.session.setPermissionCheckHandler((webContents, permission, requestingOrigin, details) => {
    if (permission === 'hid') {
      // Add logic here to determine if permission should be given to allow HID selection
      return true
    }
    return false
  })
  // Optionally, retrieve previously persisted devices from a persistent store
  const grantedDevices = fetchGrantedDevices()
  win.webContents.session.setDevicePermissionHandler((details) => {
    if (new URL(details.origin).hostname === 'some-host' && details.deviceType === 'hid') {
      if (details.device.vendorId === 123 && details.device.productId === 345) {
        // Always allow this type of device (this allows skipping the call to `navigator.hid.requestDevice` first)
        return true
      }
      // Search through the list of devices that have previously been granted permission
      return grantedDevices.some((grantedDevice) => {
        return grantedDevice.vendorId === details.device.vendorId &&
              grantedDevice.productId === details.device.productId &&
              grantedDevice.serialNumber && grantedDevice.serialNumber === details.device.serialNumber
      })
    }
    return false
  })
  win.webContents.session.on('select-hid-device', (event, details, callback) => {
    event.preventDefault()
    const selectedDevice = details.deviceList.find((device) => {
      return device.vendorId === '9025' && device.productId === '67'
    })
    callback(selectedDevice?.deviceId)
  })
})

Event: ‘hid-device-added’

返回:

• event Event
• details Object
  • device HIDDevice[]
  • frame WebFrameMain

如果在 select-hid-device 回调被调用之前有新设备变为可用，会在 navigator.hid.requestDevice 被调用和 select-hid-device 触发后触发。 此事件用于使用 UI 让用户选择设备，以便可以使用新添加的设备更新 UI。

Event: ‘hid-device-removed’

返回:

• event Event
• details Object
  • device HIDDevice[]
  • frame WebFrameMain

如果在 select-hid-device 回调被调用之前有设备被移除，会在 navigator.hid.requestDevice 被调用和 select-hid-device 触发后触发。 此事件用于使用 UI 让用户选择设备，以便可以移除指定的设备来更新 UI。

Event: ‘hid-device-revoked’

返回:

• event Event
• details Object
  • device HIDDevice[]
  • origin string (optional) - 已被取消的设备。

当 HIDDevice.forget() 被调用后触发。 该事件被用于当 setDevicePermissionHandler 被使用时帮助维护权限的持久存储。

Event: ‘select-serial-port’

返回:

• event Event
• portList SerialPort[]
• webContents WebContents
• callback Function
  • portId string

调用 navigator.serial.requestPort 并选择一系列端口时触发此事件。 callback 方法将在portId 被选中后调用, 给callback 方法一个空字符串参数将取消请求。 此外， navigator.serial 的许可权可以通过使用 ses.setPermissionCheckHandler(handler) 来设置 serial 权限。

const { app, BrowserWindow } = require('electron')
let win = null
app.whenReady().then(() => {
  win = new BrowserWindow({
    width: 800,
    height: 600
  })
  win.webContents.session.setPermissionCheckHandler((webContents, permission, requestingOrigin, details) => {
    if (permission === 'serial') {
      // Add logic here to determine if permission should be given to allow serial selection
      return true
    }
    return false
  })
  // Optionally, retrieve previously persisted devices from a persistent store
  const grantedDevices = fetchGrantedDevices()
  win.webContents.session.setDevicePermissionHandler((details) => {
    if (new URL(details.origin).hostname === 'some-host' && details.deviceType === 'serial') {
      if (details.device.vendorId === 123 && details.device.productId === 345) {
        // Always allow this type of device (this allows skipping the call to `navigator.serial.requestPort` first)
        return true
      }
      // Search through the list of devices that have previously been granted permission
      return grantedDevices.some((grantedDevice) => {
        return grantedDevice.vendorId === details.device.vendorId &&
              grantedDevice.productId === details.device.productId &&
              grantedDevice.serialNumber && grantedDevice.serialNumber === details.device.serialNumber
      })
    }
    return false
  })
  win.webContents.session.on('select-serial-port', (event, portList, webContents, callback) => {
    event.preventDefault()
    const selectedPort = portList.find((device) => {
      return device.vendorId === '9025' && device.productId === '67'
    })
    if (!selectedPort) {
      callback('')
    } else {
      callback(selectedPort.portId)
    }
  })
})

Event: ‘serial-port-added’

返回:

• event Event
• port SerialPort
• webContents WebContents

如果在 select-serial-port 回调被调用之前有新端口变为可用，会在 navigator.serial.requestPort 被调用和 select-serial-port 触发后触发。 此事件用于使用 UI 让用户选择端口，以便可以使用新添加的端口更新 UI。

Event: ‘serial-port-removed’

返回:

• event Event
• port SerialPort
• webContents WebContents

如果在 select-serial-port 回调被调用之前有端口被移除，会在 navigator.serial.requestPort 被调用和 select-serial-port 触发后触发。 此事件用于使用 UI 让用户选择端口，以便可以移除指定的端口来更新 UI。

Event: ‘serial-port-revoked’

返回:

• event Event
• details Object
  • port SerialPort
  • frame WebFrameMain
  • origin string - The origin that the device has been revoked from.

Emitted after SerialPort.forget() has been called. This event can be used to help maintain persistent storage of permissions when setDevicePermissionHandler is used.

// Browser Process
const { app, BrowserWindow } = require('electron')
app.whenReady().then(() => {
  const win = new BrowserWindow({
    width: 800,
    height: 600
  })
  win.webContents.session.on('serial-port-revoked', (event, details) => {
    console.log(`Access revoked for serial device from origin ${details.origin}`)
  })
})

// Renderer Process
const portConnect = async () => {
  // Request a port.
  const port = await navigator.serial.requestPort()
  // Wait for the serial port to open.
  await port.open({ baudRate: 9600 })
  // ...later, revoke access to the serial port.
  await port.forget()
}

Event: ‘select-usb-device’

返回:

• event Event
• details Object
  • deviceList USBDevice[]
  • frame WebFrameMain
• callback Function
  • deviceId string (optional)

Emitted when a USB device needs to be selected when a call to navigator.usb.requestDevice is made. 需在选中 deviceId 后调用 callback 函数；不向 callback 传参代表取消此次请求。 Additionally, permissioning on navigator.usb can be further managed by using ses.setPermissionCheckHandler(handler) and ses.setDevicePermissionHandler(handler)`.

const { app, BrowserWindow } = require('electron')
let win = null
app.whenReady().then(() => {
  win = new BrowserWindow()
  win.webContents.session.setPermissionCheckHandler((webContents, permission, requestingOrigin, details) => {
    if (permission === 'usb') {
      // Add logic here to determine if permission should be given to allow USB selection
      return true
    }
    return false
  })
  // Optionally, retrieve previously persisted devices from a persistent store (fetchGrantedDevices needs to be implemented by developer to fetch persisted permissions)
  const grantedDevices = fetchGrantedDevices()
  win.webContents.session.setDevicePermissionHandler((details) => {
    if (new URL(details.origin).hostname === 'some-host' && details.deviceType === 'usb') {
      if (details.device.vendorId === 123 && details.device.productId === 345) {
        // Always allow this type of device (this allows skipping the call to `navigator.usb.requestDevice` first)
        return true
      }
      // Search through the list of devices that have previously been granted permission
      return grantedDevices.some((grantedDevice) => {
        return grantedDevice.vendorId === details.device.vendorId &&
              grantedDevice.productId === details.device.productId &&
              grantedDevice.serialNumber && grantedDevice.serialNumber === details.device.serialNumber
      })
    }
    return false
  })
  win.webContents.session.on('select-usb-device', (event, details, callback) => {
    event.preventDefault()
    const selectedDevice = details.deviceList.find((device) => {
      return device.vendorId === '9025' && device.productId === '67'
    })
    if (selectedDevice) {
      // Optionally, add this to the persisted devices (updateGrantedDevices needs to be implemented by developer to persist permissions)
      grantedDevices.push(selectedDevice)
      updateGrantedDevices(grantedDevices)
    }
    callback(selectedDevice?.deviceId)
  })
})

Event: ‘usb-device-added’

返回:

• event Event
• details Object
  • device USBDevice
  • frame WebFrameMain

Emitted after navigator.usb.requestDevice has been called and select-usb-device has fired if a new device becomes available before the callback from select-usb-device is called. 此事件用于使用 UI 让用户选择设备，以便可以使用新添加的设备更新 UI。

Event: ‘usb-device-removed’

返回:

• event Event
• details Object
  • device USBDevice
  • frame WebFrameMain

Emitted after navigator.usb.requestDevice has been called and select-usb-device has fired if a device has been removed before the callback from select-usb-device is called. 此事件用于使用 UI 让用户选择设备，以便可以移除指定的设备来更新 UI。

Event: ‘usb-device-revoked’

返回:

• event Event
• details Object
  • device USBDevice[]
  • origin string (optional) - 已被取消的设备。

Emitted after USBDevice.forget() has been called. 该事件被用于当 setDevicePermissionHandler 被使用时帮助维护权限的持久存储。

实例方法

在Session实例对象中，有以下方法:

ses.getCacheSize()

Returns Promise<Integer> - 当前 session 会话缓存大小，用 byte 字节作为单位。

ses.clearCache()

Returns Promise<void> - 当缓存清除操作完成时可获取

清除session的HTTP缓存。

ses.clearStorageData([options])

• options Object (可选)
  • origin string (可选) - 格式与 window.location.origin 相同 scheme://host:port
  • storages string[] (optional) - The types of storages to clear, can contain: cookies, filesystem, indexdb, localstorage, shadercache, websql, serviceworkers, cachestorage. 如果没有指定storages，将会清除所有的storages类型
  • quotas string[] (optional) - The types of quotas to clear, can contain: temporary, syncable. 如果没有指定，将会清除所有的quotas。

Returns Promise<void> - 当存储的数据已经被清理时可获得

ses.flushStorageData()

写入任何未写入DOMStorage数据到磁盘.

ses.setProxy(config)

• config Object
  • mode string (optional) - 代理模式。 可以是其中之一： direct, auto_detect, pac_script, fixed_servers 或 system。 如未指定，则根据其他选项自动判断
    • direct 在直接模式下，所有连接都是直接创建的，无需任何代理。
    • auto_detect 在auto_detect模式下，代理配置由 PAC 脚本决定，该脚本 可在 http://wpad/wpad.dat 下载。
    • pac_script 在 pac_script 模式中，代理配置由一个 PAC 脚本确定，它是 从 pacScript 中指定的 URL 中获取。 如果指定 pacScript 这是默认模式。
    • fixed_servers 在固定服务器模式下，代理配置在 proxyRules 中指定。 如果指定 proxyRules ，这是默认模式。
    • system 在系统模式下，代理配置取自操作系统。 请注意，系统模式不同于设置无代理配置。 在后一种情况下，只有当没有命令行选项影响代理配置时，Electron 才返回系统设置 。
  • pacScript string (optional) - 与 PAC 文件关联的 URL。
  • proxyRules string (optional) - 表明要使用的代理规则。
  • proxyBypassRules string (optional) - 表明哪些 url 应绕过代理设置的规则。

返回 Promise<void> - 代理设置进程完成。

代理设置

当 mode 未指定时， pacScript 和 proxyRules 一起提供， proxyRules 选项被忽略， pacScript 配置被应用。

您可能需要 ses.closeAllConnections 关闭当前在飞行连接，以防止使用以前代理服务器的集合套接口被未来请求重新使用。

proxyRules 要遵循以下规则:

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:80 for http:// URLs, and HTTP proxy foopy2:80 for ftp:// URLs.
• foopy:80 - Use HTTP proxy foopy:80 for all URLs.
• foopy:80,bar,direct:// - Use HTTP proxy foopy:80 for all URLs, failing over to bar if foopy:80 is unavailable, and after that using no proxy.
• socks4://foopy - Use SOCKS v4 proxy foopy:1080 for all URLs.
• http=foopy,socks5://bar.com - Use HTTP proxy foopy for http URLs, and fail over to the SOCKS5 proxy bar.com if foopy is unavailable.
• http=foopy,direct:// - Use HTTP proxy foopy for http URLs, and use no proxy if foopy is unavailable.
• http=foopy;socks=foopy2 - 对于http URL，用foopy作为HTTP协议代理，而其它所有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 地址文本的 url。

  例如: “127.0.1”, “[0:0::1]“, “[::1]“, “http://\[::1\]:99“

• IP_LITERAL "/" PREFIX_LENGTH_IN_BITS

  匹配任何在给定IP范围内失败的URL。 IP范围使用指定的CIDR。

  例如: “192.168.1.1/16”, “fefe:13::abc/33”.

• <local>

  匹配本地地址。 <local> 指”127.0.0.1”, “::1”, “localhost”的其中之一。

ses.resolveProxy(url)

• url URL

返回 Promise<string> - 使用 url 的代理信息解析。

ses.forceReloadProxyConfig()

返回 Promise<void> - 当代理服务的所有内部状态被重置并且最新的代理配置已经可用时重新应用时被解析。 如果代理模式为 pac_script ，将再次从 pacScript 获取 pac 脚本。

ses.setDownloadPath(path)

• path string - 下载目录。

设置下载目录 默认情况下, 下载目录将是相应应用程序文件夹下的 Downloads。

ses.enableNetworkEmulation(options)

• 选项 对象
  • offline boolean (optional) - Whether to emulate network outage. Defaults to false.
  • latency Double (optional) - RTT in ms. Defaults to 0 which will disable latency throttling.
  • downloadThroughput Double (optional) - Download rate in Bps. Defaults to 0 which will disable download throttling.
  • uploadThroughput Double (optional) - Upload rate in Bps. Defaults to 0 which will disable upload throttling.

通过指定的配置为 session 模拟网络。

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

• 选项 对象
  • url string - URL for preconnect. Only the origin is relevant for opening the socket.
  • numSockets number (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.closeAllConnections()

Returns Promise<void> - Resolves when all connections are closed.

Note: It will terminate / fail all requests currently in flight.

ses.disableNetworkEmulation()

Disables any network emulation already active for the session. Resets to the original network configuration.

ses.setCertificateVerifyProc(proc)

• proc Function | null
  • request Object
    • hostname string
    • certificate 证书
    • validatedCertificate 证书
    • isIssuedByKnownRoot boolean - true if Chromium recognises the root CA as a standard root. If it isn’t then it’s probably the case that this certificate was generated by a MITM proxy whose root has been installed locally (for example, by a corporate proxy). This should not be trusted if the verificationResult is not OK.
    • verificationResult string - OK if the certificate is trusted, otherwise an error like CERT_REVOKED.
    • errorCode Integer - 错误代码
  • callback Function
    • verificationResult Integer - Value can be one of certificate error codes from here. 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）将恢复为默认证书验证过程。

const { BrowserWindow } = require('electron')
const win = new BrowserWindow()
win.webContents.session.setCertificateVerifyProc((request, callback) => {
  const { hostname } = request
  if (hostname === 'github.com') {
    callback(0)
  } else {
    callback(-2)
  }
})

NOTE: The result of this procedure is cached by the network service.

ses.setPermissionRequestHandler(handler)

• handler Function | null
  • webContents WebContents - 请求权限的WebContents。 Please note that if the request comes from a subframe you should use requestingUrl to check the request origin.
  • permission string - The type of requested permission.
    • clipboard-read - Request access to read from the clipboard.
    • clipboard-sanitized-write - Request access to write to the clipboard.
    • media - Request access to media devices such as camera, microphone and speakers.
    • display-capture - Request access to capture the screen.
    • mediaKeySystem - Request access to DRM protected content.
    • geolocation - Request access to user’s current location.
    • notifications - Request notification creation and the ability to display them in the user’s system tray.
    • midi - Request MIDI access in the webmidi API.
    • midiSysex - Request the use of system exclusive messages in the webmidi API.
    • pointerLock - Request to directly interpret mouse movements as an input method. Click here to know more. These requests always appear to originate from the main frame.
    • fullscreen - Request for the app to enter fullscreen mode.
    • openExternal - Request to open links in external applications.
    • window-management - Request access to enumerate screens using the getScreenDetails API.
    • unknown - An unrecognized permission request
  • callback Function
    • permissionGranted boolean - 允许或拒绝该权限.
  • details Object - Some properties are only available on certain permission types.
    • externalURL string (optional) - The url of the openExternal request.
    • securityOrigin string (optional) - The security origin of the media request.
    • mediaTypes string[] (optional) - The types of media access being requested, elements can be video or audio
    • requestingUrl string - The last URL the requesting frame loaded
    • isMainFrame boolean - Whether the frame making the request is the main frame

设置可用于响应 session 的权限请求的处理程序。 调用 callback(true) 将允许该权限, 调用 callback(false) 将拒绝它。 若要清除处理程序, 请调用 setPermissionRequestHandler (null)。 Please note that you must also implement setPermissionCheckHandler to get complete permission handling. Most web APIs do a permission check and then make a permission request if the check is denied.

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)

• handler Function<boolean> | null
  • webContents (WebContents | null) - WebContents checking the permission. Please note that if the request comes from a subframe you should use requestingUrl to check the request origin. 所有进行权限检查的跨源子帧将传递一个 null 的 webContents 对象给此处理程序，而某些其他权限检查（如 notifications 检查）将始终传递一个 null。 You should use embeddingOrigin and requestingOrigin to determine what origin the owning frame and the requesting frame are on respectively.
  • permission string - Type of permission check. Valid values are midiSysex, notifications, geolocation, media,mediaKeySystem,midi, pointerLock, fullscreen, openExternal, hid, serial, or usb.
  • requestingOrigin string - The origin URL of the permission check
  • details Object - Some properties are only available on certain permission types.
    • embeddingOrigin string (optional) - The origin of the frame embedding the frame that made the permission check. Only set for cross-origin sub frames making permission checks.
    • securityOrigin string (optional) - The security origin of the media check.
    • mediaType string (optional) - The type of media access being requested, can be video, audio or unknown
    • requestingUrl string (optional) - The last URL the requesting frame loaded. This is not provided for cross-origin sub frames making permission checks.
    • isMainFrame boolean - 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 true will allow the permission and false will reject it. Please note that you must also implement setPermissionRequestHandler to get complete permission handling. Most web APIs do a permission check and then make a permission request if the check is denied. To clear the handler, call setPermissionCheckHandler(null).

const { session } = require('electron')
const url = require('url')
session.fromPartition('some-partition').setPermissionCheckHandler((webContents, permission, requestingOrigin) => {
  if (new URL(requestingOrigin).hostname === 'some-host' && permission === 'notifications') {
    return true // granted
  }
  return false // denied
})

ses.setDisplayMediaRequestHandler(handler)

• handler Function | null
  • request Object
    • frame WebFrameMain - Frame that is requesting access to media.
    • securityOrigin String - Origin of the page making the request.
    • videoRequested Boolean - true if the web content requested a video stream.
    • audioRequested Boolean - true if the web content requested an audio stream.
    • userGesture Boolean - Whether a user gesture was active when this request was triggered.
  • callback Function
    • streams Object
      • video Object | WebFrameMain (optional)
        • id String - The id of the stream being granted. This will usually come from a DesktopCapturerSource object.
        • name String - The name of the stream being granted. This will usually come from a DesktopCapturerSource object.
      • audio String | WebFrameMain (optional) - If a string is specified, can be loopback or loopbackWithMute. Specifying a loopback device will capture system audio, and is currently only supported on Windows. If a WebFrameMain is specified, will capture audio from that frame.

This handler will be called when web content requests access to display media via the navigator.mediaDevices.getDisplayMedia API. Use the desktopCapturer API to choose which stream(s) to grant access to.

const { session, desktopCapturer } = require('electron')
session.defaultSession.setDisplayMediaRequestHandler((request, callback) => {
  desktopCapturer.getSources({ types: ['screen'] }).then((sources) => {
    // Grant access to the first screen found.
    callback({ video: sources[0] })
  })
})

Passing a WebFrameMain object as a video or audio stream will capture the video or audio stream from that frame.

const { session } = require('electron')
session.defaultSession.setDisplayMediaRequestHandler((request, callback) => {
  // Allow the tab to capture itself.
  callback({ video: request.frame })
})

Passing null instead of a function resets the handler to its default state.

ses.setDevicePermissionHandler(handler)

• handler Function<boolean> | null
  • details Object
    • deviceType string - The type of device that permission is being requested on, can be hid, serial, or usb.
    • origin string - The origin URL of the device permission check.
    • device HIDDevice | SerialPort- the device that permission is being requested for.

Sets the handler which can be used to respond to device permission checks for the session. Returning true will allow the device to be permitted and false will reject it. To clear the handler, call setDevicePermissionHandler(null). This handler can be used to provide default permissioning to devices without first calling for permission to devices (eg via navigator.hid.requestDevice). If this handler is not defined, the default device permissions as granted through device selection (eg via navigator.hid.requestDevice) will be used. Additionally, the default behavior of Electron is to store granted device permision in memory. If longer term storage is needed, a developer can store granted device permissions (eg when handling the select-hid-device event) and then read from that storage with setDevicePermissionHandler.

const { app, BrowserWindow } = require('electron')
let win = null
app.whenReady().then(() => {
  win = new BrowserWindow()
  win.webContents.session.setPermissionCheckHandler((webContents, permission, requestingOrigin, details) => {
    if (permission === 'hid') {
      // Add logic here to determine if permission should be given to allow HID selection
      return true
    } else if (permission === 'serial') {
      // Add logic here to determine if permission should be given to allow serial port selection
    } else if (permission === 'usb') {
      // Add logic here to determine if permission should be given to allow USB device selection
    }
    return false
  })
  // Optionally, retrieve previously persisted devices from a persistent store
  const grantedDevices = fetchGrantedDevices()
  win.webContents.session.setDevicePermissionHandler((details) => {
    if (new URL(details.origin).hostname === 'some-host' && details.deviceType === 'hid') {
      if (details.device.vendorId === 123 && details.device.productId === 345) {
        // Always allow this type of device (this allows skipping the call to `navigator.hid.requestDevice` first)
        return true
      }
      // Search through the list of devices that have previously been granted permission
      return grantedDevices.some((grantedDevice) => {
        return grantedDevice.vendorId === details.device.vendorId &&
              grantedDevice.productId === details.device.productId &&
              grantedDevice.serialNumber && grantedDevice.serialNumber === details.device.serialNumber
      })
    } else if (details.deviceType === 'serial') {
      if (details.device.vendorId === 123 && details.device.productId === 345) {
        // Always allow this type of device (this allows skipping the call to `navigator.hid.requestDevice` first)
        return true
      }
    }
    return false
  })
  win.webContents.session.on('select-hid-device', (event, details, callback) => {
    event.preventDefault()
    const selectedDevice = details.deviceList.find((device) => {
      return device.vendorId === '9025' && device.productId === '67'
    })
    callback(selectedPort?.deviceId)
  })
})

ses.setBluetoothPairingHandler(handler) Windows Linux

• handler Function | null
  • details Object
    • deviceId string 设备Id
    • pairingKind string - The type of pairing prompt being requested. 以下值之一：
      • confirm This prompt is requesting confirmation that the Bluetooth device should be paired.
      • confirmPin This prompt is requesting confirmation that the provided PIN matches the pin displayed on the device.
      • providePin This prompt is requesting that a pin be provided for the device.
    • frame WebFrameMain
    • pin string (optional) - The pin value to verify if pairingKind is confirmPin.
  • callback Function
    • response Object
      • confirmed boolean - false should be passed in if the dialog is canceled. If the pairingKind is confirm or confirmPin, this value should indicate if the pairing is confirmed. If the pairingKind is providePin the value should be true when a value is provided.
      • pin string | null (optional) - When the pairingKind is providePin this value should be the required pin for the Bluetooth device.

Sets a handler to respond to Bluetooth pairing requests. This handler allows developers to handle devices that require additional validation before pairing. When a handler is not defined, any pairing on Linux or Windows that requires additional validation will be automatically cancelled. macOS does not require a handler because macOS handles the pairing automatically. To clear the handler, call setBluetoothPairingHandler(null).

const { app, BrowserWindow, ipcMain, session } = require('electron')
let bluetoothPinCallback = null
function createWindow () {
  const mainWindow = new BrowserWindow({
    webPreferences: {
      preload: path.join(__dirname, 'preload.js')
    }
  })
}
// Listen for an IPC message from the renderer to get the response for the Bluetooth pairing.
ipcMain.on('bluetooth-pairing-response', (event, response) => {
  bluetoothPinCallback(response)
})
mainWindow.webContents.session.setBluetoothPairingHandler((details, callback) => {
  bluetoothPinCallback = callback
  // Send a IPC message to the renderer to prompt the user to confirm the pairing.
  // Note that this will require logic in the renderer to handle this message and
  // display a prompt to the user.
  mainWindow.webContents.send('bluetooth-pairing-request', details)
})
app.whenReady().then(() => {
  createWindow()
})

ses.clearHostResolverCache()

Returns Promise<void> - Resolves when the operation is complete.

清除主机解析程序的缓存。

ses.allowNTLMCredentialsForDomains(domains)

• domains string - A comma-separated list of servers for which integrated authentication is enabled.

动态设置是否始终为 HTTP NTLM 发送凭据或协商身份验证。

const { session } = require('electron')
// consider any url ending with `example.com`, `foobar.com`, `baz`
// for integrated authentication.
session.defaultSession.allowNTLMCredentialsForDomains('*example.com, *foobar.com, *baz')
// 所有的 url 都可以用作身份验证
session.defaultSession.allowNTLMCredentialsForDomains('*')

ses.setUserAgent(userAgent[, acceptLanguages])

• userAgent string
• acceptLanguages string (optional)

覆盖当前会话的 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 webContents session of a BrowserWindow is 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.setSSLConfig(config)

• config Object
  • minVersion string (optional) - Can be tls1, tls1.1, tls1.2 or tls1.3. The minimum SSL version to allow when connecting to remote servers. Defaults to tls1.
  • maxVersion string (optional) - Can be tls1.2 or tls1.3. The maximum SSL version to allow when connecting to remote servers. Defaults to tls1.3.
  • disabledCipherSuites Integer[] (optional) - List of cipher suites which should be explicitly prevented from being used in addition to those disabled by the net built-in policy. Supported literal forms: 0xAABB, where AA is cipher_suite[0] and BB is cipher_suite[1], as defined in RFC 2246, Section 7.4.1.2. Unrecognized but parsable cipher suites in this form will not return an error. Ex: To disable TLS_RSA_WITH_RC4_128_MD5, specify 0x0004, while to disable TLS_ECDH_ECDSA_WITH_RC4_128_SHA, specify 0xC002. Note that TLSv1.3 ciphers cannot be disabled using this mechanism.

Sets the SSL configuration for the session. All subsequent network requests will use the new configuration. Existing network connections (such as WebSocket connections) will not be terminated, but old sockets in the pool will not be reused for new connections.

ses.getBlobData(identifier)

• identifier string - Valid UUID.

Returns Promise<Buffer> - resolves with blob data.

ses.downloadURL(url)

• url string

Initiates a download of the resource at url. The API will generate a DownloadItem that can be accessed with the will-download event.

Note: This does not perform any security checks that relate to a page’s origin, unlike webContents.downloadURL.

ses.createInterruptedDownload(options)

• 选项 对象
  • path string - Absolute path of the download.
  • urlChain string[] - Complete URL chain for the download.
  • mimeType string (optional)
  • offset Integer - 下载的开始范围.
  • length Integer - 下载的总长度。
  • lastModified string (可选) - Last-Modified 标头值。
  • eTag string (可选) - ETag 标头值。
  • startTime Double (optional) - 下载的时间是从 UNIX 时代以来的秒数开始的。

允许从上一个 Session 恢复 cancelled 或 interrupted 下载。 The API will generate a DownloadItem that can be accessed with the will-download event. The DownloadItem will not have any WebContents associated with it and the initial state will be interrupted. The download will start only when the resume API is called on the DownloadItem.

ses.clearAuthCache()

Returns Promise<void> - resolves when the session’s HTTP authentication cache has been cleared.

ses.setPreloads(preloads)

• preloads string[] - An array of absolute path to preload scripts

Adds scripts that will be executed on ALL web contents that are associated with this session just before normal preload scripts run.

ses.getPreloads()

Returns string[] an array of paths to preload scripts that have been registered.

ses.setCodeCachePath(path)

• path String - Absolute path to store the v8 generated JS code cache from the renderer.

Sets the directory to store the generated JS code cache for this session. The directory is not required to be created by the user before this call, the runtime will create if it does not exist otherwise will use the existing directory. If directory cannot be created, then code cache will not be used and all operations related to code cache will fail silently inside the runtime. By default, the directory will be Code Cache under the respective user data folder.

ses.clearCodeCaches(options)

• 选项 对象
  • urls String[] (optional) - An array of url corresponding to the resource whose generated code cache needs to be removed. If the list is empty then all entries in the cache directory will be removed.

Returns Promise<void> - resolves when the code cache clear operation is complete.

ses.setSpellCheckerEnabled(enable)

• enable boolean

设置是否启用内置拼写检查器。

ses.isSpellCheckerEnabled()

返回 boolean - 内置拼写检查是否启用。

ses.setSpellCheckerLanguages(languages)

• languages string[] - 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.availableSpellCheckerLanguages property.

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 its own list of languages. On macOS, this API will return whichever languages have been configured by the OS.

ses.setSpellCheckerDictionaryDownloadURL(url)

• url string - 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.zip file with each release which contains the files you need to host here.

The file server must be case insensitive. If you cannot do this, you must upload each file twice: once with the case it has in the ZIP file and once with the filename as all lowercase.

If the files present in hunspell_dictionaries.zip are 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[, options])

• path string - Path to a directory containing an unpacked Chrome extension
• options Object (可选)
  • allowFileAccess boolean - Whether to allow the extension to read local files over file:// protocol and inject content scripts into file:// pages. This is required e.g. for loading devtools extensions on file:// URLs. 默认值为 false.

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.

const { app, session } = require('electron')
const path = require('path')
app.on('ready', async () => {
  await session.defaultSession.loadExtension(
    path.join(__dirname, 'react-devtools'),
    // allowFileAccess is required to load the devtools extension on file:// URLs.
    { allowFileAccess: true }
  )
  // Note that in order to use the React DevTools extension, you'll need to
  // download and unzip a copy of the extension.
})

此 API 不支持加载打包后 (.crx) 的扩展。

注意：此 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

卸载扩展。

注意：此 API 不能在 app 模块的 ready 事件被发出之前使用。

ses.getExtension(extensionId)

• extensionId string - 需要查询的扩展 ID

返回 Extension | null - 获取到的扩展。

注意：此 API 不能在 app 模块的 ready 事件被发出之前使用。

ses.getAllExtensions()

返回 Extension[] - 所有已加载扩展的列表。

注意：此 API 不能在 app 模块的 ready 事件被发出之前使用。

ses.getStoragePath()

Returns string | null - The absolute file system path where data for this session is persisted on disk. For in memory sessions this returns null.

实例属性

以下属性在Session实例上可用：

ses.availableSpellCheckerLanguages 只读

A string[] array which consists of all the known available spell checker languages. Providing a language code to the setSpellCheckerLanguages API that isn’t in this array will result in an error.

ses.spellCheckerEnabled

boolean 表示是否启用内置拼写检查器。

ses.storagePath 只读

A string | null indicating the absolute file system path where data for this session is persisted on disk. For in memory sessions this returns null.

ses.cookies 只读

Session中使用Cookies对象

ses.serviceWorkers 只读

Session中使用ServiceWorkers对象

ses.webRequest 只读

Session中使用WebRequest对象

ses.protocol 只读

Session中使用Protocol对象

const { app, session } = require('electron')
const path = require('path')
app.whenReady().then(() => {
  const protocol = session.fromPartition('some-partition').protocol
  if (!protocol.registerFileProtocol('atom', (request, callback) => {
    const url = request.url.substr(7)
    callback({ path: path.normalize(`${__dirname}/${url}`) })
  })) {
    console.error('Failed to register protocol')
  }
})

ses.netLog 只读

Session中使用NetLog对象

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