session | Electron 跳转到主内容 Electron 文档 应用开发接口（API） 博客 工具 * Electron Forge * Electron Fiddle 社区 * 治理 * 案例展示 * 资源 版本发布 中文 * English * Deutsch * Español * Français * 日本語 * Português * Русский * 中文 搜索 * Main Process 模块 * app * autoUpdater * BaseWindow * BrowserView * Deprecated * BrowserWindow * clipboard * contentTracing * crashReporter * desktopCapturer * dialog * globalShortcut * ImageView * inAppPurchase * ipcMain * Menu * MenuItem * MessageChannelMain * MessagePortMain * nativeImage * nativeTheme * net * netLog * 通知 * powerMonitor * powerSaveBlocker * process * protocol * pushNotifications * 安全存储 * screen * session * sharedTexture * ShareMenu * shell * systemPreferences * 触控板 * 系统托盘 * utilityProcess * webContents * WebContentsView * webFrameMain * View * Renderer Process 模块 * Utility Process Modules * 自定义 DOM 元素 * Chromium 和 Node.js * 类 * API 结构 * * Main Process 模块 * session 在本页面 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 (可选) * cache boolean - 是否启用缓存。 Default is true unless the --disable-http-cache switch is used. 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 (可选) * cache boolean - 是否启用缓存。 Default is true unless the --disable-http-cache switch is used. 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' ​ 返回: * 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 ( 'node:fs' ) . writeFileSync ( '/somewhere' , response . body ) } ) } ) Event: 'extension-loaded' ​ 返回: * event Event * extension Extension 在扩展插件加载完成后触发。 当一个扩展插件被添加到 "enabled" 的扩展插件集合内部时， 将自动触发 这包括： * 扩展插件正在从 Session.loadExtension 中被加载 * 扩展插件正在被重新加载： * 由于崩溃 * 扩展插件被请求重新载入 ( chrome.runtime.reload() ). Event: 'extension-unloaded' ​ 返回: * event Event * extension Extension 当一个扩展插件被卸载后触发。 当 Session.removeExtension 被调用时也会触发。 Event: 'extension-ready' ​ 返回: * event Event * extension Extension 当一个扩展插件加载完成，同时所有必要的浏览器状态也初始化完毕，允许启动插件背景页面时， 将触发此事件。 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' ​ 返回: * 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 | 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' ​ 返回: * event Event * device USBDevice * webContents WebContents 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 * device USBDevice * webContents WebContents 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 被使用时帮助维护权限的持久存储。 Event: 'select-webauthn-account' ​ 返回: * event Event * details Object * relyingPartyId string - The relying party identifier from the WebAuthn request. * accounts WebAuthnAccount[] * frame WebFrameMain | null - The frame initiating this event. May be null if accessed after the frame has either navigated or been destroyed. * callback Function * credentialId string | null (optional) Emitted when a call to navigator.credentials.get() resolves multiple discoverable WebAuthn credentials and the user must choose one. callback should be called with the credentialId of the selected account; passing no arguments — or a credentialId that does not match one of the provided accounts — will cancel the request and the page will receive a NotAllowedError . If no listener is registered for this event, the request is cancelled with the same error. The credential request remains pending until the listener invokes the callback, so always invoke it exactly once — typically from a try { … } finally { callback(…) } block. On macOS, the Touch ID platform authenticator surfaces accounts via this event once it has been configured with app.configureWebAuthn .