# BrowserWindow
> 创建并控制浏览器窗口。
```javascript
// 主进程中
const {BrowserWindow} = require('electron')
// 或者在渲染进程中使用 `remote`
// const {BrowserWindow} = require('electron').remote
let win = new BrowserWindow({width: 800, height: 600})
win.on('closed', () => {
win = null
})
// 载入一个远程 URL
win.loadURL('https://github.com')
// 或者载入本地 HTML 文件
win.loadURL(`file://${__dirname}/app/index.html`)
```
## 无框架窗口
要创建一个没有 chrome,或者一个任意形状的透明窗口,可以使用 [Frameless Window](frameless-window.md) API。
## 优雅的显示窗口
当直接在一个窗口中载入一个页面,用户将看到一个加载页面的进度条,对于原生应用这并不是一个好的体验。要让窗口不显示视觉效果,对于不同的情况有两种方案。
### 使用 `ready-to-show` 事件
载入页面时, `ready-to-show` 事件会在渲染进程已经完成首次绘制时被发送,在这个事件之后显示窗口,就不会看到视觉效果:
```javascript
const {BrowserWindow} = require('electron')
let win = new BrowserWindow({show: false})
win.once('ready-to-show', () => {
win.show()
})
```
这个事件通常在 `did-finish-load` 事件之后发送,但是对于有太多远程资源的页面,也有可能在 `did-finish-load` 事件之前发送。
### 设置 `backgroundColor`
对于一个复杂的应用, `ready-to-show` 事件可能很晚才被发送,使应用感觉很慢。这种情况,建议立即显示窗口,并使用一个接近应用背景的 `backgroundColor` :
```javascript
const {BrowserWindow} = require('electron')
let win = new BrowserWindow({backgroundColor: '#2e2c29'})
win.loadURL('https://github.com')
```
注意,即使使用了 `ready-to-show` 事件的应用,仍然建议设置 `backgroundColor` 以使应用感觉更接近原生。
## 父和子窗口
通过使用 `parent` 选项,可以创建子窗口:
```javascript
const {BrowserWindow} = require('electron')
let top = new BrowserWindow()
let child = new BrowserWindow({parent: top})
child.show()
top.show()
```
`child` 窗口总是显示在 `top` 窗口上方。
### 模态窗口
模态窗口是一个禁用了父窗口的子窗口,要创建一个模态差un港口,必须设置 `parent` 和 `modal` 选项:
```javascript
const {BrowserWindow} = require('electron')
let child = new BrowserWindow({parent: top, modal: true, show: false})
child.loadURL('https://github.com')
child.once('ready-to-show', () => {
child.show()
})
```
### 平台注意事项
* 在 macOS 上,当父窗口移动时,子窗口会保持相对于父窗口的位置;而在 Windows 和 Linux 上,子窗口不会移动。
* 在 Windows 上,不支持动态改变父窗口。
* 在 Linux 上,模态窗口的 类型被改变为 `dialog`。
* 在 Linux 上的许多桌面环境不支持隐藏一个模态窗口。
## Class: BrowserWindow
`BrowserWindow` 是一个 [EventEmitter](http://nodejs.org/api/events.html#events_class_events_eventemitter)。
它使用通过 `options` 设置的原生属性创建一个新 `BrowserWindow` 。
### `new BrowserWindow([options])`
* `options` Object
* `width` Integer —— 窗口的像素宽度。默认为 `800`。
* `height` Integer —— 窗口的像素高度。默认为 `600`。
* `x` Integer (**必须** 如果 y 被使用) —— 窗口相对屏幕的左偏移。默认显示在窗口中央。
* `y` Integer (**必须** 如果 x 被使用) —— 窗口相对屏幕的顶部偏移。默认显示在窗口中央。
* `useContentSize` Boolean —— `width` 和 `height` 将被用作 web 页面大小 ,也就是说实际的窗口大小会包含窗口 frame 的大小并且可能略大。默认为 `false`。
* `center` Boolean —— 在屏幕中央显示窗口。
* `minWidth` Integer —— 窗口的最小宽度。默认为 `0`。
* `minHeight` Integer —— 窗口的最小高度。默认为 `0`。
* `maxWidth` Integer —— 窗口的最大宽度。默认没有限制。
* `maxHeight` Integer —— 窗口的最大高度。默认没有限制。
* `resizable` Boolean —— 窗口是否能重设大小。默认为 `true`。
* `movable` Boolean —— 窗口是否可以移动。在 Linux 上没有被实现。默认为 `true`。
* `minimizable` Boolean —— 窗口是否可以最小化。在 Linux 上没有被实现。默认为 `true`。
* `maximizable` Boolean —— 窗口是否可以最大化。在 Linux 上没有被实现。默认为 `true`。
* `closable` Boolean —— 窗口是否可关闭。在 Linux 上没有被实现。默认为 `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`。
* `skipTaskbar` Boolean —— 是否在任务栏中显示窗口。默认为 `false`。
* `kiosk` Boolean —— kiosk 模式。默认为 `false`。
* `title` String —— 默认的窗口标题。默认为 `"Electron"`。
* `icon` [NativeImage](native-image.md) —— 窗口 icon 。在 Windows 上建议使用 `ICO` icons 来获得最好的视觉效果,也可以留为 undefined 将使用可执行程序的 icon 。
* `show` Boolean —— 当窗口创建后是否可以显示。默认为 `true`。
* `frame` Boolean —— 指定为 `false` 来创建一个 [无框架](frameless-window.md)窗口。默认为 `true`。
* `parent` BrowserWindow —— 指定父窗口。默认为 `null`。
* `modal` Boolean —— 是否是一个模态窗口。只有窗口是子窗口的时候才能工作。默认为 `false`。
* `acceptFirstMouse` Boolean —— web 视图是否接受一个独立的 mouse-down 同时激活窗口的事件默认为 `false`。
* `disableAutoHideCursor` Boolean —— 当输入时是否隐藏游标。默认为 `false`。
* `autoHideMenuBar` Boolean —— 自动隐藏菜单栏,除非 `Alt` 键被按下。默认为 `false`。
* `enableLargerThanScreen` Boolean —— 开启窗口可以被设置大于屏幕大小。默认为 `false`。
* `backgroundColor` String —— 十六进制值的窗口背景色,如 `#66CD00` 或 `#FFF` 或 `#80FFFFFF` (支持透明通道)。默认为 `#FFF` (白色)。
* `hasShadow` Boolean —— 窗口是否有阴影。只在 macOS 上实现了。默认为 `true`。
* `darkTheme` Boolean —— 强制为窗口使用 dark 主题,只在一些 GTK+3 桌面环境上工作。默认为 `false`。
* `transparent` Boolean —— 使窗口 [透明](frameless-window.md)。默认为 `false`。
* `type` String —— 窗口类型,默认为一般窗口。在下面会看到更多相关信息。
* `titleBarStyle` String —— 窗口的标题栏样式。默认为 `default`。可能的值为:
* `default` —— 生成一个标准的灰色不透明的 Mac 标题栏。
* `hidden` —— 生成到一个隐藏的标题栏和一个全窗口的内容窗口,但是标题栏仍然保留了标准的窗口控制器("traffic lights")在左上方。
* `hidden-inset` - 生成到一个隐藏的标题栏,另外的外观,traffic light 按钮轻微从窗口边缘插入。
* `thickFrame` Boolean —— 在 Windows 上为无框架窗口使用 `WS_THICKFRAME` 样式,即扩大标准的窗口框架。设置为 `false` 将移除窗口阴影和窗口动画。默认为 `true`。
* `webPreferences` Object —— web 页面的功能设置。
* `devTools` Boolean —— 是否启用开发者工具。如果设置为 `false`,不能使用 `BrowserWindow.webContents.openDevTools()` 打开开发者工具。默认为 `true`。
* `nodeIntegration` Boolean —— 是否启用 node 集成。默认为 `true`。
* `preload` String —— 指定一个会在这个页面中运行的脚本之前加载的脚本。这个脚本一直有权限访问 node APIs 无论是否打开或者关闭了 node 集成。这个值可以是一个脚本的绝对文件路径。当 node 集成被关闭时,preload 脚本可以恢复 Node 的全局符号回到全局作用域。查看 [示例](process.md#event-loaded)。
* `session` [Session](session.md#class-session) —— 设置页面使用的 session 。你可以选择使用 `partition` 选项,即接受一个 partition 字符串,来替代直接传递 Session 对象。当 `session` 和 `partition` 都被提供, `session` 是优先的。默认是默认的 session。
* `partition` String —— 柑橘 session 的 partition 字符串设置页面使用的 session 。如果 `partition` 以 `persist:` 开头,页面会使用一个持久的 session,在 app 中带有相同 `partition` 的页面都可用。如果没有 `persist:` 前缀,页面会使用一个内存中的 session 。通过赋值相同的 `partition`,多个页面可以共享同样的 session。默认为默认的 session 。
* `zoomFactor` Number —— 页面默认的缩放因子, `3.0` 表示 `300%`。默认为 `1.0`。
* `javascript` Boolean —— 启用 JavaScript 支持。默认为 `true`。
* `webSecurity` Boolean —— 当为 `false` 时,将禁用同源策略(通常被用来测试站点),并且如果 `allowDisplayingInsecureContent` 和 `allowRunningInsecureContent` 这两个选项还未被用户设定,会将其设置 为 `true` 。默认为 `true`。
* `allowDisplayingInsecureContent` Boolean —— 允许一个 https 页面显示从 http URLs 而来的如图片内容。默认为 `false`。
* `allowRunningInsecureContent` Boolean —— 允许一个 https 页面运行 JavaScript, CSS 或着由 http URLs 而来的插件。默认为 `false`。
* `images` Boolean —— 启用图片支持。默认为 `true`。
* `textAreasAreResizable` Boolean —— 使 textarea 元素可以被重设大小。默认为 `true`。
* `webgl` Boolean —— 启用 WebGL 支持。默认为 `true`。
* `webaudio` Boolean —— 启用 WebAudio 支持。默认为 `true`。
* `plugins` Boolean —— 插件是否可以被启用。默认为 `false`。
* `experimentalFeatures` Boolean —— 启用 Chromium 的实验性功能。默认为 `false`。
* `experimentalCanvasFeatures` Boolean —— 启用 Chromium 的试验性 canvas 功能。默认为 `false`。
* `scrollBounce` Boolean —— 在 macOS 上启用滚动回弹(橡皮筋)效果 。默认为 `false`。
* `blinkFeatures` String —— 一个特性的字符串列表,通过 `,` 分隔,像 `CSSVariables,KeyboardEventKey` 来启用它们。 支持特性字符串的完整列表可以在 [RuntimeEnabledFeatures.in][blink-feature-string] 文件中找到。
* `disableBlinkFeatures` String —— 一个特性字符串的列表,通过 `,` 分隔,像 `CSSVariables,KeyboardEventKey` 来禁用它们。支持的特性字符串的完整列表可以在 [RuntimeEnabledFeatures.in][blink-feature-string] 文件中找到。
* `defaultFontFamily` Object —— 设置默认的字体
* `standard` String —— 默认为 `Times New Roman`。
* `serif` String —— 默认为 `Times New Roman`。
* `sansSerif` String —— 默认为 `Arial`。
* `monospace` String —— 默认为 `Courier New`。
* `defaultFontSize` Integer —— 默认为 `16`。
* `defaultMonospaceFontSize` Integer —— 默认为 `13`。
* `minimumFontSize` Integer —— 默认为 `0`。
* `defaultEncoding` String —— 默认为 `ISO-8859-1`。
* `backgroundThrottling` Boolean —— 当页面成为背景时是否遏制动画和计时器。默认为 `true`。
* `offscreen` Boolean —— 是否为浏览器窗口开启离屏渲染。默认为 `false`。
* `sandbox` Boolean —— 是否启用 Chromium OS级的沙盒。
当使用 `minWidth`/`maxWidth`/ `minHeight`/`maxHeight` 设置窗口的最小/最大宽高度,它只能约束用户。不能阻止你传递一个不遵照大小约束的值到 `setBounds`/`setSize` 或到 `BrowserWindow` 的构造函数中。
`type` 选项可能的值和行为根据平台而定。
可能的值有:
* 在 Linux 上,可能的类型为 `desktop`, `dock`, `toolbar`, `splash`, `notification`。
* 在 macOS 上,可能的类型为 `desktop`, `textured`。
* `textured` 类型增加金属梯度外观(`NSTexturedBackgroundWindowMask`)。
* `desktop` 类型将窗口置于桌面背景窗口级别(`kCGDesktopWindowLevel - 1`)。注意,桌面窗口不接受焦点、键盘或者鼠标事件,但是可以使用 `globalShortcut` 来接收保守的输入。
* 在 Windows 上,可能的类型为 `toolbar`。
### 实例事件
`new BrowserWindow` 创建的对象发送如下事件:
**注意:** 一些事件只在特定操作系统下有效,会对它们进行标记。
#### Event: 'page-title-updated'
返回:
* `event` Event
* `title` String
当文档改变了标题后发生,调用 `event.preventDefault()` 将阻止原生窗口标题的改变。
#### Event: 'close'
返回:
* `event` Event
当窗口将要被关闭时发生。发生在 DOM 的 `beforeunload` 和 `unload` 事件之前。调用 `event.preventDefault()`
将取消关闭。
通常你可能想要使用 `beforeunload` 处理程序来决定窗口是否应该被关闭,它在窗口被重新载入时也会被调用。在 Electron 中,返回任何值而不是 `undefined` 将会取消关闭。例如:
```javascript
window.onbeforeunload = (e) => {
console.log('I do not want to be closed')
// 不像一般浏览器一个消息框会被提示给用户,返回
// 一个 非 void 的值会静静的取消关闭。
// 建议使用 dialog API 来使用户确认关闭应用
e.returnValue = false
}
```
#### Event: 'closed'
当窗口被关闭后发射。在你接受到这个事件之后,应该移除对窗口的引用避免使用它。
#### Event: 'unresponsive'
当 web 页面变成无响应时发生。
#### Event: 'responsive'
当无响应页面重新响应时发生。
#### Event: 'blur'
当窗口失去焦点时发生。
#### Event: 'focus'
当窗口获得焦点时发生。
#### Event: 'show'
当窗口被显示时发生。
#### Event: 'hide'
当窗口被隐藏时发生。
#### Event: 'ready-to-show'
当 web 页面已经被渲染,而且窗口可以被显示为没有可视载入中效果时发生。
#### Event: 'maximize'
当窗口被最大化时发生。
#### Event: 'unmaximize'
当窗口从最大化退出时发生。
#### Event: 'minimize'
当窗口被最小化时发生。
#### Event: 'restore'
当窗口从一个最小化状态恢复时发生。
#### Event: 'resize'
当窗口被重设大小时发生。
#### Event: 'move'
当窗口被移动到一个新的位置时发生。
__注意__: 在 macOS 上这个事件只是 `moved` 事件的一个别名。
#### Event: 'moved' _macOS_
当窗口被移动到一个新位置时发生一次。
#### Event: 'enter-full-screen'
当窗口进入全屏状态时发生。
#### Event: 'leave-full-screen'
当窗口离开全屏状态时发生。
#### Event: 'enter-html-full-screen'
当窗口被 HTML API 触发进入一个全屏状态时发生。
#### Event: 'leave-html-full-screen'
当窗口离开由 HTML API 触发的全屏时发生。
#### Event: 'app-command' _Windows_
返回:
* `event` Event
* `command` String
当一个 [App Command](https://msdn.microsoft.com/en-us/library/windows/desktop/ms646275(v=vs.85).aspx) 被调用时发生。通常是相关键盘媒体键或者浏览器命令,也包括 Windows 上一些鼠标的 "Back" 键。
命令是小写的,下划线被连接符取代,而且 `APPCOMMAND_` 前缀被剥去。例如 `APPCOMMAND_BROWSER_BACKWARD` 被发送为 `browser-backward`。
```javascript
const {BrowserWindow} = require('electron')
let win = new BrowserWindow()
win.on('app-command', (e, cmd) => {
// 当用户点击它们的鼠标后退按钮,导航窗口后退
if (cmd === 'browser-backward' && win.webContents.canGoBack()) {
win.webContents.goBack()
}
})
```
#### Event: 'scroll-touch-begin' _macOS_
当滚动滚轮事件阶段开始时发生。
#### Event: 'scroll-touch-end' _macOS_
当滚动滚轮事件结束时发生。
#### Event: 'scroll-touch-edge' _macOS_
当滚动滚轮阶段到达元素边缘时发生。
#### Event: 'swipe' _macOS_
返回:
* `event` Event
* `direction` String
3指滑动发生。可能的 `directions` 为 `up`, `right`, `down`, `left`。
### 静态方法
`BrowserWindow` 类有以下静态方法:
#### `BrowserWindow.getAllWindows()`
返回 `BrowserWindow[]` —— 所有打开的浏览器窗口的一个数组。
#### `BrowserWindow.getFocusedWindow()`
返回 `BrowserWindow` —— 应用中获得了焦点的窗口,否则返回 `null`。
#### `BrowserWindow.fromWebContents(webContents)`
* `webContents` [WebContents](web-contents.md)
返回 `BrowserWindow` —— 拥有指定 `webContents` 的窗口。
#### `BrowserWindow.fromId(id)`
* `id` Integer
返回 `BrowserWindow` —— 指定 `id` 的窗口。
#### `BrowserWindow.addDevToolsExtension(path)`
* `path` String
增加位于 `path` 的开发者工具扩展,返回扩展的名字。
扩展 将被记住,所以你只需要调用这个 API 一次,这个 API 不是用于编程。如果你试图增加一个已经载入的扩展,这个方法没有返回,而是记录一个警告到控制台。
如果扩展的 manifest 丢失或者错误,这个方法也不会返回。
**注意:** 在 `app` 模块的 `ready` 事件发生之前这个 API 不能被调用。
#### `BrowserWindow.removeDevToolsExtension(name)`
* `name` String
通过名字移除一个开发者工具扩展。
**注意:** 这个 API 在 `app` 模块的 `ready` 事件发生之前不能被调用。
#### `BrowserWindow.getDevToolsExtensions()`
返回 `Object` —— keys 是扩展的名称,每个值都是一个对象,包括 `name` 和 `version` 属性。
要检查一个开发者工具扩展是否安装,可以运行下面的脚本:
```javascript
const {BrowserWindow} = require('electron')
let installed = BrowserWindow.getDevToolsExtensions().hasOwnProperty('devtron')
console.log(installed)
```
**注意:** 这个 API 在 `app` 模块的 `ready` 事件发生之前不能被调用。
### 实例属性
通过 `new BrowserWindow` 创建的对象有如下属性:
```javascript
const {BrowserWindow} = require('electron')
// In this example `win` is our instance
let win = new BrowserWindow({width: 800, height: 600})
win.loadURL('https://github.com')
```
#### `win.webContents`
一个当前窗口拥有的 `WebContents` 对象。所有 web 页面相关的事件和操作都通过它进行。
查看 [`webContents` documentation](web-contents.md) 了解它的方法和事件。
#### `win.id`
一个 `Integer` ,代表这个窗口唯一的 ID 。
### 实例方法
使用 `new BrowserWindow` 创建的对象有以下实例方法:
**注意:** 一些方法只在特定操作系统有效,将对其进行标记。
#### `win.destroy()`
强制关闭窗口, `unload` 和 `beforeunload` 事件都不会被发送给 web 页面, `close` 事件也不会向这个窗口发送,但是它担保 `closed` 事件会被发送。
#### `win.close()`
尝试关闭窗口。和用户手动点击窗口的关闭按钮有同样效果。web 页面可以取消这个关闭。查看 [close event](#event-close)。
#### `win.focus()`
使窗口获得焦点。
#### `win.blur()`
从这个窗口移除焦点。
#### `win.isFocused()`
返回 `Boolean` —— 窗口是否被聚焦。
#### `win.isDestroyed()`
返回 `Boolean` —— 窗口是否被销毁。
#### `win.show()`
显示并给予窗口焦点。
#### `win.showInactive()`
显示窗口但是不会给予焦点。
#### `win.hide()`
隐藏窗口。
#### `win.isVisible()`
返回 `Boolean` —— 窗口是否对用户可见。
#### `win.isModal()`
返回 `Boolean` —— 当前窗口是否是一个模态窗口。
#### `win.maximize()`
最大化窗口。
#### `win.unmaximize()`
取消窗口最大化。
#### `win.isMaximized()`
返回 `Boolean` —— 窗口是否最大化。
#### `win.minimize()`
最小化窗口。在一些平台上最小化窗口会被显示到 Dock 。
#### `win.restore()`
从最小化状态恢复窗口到前一个状态。
#### `win.isMinimized()`
返回 `Boolean` —— 窗口是否最小化。
#### `win.setFullScreen(flag)`
* `flag` Boolean
设置窗口是否可以进入全屏模式。
#### `win.isFullScreen()`
返回 `Boolean` —— 窗口是否在全屏模式。
#### `win.setAspectRatio(aspectRatio[, extraSize])` _macOS_
* `aspectRatio` Float —— 对于一些内容视图部分要维持的宽高比。
* `extraSize` Object (可选) —— 当维持宽高比时不包括的大小。
* `width` Integer
* `height` Integer
这使一个窗口维持一个宽高比。额外的大小 `extraSize` 允许开发者使用像素指定间隔,不包括在宽高比的计算中。这个 API 已经考虑了窗口大小和它的内容大小的差别。
考虑一个普通窗口中带有一个 HD 视频播放器和相关的控制区域。或者有在左侧边缘有 15像素的 控制区域,右侧边缘有25像素的控制区域,播放器之下也有 50 像素的控制区域。为了在播放器自身中维持一个 16:9 宽高比(HD @1920x1080 的标准宽高比)我们可以调用这个函数,参数为 16/9 和 [ 40, 50 ]。第二个参数不关心哪里是内容视图中额外的宽度和高度 —— 只有它们存在。 只汇总任何已经在整个内容视图中的额外宽度和高度区域。
#### `win.previewFile(path[, displayName])` _macOS_
* `path` String —— 要使用 QuickLook 预览的文件的绝对路径。因为 Quick Look 使用路径上的文件名和扩展名来决定要打开文件的类型,所以这很重要。
* `displayName` String (可选) —— 要在 Quick Look 模态视图中显示的文件的名称。这只是纯粹的显示,并不影响文件的内容类型。默认为 `path`。
使用 [Quick Look][quick-look] 来预览指定 path 的一个文件。
#### `win.setBounds(bounds[, animate])`
* `bounds` [Rectangle](structures/rectangle.md)
* `animate` Boolean (可选)_macOS_
重设大小并移动窗口到提供的边界。
#### `win.getBounds()`
返回 [`Rectangle`](structures/rectangle.md)
#### `win.setContentBounds(bounds[, animate])`
* `bounds` [Rectangle](structures/rectangle.md)
* `animate` Boolean (可选) _macOS_
重设大小并移动窗口的客户端区域(例如 web 页面)到提供的边界。
#### `win.getContentBounds()`
返回 [`Rectangle`](structures/rectangle.md)
#### `win.setSize(width, height[, animate])`
* `width` Integer
* `height` Integer
* `animate` Boolean (可选) _macOS_
重设窗口大小为 `width` `height`。
#### `win.getSize()`
返回 `Integer[]` —— 包含窗口的 width 和 height 。
#### `win.setContentSize(width, height[, animate])`
* `width` Integer
* `height` Integer
* `animate` Boolean (可选) _macOS_
重设窗口的客户端区域(如 web 页面)大小到 `width` 和 `height`。
#### `win.getContentSize()`
返回 `Integer[]` —— 包括窗口的客户端区域的 width 和 height。
#### `win.setMinimumSize(width, height)`
* `width` Integer
* `height` Integer
设置窗口的最小大小到 `width` 和 `height`。
#### `win.getMinimumSize()`
返回 `Integer[]` —— 包括窗口的最小的 width 和 height。
#### `win.setMaximumSize(width, height)`
* `width` Integer
* `height` Integer
设置窗口的最大 `width` 和 `height`。
#### `win.getMaximumSize()`
返回 `Integer[]` —— 包括窗口的最大 width 和 height。
#### `win.setResizable(resizable)`
* `resizable` Boolean
设置窗口是否可以被用户手动重设大小。
#### `win.isResizable()`
返回 `Boolean` —— 窗口是否可以被用户手动重设大小。
#### `win.setMovable(movable)` _macOS_ _Windows_
* `movable` Boolean
设置窗口是否可以被用户移动。在 Linux 上什么也不做。
#### `win.isMovable()` _macOS_ _Windows_
返回 `Boolean` —— 窗口是否可以被用户移动。在 Linux 上总是返回 `true`。
#### `win.setMinimizable(minimizable)` _macOS_ _Windows_
* `minimizable` Boolean
设置窗口是否可以被用户手动最小化。在 Linux 上什么也不做。
#### `win.isMinimizable()` _macOS_ _Windows_
返回 `Boolean` —— 窗口是否可以被用户手动最小化。在 Linux 上总是返回 `true`。
#### `win.setMaximizable(maximizable)` _macOS_ _Windows_
* `maximizable` Boolean
设置窗口是否可以被用户手动最大化。在 Linux 上什么也不做。
#### `win.isMaximizable()` _macOS_ _Windows_
返回 `Boolean` —— 窗口是否可以被用户手动最大化。在 Linux 上总是返回 `true`。
#### `win.setFullScreenable(fullscreenable)`
* `fullscreenable` Boolean
设置窗口的 最大化/缩放 按钮是否可以切换全屏模式或者最大化窗口。
#### `win.isFullScreenable()`
返回 `Boolean` —— 是否窗口的 最大化/缩放按钮 可以切换全屏模式或者最大化窗口。
#### `win.setClosable(closable)` _macOS_ _Windows_
* `closable` Boolean
设置窗口是否可以被用户手动关闭。在 Linux 上什么也不做。
#### `win.isClosable()` _macOS_ _Windows_
返回 `Boolean` —— 窗口是否可以被用户手动关闭。在 Linux 上总是返回 `true`。
#### `win.setAlwaysOnTop(flag[, level])`
* `flag` Boolean
* `level` String (可选) _macOS_ —— 包括 `normal`, `floating`, `torn-off-menu`, `modal-panel`, `main-menu`, `status`, `pop-up-menu`, `screen-saver`,和 `dock` 的值。默认的是 `floating`。查看
[macOS docs][window-levels] 了解详情。
设置窗口是否可以总是显示在其它窗口的上方。当设置了它,窗口仍然是一个普通窗口,而不是一个不能被聚焦的 toolbox 窗口。
#### `win.isAlwaysOnTop()`
返回 `Boolean` —— 是否窗口总是在其它窗口上方。
#### `win.center()`
移动窗口到屏幕中央。
#### `win.setPosition(x, y[, animate])`
* `x` Integer
* `y` Integer
* `animate` Boolean (可选) _macOS_
移动窗口到 `x` 和 `y`。
#### `win.getPosition()`
返回 `Integer[]` —— 包括窗口当前的位置。
#### `win.setTitle(title)`
* `title` String
修改原生窗口的标题为 `title`。
#### `win.getTitle()`
返回 `String` —— 或者原生窗口的标题。
**注意:** web 页面的标题可以不同于原生窗口的标题。
#### `win.setSheetOffset(offsetY[, offsetX])` _macOS_
* `offsetY` Float
* `offsetX` Float (可选)
Changes the attachment point for sheets on macOS. 默认, sheets are
attached just below the window frame, 但是你可能想要在一个 HTML 渲染的工具栏之下显示它们。例如:
```javascript
const {BrowserWindow} = require('electron')
let win = new BrowserWindow()
let toolbarRect = document.getElementById('toolbar').getBoundingClientRect()
win.setSheetOffset(toolbarRect.height)
```
#### `win.flashFrame(flag)`
* `flag` Boolean
开始或者停止闪动窗口来引起用户的注意。
#### `win.setSkipTaskbar(skip)`
* `skip` Boolean
使窗口不显示在任务栏中。
#### `win.setKiosk(flag)`
* `flag` Boolean
进入或者离开 kiosk 模式。
#### `win.isKiosk()`
返回 `Boolean` —— 窗口是否在 kiosk 模式。
#### `win.getNativeWindowHandle()`
返回 `Buffer` —— 平台特定的窗口处理。
在 Windows 上处理程序的原生类型是 `HWND` , 在 macOS 上是 `NSView*` ,在 Linux 上是 `Window` (`unsigned long`)。
#### `win.hookWindowMessage(message, callback)` _Windows_
* `message` Integer
* `callback` Function
挂住一个窗口消息。 当消息在 WndProc 中被接收到 `callback` 被调用。
#### `win.isWindowMessageHooked(message)` _Windows_
* `message` Integer
返回 `Boolean` —— `true` 或 `false` 取决于消息是否被挂住。
#### `win.unhookWindowMessage(message)` _Windows_
* `message` Integer
松开窗口消息。
#### `win.unhookAllWindowMessages()` _Windows_
松开所有的窗口消息。
#### `win.setRepresentedFilename(filename)` _macOS_
* `filename` String
设置窗口展现的文件的路径名,和在窗口的标题栏中显示的 文件的 icon 。
#### `win.getRepresentedFilename()` _macOS_
返回 `String` —— 窗口呈现的文件的路径名。
#### `win.setDocumentEdited(edited)` _macOS_
* `edited` Boolean
指定窗口的文档是否被编辑过,如果设置为 `true` 标题栏中的 icon 将会变灰。
#### `win.isDocumentEdited()` _macOS_
是否 `Boolean` —— 窗口的文档是否被编辑过。
#### `win.focusOnWebView()`
#### `win.blurWebView()`
#### `win.capturePage([rect, ]callback)`
* `rect` [Rectangle](structures/rectangle.md) (可选) —— 要捕获的边界。
* `callback` Function
* `image` [NativeImage](native-image.md)
和 `webContents.capturePage([rect, ]callback)` 相同。
#### `win.loadURL(url[, options])`
* `url` URL
* `options` Object (可选)
* `httpReferrer` String —— 一个 HTTP Referrer url。
* `userAgent` String —— 一个请求源的用户代理。
* `extraHeaders` String —— 通过 "\n" 分隔的额外的 headers。
和 `webContents.loadURL(url[, options])` 相同。
`url` 可以是一个远程地址(例如 `http://`)或者一个本地 HTML 文件路径,使用 `file://` 协议。
要确保文件 URLs 被正确的格式化,建议使用 Node 的 [`url.format`](https://nodejs.org/api/url.html#url_url_format_urlobject) 方法:
```javascript
let url = require('url').format({
protocol: 'file',
slashes: true,
pathname: require('path').join(__dirname, 'index.html')
})
win.loadURL(url)
```
#### `win.reload()`
和 `webContents.reload` 相同。
#### `win.setMenu(menu)` _Linux_ _Windows_
* `menu` Menu
设置 `menu` 作为窗口的菜单栏。设置为 `null` 将会移除菜单栏。
#### `win.setProgressBar(progress[, options])`
* `progress` Double
* `options` Object (可选)
* `mode` String _Windows_ —— 进度条的模式(`none`, `normal`, `indeterminate`, `error`, 或 `paused`)
设置进度条中的进度值。有效范围在 [0, 1.0]。
当进度小于0时移除进度条;
当进度大于1进入不确定模式。
在 Linux 平台,只支持 Unity 桌面环境,你需要在 `package.json` 中指定 `*.desktop` 文件名到 `desktopName` 字段 。默认,它将假设 `app.getName().desktop`。
在 Windows 上,一个模式可以被传递。接受的值为 `none`, `normal`,`indeterminate`, `error` 和 `paused`。 如果你调用 `setProgressBar` 而没有使用一个模式设置(但是有一个可用范围的值), `normal` 被会假定。
#### `win.setOverlayIcon(overlay, description)` _Windows_
* `overlay` [NativeImage](native-image.md) —— 任务栏 icon右下角显示的 icon 。如果这个参数是 `null`, 覆盖被清除。
* `description` String —— 将会提供给易访问屏幕阅读器的一个描述。
设置一个 16 x 16 像素的覆盖到当前的任务栏 icon ,通常用来传达一些应用状态的种类或者消极通知用户。
#### `win.setHasShadow(hasShadow)` _macOS_
* `hasShadow` Boolean
设置窗口是否有一个阴影。在 Windows 和 Linux 上什么也不做。
#### `win.hasShadow()` _macOS_
返回 `Boolean` —— 窗口是否有一个阴影。
在 Windows 和 Linux 上总是返回 `true`。
#### `win.setThumbarButtons(buttons)` _Windows_
* `buttons` [ThumbarButton[]](structures/thumbar-button.md)
返回 `Boolean` —— 是否按钮添加成功。
使用一个指定的按钮设置增加一个缩略图工具栏到任务栏按钮布局中。返回一个 `Boolean` 对象表示缩略图是否被成功添加。
在缩略图工具栏中按钮的数量,由于有限的空间应该不大于 7。 一旦设置了缩略图工具栏,由于平台的限制工具栏不能被移除。但是你可以调用这个 API 使用一个空的数组来清除按钮。
`buttons` 是一个 `Button` 对象的数组:
* `Button` Object
* `icon` [NativeImage](native-image.md) —— 显示在缩略图工具栏中的 icon 。
* `click` Function
* `tooltip` String (可选) —— 按钮的 tooltip 的文本。
* `flags` String[] (可选) —— 控制指定按钮的状态和行为。默认的,它是 `['enabled']`。
`flags` 是一个可以包含如下 `String` 的数组:
* `enabled` —— 按钮激活并可以被用户使用。
* `disabled` —— 按钮被禁用。它被呈现,但是有一个表示不能响应用户操作的可视状态。
* `dismissonclick` —— 当按钮被点击,缩略图窗口会被立即关闭。
* `nobackground` —— 不绘制按钮 border,只使用图片。
* `hidden` —— 按钮不显示给用户。
* `noninteractive` —— 按钮被启用,但是没有交互;不绘制按下按钮状态。这个值被用在一个通知中的按钮实例继承。
#### `win.setThumbnailClip(region)` _Windows_
* `region` [Rectangle](structures/rectangle.md) —— 窗口范围。
设置当悬停到任务栏上的窗口上时显示为缩略图的窗口的区域。可以通过指定一个空的范围重设缩略图为整个窗口:`{x: 0, y: 0, width: 0, height: 0}`.
#### `win.setThumbnailToolTip(toolTip)` _Windows_
* `toolTip` String
设置当悬停到任务栏上的窗口缩略图时显示的 toolTip 。
#### `win.showDefinitionForSelection()` _macOS_
和 `webContents.showDefinitionForSelection()` 相同。
#### `win.setIcon(icon)` _Windows_ _Linux_
* `icon` [NativeImage](native-image.md)
修改窗口 icon。
#### `win.setAutoHideMenuBar(hide)`
* `hide` Boolean
设置窗口菜单栏是否可以自己自动隐藏。一旦设置,菜单栏只有当用户按下 `Alt` 键才能显示。
如果菜单栏已经可见,调用 `setAutoHideMenuBar(true)` 不会立即隐藏它。
#### `win.isMenuBarAutoHide()`
返回 `Boolean` —— 菜单栏是否自己自动隐藏。
#### `win.setMenuBarVisibility(visible)` _Windows_ _Linux_
* `visible` Boolean
设置菜单栏是否可见。如果菜单栏是自动隐藏,用户仍然可以通过按下 `Alt` 键调出菜单栏。
#### `win.isMenuBarVisible()`
返回 `Boolean` —— 菜单栏是否可见。
#### `win.setVisibleOnAllWorkspaces(visible)`
* `visible` Boolean
设置窗口是否可以显示在所有工作空间。
**注意:** 这个 API 在 Windows 上不做任何事。
#### `win.isVisibleOnAllWorkspaces()`
返回 `Boolean` —— 窗口是否在所有工作空间中可见。
**注意:** 这个 API 在 Windows 上总是返回 false 。
#### `win.setIgnoreMouseEvents(ignore)`
* `ignore` Boolean
使窗口忽略所有的鼠标事件。
这个窗口上发生的所有鼠标事件都会被传递到下面的窗口,但是如果这个窗口有焦点,仍然可以接受键盘事件。
#### `win.setContentProtection(enable)` _macOS_ _Windows_
* `enable` Boolean
阻止窗口内容被其它应用捕获。
在 macOS 上它设置 `NSWindow` 的 `sharingType` 为 `NSWindowSharingNone`。
在 Windows 上它调用 `SetWindowDisplayAffinity` 使用 `WDA_MONITOR`。
#### `win.setFocusable(focusable)` _Windows_
* `focusable` Boolean
修改窗口是否可以获得焦点。
* [blink-feature-string]: https://cs.chromium.org/chromium/src/third_party/WebKit/Source/platform/RuntimeEnabledFeatures.in
#### `win.setParentWindow(parent)` _Linux_ _macOS_
* `parent` BrowserWindow
设置 `parent` 作为当前窗口的父窗口,传递 `null` 会使当前窗口成为一个 toop-level 窗口。
#### `win.getParentWindow()`
返回 `BrowserWindow` —— 父窗口。
#### `win.getChildWindows()`
返回 `BrowserWindow[]` —— 所有子窗口。
* [window-levels]: https://developer.apple.com/reference/appkit/nswindow/1664726-window_levels
* [quick-look]: https://en.wikipedia.org/wiki/Quick_Look
- 索引
- 前言.关于Electron
- 第一部分 开发指南
- 第1章.平台支持
- 第2章.安全、原生功能和你的责任
- 第3章.版本说明
- 第4章.发行应用
- 第5章.Mac App商店提交指南
- 第6章.Windows商店指南
- 第7章.应用打包
- 第8章.使用Node原生模块
- 第9章.调试主进程
- 9.1.在VSCode中调试
- 9.2.在node-inspector中调试
- 第10章.使用Selenium和WebDriver
- 第11章.DevTools扩展
- 第12章.使用Pepper Flash插件
- 第13章.使用Widevine CDM插件
- 第14章.通过自动化持续集成系统进行测试
- 第15章.离屏渲染
- 第二部分 使用教程
- 第16章.快速入门
- 第17章.桌面环境集成
- 第18章.在线/离线事件探测
- 第19章.应答式编译器(REPL)
- 第三部分 API参考
- 第20章.API简介
- 第21章.进程对象
- 第22章.Chrome的命令行开关
- 第23章.环境变量
- 第24章.定制的DOM元素
- 24.1.File 对象
- 24.2.webview 标签
- 第25章.主进程模块
- 25.1.app
- 25.2.BrowserWindow
- 25.3.无框架窗口
- 第26章.渲染进程模块
- 第27章.两种进程可用的模块
- 第四部分 高级主题
- 附 FAQ
- 附 文档规范
- 附 示例用例
- 1.无边框窗口