diff --git a/docs-translations/zh-CN/api/browser-window.md b/docs-translations/zh-CN/api/browser-window.md new file mode 100644 index 000000000000..6e486406d63c --- /dev/null +++ b/docs-translations/zh-CN/api/browser-window.md @@ -0,0 +1,761 @@ +# BrowserWindow + + `BrowserWindow` 类让你有创建一个浏览器窗口的权力。例如: + +```javascript +// In the main process. +const BrowserWindow = require('electron').BrowserWindow; + +// Or in the renderer process. +const BrowserWindow = require('electron').remote.BrowserWindow; + +var win = new BrowserWindow({ width: 800, height: 600, show: false }); +win.on('closed', function() { + win = null; +}); + +win.loadURL('https://github.com'); +win.show(); +``` + +你也可以不通过chrome创建窗口,使用 +[Frameless Window](frameless-window.md) API. + +## 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` Integer - 窗口相对于屏幕的顶部偏移位置.默认居中. + * `useContentSize` Boolean - `width` 和 `height` 使用web网页size, 这意味着实际窗口的size应该包括窗口框架的size,稍微会大一点,默认为 `false`. + * `center` Boolean - 窗口屏幕居中. + * `minWidth` Integer - 窗口最小宽度,默认为 `0`. + * `minHeight` Integer - 窗口最小高度,默认为 `0`. + * `maxWidth` Integer - 窗口最大宽度,默认无限制. + * `maxHeight` Integer - 窗口最大高度,默认无限制. + * `resizable` Boolean - 是否可以改变窗口size,默认为 `true`. + * `movable` Boolean - 窗口是否可以拖动. 在 Linux 上无效. 默认为 `true`. + * `minimizable` Boolean - 窗口是否可以最小化. 在 Linux 上无效. 默认为 `true`. + * `maximizable` Boolean - 窗口是否可以最大化. 在 Linux 上无效. 默认为 `true`. + * `closable` Boolean - 窗口是否可以关闭. 在 Linux 上无效. 默认为 `true`. + * `alwaysOnTop` Boolean - 窗口是否总是显示在其他窗口之前. 在 Linux 上无效. 默认为 `false`. + * `fullscreen` Boolean - 窗口是否可以全屏幕. 当明确设置值为When `false` ,全屏化按钮将会隐藏,在 OS X 将禁用. 默认 `false`. + * `fullscreenable` Boolean - 在 OS X 上,全屏化按钮是否可用,默认为 `true`. + * `skipTaskbar` Boolean - 是否在人物栏中显示窗口. 默认是`false`. + * `kiosk` Boolean - kiosk 方式. 默认为 `false`. + * `title` String - 窗口默认title. 默认 `"Electron"`. + * `icon` [NativeImage](native-image.md) - 窗口图标, 如果不设置,窗口将使用可用的默认图标. + * `show` Boolean - 窗口创建的时候是否显示. 默认为 `true`. + * `frame` Boolean - 指定 `false` 来创建一个 + [Frameless Window](frameless-window.md). 默认为 `true`. + * `acceptFirstMouse` Boolean - 是否允许单击web view来激活窗口 . 默认为 `false`. + * `disableAutoHideCursor` Boolean - 当 typing 时是否隐藏鼠标.默认 `false`. + * `autoHideMenuBar` Boolean - 除非点击 `Alt`,否则隐藏菜单栏.默认为 `false`. + * `enableLargerThanScreen` Boolean - 是否允许允许改变窗口大小大于屏幕. 默认是 `false`. + * `backgroundColor` String -窗口的 background color 值为十六进制,如 `#66CD00` 或 `#FFF` 或 `#80FFFFFF` (支持透明度). 默认为在 Linux 和 Windows 上为 + `#000` (黑色) , Mac上为 `#FFF`(或透明). + * `hasShadow` Boolean - 窗口是否有阴影. 只在 OS X 上有效. 默认为 `true`. + * `darkTheme` Boolean - 为窗口使用 dark 主题, 只在一些拥有 GTK+3 桌面环境上有效. 默认为 `false`. + * `transparent` Boolean - 窗口 [透明](frameless-window.md). + 默认为 `false`. + * `type` String - 窗口type, 默认普通窗口. 下面查看更多. + * `titleBarStyle` String - 窗口标题栏样式. 下面查看更多. + * `webPreferences` Object - 设置界面特性. 下面查看更多. + +`type` 的值和效果不同平台展示效果不同,具体: + +* Linux, 可用值为 `desktop`, `dock`, `toolbar`, `splash`, + `notification`. +* OS X, 可用值为 `desktop`, `textured`. + * `textured` type 添加金属梯度效果 + (`NSTexturedBackgroundWindowMask`). + * `desktop` 设置窗口在桌面背景窗口水平 + (`kCGDesktopWindowLevel - 1`). 注意桌面窗口不可聚焦, 不可不支持键盘和鼠标事件, 但是可以使用 `globalShortcut` 来解决输入问题. + +`titleBarStyle` 只在 OS X 10.10 Yosemite 或更新版本上支持. +可用值: + +* `default` 以及无值, 显示在 Mac 标题栏上为不透明的标准灰色. +* `hidden` 隐藏标题栏,内容充满整个窗口, 然后它依然在左上角,仍然受标准窗口控制. +* `hidden-inset`主体隐藏,显示小的控制按钮在窗口边缘. + +`webPreferences` 参数是个对象,它的属性: + +* `nodeIntegration` Boolean - 是否完整支持node. 默认为 `true`. +* `preload` String - 界面的其它脚本运行之前预先加载一个指定脚本. 这个脚本将一直可以使用 node APIs 无论 node integration 是否开启. 脚本路径为绝对路径. + 当 node integration 关闭, 预加载的脚本将从全局范围重新引入node的全局引用标志. 查看例子 + [here](process.md#event-loaded). +* `session` [Session](session.md#class-session) - 设置界面session. 而不是直接忽略session对象 , 也可用 `partition` 来代替, 它接受一个 partition 字符串. 当同时使用 `session` 和 `partition`, `session` 优先级更高. + 默认使用默认 session. +* `partition` String - 通过session的partition字符串来设置界面session. 如果 `partition` 以 `persist:` 开头, 这个界面将会为所有界面使用相同的 `partition`. 如果没有 `persist:` 前缀, 界面使用历史session. 通过分享同一个 `partition`, 所有界面使用相同的session. 默认使用默认 session. +* `zoomFactor` Number - 界面默认缩放值, `3.0` 表示 + `300%`. 默认 `1.0`. +* `javascript` Boolean - 开启javascript支持. 默认为`true`. +* `webSecurity` Boolean - 当设置为 `false`, 它将禁用相同地方的规则 (通常测试服), 并且如果有2个非用户设置的参数,就设置 + `allowDisplayingInsecureContent` 和 `allowRunningInsecureContent` 的值为 + `true`. 默认为 `true`. +* `allowDisplayingInsecureContent` Boolean -允许一个使用 https的界面来展示由 http URLs 传过来的资源. 默认`false`. +* `allowRunningInsecureContent` Boolean - Boolean -允许一个使用 https的界面来渲染由 http URLs 提交的html,css,javascript. 默认为 `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`. +* `directWrite` Boolean - 开启窗口的 DirectWrite font 渲染系统. 默认为 `true`. +* `blinkFeatures` String - 以 `,` 分隔的特性列表, 如 + `CSSVariables,KeyboardEventKey`. 被支持的所有特性可在 [setFeatureEnabledFromString][blink-feature-string] + 中找到. +* `defaultFontFamily` Object - 设置 font-family 默认字体. + * `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`. + +## 事件 + + `BrowserWindow` 对象可触发下列事件: + +**注意:** 一些事件只能在特定os环境中触发,已经尽可能地标出. + +### Event: 'page-title-updated' + +返回: + +* `event` Event + +当文档改变标题时触发,使用 `event.preventDefault()` 可以阻止原窗口的标题改变. + +### Event: 'close' + +返回: + +* `event` Event + +在窗口要关闭的时候触发. 它在DOM的 `beforeunload` and `unload` 事件之前触发.使用 `event.preventDefault()` 可以取消这个操作 + +通常你想通过 `beforeunload` 处理器来决定是否关闭窗口,但是它也会在窗口重载的时候被触发. 在 Electron 中,返回一个空的字符串或 `false` 可以取消关闭.例如: + +```javascript +window.onbeforeunload = function(e) { + console.log('I do not want to be closed'); + + // Unlike usual browsers, in which a string should be returned and the user is + // prompted to confirm the page unload, Electron gives developers more options. + // Returning empty string or false would prevent the unloading now. + // You can also use the dialog API to let the user confirm closing the application. + e.returnValue = false; +}; +``` + +### Event: 'closed' + +当窗口已经关闭的时候触发.当你接收到这个事件的时候,你应当删除对已经关闭的窗口的引用对象和避免再次使用它. + +### Event: 'unresponsive' + +在界面卡死的时候触发事件. + +### Event: 'responsive' + +在界面恢复卡死的时候触发. + +### Event: 'blur' + +在窗口失去焦点的时候触发. + +### Event: 'focus' + +在窗口获得焦点的时候触发. + +### Event: 'maximize' + +在窗口最大化的时候触发. + +### Event: 'unmaximize' + +在窗口退出最大化的时候触发. + +### Event: 'minimize' + +在窗口最小化的时候触发. + +### Event: 'restore' + +在窗口从最小化恢复的时候触发. + +### Event: 'resize' + +在窗口size改变的时候触发. + +### Event: 'move' + +在窗口移动的时候触发. + +注意:在 OS X 中别名为 `moved`. + +### Event: 'moved' _OS X_ + +在窗口移动的时候触发. + +### 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_ + +在请求一个[App Command](https://msdn.microsoft.com/en-us/library/windows/desktop/ms646275(v=vs.85).aspx)的时候触发. +典型的是键盘媒体或浏览器命令, Windows上的 "Back" 按钮用作鼠标也会触发. + +```js +someWindow.on('app-command', function(e, cmd) { + // Navigate the window back when the user hits their mouse back button + if (cmd === 'browser-backward' && someWindow.webContents.canGoBack()) { + someWindow.webContents.goBack(); + } +}); +``` + +### Event: 'scroll-touch-begin' _OS X_ + +在滚动条事件开始的时候触发. + +### Event: 'scroll-touch-end' _OS X_ + +在滚动条事件结束的时候触发. + +## 方法 + +`BrowserWindow` 对象有如下方法: + +### `BrowserWindow.getAllWindows()` + +返回一个所有已经打开了窗口的对象数组. + +### `BrowserWindow.getFocusedWindow()` + +返回应用当前获得焦点窗口,如果没有就返回 `null`. + +### `BrowserWindow.fromWebContents(webContents)` + +* `webContents` [WebContents](web-contents.md) + +根据 `webContents` 查找窗口. + +### `BrowserWindow.fromId(id)` + +* `id` Integer + +根据 id 查找窗口. + +### `BrowserWindow.addDevToolsExtension(path)` + +* `path` String + +添加位于 `path` 的开发者工具栏扩展,并且返回扩展项的名字. + +这个扩展会被添加到历史,所以只需要使用这个API一次,这个api不可用作编程使用. + +### `BrowserWindow.removeDevToolsExtension(name)` + +* `name` String + +删除开发者工具栏名为 `name` 的扩展. + +## 实例属性 + +使用 `new BrowserWindow` 创建的实例对象,有如下属性: + +```javascript +// In this example `win` is our instance +var win = new BrowserWindow({ width: 800, height: 600 }); +``` + +### `win.webContents` + +这个窗口的 `WebContents` 对象,所有与界面相关的事件和方法都通过它完成的. + +查看 [`webContents` documentation](web-contents.md) 的方法和事件. + +### `win.id` + +窗口的唯一id. + +## 实例方法 + +使用 `new BrowserWindow` 创建的实例对象,有如下方法: + +**注意:** 一些方法只能在特定os环境中调用,已经尽可能地标出. + +### `win.destroy()` + +强制关闭窗口, `unload` and `beforeunload` 不会触发,并且 `close` 也不会触发, 但是它保证了 `closed` 触发. + +### `win.close()` + +尝试关闭窗口,这与用户点击关闭按钮的效果一样. 虽然网页可能会取消关闭,查看 [close event](#event-close). + +### `win.focus()` + +窗口获得焦点. + +### `win.isFocused()` + +返回 boolean, 窗口是否获得焦点. + +### `win.show()` + +展示并且使窗口获得焦点. + +### `win.showInactive()` + +展示窗口但是不获得焦点. + +### `win.hide()` + +隐藏窗口. + +### `win.isVisible()` + +返回 boolean, 窗口是否可见. + +### `win.maximize()` + +窗口最大化. + +### `win.unmaximize()` + +取消窗口最大化. + +### `win.isMaximized()` + +返回 boolean, 窗口是否最大化. + +### `win.minimize()` + +窗口最小化. 在一些os中,它将在dock中显示. + +### `win.restore()` + +将最小化的窗口恢复为之前的状态. + +### `win.isMinimized()` + +返回 boolean, 窗口是否最小化. + +### `win.setFullScreen(flag)` + +* `flag` Boolean + +设置是否全屏. + +### `win.isFullScreen()` + +返回 boolean, 窗口是否全屏化. + +### `win.setAspectRatio(aspectRatio[, extraSize])` _OS X_ + +* `aspectRatio` 维持部分视图内容窗口的高宽比值. +* `extraSize` Object (可选) - 维持高宽比值时不包含的额外size. + * `width` Integer + * `height` Integer + +由一个窗口来维持高宽比值. `extraSize` 允许开发者使用它,它的单位为像素,不包含在 `aspectRatio` 中.这个 API 可用来区分窗口的size和内容的size . + +想象一个普通可控的HD video 播放器窗口. 假如左边缘有15控制像素,右边缘有25控制像素,在播放器下面有50控制像素.为了在播放器内保持一个 16:9 的高宽比例,我们可以调用这个api传入参数16/9 and +[ 40, 50 ].第二个参数不管网页中的额外的宽度和高度在什么位置,只要它们存在就行.只需要把网页中的所有额外的高度和宽度加起来就行. + +### `win.setBounds(options[, animate])` + +* `options` Object + * `x` Integer + * `y` Integer + * `width` Integer + * `height` Integer +* `animate` Boolean (可选) _OS X_ + +重新设置窗口的宽高值,并且移动到指定的 `x`, `y` 位置. + +### `win.getBounds()` + +返回一个对象,它包含了窗口的宽,高,x坐标,y坐标. + +### `win.setSize(width, height[, animate])` + +* `width` Integer +* `height` Integer +* `animate` Boolean (可选) _OS X_ + +重新设置窗口的宽高值. + +### `win.getSize()` + +返回一个数组,它包含了窗口的宽,高. + +### `win.setContentSize(width, height[, animate])` + +* `width` Integer +* `height` Integer +* `animate` Boolean (可选) _OS X_ + +重新设置窗口客户端的宽高值(例如网页界面). + +### `win.getContentSize()` + +返回一个数组,它包含了窗口客户端的宽,高. + +### `win.setMinimumSize(width, height)` + +* `width` Integer +* `height` Integer + +设置窗口最小化的宽高值. + +### `win.getMinimumSize()` + +返回一个数组,它包含了窗口最小化的宽,高. + +### `win.setMaximumSize(width, height)` + +* `width` Integer +* `height` Integer + +设置窗口最大化的宽高值. + +### `win.getMaximumSize()` + +返回一个数组,它包含了窗口最大化的宽,高. + +### `win.setResizable(resizable)` + +* `resizable` Boolean + +设置窗口是否可以被用户改变size. + +### `win.isResizable()` + +返回 boolean,窗口是否可以被用户改变size. + +### `win.setMovable(movable)` _OS X_ _Windows_ + +* `movable` Boolean + +设置窗口是否可以被用户拖动. Linux 无效. + +### `win.isMovable()` _OS X_ _Windows_ + +返回 boolean,窗口是否可以被用户拖动. Linux 总是返回 `true`. + +### `win.setMinimizable(minimizable)` _OS X_ _Windows_ + +* `minimizable` Boolean + +设置窗口是否可以最小化. Linux 无效. + +### `win.isMinimizable()` _OS X_ _Windows_ + +返回 boolean,窗口是否可以最小化. Linux 总是返回 `true`. + +### `win.setMaximizable(maximizable)` _OS X_ _Windows_ + +* `maximizable` Boolean + +设置窗口是否可以最大化. Linux 无效. + +### `win.isMaximizable()` _OS X_ _Windows_ + +返回 boolean,窗口是否可以最大化. Linux 总是返回 `true`. + +### `win.setFullScreenable(fullscreenable)` + +* `fullscreenable` Boolean + +设置点击最大化按钮是否可以全屏或最大化窗口. + +### `win.isFullScreenable()` + +返回 boolean,点击最大化按钮是否可以全屏或最大化窗口. + +### `win.setClosable(closable)` _OS X_ _Windows_ + +* `closable` Boolean + +设置窗口是否可以人为关闭. Linux 无效. + +### `win.isClosable()` _OS X_ _Windows_ + +返回 boolean,窗口是否可以人为关闭. Linux 总是返回 `true`. + +### `win.setAlwaysOnTop(flag)` + +* `flag` Boolean + +是否设置这个窗口始终在其他窗口之上.设置之后,这个窗口仍然是一个普通的窗口,不是一个不可以获得焦点的工具箱窗口. + +### `win.isAlwaysOnTop()` + +返回 boolean,当前窗口是否始终在其它窗口之前. + +### `win.center()` + +窗口居中. + +### `win.setPosition(x, y[, animate])` + +* `x` Integer +* `y` Integer +* `animate` Boolean (可选) _OS X_ + +移动窗口到对应的 `x` and `y` 坐标. + +### `win.getPosition()` + +返回一个包含当前窗口位置的数组. + +### `win.setTitle(title)` + +* `title` String + +改变原窗口的title. + +### `win.getTitle()` + +返回原窗口的title. + +**注意:** 界面title可能和窗口title不相同. + +### `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` ,OS X `NSView*` , Linux `Window`. + +### `win.hookWindowMessage(message, callback)` _Windows_ + +* `message` Integer +* `callback` Function + +拦截windows 消息,在 WndProc 接收到消息时触发 `callback`函数. + +### `win.isWindowMessageHooked(message)` _Windows_ + +* `message` Integer + +返回 `true` or `false` 来代表是否拦截到消息. + +### `win.unhookWindowMessage(message)` _Windows_ + +* `message` Integer + +不拦截窗口消息. + +### `win.unhookAllWindowMessages()` _Windows_ + +窗口消息全部不拦截. + +### `win.setRepresentedFilename(filename)` _OS X_ + +* `filename` String + +设置窗口当前文件路径,并且将这个文件的图标放在窗口标题栏上. + +### `win.getRepresentedFilename()` _OS X_ + +获取窗口当前文件路径. + +### `win.setDocumentEdited(edited)` _OS X_ + +* `edited` Boolean + +明确指出窗口文档是否可以编辑,如果可以编辑则将标题栏的图标变成灰色. + +### `win.isDocumentEdited()` _OS X_ + +返回 boolean,当前窗口文档是否可编辑. + +### `win.focusOnWebView()` + +### `win.blurWebView()` + +### `win.capturePage([rect, ]callback)` + +* `rect` Object (可选) - 捕获Page位置 + * `x` Integer + * `y` Integer + * `width` Integer + * `height` Integer +* `callback` Function + +捕获 `rect` 中的page 的快照.完成后将调用回调函数 `callback` 并返回 `image` . `image` 是存储了快照信息的[NativeImage](native-image.md)实例.如果不设置 `rect` 则将捕获所有可见page. + +### `win.print([options])` + +类似 `webContents.print([options])` + +### `win.printToPDF(options, callback)` + +类似 `webContents.printToPDF(options, callback)` + +### `win.loadURL(url[, options])` + +类似 `webContents.loadURL(url[, options])`. + +### `win.reload()` + +类似 `webContents.reload`. + +### `win.setMenu(menu)` _Linux_ _Windows_ + +* `menu` Menu + +设置菜单栏的 `menu` ,设置它为 `null` 则表示不设置菜单栏. + +### `win.setProgressBar(progress)` + +* `progress` Double + +在进度条中设置进度值,有效范围 [0, 1.0]. + +当进度小于0时则不显示进度; +当进度大于0时显示结果不确定. + +在libux上,只支持Unity桌面环境,需要指明 `*.desktop` 文件并且在 `package.json` 中添加文件名字.默认它为 `app.getName().desktop`. + +### `win.setOverlayIcon(overlay, description)` _Windows 7+_ + +* `overlay` [NativeImage](native-image.md) - 在底部任务栏右边显示图标. +* `description` String - 描述. + +向当前任务栏添加一个 16 x 16 像素的图标,通常用来覆盖一些应用的状态,或者直接来提示用户. + +### `win.setHasShadow(hasShadow)` _OS X_ + +* `hasShadow` (Boolean) + +设置窗口是否应该有阴影.在Windows和Linux系统无效. + +### `win.hasShadow()` _OS X_ + +返回 boolean,设置窗口是否有阴影.在Windows和Linux系统始终返回 +`true`. + +### `win.setThumbarButtons(buttons)` _Windows 7+_ + +* `buttons` Array + +在窗口的任务栏button布局出为缩略图添加一个有特殊button的缩略图工具栏. 返回一个 `Boolean` 对象来指示是否成功添加这个缩略图工具栏. + +因为空间有限,缩略图工具栏上的 button 数量不应该超过7个.一旦设置了,由于平台限制,就不能移动它了.但是你可使用一个空数组来调用api来清除 buttons . + +所有 `buttons` 是一个 `Button` 对象数组: + +* `Button` Object + * `icon` [NativeImage](native-image.md) - 在工具栏上显示的图标. + * `click` Function + * `tooltip` String (可选) - tooltip 文字. + * `flags` Array (可选) - 控制button的状态和行为. 默认它是 `['enabled']`. + +`flags` 是一个数组,它包含下面这些 `String`s: + +* `enabled` - button 为激活状态并且开放给用户. +* `disabled` -button 不可用. 目前它有一个可见的状态来表示它不会响应你的行为. +* `dismissonclick` - 点击button,这个缩略窗口直接关闭. +* `nobackground` - 不绘制边框,仅仅使用图像. +* `hidden` - button 对用户不可见. +* `noninteractive` - button 可用但是不可响应; 也不显示按下的状态. 它的值意味着这是一个在通知单使用 button 的实例. + +### `win.showDefinitionForSelection()` _OS X_ + +在界面查找选中文字时显示弹出字典. + +### `win.setAutoHideMenuBar(hide)` + +* `hide` Boolean + +设置窗口的菜单栏是否可以自动隐藏. 一旦设置了,只有当用户按下 `Alt` 键时则显示. + +如果菜单栏已经可见,调用 `setAutoHideMenuBar(true)` 则不会立刻隐藏. + +### `win.isMenuBarAutoHide()` + +返回 boolean,窗口的菜单栏是否可以自动隐藏. + +### `win.setMenuBarVisibility(visible)` + +* `visible` Boolean + +设置菜单栏是否可见.如果菜单栏自动隐藏,用户仍然可以按下 `Alt` 键来显示. + +### `win.isMenuBarVisible()` + +返回 boolean,菜单栏是否可见. + +### `win.setVisibleOnAllWorkspaces(visible)` + +* `visible` Boolean + +设置窗口是否在所有地方都可见. + +**注意:** 这个api 在windows无效. + +### `win.isVisibleOnAllWorkspaces()` + +返回 boolean,窗口是否在所有地方都可见. + +**注意:** 在 windows上始终返回 false. + +### `win.setIgnoreMouseEvents(ignore)` _OS X_ + +* `ignore` Boolean + +忽略窗口的所有鼠标事件. + +[blink-feature-string]: https://code.google.com/p/chromium/codesearch#chromium/src/out/Debug/gen/blink/platform/RuntimeEnabledFeatures.cpp&sq=package:chromium&type=cs&l=527 \ No newline at end of file diff --git a/docs-translations/zh-CN/api/content-tracing.md b/docs-translations/zh-CN/api/content-tracing.md new file mode 100644 index 000000000000..fd1edc9bc2f0 --- /dev/null +++ b/docs-translations/zh-CN/api/content-tracing.md @@ -0,0 +1,129 @@ +# contentTracing + +`content-tracing` 模块是用来收集由底层的Chromium content 模块 产生的搜索数据. 这个模块不具备web接口,所有需要我们在chrome浏览器中添加 `chrome://tracing/` 来加载生成文件从而查看结果. + +```javascript +const contentTracing = require('electron').contentTracing; + +const options = { + categoryFilter: '*', + traceOptions: 'record-until-full,enable-sampling' +} + +contentTracing.startRecording(options, function() { + console.log('Tracing started'); + + setTimeout(function() { + contentTracing.stopRecording('', function(path) { + console.log('Tracing data recorded to ' + path); + }); + }, 5000); +}); +``` + +## 方法 + + `content-tracing` 模块的方法如下: + +### `contentTracing.getCategories(callback)` + +* `callback` Function + +获得一组分类组. 分类组可以更改为新的代码路径。 + +一旦所有的子进程都接受到了`getCategories`方法请求, 分类组将调用 `callback`. + +### `contentTracing.startRecording(options, callback)` + +* `options` Object + * `categoryFilter` String + * `traceOptions` String +* `callback` Function + +开始向所有进程进行记录.(recording) + +一旦收到可以开始记录的请求,记录将会立马启动并且在子进程是异步记录听的. 当所有的子进程都收到 `startRecording` 请求的时候,`callback` 将会被调用. + +`categoryFilter`是一个过滤器,它用来控制那些分类组应该被用来查找.过滤器应当有一个可选的 `-` 前缀来排除匹配的分类组.不允许同一个列表既是包含又是排斥. + +例子: + +* `test_MyTest*`, +* `test_MyTest*,test_OtherStuff`, +* `"-excluded_category1,-excluded_category2` + +`traceOptions` 控制着哪种查找应该被启动,这是一个用逗号分隔的列表.可用参数如下: + +* `record-until-full` +* `record-continuously` +* `trace-to-console` +* `enable-sampling` +* `enable-systrace` + +前3个参数是来查找记录模块,并且以后都互斥.如果在`traceOptions` 中超过一个跟踪 +记录模式,那最后一个的优先级最高.如果没有指明跟踪 +记录模式,那么它默认为 `record-until-full`. + +在 `traceOptions` 中的参数被解析应用之前,查找参数初始化默认为 (`record_mode` 设置为 +`record-until-full`, `enable_sampling` 和 `enable_systrace` 设置为 `false`). + +### `contentTracing.stopRecording(resultFilePath, callback)` + +* `resultFilePath` String +* `callback` Function + +停止对所有子进程的记录. + +子进程通常缓存查找数据,并且仅仅将数据截取和发送给主进程.这有利于在通过 IPC 发送查找数据之前减小查找时的运行开销,这样做很有价值.因此,发送查找数据,我们应当异步通知所有子进程来截取任何待查找的数据. + +一旦所有子进程接收到了 `stopRecording` 请求,将调用 `callback` ,并且返回一个包含查找数据的文件. + +如果 `resultFilePath` 不为空,那么将把查找数据写入其中,否则写入一个临时文件.实际文件路径如果不为空,则将调用 `callback` . + +### `contentTracing.startMonitoring(options, callback)` + +* `options` Object + * `categoryFilter` String + * `traceOptions` String +* `callback` Function + +开始向所有进程进行监听.(monitoring) + +一旦收到可以开始监听的请求,记录将会立马启动并且在子进程是异步记监听的. 当所有的子进程都收到 `startMonitoring` 请求的时候,`callback` 将会被调用. + +### `contentTracing.stopMonitoring(callback)` + +* `callback` Function + +停止对所有子进程的监听. + +一旦所有子进程接收到了 `stopMonitoring` 请求,将调用 `callback` . + +### `contentTracing.captureMonitoringSnapshot(resultFilePath, callback)` + +* `resultFilePath` String +* `callback` Function + +获取当前监听的查找数据. + +子进程通常缓存查找数据,并且仅仅将数据截取和发送给主进程.因为如果直接通过 IPC 来发送查找数据的代价昂贵,我们宁愿避免不必要的查找运行开销.因此,为了停止查找,我们应当异步通知所有子进程来截取任何待查找的数据. + +一旦所有子进程接收到了 `captureMonitoringSnapshot` 请求,将调用 `callback` ,并且返回一个包含查找数据的文件. + +### `contentTracing.getTraceBufferUsage(callback)` + +* `callback` Function + +通过查找 buffer 进程来获取百分比最大使用量.当确定了TraceBufferUsage 的值确定的时候,就调用 `callback` . + +### `contentTracing.setWatchEvent(categoryName, eventName, callback)` + +* `categoryName` String +* `eventName` String +* `callback` Function + +任意时刻在任何进程上指定事件发生时将调用 `callback` . + +### `contentTracing.cancelWatchEvent()` + +取消 watch 事件. 如果启动查找,这或许会造成 watch 事件的回调函数 出错. \ No newline at end of file diff --git a/docs-translations/zh-CN/api/dialog.md b/docs-translations/zh-CN/api/dialog.md new file mode 100644 index 000000000000..3e77eeaa2a55 --- /dev/null +++ b/docs-translations/zh-CN/api/dialog.md @@ -0,0 +1,94 @@ +# dialog + +`dialog` 模块提供了api来展示原生的系统对话框,例如打开文件框,alert框,所以web应用可以给用户带来跟系统应用相同的体验. + +对话框例子,展示了选择文件和目录: + +```javascript +var win = ...; // BrowserWindow in which to show the dialog +const dialog = require('electron').dialog; +console.log(dialog.showOpenDialog({ properties: [ 'openFile', 'openDirectory', 'multiSelections' ]})); +``` + +**OS X 上的注意事项**: 如果你想像sheets一样展示对话框,只需要在`browserWindow` 参数中提供一个 `BrowserWindow` 的引用对象. + +## 方法 + +`dialog` 模块有以下方法: + +### `dialog.showOpenDialog([browserWindow, ]options[, callback])` + +* `browserWindow` BrowserWindow (可选) +* `options` Object + * `title` String + * `defaultPath` String + * `filters` Array + * `properties` Array - 包含了对话框的特性值, 可以包含 `openFile`, `openDirectory`, `multiSelections` and + `createDirectory` +* `callback` Function (可选) + +成功使用这个方法的话,就返回一个可供用户选择的文件路径数组,失败返回 `undefined`. + +`filters` 当需要限定用户的行为的时候,指定一个文件数组给用户展示或选择. 例如: + +```javascript +{ + filters: [ + { name: 'Images', extensions: ['jpg', 'png', 'gif'] }, + { name: 'Movies', extensions: ['mkv', 'avi', 'mp4'] }, + { name: 'Custom File Type', extensions: ['as'] }, + { name: 'All Files', extensions: ['*'] } + ] +} +``` + +`extensions` 数组应当只包含扩展名,不应该包含通配符或'.'号 (例如 +`'png'` 正确,但是 `'.png'` 和 `'*.png'` 不正确). 展示全部文件的话, 使用 +`'*'` 通配符 (不支持其他通配符). + +如果 `callback` 被调用, 将异步调用 API ,并且结果将用过 `callback(filenames)` 展示. + +**注意:** 在 Windows 和 Linux ,一个打开的 dialog 不能既是文件选择框又是目录选择框, 所以如果在这些平台上设置 `properties` 的值为 +`['openFile', 'openDirectory']` , 将展示一个目录选择框. + +### `dialog.showSaveDialog([browserWindow, ]options[, callback])` + +* `browserWindow` BrowserWindow (可选) +* `options` Object + * `title` String + * `defaultPath` String + * `filters` Array +* `callback` Function (可选) + +成功使用这个方法的话,就返回一个可供用户选择的文件路径数组,失败返回 `undefined`. + +`filters` 指定展示一个文件类型数组, 例子 +`dialog.showOpenDialog` . + +如果 `callback` 被调用, 将异步调用 API ,并且结果将用过 `callback(filenames)` 展示. + +### `dialog.showMessageBox([browserWindow, ]options[, callback])` + +* `browserWindow` BrowserWindow (可选) +* `options` Object + * `type` String - 可以是 `"none"`, `"info"`, `"error"`, `"question"` 或 + `"warning"`. 在 Windows, "question" 与 "info" 展示图标相同, 除非你使用 "icon" 参数. + * `buttons` Array - buttons 内容,数组. + * `defaultId` Integer - 在message box 对话框打开的时候,设置默认button选中,值为在 buttons 数组中的button索引. + * `title` String - message box 的标题,一些平台不显示. + * `message` String - message box 内容. + * `detail` String - 额外信息. + * `icon` [NativeImage](native-image.md) + * `cancelId` Integer - 当用户关闭对话框的时候,不是通过点击对话框的button,就返回值.默认值为对应 "cancel" 或 "no" 标签button 的索引值, 或者如果没有这种button,就返回0. 在 OS X 和 Windows 上, "Cancel" button 的索引值将一直是 `cancelId`, 不管之前是不是特别指出的. + * `noLink` Boolean - 在 Windows ,Electron 将尝试识别哪个button 是普通 button (如 "Cancel" 或 "Yes"), 然后再对话框中以链接命令(command links)方式展现其它的 button . 这能让对话框展示得很炫酷.如果你不喜欢这种效果,你可以设置 `noLink` 为 `true`. +* `callback` Function + +展示 message box, 它会阻塞进程,直到 message box 关闭为止.返回点击按钮的索引值. + +如果 `callback` 被调用, 将异步调用 API ,并且结果将用过 `callback(response)` 展示. + +### `dialog.showErrorBox(title, content)` + +展示一个传统的包含错误信息的对话框. + +在 `app` 模块触发 `ready` 事件之前,这个 api 可以被安全调用,通常它被用来在启动的早期阶段报告错误. 在 Linux 上,如果在 `app` 模块触发 `ready` 事件之前调用,message 将会被触发显示stderr,并且没有实际GUI 框显示. \ No newline at end of file diff --git a/docs-translations/zh-CN/api/web-view-tag.md b/docs-translations/zh-CN/api/web-view-tag.md new file mode 100644 index 000000000000..f1f3ef9080c5 --- /dev/null +++ b/docs-translations/zh-CN/api/web-view-tag.md @@ -0,0 +1,690 @@ +# `` 标签 + +使用 `webview` 标签来把 'guest' 内容(例如 web pages )嵌入到你的 Electron app 中. guest内容包含在 `webview` 容器中.一个嵌入你应用的page控制着guest内容如何布局摆放和表达含义. + +与 `iframe` 不同, `webview` 和你的应用运行的是不同的进程. 它不拥有渲染进程的权限,并且应用和嵌入内容之间的交互全部都是异步的.因为这能保证应用的安全性不受嵌入内容的影响. + +## 例子 + +把一个 web page 嵌入到你的app,首先添加 `webview` 标签到你的app待嵌入page(展示 guest content). 在一个最简单的 `webview` 中,它包含了 web page 的文件路径和一个控制 `webview` 容器展示效果的css样式: + +```html + +``` + +如果想随时控制 guest 内容,可以添加 JavaScript 脚本来监听 `webview` 事件使用 `webview` 方法来做出响应. 这里是2个事件监听的例子:一个监听 web page 准备加载,另一个监听 web page 停止加载,并且在加载的时候显示一条 "loading..." 信息: + +```html + +``` + +## 标签属性 + +`webview` 标签有下面一些属性 : + +### `src` + +```html + +``` + +将一个可用的url做为这个属性的初始值添加到顶部导航. + +如果把当前页的src添加进去将加载当前page. + + `src`同样可以填 data urls,例如 +`data:text/plain,Hello, world!`. + +### `autosize` + +```html + +``` + +如果这个属性的值为 "on" , `webview` 容器将会根据属性`minwidth`, `minheight`, `maxwidth`, 和 +`maxheight` 的值在它们之间自适应. 只有在 `autosize` 开启的时候这个约束才会有效. 当 `autosize` 开启的时候, `webview` 容器的 size 只能在上面那四个属性值之间. + +### `nodeintegration` + +```html + +``` + +如果设置了这个属性, `webview` 中的 guest page 将整合node,并且拥有可以使用系统底层的资源,例如 `require` 和 `process` . + +### `plugins` + +```html + +``` + +如果这个属性的值为 "on" , `webview` 中的 guest page 就可以使用浏览器插件。 + +### `preload` + +```html + +``` + +在 guest page 中的其他脚本执行之前预加载一个指定的脚本。规定预加载脚本的url须如 `file:` 或者 `asar:`,因为它在是 guest page 中通过通过 `require` 命令加载的。 + +如果 guest page 没有整合 node ,这个脚本将试图使用真个 Node APIs ,但是在这个脚本执行完毕时,之前由node插入的全局对象会被删除。 + + +### `httpreferrer` + +```html + +``` + +为 guest page 设置 referrer URL。 + +### `useragent` + +```html + +``` + +在 guest page 加载之前为其设置用户代理。如果页面已经加载了,可以使用 `setUserAgent` 方法来改变用户代理。 + +### `disablewebsecurity` + +```html + +``` + +如果这个属性的值为 "on" , guest page会禁用web安全控制. + +### partition + +```html + + +``` + +为page设置session。如果初始值为 `partition` ,这个 page 将会为app中的所有 page 应用同一个持续有效的 session。如果没有 `persist:` 前缀, 这个 page 将会使用一个历史 session 。通过分配使用相同的 `partition`, 所有的page都可以分享相同的session。如果 `partition` 没有设置,那app将使用默认的session. + +这个值只能在在第一个渲染进程之前设置修改,之后修改的话会无效并且抛出一个DOM异常. + +### `allowpopups` + +```html + +``` + +如果这个属性的值为 "on" ,将允许 guest page 打开一个新窗口。 + +### `blinkfeatures` + +```html + +``` + +这个属性的值为一个用逗号分隔的列表,它的值指定特性被启用。你可以从[setFeatureEnabledFromString][blink-feature-string]函数找到完整的支持特性。 + +## 方法 + + `webview` 的方法集合: + +**注意:** webview 元素必须在使用这些方法之前加载完毕。 + +**例如** + +```javascript +webview.addEventListener("dom-ready", function() { + webview.openDevTools(); +}); +``` + +### `.loadURL(url[, options])` + +* `url` URL +* `options` Object (可选) + * `httpReferrer` String - 一个http类型的url. + * `userAgent` String -用于发起请求的用户代理. + * `extraHeaders` String - 额外的headers,用 "\n"分隔. + +加载 webview 中的 `url`,`url` 必须包含协议前缀,例如 `http://` 或 `file://`. + +### `.getURL()` + +从 guest page 中返回 url. + +### `.getTitle()` + +从 guest page 中返回 title. + +### `.isLoading()` + +返回一个 guest page 是否仍在加载资源的布尔值. + +### `.isWaitingForResponse()` + +返回一个 guest page 是否正在等待page的主要资源做出回应的布尔值. + + +### `.stop()` + +停止渲染. + +### `.reload()` + +重新加载 guest page. + +### `.reloadIgnoringCache()` + +忽视缓存,重新加载 guest page. + +### `.canGoBack()` + +返回一个 guest page 是否能够回退的布尔值. + +### `.canGoForward()` + +返回一个 guest page 是否能够前进的布尔值. + +### `.canGoToOffset(offset)` + +* `offset` Integer + +返回一个 guest page 是否能够前进到 `offset` 的布尔值. + +### `.clearHistory()` + +清除导航历史. + +### `.goBack()` + +guest page 回退. + +### `.goForward()` + +guest page 前进. + +### `.goToIndex(index)` + +* `index` Integer + +guest page 导航到指定的绝对位置. + +### `.goToOffset(offset)` + +* `offset` Integer + +guest page 导航到指定的相对位置. + +### `.isCrashed()` + +返回一个 渲染进程是否崩溃 的布尔值. + +### `.setUserAgent(userAgent)` + +* `userAgent` String + +重新设置用户代理. + +### `.getUserAgent()` + +返回用户代理名字,返回类型:`String`. + +### `.insertCSS(css)` + +* `css` String + +插入css. + +### `.executeJavaScript(code, userGesture, callback)` + +* `code` String +* `userGesture` Boolean - 默认 `false`. +* `callback` Function (可选) - 回调函数. + * `result` + +评估 `code` ,如果 `userGesture` 值为 true ,它将在这个page里面创建用户手势. HTML APIs ,如 `requestFullScreen`,它需要用户响应,那么将自动通过这个参数优化. + +### `.openDevTools()` + +为 guest page 打开开发工具调试窗口. + +### `.closeDevTools()` + +为 guest page 关闭开发工具调试窗口. + +### `.isDevToolsOpened()` + +返回一个 guest page 是否打开了开发工具调试窗口的布尔值. + +### `.isDevToolsFocused()` + +返回一个 guest page 是否聚焦了开发工具调试窗口的布尔值. + +### `.inspectElement(x, y)` + +* `x` Integer +* `y` Integer + +开始检查 guest page 在 (`x`, `y`) 位置的元素. + +### `.inspectServiceWorker()` + +在 guest page 中为服务人员打开开发工具. + +### `.setAudioMuted(muted)` + +* `muted` Boolean +设置 guest page 流畅(muted). + +### `.isAudioMuted()` + +返回一个 guest page 是否流畅的布尔值. + +### `.undo()` + +在page中编辑执行 `undo` 命令. + +### `.redo()` + +在page中编辑执行 `redo` 命令. + +### `.cut()` + +在page中编辑执行 `cut` 命令. + +### `.copy()` + +在page中编辑执行 `copy` 命令. + +### `.paste()` + +在page中编辑执行 `paste` 命令. + +### `.pasteAndMatchStyle()` + +在page中编辑执行 `pasteAndMatchStyle` 命令. + +### `.delete()` + +在page中编辑执行 `delete` 命令. + +### `.selectAll()` + +在page中编辑执行 `selectAll` 命令. + +### `.unselect()` + +在page中编辑执行 `unselect` 命令. + +### `.replace(text)` + +* `text` String + +在page中编辑执行 `replace` 命令. + +### `.replaceMisspelling(text)` + +* `text` String + +在page中编辑执行 `replaceMisspelling` 命令. + +### `.insertText(text)` + +* `text` String + +插入文本. + +### `.findInPage(text[, options])` + +* `text` String - 搜索内容,不能为空. +* `options` Object (可选) + * `forward` Boolean - 向前或向后, 默认为 `true`. + * `findNext` Boolean - 是否查找的第一个结果, + 默认为 `false`. + * `matchCase` Boolean - 是否区分大小写, + 默认为 `false`. + * `wordStart` Boolean - 是否只查找首字母. + 默认为 `false`. + * `medialCapitalAsWordStart` Boolean - 当配合 `wordStart`的时候,接受一个文字中的匹配项,要求匹配项是以大写字母开头后面跟小写字母或者没有字母。可以接受一些其他单词内部匹配, 默认为 `false`. + +发起一个请求来寻找页面中的所有匹配 `text` 的地方并且返回一个 `Integer`来表示这个请求用的请求Id. 这个请求结果可以通过订阅[`found-in-page`](web-view-tag.md#event-found-in-page) 事件来取得. + +### `.stopFindInPage(action)` + +* `action` String - 指定一个行为来接替停止 + [`.findInPage`](web-view-tag.md#webviewtagfindinpage) 请求. + * `clearSelection` - 转变为一个普通的 selection. + * `keepSelection` - 清除 selection. + * `activateSelection` - 聚焦并点击 selection node. + +使用 `action` 停止 `findInPage` 请求. + +### `.print([options])` + +打印输出 `webview` 的 web page. 类似 `webContents.print([options])`. + +### `.printToPDF(options, callback)` + +以pdf格式打印输出 `webview` 的 web page. 类似 `webContents.printToPDF(options, callback)`. + +### `.send(channel[, arg1][, arg2][, ...])` + +* `channel` String +* `arg` (可选) + +通过 `channel` 向渲染进程发出异步消息,你也可以发送任意的参数。 +渲染进程通过`ipcRenderer` 模块监听 `channel` 事件来控制消息. + +例子 +[webContents.send](web-contents.md#webcontentssendchannel-args). + +### `.sendInputEvent(event)` + +* `event` Object + +向 page 发送输入事件. + +查看 [webContents.sendInputEvent](web-contents.md##webcontentssendinputeventevent) +关于 `event` 对象的相信介绍. + +### `.getWebContents()` + +返回和这个 `webview` 相关的 [WebContents](web-contents.md). + +## DOM 事件 + +`webview` 可用下面的 DOM 事件: + +### Event: 'load-commit' + +返回: + +* `url` String +* `isMainFrame` Boolean + +加载完成触发. 这个包含当前文档的导航和副框架的文档加载,但是不包含异步资源加载. + +### Event: 'did-finish-load' + +在导航加载完成时触发,也就是tab 的 spinner停止spinning,并且加载事件处理. + +### Event: 'did-fail-load' + +Returns: + +* `errorCode` Integer +* `errorDescription` String +* `validatedURL` String + +类似 `did-finish-load` ,在加载失败或取消是触发,例如提出 `window.stop()`. + +### Event: 'did-frame-finish-load' + +返回: + +* `isMainFrame` Boolean + +当一个 frame 完成 加载时触发. + +### Event: 'did-start-loading' + +开始加载时触发. + +### Event: 'did-stop-loading' + +停止家在时触发. + +### Event: 'did-get-response-details' + +返回: + +* `status` Boolean +* `newURL` String +* `originalURL` String +* `httpResponseCode` Integer +* `requestMethod` String +* `referrer` String +* `headers` Object + +当获得返回详情的时候触发. + +`status` 指示 socket 连接来下载资源. + +### Event: 'did-get-redirect-request' + +返回: + +* `oldURL` String +* `newURL` String +* `isMainFrame` Boolean + +当重定向请求资源被接收的时候触发. + +### Event: 'dom-ready' + +当指定的frame文档加载完毕时触发. + +### Event: 'page-title-updated' + +返回: + +* `title` String +* `explicitSet` Boolean + +当导航中的页面title被设置时触发. +在title通过文档路径异步加载时`explicitSet`为false. + +### Event: 'page-favicon-updated' + +返回: + +* `favicons` Array - Array of URLs. + +当page收到了图标url时触发. + +### Event: 'enter-html-full-screen' + +当通过HTML API使界面进入全屏时触发. + +### Event: 'leave-html-full-screen' + +当通过HTML API使界面退出全屏时触发. + +### Event: 'console-message' + +返回: + +* `level` Integer +* `message` String +* `line` Integer +* `sourceId` String + +当客户端输出控制台信息的时候触发. + +下面示例代码将所有信息输出到内置控制台,没有考虑到输出等级和其他属性。 + +```javascript +webview.addEventListener('console-message', function(e) { + console.log('Guest page logged a message:', e.message); +}); +``` + +### Event: 'found-in-page' + +返回: + +* `result` Object + * `requestId` Integer + * `finalUpdate` Boolean - 指明下面是否还有更多的回应. + * `matches` Integer (optional) - 匹配数量. + * `selectionArea` Object (optional) - 整合第一个匹配域. + +在请求[`webview.findInPage`](web-view-tag.md#webviewtagfindinpage)结果有效时触发. + +```javascript +webview.addEventListener('found-in-page', function(e) { + if (e.result.finalUpdate) + webview.stopFindInPage("keepSelection"); +}); + +const rquestId = webview.findInPage("test"); +``` + +### Event: 'new-window' + +返回: + +* `url` String +* `frameName` String +* `disposition` String - 可以为 `default`, `foreground-tab`, `background-tab`, + `new-window` 和 `other`. +* `options` Object - 参数应该被用作创建新的 + `BrowserWindow`. + +在 guest page 试图打开一个新的浏览器窗口时触发. + +下面示例代码在系统默认浏览器中打开了一个新的url. + +```javascript +webview.addEventListener('new-window', function(e) { + require('electron').shell.openExternal(e.url); +}); +``` + +### Event: 'will-navigate' + +返回: + +* `url` String + +当用户或page尝试开始导航时触发. +它能在 `window.location` 变化或者用户点击连接的时候触发. + +这个事件在以 APIS 编程方式开始导航时不会触发,例如 `.loadURL` 和 `.back`. + +在页面内部导航跳转也将不回触发这个事件,例如点击锚链接或更新 `window.location.hash`.使用 `did-navigate-in-page` 来实现页内跳转事件. + +使用 `event.preventDefault()` 并不会起什么用. + +### Event: 'did-navigate' + +返回: + +* `url` String + +当导航结束时触发. + +在页面内部导航跳转也将不回触发这个事件,例如点击锚链接或更新 `window.location.hash`.使用 `did-navigate-in-page` 来实现页内跳转事件. + +### Event: 'did-navigate-in-page' + +返回: + +* `url` String + +当页内导航发生时触发. +当业内导航发生时,page url改变了,但是不会跳出 page . 例如在锚链接被电击或DOM `hashchange` 事件发生时触发. + +### Event: 'close' + +在 guest page试图关闭自己的时候触发. + +下面的示例代码指示了在客户端试图关闭自己的时候将改变导航连接为`about:blank`. + +```javascript +webview.addEventListener('close', function() { + webview.src = 'about:blank'; +}); +``` + +### Event: 'ipc-message' + +返回: + +* `channel` String +* `args` Array + +在 guest page 向嵌入页发送一个异步消息的时候触发. + +你可以很简单的使用 `sendToHost` 方法和 `ipc-message` 事件在 guest page 和 嵌入页(embedder page)之间通信: + +```javascript +// In embedder page. +webview.addEventListener('ipc-message', function(event) { + console.log(event.channel); + // Prints "pong" +}); +webview.send('ping'); +``` + +```javascript +// In guest page. +var ipcRenderer = require('electron').ipcRenderer; +ipcRenderer.on('ping', function() { + ipcRenderer.sendToHost('pong'); +}); +``` + +### Event: 'crashed' + +在渲染进程崩溃的时候触发. + +### Event: 'gpu-crashed' + +在GPU进程崩溃的时候触发. + +### Event: 'plugin-crashed' + +返回: + +* `name` String +* `version` String + +在插件进程崩溃的时候触发. + +### Event: 'destroyed' + +在界面内容销毁的时候触发. + +### Event: 'media-started-playing' + +在媒体准备播放的时候触发. + +### Event: 'media-paused' + +在媒体暂停播放或播放放毕的时候触发. + +### Event: 'did-change-theme-color' + +在页面的主体色改变的时候触发. +在使用 meta 标签的时候这就很常见了: + +```html + +``` + +### Event: 'devtools-opened' + +在开发者工具打开的时候触发. + +### Event: 'devtools-closed' + +在开发者工具关闭的时候触发. + +### Event: 'devtools-focused' + +在开发者工具获取焦点的时候触发. + +[blink-feature-string]: https://code.google.com/p/chromium/codesearch#chromium/src/out/Debug/gen/blink/platform/RuntimeEnabledFeatures.cpp&sq=package:chromium&type=cs&l=527 \ No newline at end of file diff --git a/docs-translations/zh-CN/api/window-open.md b/docs-translations/zh-CN/api/window-open.md new file mode 100644 index 000000000000..069e2c352263 --- /dev/null +++ b/docs-translations/zh-CN/api/window-open.md @@ -0,0 +1,60 @@ +# `window.open` 函数 + +当在界面中使用 `window.open` 来创建一个新的窗口时候,将会创建一个 `BrowserWindow` 的实例,并且将返回一个标识,这个界面通过标识来对这个新的窗口进行有限的控制. + +这个标识对传统的web界面来说,通过它能对子窗口进行有限的功能性兼容控制. +想要完全的控制这个窗口,可以直接创建一个 `BrowserWindow` . + +新创建的 `BrowserWindow` 默认为继承父窗口的属性参数,想重写属性的话可以在 `features` 中设置他们. + +### `window.open(url[, frameName][, features])` + +* `url` String +* `frameName` String (可选) +* `features` String (可选) + +创建一个新的window并且返回一个 `BrowserWindowProxy` 类的实例. + + `features` 遵循标准浏览器的格式,但是每个feature 应该作为 `BrowserWindow` 参数的一个字段. + +### `window.opener.postMessage(message, targetOrigin)` + +* `message` String +* `targetOrigin` String + +通过指定位置或用 `*` 来代替没有明确位置来向父窗口发送信息. + +## Class: BrowserWindowProxy + +`BrowserWindowProxy` 由`window.open` 创建返回,并且提供了对子窗口的有限功能性控制. + +### `BrowserWindowProxy.blur()` + +子窗口的失去焦点. +### `BrowserWindowProxy.close()` + +强行关闭子窗口,忽略卸载事件. + +### `BrowserWindowProxy.closed` + +在子窗口关闭之后恢复正常. + +### `BrowserWindowProxy.eval(code)` + +* `code` String + +评估子窗口的代码. + +### `BrowserWindowProxy.focus()` + +子窗口获得焦点(让其显示在最前). + +### `BrowserWindowProxy.postMessage(message, targetOrigin)` + +* `message` String +* `targetOrigin` String + + +通过指定位置或用 `*` 来代替没有明确位置来向子窗口发送信息. + +除了这些方法,子窗口还可以无特性和使用单一方法来实现 `window.opener` 对象. \ No newline at end of file