Electron 知识点速查

NPM version Downloads Repo Dependents Github repo

此快速参考备忘单提供了 Electron v21 API 说明和使用示例

入门

快速开始

Electron 是一个使用 JavaScript、HTML 和 CSS 构建桌面应用程序的框架

创建你的应用程序

  • 安装

    mkdir my-app && cd my-app
    npm init
    

    在项目根目录会生成 package.json

    {
      "name": "my-app",
      "version": "1.0.0",
      "description": "Hello World!",
      "main": "main.js",
      "author": "Jane Doe",
      "license": "MIT"
    }
    
  • 安装依赖包

    npm install --save-dev electron
    
  • 添加开发模式打开您的应用命令

    "scripts": {
      "start": "electron ."
    }
    
  • 运行命令,启动应用程序

    npm start
    

    入口都是 main 文件。这个文件控制了主进程,它运行在一个完整的Node.js环境中

  • 创建 index.html 页面

    <!DOCTYPE html>
    <html>
      <head>
        <meta charset="UTF-8">
        <!-- https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP -->
        <meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'">
        <title>Hello World!</title>
      </head>
      <body>
        <h1>Hello World!</h1>
      </body>
    </html>
    
  • 窗口中打开您的页面

    const {
      app,
      BrowserWindow
    } = require('electron');
    
    const createWindow = () => {
      const win = new BrowserWindow({
        width: 800,
        height: 600
      });
      win.loadFile('index.html');
    }
    
    app.whenReady().then(() => {
      createWindow()
    })
    

关闭所有窗口时退出应用

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

创建无边框窗口

const win = new BrowserWindow({
  frame: false
})

自定义标题栏样式

const win = new BrowserWindow({
  titleBarStyle: 'hidden'
})

控制红绿灯 (macOS)

const win = new BrowserWindow({
  titleBarStyle: 'customButtonsOnHover'
})

通过预加载脚本从渲染器访问 Node.js

创建一个名为 preload.js 的新脚本如下

window.addEventListener('DOMContentLoaded', () => {
  const replaceText = (selector, text) => {
    const element = document.getElementById(selector)
    if (element) element.innerText = text
  }

  for (const dependency of ['chrome', 'node', 'electron']) {
    replaceText(`${dependency}-version`, process.versions[dependency])
  }
})

在创建窗口方法中传递 preload 参数

const path = require('path')

const createWindow = () => {
  const win = new BrowserWindow({
    width: 800,
    height: 600,
    webPreferences: {
      preload: path.join(__dirname, 'preload.js')
    }
  })

  win.loadFile('index.html')
}

将的 process.versions 对象暴露给渲染器

const { contextBridge } = require('electron')

contextBridge.exposeInMainWorld(
  'versions', {
    // 能暴露的不仅仅是函数,我们还可以暴露变量
    node: 
      () => process.versions.node,
    chrome: 
      () => process.versions.chrome,
    electron: 
      () => process.versions.electron,
  }
);

通过 preload.js 脚本将 versions 这一全局变量暴露给渲染器

启用拼写检查器

const myWindow = new BrowserWindow({
  webPreferences: {
    spellcheck: true
  }
})

设置拼写检查器以检查英语 和 法语

myWindow.session
  .setSpellCheckerLanguages([
    'en-US', 'fr'
  ])

app

事件绑定方法使用示例

const { app } = require('electron');

app.on('session-created', (session) => {
  console.log(session);
})

// 立即重启当前实例并向新的实例添加新的命令行参数的示例
app.relaunch({
  args: process.argv.slice(1).concat(['--relaunch']);
})

app.exit(0);

方法

