跳转到主内容

session

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

Process: Main

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

You can also access the session of existing pages by using the session property of WebContents, or from the session module.

const { BrowserWindow } = require('electron')

const win = new BrowserWindow({ width: 800, height: 600 })
win.loadURL('https://github.com')

const ses = win.webContents.session
console.log(ses.getUserAgent())

方法​

session 模块具有以下方法:

session.fromPartition(partition[, options])​

  • partition string
  • options Object (可选)

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.fromPath(path[, options])​

  • path string
  • options Object (可选)

Returns Session - A session instance from the absolute path as specified by the path string. When there is an existing Session with the same absolute path, it will be returned; otherwise a new Session instance will be created with options. The call will throw an error if the path is not an absolute path. Additionally, an error will be thrown if an empty string is provided.

To create a Session with options, you have to ensure the Session with the path has never been used before. 没有办法修改一个已存在的Session对象的options。

属性​

session 模块具有以下方法:

session.defaultSession​

A Session object, the default session object of the app, available after app.whenReady is called.

类: Session​

获取和设置Session的属性。

Process: Main
This class is not exported from the 'electron' module. 它只能作为 Electron API 中其他方法的返回值。

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

const { session } = require('electron')

const ses = session.fromPartition('persist:name')
console.log(ses.getUserAgent())

实例事件​

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

Event: 'will-download'​

返回:

当 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('node:fs').writeFileSync('/somewhere', response.body)
  })
})

Event: 'extension-loaded'​

返回:

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

  • 扩展插件正在从 Session.loadExtension 中被加载
  • 扩展插件正在被重新加载：

Event: 'extension-unloaded'​

返回:

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

Event: 'extension-ready'​

返回:

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

Event: 'file-system-access-restricted'​

返回:

  • event Event
  • details Object
    • origin string - The origin that initiated access to the blocked path.
    • isDirectory boolean - Whether or not the path is a directory.
    • path string - The blocked path attempting to be accessed.
  • callback Function
    • action string - The action to take as a result of the restricted path access attempt.
      • allow - This will allow path to be accessed despite restricted status.
      • deny - This will block the access request and trigger an AbortError.
      • tryAgain - This will open a new file picker and allow the user to choose another path.
const { app, dialog, BrowserWindow, session } = require('electron')

async function createWindow () {
  const mainWindow = new BrowserWindow()

  await mainWindow.loadURL('https://buzzfeed.com')

  session.defaultSession.on('file-system-access-restricted', async (e, details, callback) => {
    const { origin, path } = details
    const { response } = await dialog.showMessageBox({
      message: `Are you sure you want ${origin} to open restricted path ${path}?`,
      title: 'File System Access Restricted',
      buttons: ['Choose a different folder', 'Allow', 'Cancel'],
      cancelId: 2
    })

    if (response === 0) {
      callback('tryAgain')
    } else if (response === 1) {
      callback('allow')
    } else {
      callback('deny')
    }
  })

  mainWindow.webContents.executeJavaScript(`
    window.showDirectoryPicker({
      id: 'electron-demo',
      mode: 'readwrite',
      startIn: 'downloads',
    }).catch(e => {
      console.log(e)
    })`, true
  )
}

app.whenReady().then(() => {
  createWindow()

  app.on('activate', () => {
    if (BrowserWindow.getAllWindows().length === 0) createWindow()
  })
})

app.on('window-all-closed', function () {
  if (process.platform !== 'darwin') app.quit()
})

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 | null - The frame initiating this event. May be null if accessed after the frame has either navigated or been destroyed.
  • 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 | null - The frame initiating this event. May be null if accessed after the frame has either navigated or been destroyed.

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

Event: 'hid-device-removed'​

返回:

  • event Event
  • details Object
    • device HIDDevice
    • frame WebFrameMain | null - The frame initiating this event. May be null if accessed after the frame has either navigated or been destroyed.

如果在 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'​

返回:

调用 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'​

返回:

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

Event: 'serial-port-removed'​

返回:

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

Event: 'serial-port-revoked'​

