BrowserWindow | 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 模块 * BrowserWindow 在本页面 BrowserWindow 创建并控制浏览器窗口。 Process: Main 在 app 模块 emitted ready 事件之前，您不能使用此模块。 // 在主进程中. const { BrowserWindow } = require ( 'electron' ) const win = new BrowserWindow ( { width : 800 , height : 600 } ) // Load a remote URL win . loadURL ( 'https://github.com' ) // Or load a local HTML file win . loadFile ( 'index.html' ) 自定义窗口 ​ BrowserWindow 类暴露了各种方法来修改应用窗口的外观和行为。 For more details, see the Window Customization tutorial. 优雅地显示窗口 ​ 每次加载页面都是直接展示，用户突然就看到了，这不是一个好的本地应用使用体验 要使窗口显示时没有视觉闪烁，对于不同情况有两种解决方案。 使用 ready-to-show 事件 ​ 在加载页面时，渲染进程第一次完成绘制时，如果窗口还没有被显示，渲染进程会发出 ready-to-show 事件 。 在此事件后显示窗口将没有视觉闪烁： const { BrowserWindow } = require ( 'electron' ) const win = new BrowserWindow ( { show : false } ) win . once ( 'ready-to-show' , ( ) => { win . show ( ) } ) 这个事件通常在 did-finish-load 事件之后发出，但是页面有许多远程资源时，它可能会在 did-finish-load 之前发出事件。 请注意，使用此事件意味着渲染器会被认为是"可见的"并绘制，即使 show 是false。 如果您使用 paintWhenInitiallyHidden: false ，此事件将永远不会被触发。 设置 backgroundColor 属性 ​ 对于一个复杂的应用， ready-to-show 可能发出的太晚，会让应用感觉缓慢。 在这种情况下，建议立刻显示窗口，并使用接近应用程序背景的 backgroundColor const { BrowserWindow } = require ( 'electron' ) const win = new BrowserWindow ( { backgroundColor : '#2e2c29' } ) win . loadURL ( 'https://github.com' ) 请注意，即使对于使用 ready-to-show 事件的应用，仍建议 设置 backgroundColor ，以使应用感觉更接近原生。 一些包括 backgroundColor 的有效值的例子： const win = new BrowserWindow ( ) win . setBackgroundColor ( 'hsl(230, 100%, 50%)' ) win . setBackgroundColor ( 'rgb(255, 145, 145)' ) win . setBackgroundColor ( '#ff00a3' ) win . setBackgroundColor ( 'blueviolet' ) 有关这些颜色类型的有效选项，请参阅 win.setBackgroundColor 。 父子窗口 ​ 通过使用 parent 选项，你可以创建子窗口： const { BrowserWindow } = require ( 'electron' ) const top = new BrowserWindow ( ) const child = new BrowserWindow ( { parent : top } ) child . show ( ) top . show ( ) child 窗口将总是显示在 top 窗口的顶部. 模态窗口 ​ 模态窗口是禁用父窗口的子窗口。 要创建模态窗口，必须同时设置 parent 和 modal 属性： const { BrowserWindow } = require ( 'electron' ) const top = new BrowserWindow ( ) const child = new BrowserWindow ( { parent : top , modal : true , show : false } ) child . loadURL ( 'https://github.com' ) child . once ( 'ready-to-show' , ( ) => { child . show ( ) } ) 页面可见性 ​ 页面可见性 API 的工作方式如下: * 在所有平台上, 可见性状态与窗口是否隐藏/最小化相关。 * 此外, 在 macOS 上, 可见性状态还会跟踪窗口的遮挡状态。 如果窗口被另一个窗口完全遮挡了，可见性状态为 hidden . 在其他平台上，可见性状态只有在使用 win.hide() 使窗口最小化或者隐藏时才为 hidden * 如果创建 BrowserWindow 时带有 show: false 的参数, 最初的可见性状态将为 visible 尽管窗口实际上是隐藏的。 * 如果 backgroundThrottling 被禁用，可见性状态将保持为 visible 即使窗口被最小化、遮挡或隐藏。 推荐您在可见性状态为 hidden 时暂停消耗资源的操作以便减少电力消耗。 平台相关的提示 ​ * 在 macOS 上，modal 窗口将显示为附加到父窗口的工作表。 * 在 macOS 上，子窗口将保持与父窗口的相对位置。而在 Windows 和 Linux 中，当父窗口移动时子窗口不会移动。 * 在Linux上，模态窗口的类型将更改为 dialog . * 在Linux上，许多桌面环境不支持隐藏模态窗口。 * On Wayland (Linux) it is generally not possible to programmatically resize windows after creation, or to position, move, focus, or blur windows without user input. If your app needs these capabilities, run it in Xwayland by appending the flag --ozone-platform=x11 . Class: BrowserWindow extends BaseWindow ​ 创建并控制浏览器窗口。 Process: Main BrowserWindow 是一个 EventEmitter 。 通过 options 可以创建一个具有原生属性的 BrowserWindow 。 [!WARNING] Electron's built-in classes cannot be subclassed in user code. For more information, see the FAQ . new BrowserWindow([options]) ​ * options BrowserWindowConstructorOptions (optional) * webPreferences WebPreferences （可选）—— 网页功能设置 * devTools boolean (可选) - 是否开启 DevTools. 如果设置为 false , 则无法使用 BrowserWindow.webContents.openDevTools () 打开 DevTools。 默认值为 true 。 * nodeIntegration boolean (可选) - 是否启用Node integration. 默认值为 false . * nodeIntegrationInWorker boolean (可选) - 是否在Web工作器中启用了Node集成. 默认值为 false . More about this can be found in Multithreading . * nodeIntegrationInSubFrames boolean (可选项)(实验性)，是否允许在子页面(iframe)或子窗口(child window)中集成Node.js； 预先加载的脚本会被注入到每一个iframe，你可以用 process.isMainFrame 来判断当前是否处于主框架（main frame）中。 * preload string (可选) -在页面运行其他脚本之前预先加载指定的脚本 无论页面是否集成Node, 此脚本都可以访问所有Node API 脚本路径为文件的绝对路径。 当 node integration 关闭时, 预加载的脚本将从全局范围重新引入node的全局引用标志 See example here . * sandbox boolean (可选)-如果设置该参数, 沙箱的渲染器将与窗口关联, 使它与Chromium OS-level 的沙箱兼容, 并禁用 Node. js 引擎。 它与 nodeIntegration 的选项不同，且预加载脚本的 API 也有限制. Default is true since Electron 20. The sandbox will automatically be disabled when nodeIntegration is set to true . Read more about the option here . * session Session (optional) - Sets the session used by the page. 而不是直接忽略 Session 对象, 也可用 partition 选项来代替，它接受一个 partition 字符串. 同时设置了 session 和 partition 时, session 的优先级更高. 默认使用默认的 session. * partition string (optional) - 通过 session 的 partition 字符串来设置界面session. 如果 partition 以 persist: 开头, 该页面将使用持续的 session，并在所有页面生效，且使用同一个 partition . 如果没有 persist: 前缀, 页面将使用 in-memory session. 通过分配相同的 partition , 多个页可以共享同一会话。 默认使用默认的 session. * zoomFactor number (可选) - 页面的默认缩放系数, 3.0 表示 300% 。 默认值为 1.0 . * javascript boolean (可选) - 是否启用 JavaScript 支持。 默认值为 true 。 * webSecurity boolean (optional) - When false , it will disable the same-origin policy (usually using testing websites by people), and set allowRunningInsecureContent to true if this option has not been set by user. 默认值为 true 。 * allowRunningInsecureContent boolean (可选) - 允许一个 https 页面运行来自http url的JavaScript, CSS 或 plugins。 默认值为 false . * images boolean (可选) - 允许加载图片。 默认值为 true 。 * imageAnimationPolicy string (可选) - 指定如何运行图像动画 (比如： GIF等). 可以是 animate , animateOnce 或 noAnimation . 默认值为 animate . * textAreasAreResizable boolean (可选) - 允许调整 TextArea 元素大小。 默认值为 true 。 * webgl boolean (可选) - 启用 WebGL 支持。 默认值为 true 。 * plugins boolean (可选) - 是否应该启用插件。 默认值为 false . * experimentalFeatures boolean (可选) - 启用 Chromium 的实验功能。 默认值为 false . * scrollBounce boolean (可选) macOS - 启用滚动回弹（橡皮筋）效果。 默认值为 false . * enableBlinkFeatures string(可选) - 以 逗号 分隔的需要启用的特性列表，譬如 CSSVariables,KeyboardEventKey 在 RuntimeEnabledFeatures.json5 文件中查看被支持的所有特性. * disableBlinkFeatures string (可选) - 以 , 分隔的禁用特性列表, 如 CSSVariables,KeyboardEventKey . 在 RuntimeEnabledFeatures.json5 文件中查看被支持的所有特性. * defaultFontFamily Object (可选) - 为font-family设置默认字体。 * standard string (可选) - 默认值为 Times New Roman . * serif string (可选) - 默认值为 Times New Roman . * sansSerif string (可选) - 默认值为 Arial . * monospace string (可选) - 默认值为 Courier New . * cursive string (可选) - 默认值为 Script . * fantasy string (可选) - 默认值为 Impact . * math string (可选) - 默认值为 Latin Modern Math . * defaultFontSize Integer (可选) - 默认值为 16 . * defaultMonospaceFontSize Integer (可选) - 默认值为 13 . * minimumFontSize Integer (可选) - 默认值为 0 . * defaultEncoding string (可选) - 默认值为 ISO-8859-1 . * backgroundThrottling boolean (可选)-是否在页面成为背景时限制动画和计时器。 This also affects the Page Visibility API . When at least one webContents displayed in a single browserWindow has disabled backgroundThrottling then frames will be drawn and swapped for the whole window and other webContents displayed by it. 默认值为 true 。 * offscreen Object | boolean (optional) - Whether to enable offscreen rendering for the browser window. 默认值为 false . See the offscreen rendering tutorial for more details. * useSharedTexture boolean (optional) Experimental - Whether to use GPU shared texture for accelerated paint event. 默认值为 false . See the offscreen rendering tutorial for more details. * sharedTexturePixelFormat string (optional) Experimental - The requested output format of the shared texture. 默认值为： argb 。 The name is originated from Chromium media::VideoPixelFormat enum suffix and only subset of them are supported. The actual output pixel format and color space of the texture should refer to OffscreenSharedTexture object in the paint event. * argb - The requested output texture format is 8-bit unorm RGBA, with SRGB SDR color space. * rgbaf16 - The requested output texture format is 16-bit float RGBA, with scRGB HDR color space. * nv12 - The requested output texture format is 12bpp with Y plane followed by a 2x2 interleaved UV plane, with REC709 color space. * deviceScaleFactor number (optional) Experimental - The device scale factor of the offscreen rendering output. If not set, will use 1 as default. * contextIsolation boolean (可选) - 是否在独立 JavaScript 环境中运行 Electron API和指定的 preload 脚本. 默认为 true 。 预加载 脚本所运行的上下文环境只能访问其自身专用的 文档 和全局 窗口 ，其自身一系列内置的JavaScript ( Array , Object , JSON , 等等) 也是如此，这些对于已加载的内容都是不可见的。 Electron API 将只在 预加载 脚本中可用，在已加载页面中不可用。 这个选项应被用于加载可能不被信任的远程内容时来确保加载的内容无法篡改 预加载 脚本和任何正在使用的Electron api。 该选项使用的是与 Chrome内容脚本 相同的技术。 你可以在开发者工具Console选项卡内顶部组合框中选择 'Electron Isolated Context'条目来访问这个上下文。 * webviewTag boolean (optional) - Whether to enable the <webview> tag . 默认值为 false . ** 注意: **为 < webview> 配置的 preload 脚本在执行时将启用节点集成, 因此应确保远程或不受信任的内容无法创建恶意的 preload 脚本 。 You can use the will-attach-webview event on webContents to strip away the preload script and to validate or alter the <webview> 's initial settings. * additionalArguments string[] (可选) - 一个将被附加到当前应用程序的渲染器进程中 process.argv 的字符串列表 。 可用于将少量的数据传递到渲染器进程预加载脚本中。 * safeDialogs boolean (可选) - 是否启用浏览器样式的持续对话框保护。 默认值为 false . * safeDialogsMessage string (可选) - 当持续对话框保护被触发时显示的消息。 如果没有定义，那么将使用缺省的消息。注意：当前缺省消息是英文，并没有本地化。 * disableDialogs boolean (可选) - 是否完全禁用对话框。 覆盖 safeDialogs 。 默认值为 false . * navigateOnDragDrop boolean (可选) - 将文件或链接拖放到页面上时是否触发页面跳转。 默认值为 false . * autoplayPolicy string (可选) - 窗口中内容要使用的自动播放策略，值可以是 no-user-gesture-required , user-gesture-required , document-user-activation-required 。 默认为 no-user-gesture-required 。 * disableHtmlFullscreenWindowResize boolean (可选) - 是否阻止窗口在进入 HTML 全屏时调整大小。 默认值为 false . * accessibleTitle string (可选) - 仅提供给如屏幕读取器等辅助工具的替代标题字符串。 此字符串不直接对用户可见。 * spellcheck boolean (可选) - 是否启用内置拼写检查器。 默认值为 true 。 * enableWebSQL boolean (可选) - 是否启用 WebSQL api 。 默认值为 true 。 * v8CacheOptions string (可选) - 强制 blink 使用 v8 代码缓存策略。 可接受的值为： * none - 禁用代码缓存 * code - 基于启发式代码缓存 * bypassHeatCheck - 绕过启发式代码缓存，但使用懒编译。 * bypassHeatCheckAndEagerCompile - 与上面相同，除了编译是及时的。 默认策略是 code 。 * enablePreferredSizeMode boolean (可选) - 是否启用首选大小模式。 首选大小是包含文档布局所需的最小大小--无需滚动。 启用该属性将导致在首选大小发生变化时，在 WebContents 上触发 preferred-size-changed 事件。 默认值为 false . * transparent boolean (optional) - Whether to enable background transparency for the guest page. 默认值为 true 。 Note: The guest page's text and background colors are derived from the color scheme of its root element. When transparency is enabled, the text color will still change accordingly but the background will remain transparent. * enableDeprecatedPaste boolean (optional) Deprecated - Whether to enable the paste execCommand . 默认值为 false . * focusOnNavigation boolean (optional) - Whether to focus the WebContents when navigating. 默认值为 true 。 * paintWhenInitiallyHidden boolean(可选) - 当 show 为 false 并且渲染器刚刚被创建时，它是否应激活。 为了让 document.visibilityState 在 show: false 的情况下第一次加载时正确地工作，你应该把这个设置成 false . 设置为 false 将会导致 ready-to-show 事件不触发。 默认值为 true 。 实例事件 ​ 使用 new BrowserWindow 创建的对象具有以下属性: [!NOTE] Some events are only available on specific operating systems and are labeled as such. 事件： 'page-title-updated' ​ 返回: * event Event * title string * explicitSet boolean 文档更改标题时触发，调用 event.preventDefault() 将阻止更改标题 当标题合成自文件 URL 中时， explicitSet 的值为false。 事件： 'close' ​ 返回: * event Event 在窗口要关闭的时候触发。 它在DOM 的 beforeunload 和 unload 事件之前触发. 调用 event.preventDefault() 将阻止这个操作。 通常你想通过 beforeunload 处理器来决定是否关闭窗口，但是它也会在窗口重载的时候触发. 在 Electron 里，返回除 undefined 之外的任何值都将取消关闭. 例如： window . onbeforeunload = ( e ) => { console . log ( 'I do not want to be closed' ) // 与通常的浏览器不同,会提示给用户一个消息框, //返回非空值将默认取消关闭 //建议使用对话框 API 让用户确认关闭应用程序. e . returnValue = false } [!NOTE] There is a subtle difference between the behaviors of window.onbeforeunload = handler and window.addEventListener('beforeunload', handler) . It is recommended to always set the event.returnValue explicitly, instead of only returning a value, as the former works more consistently within Electron. 事件： 'closed' ​ 在窗口关闭时触发 当你接收到这个事件的时候, 你应当移除相应窗口的引用对象，避免再次使用它. Event: 'query-session-end' Windows ​ 返回: * event WindowSessionEndEvent Emitted when a session is about to end due to a shutdown, machine restart, or user log-off. Calling event.preventDefault() can delay the system shutdown, though it’s generally best to respect the user’s choice to end the session. However, you may choose to use it if ending the session puts the user at risk of losing data. 事件: 'session-end' Windows ​ 返回: * event WindowSessionEndEvent Emitted when a session is about to end due to a shutdown, machine restart, or user log-off. Once this event fires, there is no way to prevent the session from ending. 事件: 'unresponsive' ​ 网页变得未响应时触发 事件: 'responsive' ​ 未响应的页面变成响应时触发 事件: 'blur' ​ 当窗口失去焦点时触发 事件: 'focus' ​ 当窗口获得焦点时触发 事件: 'show' ​ 当窗口显示时触发 事件: 'hide' ​ 当窗口隐藏时触发 事件: 'ready-to-show' ​ 当页面已经渲染完成(但是还没有显示) 并且窗口可以被现实时触发 请注意，使用此事件意味着渲染器会被认为是"可见的"并绘制，即使 show 是false。 如果您使用 paintWhenInitiallyHidden: false ，此事件将永远不会被触发。 事件: 'maximize' ​ 窗口最大化时触发 事件: 'unmaximize' ​ 当窗口从最大化状态退出时触发 事件: 'minimize' ​ 窗口最小化时触发 [!NOTE] On Wayland, “minimized” is not currently a supported state. The minimize event will only fire when triggered by client-side decoration (e.g. clicking the minimize button on a frameless window’s Window Control Overlay) 事件: 'restore' ​ 当窗口从最小化状态恢复时触发 事件: 'will-resize' macOS Windows ​ 返回: * event Event * newBounds Rectangle - Size the window is being resized to. * details Object * edge (string) - 窗口边缘被拖动以调整大小。 值可以是 bottom , left , right , top-left , top-right , bottom-left 或 bottom-right . 调整窗口大小前触发。 调用 event.preventDefault() 将阻止窗口大小调整。 请注意，该事件仅在手动调整窗口大小时触发。 通过 setBounds / setSize 调整窗口大小不会触发此事件。 edge 选项的可用值和行为选项与平台相关 可能的值有 * 在 Windows 平台可用值有 bottom , top , left , right , top-left , top-right , bottom-left , bottom-right . * 在 macOS, 可用值有 bottom 和 right . * bottom 值用于表示垂直调整大小。 * right 值用于表示水平调整大小。 事件: 'resize' ​ 调整窗口大小后触发。 事件：'resized' macOS Windows ​ 当窗口完成调整大小后触发一次。 这通常在手动调整窗口大小后触发。 在 macOS 系统上，使用 setBounds / setSize 调整窗口大小并将 animate 参数设置为 true 也会在调整大小完成后触发此事件。 事件: 'will-move' macOS Windows ​ 返回: * event Event * newBounds Rectangle - Location the window is being moved to. 窗口移动前触发。 在Windows上，调用 event.preventDefault() 将阻止窗口移动。 注意：仅当手动移动窗口时才会触发此消息。 使用 setPosition / setBounds / center 移动窗口不会触发此事件。 事件: 'move' ​ 窗口移动到新位置时触发 事件: 'moved' macOS Windows ​ 当窗口移动到新位置时触发一次 [!NOTE] On macOS, this event is an alias of move . 事件: 'enter-full-screen' ​ 窗口进入全屏状态时触发 事件: 'leave-full-screen' ​ 窗口离开全屏状态时触发 事件: 'enter-html-full-screen' ​ 窗口进入由HTML API 触发的全屏状态时触发 事件: 'leave-html-full-screen' ​ 窗口离开由HTML API触发的全屏状态时触发 事件: 'always-on-top-changed' ​ 返回: * event Event * isAlwaysOnTop boolean 设置或取消设置窗口总是在其他窗口的顶部显示时触发。 事件： 'app-command' Windows__Linux ​ 返回: * event Event * command string Emitted when an App Command is invoked. 典型的是键盘上的媒体键或浏览器命令, 以及在Windows上的一些鼠标中内置的“后退”按钮。 命令是小写的，下划线替换为连字符，以及 APPCOMMAND_ 前缀将被删除。 例如 APPCOMMAND_BROWSER_BACKWARD 将被 browser-backward 触发. const { BrowserWindow } = require ( 'electron' ) const win = new BrowserWindow ( ) win . on ( 'app-command' , ( e , cmd ) => { // 当用户鼠标单击返回按钮时将自动返回上一个窗口 if ( cmd === 'browser-backward' && win . webContents . canGoBack ( ) ) { win . webContents . goBack ( ) } } ) 以下应用命令在 Linux 上有明确地支持： * browser-backward * browser-forward 事件: 'swipe' macOS ​ 返回: * event Event * direction string 三指滑动时触发。 Possible directions are up , right , down , left . 此事件的基本方法是用来处理旧的macOS风格的触摸板滑动，屏幕内容不会随着滑动而移动。 大多数macOS触摸板都不再允许配置这样的滑动，因此为了正确地触发该事件，需将 System Preferences > Trackpad > More Gestures 中'Swipe between pages'首选项设置为'Swipe with two or three fingers'。 事件: 'rotate-gesture' macOS ​ 返回: * event Event * rotation Float 在触控板旋转手势上触发。 持续触发直到旋转手势结束。 每次触发的 rotation 值是自上次触发以来旋转的角度。 旋转手势最后一次触发的事件值永远是 0 。 逆时针旋转值为正值，顺时针旋转值为负值。 事件: 'sheet-begin' macOS ​ 窗口打开sheet(工作表) 时触发 事件: 'sheet-end' macOS ​ 窗口关闭sheet(工作表) 时触发 事件: 'new-window-for-tab' macOS ​ 当用户点击原生的macOS新标签按钮时触发。 The new tab button is only visible if the current BrowserWindow has a tabbingIdentifier . You must create a window in this handler in order for macOS tabbing to work as expected. Event: 'system-context-menu' Windows Linux ​ 返回: * event Event * point Point - The screen coordinates where the context menu was triggered. 当系统上下文菜单在窗口上触发时发出， 通常只在用户右键点击你窗口的非客户端区域时触发。 非客户端区域指的是窗口标题栏或无边框窗口中被你声明为 -webkit-app-region: drag 的任意区域。 调用 event.preventDefault() 将阻止菜单显示。 To convert point to DIP, use screen.screenToDipPoint(point) . 静态方法 ​ BrowserWindow 类有以下方法: BrowserWindow.getAllWindows() ​ 返回 BrowserWindow[] - 所有打开的窗口的数组 BrowserWindow.getFocusedWindow() ​ 返回 BrowserWindow | null - 此应用程序中当前获得焦点的窗口，如果无就返回 null . BrowserWindow.fromWebContents(webContents) ​ * webContents WebContents 返回 BrowserWindow | null - 返回拥有给定 webContents 的窗口，否则如果内容不属于一个窗口，返回 null 。 BrowserWindow.fromBrowserView(browserView) Deprecated ​ * browserView BrowserView [!NOTE] The BrowserView class is deprecated, and replaced by the new WebContentsView class. 返回 BrowserWindow | null - 拥有给定 browserView 的窗口。 如果给定的视图没有附加到任何窗口，返回 null 。 BrowserWindow.fromId(id) ​ * id Integer 返回 BrowserWindow | null - 带有给定 id 的窗口。 实例属性 ​ 使用 new BrowserWindow 创建的对象具有以下属性: const { BrowserWindow } = require ( 'electron' ) // 本例中 `win` 是我们的实例 const win = new BrowserWindow ( { width : 800 , height : 600 } ) wi