:-:-
quit尝试关闭所有窗口 #
exit使用 exitCode 立即退出 #
relaunch当前实例退出,重启应用 #
isReady已完成初始化返回 boolean #
whenReady初始化完成 #
focus获得焦点/激活的 app #
hide隐藏所有的应用窗口,不是最小化 #
isHidden (mac)所有窗口是否都被隐藏 #
show (mac)显示隐藏后的应用程序窗口 #
setAppLogsPath设置或创建一个您的应用程序日志目录 #
getAppPath获取当前应用程序目录 #
getPath(name)与 name 关联的目录或文件的路径 #
getFileIcon一个 NativeImage 类型的应用图标 #
setPath(name)重写 name 的路径特定文件夹或文件 #
getVersion应用程序的版本号 #
getName应用程序的名称 #
setName设置当前应用程序的名字 #
getLocale当前应用程序区域 #
getLocaleCountryCode获取双字母 ISO 3166 国家代码 #
getSystemLocale当前系统语言环境 #
addRecentDocument (win/mac)最近打开的文件列表添加新路径 #
clearRecentDocuments (win/mac)清空最近打开的文档列表#
setAsDefaultProtocolClient设置协议(URI scheme)默认处理程序 #
removeAsDefaultProtocolClient移除默认处理器 #
isDefaultProtocolClient可执行程序是否是协议 #
getApplicationNameForProtocol返回默认处理器的应用程序名称 #
getApplicationInfoForProtocol (win/mac)返回包含应用程序名称 #
setUserTasks (win)添加 tasks 到Jump List的Tasks类别 #
getJumpListSettings (win)获取跳转列表 #
setJumpList (win)设置跳转列表 #
requestSingleInstanceLock返回应用程序实例是否成功取了锁 #
hasSingleInstanceLock返回应用实例当前是否持有单例锁 #
releaseSingleInstanceLock释放所有创建的锁 #
setUserActivity (mac)创建 NSUserActivity 并将其设置为当前活动 #
getCurrentActivityType (mac)正在运行的 activity 的类型 #
invalidateCurrentActivity (mac)使当前的Handoff用户活动无效 #
resignCurrentActivity (mac)将当前 Handoff 用户活动标记为非活动,但不使其失效 #
updateCurrentActivity (mac)将项目从 用户信息 合并到其当前 用户信息 字典中 #
setAppUserModelId (win)改变当前应用的 Application User Model ID 为 id #
setActivationPolicy (mac)为给定应用设置激活策略 #
importCertificate (linux)将 pkcs12 格式的证书导入到平台证书库 #
configureHostResolver配置主机解析器 (DNS 和 DNS-over-HTTPS) #
disableHardwareAcceleration禁用当前应用程序的硬件加速 #
disableDomainBlockingFor3DAPIsGPU 进程频繁崩溃,在每个域的基础上重新启动,禁用该行为 #
getAppMetrics返回 ProcessMetric[] #
getGPUFeatureStatus返回 GPUFeatureStatus #
getGPUInfoGPU 信息 #
setBadgeCount (mac/linux)应用设置计数器角标 #
getBadgeCount (mac/linux)获取计数器(badge)显示的当前值 #
isUnityRunning (linux)前桌面环境是否为 Unity 启动器 #
getLoginItemSettings (mac/win)为 openAtLogin 设置相同的参数已确保正确的设置 #
setLoginItemSettings (mac/win)传递指定应用程序名称的参数 #
isAccessibilitySupportEnabled (mac/win)是否开启了辅助功能 #
setAccessibilitySupportEnabled (mac/win)启用或禁用访问权限树视图 #
showAboutPanel显示程序的"关于"面板选项 #
setAboutPanelOptions设置 "关于" 面板选项 #
isEmojiPanelSupported当前操作系统是否支持本地 emoji 选择器 #
showEmojiPanel (mac/win)打开系统自身的emjio选取器 #
startAccessingSecurityScopedResource (mac)开始访问安全范围内的资源 #
enableSandbox在应用程序上启用完全沙盒模式 #
isInApplicationsFolder (mac)是否从系统应用程序文件夹运行 #
moveToApplicationsFolder (mac)#
isSecureKeyboardEntryEnabled (mac)是否已启用安全键盘输入 #
setSecureKeyboardEntryEnabled (mac)在应用中启用安全键盘输入 #

启动时激活主实例窗口的示例

const { app } = require('electron');
let myWindow = null;

const additionalData = { myKey: 'myValue' };
const gotTheLock = app.requestSingleInstanceLock(additionalData);

if (!gotTheLock) {
  app.quit();
} else {
  app.on(
    'second-instance',
    (event, commandLine, workingDirectory, additionalData) => {
      // 输出从第二个实例中接收到的数据
      console.log(additionalData);

      // 有人试图运行第二个实例,我们应该关注我们的窗口
      if (myWindow) {
        if (myWindow.isMinimized()) myWindow.restore();
        myWindow.focus();
      }
    }
  )

  // 创建 myWindow, 加载应用的其余部分, etc...
  app.whenReady().then(() => {
    myWindow = createWindow();
  })
}

事件

:-:-
will-finish-launching基础的启动的时候被触发 #
ready完成初始化时,触发一次 #
window-all-closed在程序关闭窗口前发信号 #
before-quit当所有窗口被关闭后触发,应用程序将退出 #
will-quit所有窗口被关闭后触发,应用程序将退出 #
quit在应用程序退出时触发 #
open-file (mac)在应用中打开一个文件时触发 #
open-url (mac)应用中打开一个 URL 时触发 #
activate (mac)当应用被激活时触发 #
did-become-active (mac)不同设备的活动想要恢复时在切换期间触发 #
continue-activity (mac)不同设备的活动通过 Handoff 想要恢复时触发 #
will-continue-activity (mac)恢复来自不同设备的活动之前在切换期间触发 #
continue-activity-error (mac)不同设备的活动无法恢复时在切换期间触发 #
activity-was-continued (mac)活动在另一个设备上成功恢复后切换期间触发 #
update-activity-state (mac)当即将在另一台设备上恢复切换时触发 #
new-window-for-tab (mac)用户点击原生的 macOS 新标签按钮时触发 #
browser-window-blur当 browserWindow 变得模糊时触发 #
browser-window-focus当 browserWindow 获得焦点时触发 #
browser-window-created创建新的 browserWindow 时触发 #
web-contents-created创建新的 webContents 时触发 #
certificate-error当对 url 的 certificate 证书验证失败触发 #
select-client-certificate当一个客户证书被请求的时候发出 #
login当 webContents 要进行基本身份验证时触发 #
gpu-info-update每当有 GPU 信息更新时触发 #
gpu-process-crashed 废弃当 gpu 进程崩溃或关闭(杀死)时触发 #
renderer-process-crashed 废弃渲染器进程崩溃或关闭(杀死)时触发 #
render-process-gone渲染器进程意外消失时触发 #
child-process-gone子进程意外消失时触发 #
accessibility-support-changed当 Chrome 的辅助功能状态改变时触发 #
session-created创建了一个新的 session 后被触发 #
second-instance在你的应用程序的首个实例中触发 #