返回:

  • event Event
  • details Object
    • port SerialPort
    • frame WebFrameMain | null - The frame initiating this event. May be null if accessed after the frame has either navigated or been destroyed.
    • 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 | null - The frame initiating this event. May be null if accessed after the frame has either navigated or been destroyed.
  • callback Function
    • deviceId string (optional)

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

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'​

返回:

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'​

返回:

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 be cookies, filesystem, indexdb, localstorage, shadercache, websql, serviceworkers, cachestorage. 如果没有指定storages，将会清除所有的storages类型
    • quotas string[] (optional) - The types of quotas to clear, can be temporary. 如果没有指定，将会清除所有的quotas。

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

ses.flushStorageData()​

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

ses.setProxy(config)​

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

代理设置

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

ses.resolveHost(host, [options])​

  • host string - Hostname to resolve.
  • options Object (可选)
    • queryType string (optional) - Requested DNS query type. If unspecified, resolver will pick A or AAAA (or both) based on IPv4/IPv6 settings:
      • A - Fetch only A records
      • AAAA - Fetch only AAAA records.
    • source string (optional) - The source to use for resolved addresses. Default allows the resolver to pick an appropriate source. Only affects use of big external sources (e.g. calling the system for resolution or using DNS). Even if a source is specified, results can still come from cache, resolving "localhost" or IP literals, etc. 以下值之一：
      • any (default) - Resolver will pick an appropriate source. Results could come from DNS, MulticastDNS, HOSTS file, etc
      • system - Results will only be retrieved from the system or OS, e.g. via the getaddrinfo() system call
      • dns - Results will only come from DNS queries
      • mdns - Results will only come from Multicast DNS queries
      • localOnly - No external sources will be used. Results will only come from fast local sources that are available no matter the source setting, e.g. cache, hosts file, IP literal resolution, etc.
    • cacheUsage string (optional) - Indicates what DNS cache entries, if any, can be used to provide a response. 以下值之一：
      • allowed (default) - Results may come from the host cache if non-stale
      • staleAllowed - Results may come from the host cache even if stale (by expiration or network changes)
      • disallowed - Results will not come from the host cache.
    • secureDnsPolicy string (optional) - Controls the resolver's Secure DNS behavior for this request. 以下值之一：
      • allow (default)
      • disable

Returns Promise<ResolvedHost> - Resolves with the resolved IP addresses for the host.

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 模拟网络。

const win = new BrowserWindow()

// To emulate a GPRS connection with 50kbps throughput and 500 ms latency.
win.webContents.session.enableNetworkEmulation({
  latency: 500,
  downloadThroughput: 6400,
  uploadThroughput: 6400
})

// To emulate a network outage.
win.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.fetch(input[, init])​

Returns Promise<GlobalResponse> - see Response.

Sends a request, similarly to how fetch() works in the renderer, using Chrome's network stack. This differs from Node's fetch(), which uses Node.js's HTTP stack.

示例：

async function example () {
  const response = await net.fetch('https://my.app')
  if (response.ok) {
    const body = await response.json()
    // ... use the result.
  }
}

See also net.fetch(), a convenience method which issues requests from the default session.

See the MDN documentation for fetch() for more details.

局限性:

  • net.fetch() does not support the data: or blob: schemes.
  • The value of the integrity option is ignored.
  • The .type and .url values of the returned Response object are incorrect.

By default, requests made with net.fetch can be made to custom protocols as well as file:, and will trigger webRequest handlers if present. When the non-standard bypassCustomProtocolHandlers option is set in RequestInit, custom protocol handlers will not be called for this request. This allows forwarding an intercepted request to the built-in handler. webRequest handlers will still be triggered when bypassing custom protocols.

protocol.handle('https', (req) => {
  if (req.url === 'https://my-app.com') {
    return new Response('<body>my app</body>')
  } else {
    return net.fetch(req, { bypassCustomProtocolHandlers: true })
  }
})

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 Certificate
      • validatedCertificate Certificate
      • 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 requesting the permission. 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.
      • display-capture - Request access to capture the screen via the Screen Capture API.
      • fullscreen - Request control of the app's fullscreen state via the Fullscreen API.
      • geolocation - Request access to the user's location via the Geolocation API
      • idle-detection - Request access to the user's idle state via the IdleDetector API.
      • media - Request access to media devices such as camera, microphone and speakers.
      • mediaKeySystem - Request access to DRM protected content.
      • midi - Request MIDI access in the Web MIDI API.
      • midiSysex - Request the use of system exclusive messages in the Web MIDI API.
      • notifications - Request notification creation and the ability to display them in the user's system tray using the Notifications API
      • pointerLock - Request to directly interpret mouse movements as an input method via the Pointer Lock API. These requests always appear to originate from the main frame.
      • keyboardLock - Request capture of keypresses for any or all of the keys on the physical keyboard via the Keyboard Lock API. These requests always appear to originate from the main frame.
      • openExternal - Request to open links in external applications.
      • speaker-selection - Request to enumerate and select audio output devices via the speaker-selection permissions policy.
      • storage-access - Allows content loaded in a third-party context to request access to third-party cookies using the Storage Access API.
      • top-level-storage-access - Allow top-level sites to request third-party cookie access on behalf of embedded content originating from another site in the same related website set using the Storage Access API.
      • window-management - Request access to enumerate screens using the getScreenDetails API.
      • unknown - An unrecognized permission request.
      • fileSystem - Request access to read, write, and file management capabilities using the File System API.
    • callback Function
      • permissionGranted boolean - 允许或拒绝该权限.
    • details PermissionRequest | FilesystemPermissionRequest | MediaAccessPermissionRequest | OpenExternalPermissionRequest - Additional information about the permission being requested.

设置可用于响应 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.
      • clipboard-read - Request access to read from the clipboard.
      • clipboard-sanitized-write - Request access to write to the clipboard.
      • geolocation - Access the user's geolocation data via the Geolocation API
      • fullscreen - Control of the app's fullscreen state via the Fullscreen API.
      • hid - Access the HID protocol to manipulate HID devices via the WebHID API.
      • idle-detection - Access the user's idle state via the IdleDetector API.
      • media - Access to media devices such as camera, microphone and speakers.
      • mediaKeySystem - Access to DRM protected content.
      • midi - Enable MIDI access in the Web MIDI API.
      • midiSysex - Use system exclusive messages in the Web MIDI API.
      • notifications - Configure and display desktop notifications to the user with the Notifications API.
      • openExternal - Open links in external applications.
      • pointerLock - Directly interpret mouse movements as an input method via the Pointer Lock API. These requests always appear to originate from the main frame.
      • serial - Read from and write to serial devices with the Web Serial API.
      • storage-access - Allows content loaded in a third-party context to request access to third-party cookies using the Storage Access API.
      • top-level-storage-access - Allow top-level sites to request third-party cookie access on behalf of embedded content originating from another site in the same related website set using the Storage Access API.
      • usb - Expose non-standard Universal Serial Bus (USB) compatible devices services to the web with the WebUSB API.
      • deprecated-sync-clipboard-read Deprecated - Request access to run document.execCommand("paste")
      • fileSystem - Access to read, write, and file management capabilities using the File System API.
    • 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.
      • filePath string (optional) - The path of a fileSystem request.
      • isDirectory boolean (optional) - Whether a fileSystem request is a directory.
      • fileAccessType string (optional) - The access type of a fileSystem request. 可以是 writable 或 readable。

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('node:url')

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

  return false // denied
})
note

isMainFrame will always be false for a fileSystem request as a result of Chromium limitations.

ses.setDisplayMediaRequestHandler(handler[, opts])​

  • handler Function | null
    • request Object
      • frame WebFrameMain | null - Frame that is requesting access to media. May be null if accessed after the frame has either navigated or been destroyed.
      • 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.
        • enableLocalEcho Boolean (optional) - If audio is a WebFrameMain and this is set to true, then local playback of audio will not be muted (e.g. using MediaRecorder to record WebFrameMain with this flag set to true will allow audio to pass through to the speakers while recording). 默认值为 false.
  • opts Object (optional) macOS Experimental
    • useSystemPicker Boolean - true if the available native system picker should be used. 默认值为 false. macOS Experimental

This handler will be called when web content requests access to display media via the navigator.mediaDevices.getDisplayMedia API. Use the