属性

:-:-
accessibilitySupportEnabled (mac/win)是否开启了辅助功能 #
applicationMenu传递 Menu 来给此属性赋值 #
badgeCount (mac/linux)返回应用角标计数的 Integer 属性 #
commandLineChromium 使用的命令行参数 #
dock (mac/只读)用户dock中对应用图标进行操作 #
isPackaged (只读)应用是否已经打包 #
name当前应用程序的名称 #
userAgentFallback全局回退的用户代理字符串 #
runningUnderRosettaTranslation (mac)提示下载应用程序的 arm64 版本 #
runningUnderARM64Translation (mac/win)前应用正在使用 ARM64 运行环境 #

BrowserWindow

参数

:-:-
width 整数窗口的宽度(以像素为单位)。默认值 (800)
height 整数窗口的高度(以像素为单位)。默认值 (600)
x 整数 (可选)窗口相对于屏幕左侧偏移量。默认值窗口居中
y 整数 (可选)窗口相对于屏幕顶端偏移量。默认值窗口居中
useContentSize boolean(宽)(高) 设置为web页面的尺寸。默认值 (false)
center boolean窗口是否在屏幕居中。默认值 (false)
minHeight 整数窗口的最小高度。默认值 (0)
maxWidth 整数窗口的最大宽度。默认值不限
maxHeight 整数窗口的最大高度。默认值不限
resizable boolean窗口大小是否可调整。默认值 (true)
movable boolean (win/mac)窗口是否可移动。默认值 (true)
minimizable boolean (win/mac)窗口是否可最小化。默认值 (true)
maximizable boolean (win/mac)窗口是否最大化。默认值 (true)
closable boolean (win/mac)窗口是否可关闭。默认值 (true)
focusable boolean窗口是否可以聚焦. 默认值 (true)。在 Windows 中设置 (focusable: false) 也意味着设置了 (skipTaskbar: true) 在 Linux 中设置 (focusable: false) 时窗口停止与 wm 交互, 并且窗口将始终置顶
alwaysOnTop boolean窗口是否永远在别的窗口的上面。默认值 (false)
fullscreen boolean窗口是否全屏。为 (false) 时 macOS 上按钮将被隐藏或禁用。默认值 (false)
fullscreenable boolean窗口是否可以进入全屏状态。macOS上,最大化/缩放按钮是否可用 默认值 (true)
simpleFullscreen boolean (mac)在 macOS 上使用 pre-Lion 全屏。默认值 (false)
skipTaskbar boolean (win/mac)是否在任务栏中显示窗口。默认值 (false)
kiosk boolean窗口是否进入kiosk模式。默认值 (false)
title string默认窗口标题 默认为 ("Electron") 。如果由 (loadURL()) 加载的HTML文件中含有标签 (<title>) ,此属性将被忽略
icon NativeImage/string窗口图标。在 Windows 上推荐使用 (ICO) 图标来获得最佳的视觉效果, 默认使用可执行文件的图标
show boolean窗口是否在创建时显示。默认值 (true)
paintWhenInitiallyHidden boolean(show)(false) 并且渲染器刚刚被创建时,它是否应激活。为了让 (document.visibilityState)(show: false) 的情况下第一次加载时正确地工作,你应该把这个设置成 (false)。设置为 (false) 将会导致 (ready-to-show) 事件不触发。默认值 (true)
frame boolean设置为 (false) 时可以创建一个无边框窗口,默认值 (true)
parent BrowserWindow指定父窗口 默认值 (null)
modal boolean当前是否为模态窗口。只有当窗口是子窗口时才起作用。默认值 (false)
acceptFirstMouse boolean (mac)点击 非活动窗口是否会穿透到 web contents。默认值 (false)
disableAutoHideCursor boolean是否在打字时隐藏光标。默认值 (false)
autoHideMenuBar boolean自动隐藏菜单栏,除非按了_(Alt)_键。默认值 (false)
enableLargerThanScreen boolean (mac)使窗口尺寸可大于屏幕的大小。其他操作系统默认允许大于屏幕的窗口。默认值 (false)
backgroundColor string窗口背景色,格式为 Hex, RGB, RGBA, HSL, HSLA 或 CSS 命名颜色。如果 (transparent) 设置为 (true),则支持 #AARRGGBB 格式的透明。默认值 (#FFF)(白色)
hasShadow boolean窗口是否有阴影. 默认值 (true)
opacity number (win/mac)设置窗口的初始透明度,在 0.0(全透明)和 1.0(完全不透明)之间 。 目前仅在 Windows 和 macOS上实现。
darkTheme boolean强制窗口使用深色主题,只在部分GTK+3桌面环境下有效。 默认值 (false).
transparent boolean使窗口 透明。 默认值 (false). 在Windows上,仅在无边框窗口下起作用。
type string窗口的类型, 默认为普通窗口. 更多信息见下文
visualEffectState string (mac)在 macOS 上指定外观应如何响应窗口活动状态。 必须与 (vibrancy) 属性一起使用。 可能的值有
visualEffectState.followWindow当窗口处于激活状态时,后台应自动显示为激活状态,当窗口处于非激活状态时,后台应自动显示为非激活状态。 默认为该值。
visualEffectState.active后台应一直显示为激活状态。
visualEffectState.inactive后台应一直显示为非激活状态。
titleBarStyle string (win/mac)窗口标题栏样式。默认值 (default)
titleBarStyle.default分别返回 mac 或者 win 的标准标题栏
titleBarStyle.hidden在一个隐藏的标题栏和一个全尺寸大小的内容窗口中取得结果。 在 macOS 内, 窗口将一直拥有位于左上的标准窗口控制器 (“traffic lights”)。 在 Windows上,当与 (titleBarOverlay: true) 合并时,它将激活窗口控件叠加(详情请参阅 (titleBarOverlay)),否则将不会显示窗口控件。
titleBarStyle.hiddenInset (mac)隐藏标题栏,使用窗口边缘稍微小的红绿灯按钮替代。
titleBarStyle.customButtonsOnHover (mac)隐藏的标题栏的全尺寸的内容窗口, 红绿灯按钮在鼠标悬停在窗口左上方时显示。**注意:**此选项目前是实验性的。
trafficLightPosition Point (mac)在无边框窗口中设置灯绿灯按钮位置。
roundedCorners boolean (mac)无边框窗口在 macOS 上,是否应该有圆角。 默认值为 (true)。 属性设置为 (false) ,将阻止窗口是可全屏的。
fullscreenWindowTitle boolean (mac) 已弃用titleBarStyle 设置为 (hiddenInset) 时,在 macOS 全屏模式下标题栏显示标题。默认值为 (false).
thickFrame boolean对 Windows 上的无框窗口使用 (WS_THICKFRAME) 样式,会增加标准窗口框架。 设置为 (false) 时将移除窗口的阴影和动画. 默认值为 (true)
vibrancy string (mac)为窗口添加一种类型的动态效果,仅 macOS。 可以是 (appearance-based)(light)(dark)(titlebar)(selection)(menu)(popover)(sidebar)(medium-light)(ultra-dark)(header)(sheet)(window)(hud)(fullscreen-ui)(tooltip)(content)(under-window)(under-page)。 请注意 (appearance-based)(light)(dark)(medium-light)(ultra-dark) 已弃用,在 macOS Catalina (10.15) 中已经移除。
zoomToPageWidth boolean (mac)在 macOS 上控制,当按住 option 点击工具栏绿色红绿灯按钮或点击窗口 > 放大菜单项的行为。 如果为 (true),窗口为将会缩放到适合宽度,若为 (false) 将会放大到屏幕宽度。 这也会影响,直接调用 (maximize()) 的行为。 默认值为 (false).
tabbingIdentifier string (mac)选项卡组名称,允许在原生选择卡中打开窗口,macOS 10.12+ 支持。 Windows 中,有相同选项卡标识的将会组合在一起。 这会添加一个原生新增选项卡按钮到你窗口的选项卡栏,同时 (app) 和窗口允许接收 (new-window-for-tab) 事件。
webPreferences Object网页功能设置。
webPreferences.devTools boolean是否开启 DevTools. 如果设置为 (false), 则无法使用 (BrowserWindow.webContents.openDevTools ()) 打开 DevTools。 默认值为 (true)
webPreferences.nodeIntegration boolean是否启用Node integration. 默认值为 (false).
webPreferences.nodeIntegrationInWorker boolean是否在Web工作器中启用了Node集成. 默认值为 (false). 更多内容参见 多线程
webPreferences.nodeIntegrationInSubFrames boolean 实验性是否允许在子页面(iframe)或子窗口(child window)中集成Node.js; 预先加载的脚本会被注入到每一个iframe,你可以用 (process.isMainFrame) 来判断当前是否处于主框架(main frame)中。
webPreferences.preload string在页面运行其他脚本之前预先加载指定的脚本 无论页面是否集成Node, 此脚本都可以访问所有Node API 脚本路径为文件的绝对路径。 当 node integration 关闭时, 预加载的脚本将从全局范围重新引入node的全局引用标志参考示例
webPreferences.sandbox boolean如果设置该参数, 沙箱的渲染器将与窗口关联, 使它与Chromium OS-level 的沙箱兼容, 并禁用 Node. js 引擎。 它与 (nodeIntegration) 的选项不同,且预加载脚本的 API 也有限制。更多详情
webPreferences.sessionSession 设置页面的 session 而不是直接忽略 Session 对象, 也可用 (partition) 选项来代替,它接受一个 partition 字符串. 同时设置了_(session)_ 和 _(partition)_时, (session) 的优先级更高. 默认使用默认的 session.
webPreferences.partitionstring (optional) - 通过 session 的 partition 字符串来设置界面session. 如果 (partition)(persist:)开头, 该页面将使用持续的 session,并在所有页面生效,且使用同一个(partition). 如果没有 (persist:) 前缀, 页面将使用 in-memory session. 通过分配相同的 (partition), 多个页可以共享同一会话。 默认使用默认的 session.
webPreferences.zoomFactor number页面的默认缩放系数, (3.0) 表示 (300%)。 默认值为 (1.0).
webPreferences.javascript boolean是否启用 JavaScript 支持。 默认值为 (true)
webPreferences.webSecurity boolean当设置为 (false), 它将禁用同源策略 (通常用来测试网站), 如果此选项不是由开发者设置的,还会把 _(allowRunningInsecureContent)_设置为 (true). 默认值为 (true)
webPreferences.allowRunningInsecureContent boolean允许一个 https 页面运行来自http url的JavaScript, CSS 或 plugins。 默认值为 (false)
webPreferences.images boolean允许加载图片。 默认值为 (true)
webPreferences.imageAnimationPolicy string指定如何运行图像动画 (比如: GIF等). 可以是 (animate), (animateOnce)(noAnimation)。默认值为 (animate)
webPreferences.textAreasAreResizable boolean允许调整 TextArea 元素大小。 默认值为 (true)
webPreferences.webgl boolean启用 WebGL 支持。 默认值为 (true)
webPreferences.plugins boolean是否应该启用插件。 默认值为 (false)
webPreferences.experimentalFeatures boolean启用 Chromium 的实验功能。 默认值为 (false)
webPreferences.scrollBounce boolean (mac)启用滚动回弹(橡皮筋)效果。 默认值为 (false)
webPreferences.enableBlinkFeaturesstring(逗号) 分隔的需要启用的特性列表,譬如 (CSSVariables,KeyboardEventKey)RuntimeEnabledFeatures.json5 文件中查看被支持的所有特性
webPreferences.disableBlinkFeatures string(,) 分隔的禁用特性列表, 如 (CSSVariables,KeyboardEventKey)RuntimeEnabledFeatures.json5 文件中查看被支持的所有特性
defaultFontFamily Object为 font-family 设置默认字体
defaultFontFamily.standard string默认值为 (Times New Roman)
defaultFontFamily.serif string默认值为 (Times New Roman)
defaultFontFamily.sansSerif string默认值为 (Arial)
defaultFontFamily.monospace string默认值为 (Courier New)
defaultFontFamily.cursive string默认值为 (Script)
defaultFontFamily.fantasy string默认值为 (Impact)
defaultFontSize Integer默认值为 (16)
defaultMonospaceFontSize Integer默认值为 (13)
minimumFontSize Integer默认值为 (0)
defaultEncoding string默认值为 (ISO-8859-1)
backgroundThrottling boolean是否在页面成为背景时限制动画和计时器。 这也会影响到 Visibility API。默认值为 (true)
offscreen boolean是否绘制和渲染可视区域外的窗口。默认值为 (false)。更多详情, 请参见 offscreen rendering tutorial
contextIsolation boolean是否在独立 JavaScript 环境中运行 Electron API和指定的_(preload)_ 脚本。默认为 (true)(预加载)脚本所运行的上下文环境只能访问其自身专用的 (文档) 和全局 (窗口),其自身一系列内置的JavaScript ((Array), (Object), (JSON), 等等) 也是如此,这些对于已加载的内容都是不可见的。 Electron API 将只在_(预加载)脚本中可用,在已加载页面中不可用。 这个选项应被用于加载可能不被信任的远程内容时来确保加载的内容无法篡改(预加载)_脚本和任何正在使用的Electron api。 该选项使用的是与Chrome内容脚本相同的技术。你可以在开发者工具Console选项卡内顶部组合框中选择 'Electron Isolated Context'条目来访问这个上下文
webviewTag boolean是否启用 (<webview>) tag标签。默认值为 (false)注意:(< webview>) 配置的 (preload) 脚本在执行时将启用节点集成, 因此应确保远程或不受信任的内容无法创建恶意的 (preload) 脚本 。 可以使用 webContents 上的 (will-attach-webview) 事件对 (preload) 脚本进行剥离, 并验证或更改 (<webview>) 的初始设置
additionalArguments string[]strin一个将被附加到当前应用程序的渲染器进程中_(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 代码缓存策略。 可接受的值为:
v8CacheOptions.none禁用代码缓存
v8CacheOptions.code基于启发式代码缓存
v8CacheOptions.bypassHeatCheck绕过启发式代码缓存,但使用懒编译。
v8CacheOptions.bypassHeatCheckAndEagerCompile与上面相同,除了编译是及时的。 默认策略是 (code)
enablePreferredSizeMode boolean是否启用首选大小模式。 首选大小是包含文档布局所需的最小大小--无需滚动。 启用该属性将导致在首选大小发生变化时,在 (WebContents) 上触发 (preferred-size-changed) 事件。默认值为 (false)
titleBarOverlay Object/Boolean当在 macOS 使用无框窗口结合 (win.setWindowButtonVisibility(true)) 或使用 (titleBarStyle) 以便标准窗口控制 (在 macOS为 "traffic lights") 可见,此属性将启用 Window Controls Overlay JavaScript APIsCSS Environment Variables。指定 (true) 将导致覆盖默认系统颜色。 默认值为 (false)
color String (win)启用窗口控制时覆盖面的 CSS 颜色 默认是系统颜色
symbolColor String (win)启用时窗口控制中符号的 CSS 颜色 默认是系统颜色
height Integer (win/mac)标题栏和 Window Controls Overlay,以像素为单位。 默认值为系统高度

实例事件

const { BrowserWindow } = require('electron')

const child = new BrowserWindow({ modal: true, show: false })
child.loadURL('https://github.com')
child.once('ready-to-show', () => {
  child.show()
})

:-:-
page-title-updated文档更改标题时触发 #
close在窗口要关闭的时候触发 #
closed在窗口关闭时触发 #
session-end (win)因为强制关机/重启/会话注销而导致窗口会话结束时触发 #
unresponsive网页变得未响应时触发 #
responsive未响应的页面变成响应时触发 #
blur当窗口失去焦点时触发 #
focus当窗口获得焦点时触发 #
show当窗口显示时触发 #
hide当窗口隐藏时触发 #
ready-to-show当页面已经渲染完成(还没有显示)窗口可以被显示时触发#
maximize窗口最大化时触发 #
unmaximize当窗口从最大化状态退出时触发 #
minimize窗口最小化时触发 #
restore当窗口从最小化状态恢复时触发 #
will-resize (mac/win)调整窗口大小前触发 #
resize调整窗口大小后触发 #
resized (mac/win)当窗口完成调整大小后触发一次 #
will-move (mac/win)窗口移动前触发 #
move窗口移动到新位置时触发 #
moved (mac/win)当窗口移动到新位置时触发一次 #
enter-full-screen窗口进入全屏状态时触发 #
leave-full-screen窗口离开全屏状态时触发 #
enter-html-full-screen窗口进入由HTML API 触发的全屏状态时触发 #
leave-html-full-screen窗口离开由HTML API触发的全屏状态时触发 #
always-on-top-changed设置或取消设置窗口总是在其他窗口的顶部显示时触发 #
app-command请求一个应用程序命令时触发 #
scroll-touch-begin (mac)滚轮事件阶段开始时触发 #
scroll-touch-end (mac)滚轮事件阶段结束时触发 #
scroll-touch-edge (mac)滚轮事件阶段到达元素边缘时触发 #
swipe三指滑动时触发 #
rotate-gesture (mac)在触控板旋转手势上触发 #
sheet-begin (mac)窗口打开sheet(工作表) 时触发 #
sheet-end (mac)窗口关闭sheet(工作表) 时触发 #
new-window-for-tab (mac)当点击了系统的新标签按钮时触发 #
system-context-menu (win)当系统上下文菜单在窗口上触发时触发 #

实例方法

:-:-
win.destroy()强制关闭窗口 #
win.close()尝试关闭窗口 #
win.focus()聚焦于窗口 #
win.blur()取消窗口的聚焦 #
win.isFocused()判断窗口是否聚焦 #
win.isDestroyed()判断窗口是否被销毁 #
win.show()显示并聚焦于窗口 #
win.showInactive()显示但不聚焦于窗口 #
win.hide()隐藏窗口 #
win.isVisible()判断窗口是否可见 #
win.isModal()判断是否为模态窗口 #
win.maximize()最大化窗口 #
win.unmaximize()取消窗口最大化 #
win.isMaximized()判断窗口是否最大化 #
win.minimize()最小化窗口 #
win.restore()窗口最小化状态恢复到以前的状态 #
win.isMinimized()判断窗口是否最小化 #
win.setFullScreen(flag)设置窗口是否应处于全屏模式 #
win.isFullScreen()窗口当前是否已全屏 #
win.setSimpleFullScreen(flag) (mac)进入或离开简单的全屏模式 #
win.isSimpleFullScreen()窗口是否为简单全屏模式(pre-Lion) #
win.isNormal()窗口是否处于正常状态(未最大化,未最小化,不在全屏模式下) #
win.setAspectRatio(aspectRatio[, extraSize])为内容视图保持的宽高比 #
win.setBackgroundColor(backgroundColor)颜色,格式为 Hex,RGB,RGBA,HSL,HSLA 或 CSS 命名颜色 #
win.previewFile(path[, displayName]) (mac)要用 QuickLook 预览的文件的绝对路径 #
win.closeFilePreview() (mac)关闭当前打开的 #
win.setBounds(bounds[, animate])重置窗口,并且移动窗口到指定的位置 #
win.getBounds()表示窗口的 bounds #
win.getBackgroundColor()格式获取窗口的背景色,格式为 Hex (#RRGGBB) #
win.setContentBounds(bounds[, animate])调整窗口的工作区 (如网页) 的大小并将其移动到所提供的边界。 #
win.getContentBounds()窗口客户端区域的 bounds 对象 #
win.getNormalBounds()包含正常状态下的窗口大小 #
win.setEnabled(enable)禁用或者启用窗口 #
win.isEnabled()窗口是否启用 #
win.setSize(width, height[, animate])调整窗口的 widthheight #
win.getSize()包含窗口的宽度和高度 #
win.setContentSize(width, height[, animate])将窗口的工作区 (如网页) 的大小调整为 widthheight #
win.getContentSize()包含窗口的宽度和高度 #
win.setMinimumSize(width, height)设置窗口最小化的 widthheight #
win.getMinimumSize()包含窗口最小化的宽度和高度 #
win.setMaximumSize(width, height)设置窗口最大化的 widthheight #
win.getMaximumSize()包含窗口最大化的宽度和高度 #
win.setResizable(resizable)设置用户是否可以手动调整窗口大小 #
win.isResizable()用户是否可以手动调整窗口大小 #
win.setMovable(movable) (mac/win)设置用户是否可以移动窗口 #
win.isMovable() (mac/win)窗口是否可以被用户拖动,在 Linux 上总是返回 true #
win.setMinimizable(minimizable) (mac/win)设置用户是否可以手动将窗口最小化 #
win.isMinimizable() (mac/win)用户是否可以手动最小化窗口 #
win.setMaximizable(maximizable) (mac/win)设置用户是否可以手动最大化窗口 #
win.isMaximizable() (mac/win)窗口是否可以最大化 #
win.setFullScreenable(fullscreenable)设置最大化/缩放窗口按钮是切换全屏模式还是最大化窗口 #
win.isFullScreenable()最大化/缩放窗口按钮是切换全屏模式还是最大化窗口 #
win.setClosable(closable) (mac/win)设置用户是否可以手动关闭窗口。 在Linux上不起作用 #
win.isClosable() (mac/win)窗口是否被用户关闭了 #
win.setAlwaysOnTop(flag[, level][, relativeLevel])设置窗口是否应始终显示在其他窗口的前面 #
win.isAlwaysOnTop()当前窗口是否始终在其它窗口之前 #
win.moveAbove(mediaSourceId)将窗口按z轴顺序移动到源窗口前面 #
win.moveTop()无论焦点如何, 将窗口移至顶端(z轴上的顺序) #
win.center()将窗口移动到屏幕中央 #
win.setPosition(x, y[, animate])将窗口移动到 xy #
win.getPosition()返回一个包含当前窗口位置的数组 #
win.setTitle(title)将原生窗口的标题更改为 title #
win.getTitle()网页的标题可以与原生窗口的标题不同 #
win.setSheetOffset(offsetY[, offsetX]) (mac/win)改变macOS上sheet组件的附着点,默认情况下,sheet贴在窗口边框正下方 #
win.flashFrame(flag)启动或停止闪烁窗口, 以吸引用户的注意 #
win.setSkipTaskbar(skip) (mac/win)使窗口不显示在任务栏中 #
win.setKiosk(flag)进入或离开 kiosk 模式 #
win.isKiosk()判断窗口是否处于kiosk模式 #
win.isTabletMode() (win)此 API 返回 窗口是否在平板电脑模式下,并且 调整大小 事件可以用于监听对平板模式的更改 #
win.getMediaSourceId()DesktopCapturerSource 的 id 格式的窗口 id #
win.getNativeWindowHandle()窗口的平台特定句柄 #
win.hookWindowMessage(message, callback) (win)钩住窗口消息。 当消息到达 WndProc 时调用 callback #
win.isWindowMessageHooked(message) (win)返回 boolean - true 或false,具体取决于是否钩挂了消息 #
win.unhookWindowMessage(message) (win)取消窗口信息的钩子 #
win.unhookAllWindowMessages() (win)取消所有窗口信息的钩子 #
win.setRepresentedFilename(filename) (mac)设置窗口所代表的文件的路径名,并且将这个文件的图标放在窗口标题栏上 #
win.getRepresentedFilename() (mac)获取窗口当前文件路径 #
win.setDocumentEdited(edited) (mac)明确指出窗口文档是否可以编辑,如果设置为true则将标题栏的图标变成灰色 #
win.isDocumentEdited() (mac)判断当前窗口文档是否可编辑 #
win.focusOnWebView()#
win.blurWebView()#
win.capturePage([rect])在 rect 内捕获页面的快照 #
win.loadURL(url[, options])加载页面 #
win.loadFile(filePath[, options])加载页面 #
win.reload()webContents.reload 相同 #
win.setMenu(menu) (win/linux)menu 设置为窗口的菜单栏 #
win.removeMenu() (win)删除窗口的菜单栏 #
win.setProgressBar(progress[, options])设置进度条的进度值 #
win.setOverlayIcon(overlay, description) (win)设置进度条的进度值。 有效范围为 [0, 1.0] #
win.setHasShadow(hasShadow)设置窗口是否有阴影 #
win.hasShadow()判断窗口是否有阴影 #
win.setOpacity(opacity) (win/mac)设置窗口的不透明度。 在Linux上不起作用。 超出界限的数值被限制在 [0, 1] 范围内 #
win.getOpacity()介于 0.0 (完全透明) 和 1.0 (完全不透明) 之间。在Linux上,始终返回 1 #
win.setShape(rects) (win/linux)对窗口形状的设置决定了窗口内系统允许绘制与用户交互的区域 #
win.setThumbarButtons(buttons) (win)将指定的一组按钮添加到菜单栏的缩图工具栏上 #
win.setThumbnailClip(region) (win)将窗口的区域设置为在任务栏中悬停在窗口上方时显示的缩略图图像 #
win.setThumbnailToolTip(toolTip) (win)设置在任务栏中悬停在窗口缩略图上时显示的工具提示 #
win.setAppDetails(options) (win)设置窗口任务栏按钮的属性 #
win.showDefinitionForSelection() (mac)webContents.showDefinitionForSelection() 相同 #
win.setIcon(icon) (win/linux)设置窗口图标 #
win.setWindowButtonVisibility(visible) (mac)设置是否窗口交通灯需要显示 #
win.setAutoHideMenuBar(hide) (win/linux)设置窗口菜单栏是否自动隐藏 #
win.isMenuBarAutoHide() (win/linux)判断窗口的菜单栏是否自动隐藏 #
win.setMenuBarVisibility(visible) (win/linux)设置菜单栏是否可见 #
win.isMenuBarVisible() (win/linux)判断窗口的菜单栏是否可见 #
win.setVisibleOnAllWorkspaces(visible[, options]) (mac/linux)设置窗口是否在所有工作空间上可见 #
win.isVisibleOnAllWorkspaces() (mac/linux)判断窗口是否在所有工作空间上可见 #
win.setIgnoreMouseEvents(ignore[, options])忽略窗口内的所有鼠标事件 #
win.setContentProtection(enable) (mac/linux)防止窗口内容被其他应用捕获 #
win.setFocusable(focusable) (mac/linux)设置窗口是否可聚焦 #
win.isFocusable() (mac/linux)返回当前窗口是否可以作为焦点被选中 #
win.setParentWindow(parent)设置 parent 为当前窗口的父窗口 #
win.getParentWindow()返回 BrowserWindow/null - 如果没有父窗口则为 null #
win.getChildWindows()返回 BrowserWindow[] - 首页的子窗口 #
win.setAutoHideCursor(autoHide) (mac)设置输入时是否隐藏光标 #
win.selectPreviousTab() (mac)当启用本地选项卡,并且窗口中有另一个标签时,选择上一个选项卡 #
win.selectNextTab() (mac)当启用本地选项卡,并且窗口中有另一个标签时,选择下一个选项卡 #
win.mergeAllWindows() (mac)当启用本地选项卡并且存在多个打开窗口时,将所有窗口合并到一个带有多个选项卡的窗口中 #
win.moveTabToNewWindow() (mac)如果启用了本机选项卡并且当前窗口中有多个选项卡,则将当前选项卡移动到新窗口中 #
win.toggleTabBar() (mac)如果启用了本机选项卡并且当前窗口中只有一个选项卡,则切换选项卡栏是否可见 #
win.addTabbedWindow(browserWindow) (mac)在该窗口中添加一个窗口作为选项卡,位于窗口实例的选项卡之后 #
win.setVibrancy(type) (mac)在浏览器窗口中添加一个动态特效。 传递 null 或空字符串将会移除窗口上的动态效果 #
win.setTrafficLightPosition(position) (mac)在无框窗口中设置自定义控制按钮的位置 #
win.getTrafficLightPosition() (mac)在无框窗口中自定义控制按钮的位置 #
win.setTouchBar(touchBar) (mac)设置窗口的触摸条布局 设置为 null 或undefined将清除触摸条 #
win.setBrowserView(browserView) (实验)#
win.getBrowserView() (实验功能)#
win.addBrowserView(browserView) (实验功能)#
win.removeBrowserView(browserView) (实验功能)#
win.setTopBrowserView(browserView) (实验功能)#
win.getBrowserViews() (实验功能)#
win.setTitleBarOverlay(options) (win)在已开启 Window Controls Overlay 的窗口上,此方法将更新标题栏叠加层的样式 #

静态方法

:-:-
BrowserWindow.getAllWindows()所有打开的窗口的数组 #
BrowserWindow.getFocusedWindow()当前获得焦点的窗口 #
BrowserWindow.fromWebContents(webContents)拥有给定 webContents 窗口 #
BrowserWindow.fromBrowserView(browserView)拥有给定 browserView 窗口 #
BrowserWindow.fromId(id)带有给定 id 的窗口 #

实例属性

const { BrowserWindow } = require('electron')
// 本例中 `win` 是我们的实例
const win = new BrowserWindow({ width: 800, height: 600 })
win.loadURL('https://github.com')

:-:-
win.webContents此窗口拥有的 WebContents 对象 #
win.id代表了窗口的唯一ID #
win.autoHideMenuBar决定窗口菜单栏是否自动隐藏 #
win.simpleFullScreen决定窗口是否处于简单(pre-Lion) 全屏模式 #
win.fullScreen决定窗口是否处于全屏模式 #
win.focusable确定窗口是否可作为焦点被选中的属性 #
win.visibleOnAllWorkspaces决定窗口是否在所有工作区中可见 #
win.shadow决定窗口是否显示阴影 #
win.menuBarVisible决定菜单栏是否可见 #
win.kiosk决定窗口是否处于kiosk模式 #
win.documentEdited指明窗口文档是否已被编辑 #
win.representedFilename确定窗口代表的文件的路径名 #
win.title用于确定原生窗口的标题 #
win.minimizable决定窗口是否可被用户手动最小化 #
win.maximizable决定窗口是否可被用户手动最大化 #
win.fullScreenable决定是切换全屏模式还是最大化窗口 #
win.resizable决定窗口是否可被用户手动调整大小 #
win.closable决定窗口是否可被用户手动关闭 #
win.movable决定窗口是否可被用户移动 #
win.excludedFromShownWindowsMenu决定窗口是否从 Windows 菜单排除 #
win.accessibleTitle定义一个仅为辅助工具提供的替代标题 #

另见