From 5d35d2476dfc43f117bad55838541f29fffe55d0 Mon Sep 17 00:00:00 2001 From: Weiqiang Lin <23leo@163.com> Date: Thu, 9 Feb 2017 15:24:29 +0800 Subject: [PATCH 01/16] window.open Function to zh-cn --- docs-translations/zh-CN/api/window-open.md | 57 ++++++---------------- 1 file changed, 15 insertions(+), 42 deletions(-) diff --git a/docs-translations/zh-CN/api/window-open.md b/docs-translations/zh-CN/api/window-open.md index 069e2c352263..3ef1b59f1a3f 100644 --- a/docs-translations/zh-CN/api/window-open.md +++ b/docs-translations/zh-CN/api/window-open.md @@ -1,11 +1,13 @@ # `window.open` 函数 -当在界面中使用 `window.open` 来创建一个新的窗口时候，将会创建一个 `BrowserWindow` 的实例，并且将返回一个标识，这个界面通过标识来对这个新的窗口进行有限的控制. +> 通过链接打开一个新窗口。 -这个标识对传统的web界面来说，通过它能对子窗口进行有限的功能性兼容控制. -想要完全的控制这个窗口，可以直接创建一个 `BrowserWindow` . +当在界面中使用 `window.open` 来创建一个新的窗口时候，将会创建一个 `BrowserWindow` 的实例，并且将返回一个标识，这个界面通过标识来对这个新的窗口进行有限的控制。 -新创建的 `BrowserWindow` 默认为继承父窗口的属性参数，想重写属性的话可以在 `features` 中设置他们. +这个标识对传统的web界面来说，通过它能对子窗口进行有限的功能性兼容控制。 +想要完全的控制这个窗口，可以直接创建一个 `BrowserWindow`。 + +新创建的 `BrowserWindow` 默认为继承父窗口的属性参数，想重写属性的话可以在 `features` 中设置他们。 ### `window.open(url[, frameName][, features])` @@ -13,48 +15,19 @@ * `frameName` String (可选) * `features` String (可选) -创建一个新的window并且返回一个 `BrowserWindowProxy` 类的实例. +创建一个新的 window 并且返回一个 [`BrowserWindowProxy`](browser-window-proxy.md) 类的实例。 - `features` 遵循标准浏览器的格式，但是每个feature 应该作为 `BrowserWindow` 参数的一个字段. + `features` 遵循标准浏览器的格式，但是每个 feature 应该作为 `BrowserWindow` 参数的一个字段。 + +**注意：** +* 如果在父窗口禁用 Node integration，那么在新打开的 `window` 中将始终禁用。 +* 非标准功能（不由 Chromium 或 Electron 处理）的 +   `features` 将被传递给任何注册的 `webContent` 的 `new-window` 事件 +   在 `additionalFeatures` 参数的处理程序。 ### `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 +通过指定位置或用 `*` 来代替没有明确位置来向父窗口发送信息。 From 6adf1640e589e243d23b3e87b2efafca5cf39b3b Mon Sep 17 00:00:00 2001 From: Weiqiang Lin <23leo@163.com> Date: Thu, 9 Feb 2017 15:51:48 +0800 Subject: [PATCH 02/16] autoUpdater to zh-CN --- docs-translations/zh-CN/api/auto-updater.md | 51 ++++++++++++++++++--- 1 file changed, 45 insertions(+), 6 deletions(-) diff --git a/docs-translations/zh-CN/api/auto-updater.md b/docs-translations/zh-CN/api/auto-updater.md index 845b4c24d9bf..75a816484b9c 100644 --- a/docs-translations/zh-CN/api/auto-updater.md +++ b/docs-translations/zh-CN/api/auto-updater.md @@ -1,6 +1,20 @@ # autoUpdater -这个模块提供了一个到 `Squirrel` 自动更新框架的接口。 +> 使应用程序能够自动更新。 + +进程: [Main](../glossary.md#main-process) + +`autoUpdater` 模块提供了来自 +[Squirrel](https://github.com/Squirrel) 框架的一个接口。 + +你可以快速启动多平台发布服务器来分发您的 +应用程序通过使用下列项目中的一个： + +- [nuts][nuts]: *针对你的应用程序的智能发布服务器，使用 GitHub 作为后端。 使用 Squirrel 自动更新（Mac 和 Windows）* +- [electron-release-server][electron-release-server]: *一个功能齐全， + electron 应用的自托管发布服务器，兼容 auto-updater* +- [squirrel-updates-server][squirrel-updates-server]: *对于使用 GitHub 版本的 Squirrel.Mac 和 Squirrel.Windows 的一个简单的 node.js 服务器* +- [squirrel-release-server][squirrel-release-server]: *一个简单的 Squirrel.Windows 的 PHP 应用程序，它从文件夹读取更新，并支持增量更新* ## 平台相关的提示 @@ -9,11 +23,21 @@ ### macOS 在 macOS 上，`autoUpdater` 模块依靠的是内置的 [Squirrel.Mac][squirrel-mac]，这意味着你不需要依靠其他的设置就能使用。关于 -更新服务器的配置，你可以通过阅读 [Server Support][server-support] 这篇文章来了解。 +更新服务器的配置，你可以通过阅读 [Server Support][server-support] 这篇文章来了解。注意 [App +Transport Security](https://developer.apple.com/library/content/documentation/General/Reference/InfoPlistKeyReference/Articles/CocoaKeys.html#//apple_ref/doc/uid/TP40009251-SW35) (ATS) 适用于所有请求作为的一部分 +更新过程。需要禁用 ATS 的应用程序可以在应用程序的 plist 添加 +`NSAllowsArbitraryLoads` 属性。 + +**注意：** 你的应用程序必须签署 macOS 自动更新。 +这是 `Squirrel.Mac` 的要求。 ### Windows -在 Windows 上，你必须使用安装程序将你的应用装到用户的计算机上，所以比较推荐的方法是用 [grunt-electron-installer][installer] 这个模块来自动生成一个 Windows 安装向导。 +在 Windows 上，你必须使用安装程序将你的应用装到用户的计算机上，所以比较推荐的方法是用 [electron-winstaller][installer-lib], [electron-builder][electron-builder-lib] 或者 [grunt-electron-installer][installer] 模块来自动生成一个 Windows 安装向导。 + +当使用 [electron-winstaller][installer-lib] 或者 [electron-builder][electron-builder-lib] + +当使用 [electron-winstaller][installer-lib] 或者 [electron-builder][electron-builder-lib] 确保你不尝试更新你的应用程序 [the first time it runs](https://github.com/electron/windows-installer#handling-squirrel-events)（另见 [this issue for more info](https://github.com/electron/electron/issues/7155)）。 建议使用 [electron-squirrel-startup](https://github.com/mongodb-js/electron-squirrel-startup) 获取应用程序的桌面快捷方式。 Squirrel 自动生成的安装向导会生成一个带 [Application User Model ID][app-user-model-id] 的快捷方式。 Application User Model ID 的格式是 `com.squirrel.PACKAGE_ID.YOUR_EXE_WITHOUT_DOT_EXE`, 比如 @@ -67,11 +91,16 @@ Linux 下没有任何的自动更新支持，所以我们推荐用各个 Linux `autoUpdater` 对象有以下的方法： -### `autoUpdater.setFeedURL(url)` +### `autoUpdater.setFeedURL(url[, requestHeaders])` * `url` String +* `requestHeaders` Object _macOS_ (optional) - HTTP请求头。 -设置检查更新的 `url`，并且初始化自动更新。这个 `url` 一旦设置就无法更改。 +设置检查更新的 `url`，并且初始化自动更新。 + +### `autoUpdater.getFeedURL()` + +返回 `String` - 当前更新提要 URL。 ### `autoUpdater.checkForUpdates()` @@ -81,8 +110,18 @@ Linux 下没有任何的自动更新支持，所以我们推荐用各个 Linux 在下载完成后，重启当前的应用并且安装更新。这个方法应该仅在 `update-downloaded` 事件触发后被调用。 +**注意：** `autoUpdater.quitAndInstall()` 将先关闭所有应用程序窗口 +并且只在 `app` 上发出 `before-quit` 事件。这不同于 +从正常退出的事件序列。 + [squirrel-mac]: https://github.com/Squirrel/Squirrel.Mac [server-support]: https://github.com/Squirrel/Squirrel.Mac#server-support [squirrel-windows]: https://github.com/Squirrel/Squirrel.Windows -[installer]: https://github.com/atom/grunt-electron-installer +[installer]: https://github.com/electron/grunt-electron-installer +[installer-lib]: https://github.com/electron/windows-installer +[electron-builder-lib]: https://github.com/electron-userland/electron-builder [app-user-model-id]: https://msdn.microsoft.com/en-us/library/windows/desktop/dd378459(v=vs.85).aspx +[electron-release-server]: https://github.com/ArekSredzki/electron-release-server +[squirrel-updates-server]: https://github.com/Aluxian/squirrel-updates-server +[nuts]: https://github.com/GitbookIO/nuts +[squirrel-release-server]: https://github.com/Arcath/squirrel-release-server From f949f83a578ed9ed6c53f936cdd9446fbb322a30 Mon Sep 17 00:00:00 2001 From: Weiqiang Lin <23leo@163.com> Date: Thu, 9 Feb 2017 16:17:38 +0800 Subject: [PATCH 03/16] BrowserWindow to zh-CN --- docs-translations/zh-CN/api/browser-window.md | 119 ++++++++++++++++-- 1 file changed, 107 insertions(+), 12 deletions(-) diff --git a/docs-translations/zh-CN/api/browser-window.md b/docs-translations/zh-CN/api/browser-window.md index 9faa90850331..2487133c4f65 100644 --- a/docs-translations/zh-CN/api/browser-window.md +++ b/docs-translations/zh-CN/api/browser-window.md @@ -1,32 +1,122 @@ # BrowserWindow - `BrowserWindow` 类让你有创建一个浏览器窗口的权力。例如: +> 创建和控制浏览器窗口。 + +进程: [Main](../glossary.md#main-process) ```javascript // In the main process. -const BrowserWindow = require('electron').BrowserWindow +const {BrowserWindow} = require('electron') -// Or in the renderer process. -// const BrowserWindow = require('electron').remote.BrowserWindow +// Or use `remote` from the renderer process. +// const {BrowserWindow} = require('electron').remote -var win = new BrowserWindow({ width: 800, height: 600, show: false }) -win.on('closed', function () { +let win = new BrowserWindow({width: 800, height: 600}) +win.on('closed', () => { win = null }) +// Load a remote URL win.loadURL('https://github.com') -win.show() + +// Or load a local HTML file +win.loadURL(`file://${__dirname}/app/index.html`) ``` -你也可以不通过chrome创建窗口，使用 -[Frameless Window](frameless-window.md) API. +## Frameless window + +不通过chrome创建窗口，或者一个任意形状的透明窗口， +你可以使用 [Frameless Window](frameless-window.md) API。 + +## Showing window gracefully + +When loading a page in the window directly, users may see the page load incrementally, which is not a good experience for a native app. To make the window display +without visual flash, there are two solutions for different situations. + +## 优雅地显示窗口 + +当在窗口中直接加载页面时，用户可能会看到增量加载页面，这不是一个好的原生应用程序的体验。使窗口显示 +没有可视闪烁，有两种解决方案适用于不同的情况。 + +### 使用 `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 和 child 窗口 + +使用 `parent` 选项，你可以创建 child 窗口： + +```javascript +const {BrowserWindow} = require('electron') + +let top = new BrowserWindow() +let child = new BrowserWindow({parent: top}) +child.show() +top.show() +``` + +`child` 窗口将总是显示在 `top` 窗口的顶部。 + +### Modal 窗口 + +模态窗口是禁用父窗口的子窗口，以创建模态 +窗口，你必须设置 `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 上，modal 窗口将显示为附加到父窗口的工作表。 +* 在 macOS 上，子窗口将保持与父窗口的相对位置 +   当父窗口移动时，而在 Windows 和 Linux 子窗口不会 +   移动。 +* 在Windows上，不支持动态更改父窗口。 +* 在Linux上，模态窗口的类型将更改为 `dialog`。 +* 在Linux上，许多桌面环境不支持隐藏模态窗口。 ## Class: BrowserWindow `BrowserWindow` 是一个 -[EventEmitter](http://nodejs.org/api/events.html#events_class_events_eventemitter). +[EventEmitter](http://nodejs.org/api/events.html#events_class_events_eventemitter)。 -通过 `options` 可以创建一个具有本质属性的 `BrowserWindow` . +通过 `options` 可以创建一个具有原生属性的 `BrowserWindow`。 ### `new BrowserWindow([options])` @@ -748,4 +838,9 @@ windows上句柄类型为 `HWND` ，macOS `NSView*` ， Linux `Window`. 忽略窗口的所有鼠标事件. -[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 + +[blink-feature-string]: https://cs.chromium.org/chromium/src/third_party/WebKit/Source/platform/RuntimeEnabledFeatures.in +[quick-look]: https://en.wikipedia.org/wiki/Quick_Look +[vibrancy-docs]: https://developer.apple.com/reference/appkit/nsvisualeffectview?language=objc +[window-levels]: https://developer.apple.com/reference/appkit/nswindow/1664726-window_levels +[chrome-content-scripts]: https://developer.chrome.com/extensions/content_scripts#execution-environment From db4ad8c6925df63b0fde2774f64092b31ad1021d Mon Sep 17 00:00:00 2001 From: Weiqiang Lin <23leo@163.com> Date: Thu, 9 Feb 2017 16:57:41 +0800 Subject: [PATCH 04/16] contentTracing to zh-CN --- .../zh-CN/api/content-tracing.md | 81 +++++++++++-------- 1 file changed, 47 insertions(+), 34 deletions(-) diff --git a/docs-translations/zh-CN/api/content-tracing.md b/docs-translations/zh-CN/api/content-tracing.md index f30a616b3f53..6b675d09a72a 100644 --- a/docs-translations/zh-CN/api/content-tracing.md +++ b/docs-translations/zh-CN/api/content-tracing.md @@ -1,29 +1,38 @@ # contentTracing -`content-tracing` 模块是用来收集由底层的Chromium content 模块 产生的搜索数据. 这个模块不具备web接口，所有需要我们在chrome浏览器中添加 `chrome://tracing/` 来加载生成文件从而查看结果. +> 从 Chromium 的 content 模块收集跟踪数据，以查找性能 +瓶颈和运行缓慢的原因。 + +进程: [Main](../glossary.md#main-process) + +这个模块不具备web接口，所有需要我们在 Chrome 浏览器中打开 `chrome://tracing/` 来加载生成文件从而查看结果。 + +**注意：** 你不应该使用这个模块，直到应用程序发出 `ready` 事件。 ```javascript -const contentTracing = require('electron').contentTracing +const {app, contentTracing} = require('electron') -const options = { - categoryFilter: '*', - traceOptions: 'record-until-full,enable-sampling' -} +app.on('ready', () => { + const options = { + categoryFilter: '*', + traceOptions: 'record-until-full,enable-sampling' + } -contentTracing.startRecording(options, function () { - console.log('Tracing started') + contentTracing.startRecording(options, () => { + console.log('Tracing started') - setTimeout(function () { - contentTracing.stopRecording('', function (path) { - console.log('Tracing data recorded to ' + path) - }) - }, 5000) + setTimeout(() => { + contentTracing.stopRecording('', (path) => { + console.log('Tracing data recorded to ' + path) + }) + }, 5000) + }) }) ``` ## 方法 - `content-tracing` 模块的方法如下: + `content-tracing` 模块的方法如下： ### `contentTracing.getCategories(callback)` @@ -31,7 +40,7 @@ contentTracing.startRecording(options, function () { 获得一组分类组. 分类组可以更改为新的代码路径。 -一旦所有的子进程都接受到了`getCategories`方法请求, 分类组将调用 `callback`. +一旦所有的子进程都接受到了 `getCategories` 方法请求, 分类组将调用 `callback`。 ### `contentTracing.startRecording(options, callback)` @@ -40,11 +49,11 @@ contentTracing.startRecording(options, function () { * `traceOptions` String * `callback` Function -开始向所有进程进行记录.(recording) +开始向所有进程进行记录。 -一旦收到可以开始记录的请求，记录将会立马启动并且在子进程是异步记录听的. 当所有的子进程都收到 `startRecording` 请求的时候，`callback` 将会被调用. +一旦收到可以开始记录的请求，记录将会立马启动并且在子进程是异步记录听的. 当所有的子进程都收到 `startRecording` 请求的时候，`callback` 将会被调用。 -`categoryFilter`是一个过滤器，它用来控制那些分类组应该被用来查找.过滤器应当有一个可选的 `-` 前缀来排除匹配的分类组.不允许同一个列表既是包含又是排斥. +`categoryFilter`是一个过滤器，它用来控制那些分类组应该被用来查找.过滤器应当有一个可选的 `-` 前缀来排除匹配的分类组。不允许同一个列表既是包含又是排斥。 例子: @@ -52,7 +61,7 @@ contentTracing.startRecording(options, function () { * `test_MyTest*,test_OtherStuff`, * `"-excluded_category1,-excluded_category2` -`traceOptions` 控制着哪种查找应该被启动，这是一个用逗号分隔的列表.可用参数如下: +`traceOptions` 控制着哪种查找应该被启动，这是一个用逗号分隔的列表。可用参数如下： * `record-until-full` * `record-continuously` @@ -60,25 +69,26 @@ contentTracing.startRecording(options, function () { * `enable-sampling` * `enable-systrace` -前3个参数是来查找记录模块，并且以后都互斥.如果在`traceOptions` 中超过一个跟踪 +前3个参数是来查找记录模块，并且以后都互斥。如果在 `traceOptions` 中超过一个跟踪 记录模式，那最后一个的优先级最高.如果没有指明跟踪 -记录模式，那么它默认为 `record-until-full`. +记录模式，那么它默认为 `record-until-full`。 在 `traceOptions` 中的参数被解析应用之前，查找参数初始化默认为 (`record_mode` 设置为 -`record-until-full`, `enable_sampling` 和 `enable_systrace` 设置为 `false`). +`record-until-full`, `enable_sampling` 和 `enable_systrace` 设置为 `false`)。 ### `contentTracing.stopRecording(resultFilePath, callback)` * `resultFilePath` String * `callback` Function + * `resultFilePath` String -停止对所有子进程的记录. +停止对所有子进程的记录。 -子进程通常缓存查找数据，并且仅仅将数据截取和发送给主进程.这有利于在通过 IPC 发送查找数据之前减小查找时的运行开销，这样做很有价值.因此，发送查找数据，我们应当异步通知所有子进程来截取任何待查找的数据. +子进程通常缓存查找数据，并且仅仅将数据截取和发送给主进程。这有利于在通过 IPC 发送查找数据之前减小查找时的运行开销，这样做很有价值.因此，发送查找数据，我们应当异步通知所有子进程来截取任何待查找的数据。 -一旦所有子进程接收到了 `stopRecording` 请求，将调用 `callback` ，并且返回一个包含查找数据的文件. +一旦所有子进程接收到了 `stopRecording` 请求，将调用 `callback` ，并且返回一个包含查找数据的文件。 -如果 `resultFilePath` 不为空，那么将把查找数据写入其中，否则写入一个临时文件.实际文件路径如果不为空，则将调用 `callback` . +如果 `resultFilePath` 不为空，那么将把查找数据写入其中，否则写入一个临时文件。实际文件路径如果不为空，则将调用 `callback`。 ### `contentTracing.startMonitoring(options, callback)` @@ -87,31 +97,34 @@ contentTracing.startRecording(options, function () { * `traceOptions` String * `callback` Function -开始向所有进程进行监听.(monitoring) +开始向所有进程进行监听。 -一旦收到可以开始监听的请求，记录将会立马启动并且在子进程是异步记监听的. 当所有的子进程都收到 `startMonitoring` 请求的时候，`callback` 将会被调用. +一旦收到可以开始监听的请求，记录将会立马启动并且在子进程是异步记监听的。当所有的子进程都收到 `startMonitoring` 请求的时候，`callback` 将会被调用。 ### `contentTracing.stopMonitoring(callback)` * `callback` Function -停止对所有子进程的监听. +停止对所有子进程的监听。 -一旦所有子进程接收到了 `stopMonitoring` 请求，将调用 `callback` . +一旦所有子进程接收到了 `stopMonitoring` 请求，将调用 `callback`。 ### `contentTracing.captureMonitoringSnapshot(resultFilePath, callback)` * `resultFilePath` String * `callback` Function + * `resultFilePath` String -获取当前监听的查找数据. +获取当前监听的查找数据。 -子进程通常缓存查找数据，并且仅仅将数据截取和发送给主进程.因为如果直接通过 IPC 来发送查找数据的代价昂贵，我们宁愿避免不必要的查找运行开销.因此，为了停止查找，我们应当异步通知所有子进程来截取任何待查找的数据. +子进程通常缓存查找数据，并且仅仅将数据截取和发送给主进程.因为如果直接通过 IPC 来发送查找数据的代价昂贵，我们宁愿避免不必要的查找运行开销。因此，为了停止查找，我们应当异步通知所有子进程来截取任何待查找的数据。 -一旦所有子进程接收到了 `captureMonitoringSnapshot` 请求，将调用 `callback` ，并且返回一个包含查找数据的文件. +一旦所有子进程接收到了 `captureMonitoringSnapshot` 请求，将调用 `callback` ，并且返回一个包含查找数据的文件。 ### `contentTracing.getTraceBufferUsage(callback)` * `callback` Function + * `value` Number + * `percentage` Number -通过查找 buffer 进程来获取百分比最大使用量.当确定了TraceBufferUsage 的值确定的时候，就调用 `callback` . +通过查找 buffer 进程来获取百分比最大使用量.当确定了TraceBufferUsage 的值确定的时候，就调用 `callback`。 From 4a78490a6a17074b5911f1c94b9a72de7ca1998a Mon Sep 17 00:00:00 2001 From: Weiqiang Lin <23leo@163.com> Date: Thu, 9 Feb 2017 17:01:30 +0800 Subject: [PATCH 05/16] dialog to zh-CN --- docs-translations/zh-CN/api/dialog.md | 108 +++++++++++++++++++------- 1 file changed, 79 insertions(+), 29 deletions(-) diff --git a/docs-translations/zh-CN/api/dialog.md b/docs-translations/zh-CN/api/dialog.md index 366d7b8ff3c7..702b6ea3e2bf 100644 --- a/docs-translations/zh-CN/api/dialog.md +++ b/docs-translations/zh-CN/api/dialog.md @@ -1,6 +1,8 @@ # dialog -`dialog` 模块提供了api来展示原生的系统对话框，例如打开文件框，alert框，所以web应用可以给用户带来跟系统应用相同的体验. +> 显示用于打开和保存文件，alert框等的原生的系统对话框 + +进程: [Main](../glossary.md#main-process) 对话框例子，展示了选择文件和目录: @@ -9,62 +11,95 @@ const {dialog} = require('electron') console.log(dialog.showOpenDialog({properties: ['openFile', 'openDirectory', 'multiSelections']})) ``` -**macOS 上的注意事项**: 如果你想像sheets一样展示对话框，只需要在`browserWindow` 参数中提供一个 `BrowserWindow` 的引用对象. +对话框从 Electron 的主线程打开。如果要从渲染器进程使用对话框 +对象，记得使用 remote 访问它： + +```javascript +const {dialog} = require('electron').remote +console.log(dialog) +``` ## 方法 -`dialog` 模块有以下方法: +`dialog` 模块有以下方法： ### `dialog.showOpenDialog([browserWindow, ]options[, callback])` * `browserWindow` BrowserWindow (可选) * `options` Object - * `title` String - * `defaultPath` String - * `filters` Array - * `properties` Array - 包含了对话框的特性值, 可以包含 `openFile`, `openDirectory`, `multiSelections` and - `createDirectory` + * `title` String (可选) + * `defaultPath` String (可选) + * `buttonLabel` String (可选) - Custom label for the confirmation button, when + left empty the default label will be used. + * `filters` [FileFilter[]](structures/file-filter.md) (optional) + * `properties` String[] (可选) - Contains which features the dialog should + use. The following values are supported: + * `openFile` - Allow files to be selected. + * `openDirectory` - Allow directories to be selected. + * `multiSelections` - Allow multiple paths to be selected. + * `showHiddenFiles` - Show hidden files in dialog. + * `createDirectory` _macOS_ - Allow creating new directories from dialog. + * `promptToCreate` _Windows_ - Prompt for creation if the file path entered + in the dialog does not exist. This does not actually create the file at + the path but allows non-existent paths to be returned that should be + created by the application. + * `normalizeAccessKeys` Boolean (可选) - Normalize the keyboard access keys + across platforms. Default is `false`. Enabling this assumes `&` is used in + the button labels for the placement of the keyboard shortcut access key + and labels will be converted so they work correctly on each platform, `&` + characters are removed on macOS, converted to `_` on Linux, and left + untouched on Windows. For example, a button label of `Vie&w` will be + converted to `Vie_w` on Linux and `View` on macOS and can be selected + via `Alt-W` on Windows and Linux. * `callback` Function (可选) + * `filePaths` String[] - An array of file paths chosen by the user -成功使用这个方法的话，就返回一个可供用户选择的文件路径数组，失败返回 `undefined`. +成功使用这个方法的话，就返回一个可供用户选择的文件路径数组，失败返回 `undefined`。 -`filters` 当需要限定用户的行为的时候，指定一个文件数组给用户展示或选择. 例如: +`browserWindow` 参数允许对话框将自身附加到父窗口，使其成为模态。 + +`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: ['*'] } + {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'` 不正确). 展示全部文件的话, 使用 -`'*'` 通配符 (不支持其他通配符). +`extensions` 数组应当只包含扩展名，不应该包含通配符或 '.' 号 （例如 +`'png'` 正确，但是 `'.png'` 和 `'*.png'` 不正确）。展示全部文件的话，使用 +`'*'` 通配符 （不支持其他通配符）。 -如果 `callback` 被调用, 将异步调用 API ，并且结果将用过 `callback(filenames)` 展示. +如果 `callback` 被调用，将异步调用 API ，并且结果将用过 `callback(filenames)` 展示。 **注意:** 在 Windows 和 Linux ，一个打开的 dialog 不能既是文件选择框又是目录选择框, 所以如果在这些平台上设置 `properties` 的值为 -`['openFile', 'openDirectory']` , 将展示一个目录选择框. +`['openFile', 'openDirectory']` ，将展示一个目录选择框。 ### `dialog.showSaveDialog([browserWindow, ]options[, callback])` * `browserWindow` BrowserWindow (可选) * `options` Object - * `title` String - * `defaultPath` String - * `filters` Array + * `title` String (可选) + * `defaultPath` String (可选) + * `buttonLabel` String (可选) - Custom label for the confirmation button, when + left empty the default label will be used. + * `filters` [FileFilter[]](structures/file-filter.md) (optional) * `callback` Function (可选) + * `filename` String -成功使用这个方法的话，就返回一个可供用户选择的文件路径数组，失败返回 `undefined`. +成功使用这个方法的话，就返回一个可供用户选择的文件路径数组，失败返回 `undefined`。 + +`browserWindow` 参数允许对话框将自身附加到父窗口，使其成为模态。 `filters` 指定展示一个文件类型数组, 例子 -`dialog.showOpenDialog` . +`dialog.showOpenDialog` 。 -如果 `callback` 被调用, 将异步调用 API ，并且结果将用过 `callback(filenames)` 展示. +如果 `callback` 被调用, 将异步调用 API ，并且结果将用过 `callback(filenames)` 展示。 ### `dialog.showMessageBox([browserWindow, ]options[, callback])` @@ -80,14 +115,29 @@ console.log(dialog.showOpenDialog({properties: ['openFile', 'openDirectory', 'mu * `icon` [NativeImage](native-image.md) * `cancelId` Integer - 当用户关闭对话框的时候，不是通过点击对话框的button，就返回值.默认值为对应 "cancel" 或 "no" 标签button 的索引值, 或者如果没有这种button，就返回0. 在 macOS 和 Windows 上， "Cancel" button 的索引值将一直是 `cancelId`, 不管之前是不是特别指出的. * `noLink` Boolean - 在 Windows ，Electron 将尝试识别哪个button 是普通 button (如 "Cancel" 或 "Yes"), 然后在对话框中以链接命令(command links)方式展现其它的 button . 这能让对话框展示得很炫酷.如果你不喜欢这种效果，你可以设置 `noLink` 为 `true`. -* `callback` Function + * `callback` Function (可选) + * `response` Number - The index of the button that was clicked -展示 message box, 它会阻塞进程，直到 message box 关闭为止.返回点击按钮的索引值. +返回 `Integer`，如果提供了回调，它会返回点击的按钮的索引或者 undefined 。 -如果 `callback` 被调用, 将异步调用 API ，并且结果将用过 `callback(response)` 展示. +展示 message box, 它会阻塞进程，直到 message box 关闭为止.返回点击按钮的索引值。 + +`browserWindow` 参数允许对话框将自身附加到父窗口，使其成为模态。 + +如果 `callback` 被调用, 将异步调用 API ，并且结果将用过 `callback(response)` 展示。 ### `dialog.showErrorBox(title, content)` +* `title` String - 错误框中的标题 +* `content` String - 错误框中的内容 + 展示一个传统的包含错误信息的对话框. -在 `app` 模块触发 `ready` 事件之前，这个 api 可以被安全调用，通常它被用来在启动的早期阶段报告错误. 在 Linux 上，如果在 `app` 模块触发 `ready` 事件之前调用，message 将会被触发显示stderr，并且没有实际GUI 框显示. +在 `app` 模块触发 `ready` 事件之前，这个 api 可以被安全调用，通常它被用来在启动的早期阶段报告错误. 在 Linux 上，如果在 `app` 模块触发 `ready` 事件之前调用，message 将会被触发显示 stderr ，并且没有实际 GUI 框显示. + +## Sheets + +在 macOS 上，如果你想像 sheets 一样展示对话框，只需要在`browserWindow` 参数中提供一个 `BrowserWindow` 的引用对象.，如果没有则为模态窗口。 + +你可以调用 `BrowserWindow.getCurrentWindow().setSheetOffset(offset)` 来改变 +sheets 的窗口框架的偏移量。 From 8f542b1d6954d503b38ebbdb496fbb8af59ee6a4 Mon Sep 17 00:00:00 2001 From: Weiqiang Lin <23leo@163.com> Date: Thu, 9 Feb 2017 17:08:58 +0800 Subject: [PATCH 06/16] globalShortcut to zh-CN --- .../zh-CN/api/global-shortcut.md | 47 ++++++++++++------- 1 file changed, 29 insertions(+), 18 deletions(-) diff --git a/docs-translations/zh-CN/api/global-shortcut.md b/docs-translations/zh-CN/api/global-shortcut.md index c8da091a2dba..15037c73c087 100644 --- a/docs-translations/zh-CN/api/global-shortcut.md +++ b/docs-translations/zh-CN/api/global-shortcut.md @@ -1,18 +1,21 @@ -# global-shortcut +# globalShortcut -`global-shortcut` 模块可以便捷的为您设置(注册/注销)各种自定义操作的快捷键. +> 当应用程序没有键盘焦点时检测键盘事件。 -**Note**: 使用此模块注册的快捷键是系统全局的(QQ截图那种), 不要在应用模块(app module)响应 `ready` -消息前使用此模块(注册快捷键). +进程: [Main](../glossary.md#main-process) + +`globalShortcut` 模块可以便捷的为你设置（注册/注销）各种自定义操作的快捷键。 + +**注意：** 使用此模块注册的快捷键是系统全局的(QQ截图那种), 不要在应用模块（app module）响应 `ready` +消息前使用此模块（注册快捷键）。 ```javascript -var app = require('app') -var globalShortcut = require('global-shortcut') +const {app, globalShortcut} = require('electron') -app.on('ready', function () { - // Register a 'ctrl+x' shortcut listener. - var ret = globalShortcut.register('ctrl+x', function () { - console.log('ctrl+x is pressed') +app.on('ready', () => { + // Register a 'CommandOrControl+X' shortcut listener. + const ret = globalShortcut.register('CommandOrControl+X', () => { + console.log('CommandOrControl+X is pressed') }) if (!ret) { @@ -20,12 +23,12 @@ app.on('ready', function () { } // Check whether a shortcut is registered. - console.log(globalShortcut.isRegistered('ctrl+x')) + console.log(globalShortcut.isRegistered('CommandOrControl+X')) }) -app.on('will-quit', function () { +app.on('will-quit', () => { // Unregister a shortcut. - globalShortcut.unregister('ctrl+x') + globalShortcut.unregister('CommandOrControl+X') // Unregister all shortcuts. globalShortcut.unregisterAll() @@ -34,27 +37,35 @@ app.on('will-quit', function () { ## Methods -`global-shortcut` 模块包含以下函数: +`globalShortcut` 模块包含以下函数: ### `globalShortcut.register(accelerator, callback)` * `accelerator` [Accelerator](accelerator.md) * `callback` Function -注册 `accelerator` 快捷键. 当用户按下注册的快捷键时将会调用 `callback` 函数. +注册 `accelerator` 快捷键。当用户按下注册的快捷键时将会调用 `callback` 函数。 + +当 accelerator 已经被其他应用程序占用时，此调用将 +默默地失败。这种行为是操作系统的意图，因为它们没有 +想要应用程序争取全局快捷键。 ### `globalShortcut.isRegistered(accelerator)` * `accelerator` [Accelerator](accelerator.md) -查询 `accelerator` 快捷键是否已经被注册过了,将会返回 `true`(已被注册) 或 `false`(未注册). +返回 `Boolean` - 查询 `accelerator` 快捷键是否已经被注册过了，将会返回 `true` 或 `false`。 + +当 accelerator 已经被其他应用程序占用时，此调用将 +默默地失败。这种行为是操作系统的意图，因为它们没有 +想要应用程序争取全局快捷键。 ### `globalShortcut.unregister(accelerator)` * `accelerator` [Accelerator](accelerator.md) -注销全局快捷键 `accelerator`. +注销全局快捷键 `accelerator`。 ### `globalShortcut.unregisterAll()` -注销本应用注册的所有全局快捷键. +注销本应用程序注册的所有全局快捷键。 From c7b639e28297dddc63108ed01570329171b0eb06 Mon Sep 17 00:00:00 2001 From: Weiqiang Lin <23leo@163.com> Date: Thu, 9 Feb 2017 17:16:27 +0800 Subject: [PATCH 07/16] ipcMain to zh-CN --- docs-translations/zh-CN/api/ipc-main.md | 46 ++++++++++++++----------- 1 file changed, 25 insertions(+), 21 deletions(-) diff --git a/docs-translations/zh-CN/api/ipc-main.md b/docs-translations/zh-CN/api/ipc-main.md index c3b4b90eb3bf..e84a9f4f4efc 100644 --- a/docs-translations/zh-CN/api/ipc-main.md +++ b/docs-translations/zh-CN/api/ipc-main.md @@ -1,28 +1,32 @@ # ipcMain +> 从主进程到渲染器进程异步通信。 + +进程：[Main](../glossary.md#main-process) + `ipcMain` 模块是类 -[EventEmitter](https://nodejs.org/api/events.html) 的实例.当在主进程中使用它的时候，它控制着由渲染进程(web page)发送过来的异步或同步消息.从渲染进程发送过来的消息将触发事件. +[EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter) 的实例。当在主进程中使用它的时候，它控制着由渲染进程(web page)发送过来的异步或同步消息。从渲染进程发送过来的消息将触发事件。 ## 发送消息 -同样也可以从主进程向渲染进程发送消息，查看更多 [webContents.send][web-contents-send] . +同样也可以从主进程向渲染进程发送消息，查看更多 [webContents.send][web-contents-send] 。 -* 发送消息，事件名为 `channel`. -* 回应同步消息, 你可以设置 `event.returnValue`. +* 发送消息，事件名为 `channel`。 +* 回应同步消息, 你可以设置 `event.returnValue`。 * 回应异步消息, 你可以使用 - `event.sender.send(...)`. + `event.sender.send(...)`。 -一个例子，在主进程和渲染进程之间发送和处理消息: +一个例子，在主进程和渲染进程之间发送和处理消息： ```javascript // In main process. -const ipcMain = require('electron').ipcMain -ipcMain.on('asynchronous-message', function (event, arg) { +const {ipcMain} = require('electron') +ipcMain.on('asynchronous-message', (event, arg) => { console.log(arg) // prints "ping" event.sender.send('asynchronous-reply', 'pong') }) -ipcMain.on('synchronous-message', function (event, arg) { +ipcMain.on('synchronous-message', (event, arg) => { console.log(arg) // prints "ping" event.returnValue = 'pong' }) @@ -30,56 +34,56 @@ ipcMain.on('synchronous-message', function (event, arg) { ```javascript // In renderer process (web page). -const ipcRenderer = require('electron').ipcRenderer +const {ipcRenderer} = require('electron') console.log(ipcRenderer.sendSync('synchronous-message', 'ping')) // prints "pong" -ipcRenderer.on('asynchronous-reply', function (event, arg) { +ipcRenderer.on('asynchronous-reply', (event, arg) => { console.log(arg) // prints "pong" }) ipcRenderer.send('asynchronous-message', 'ping') ``` -## 监听消息 +## 方法 -`ipcMain` 模块有如下监听事件方法: +`ipcMain` 模块有如下监听事件方法： ### `ipcMain.on(channel, listener)` * `channel` String * `listener` Function -监听 `channel`, 当新消息到达，将通过 `listener(event, args...)` 调用 `listener`. +监听 `channel`, 当新消息到达，将通过 `listener(event, args...)` 调用 `listener`。 ### `ipcMain.once(channel, listener)` * `channel` String * `listener` Function -为事件添加一个一次性用的`listener` 函数.这个 `listener` 只有在下次的消息到达 `channel` 时被请求调用，之后就被删除了. +为事件添加一个一次性用的`listener` 函数。这个 `listener` 只有在下次的消息到达 `channel` 时被请求调用，之后就被删除了。 ### `ipcMain.removeListener(channel, listener)` * `channel` String * `listener` Function -为特定的 `channel` 从监听队列中删除特定的 `listener` 监听者. +为特定的 `channel` 从监听队列中删除特定的 `listener` 监听者。 ### `ipcMain.removeAllListeners([channel])` * `channel` String (可选) -删除所有监听者，或特指的 `channel` 的所有监听者. +删除所有监听者，或特指的 `channel` 的所有监听者。 ## 事件对象 -传递给 `callback` 的 `event` 对象有如下方法: +传递给 `callback` 的 `event` 对象有如下方法： ### `event.returnValue` -将此设置为在一个同步消息中返回的值. +将此设置为在一个同步消息中返回的值。 ### `event.sender` -返回发送消息的 `webContents` ，你可以调用 `event.sender.send` 来回复异步消息，更多信息 [webContents.send][web-contents-send]. +返回发送消息的 `webContents` ，你可以调用 `event.sender.send` 来回复异步消息，更多信息 [webContents.send][web-contents-send]。 -[web-contents-send]: web-contents.md#webcontentssendchannel-arg1-arg2- \ No newline at end of file +[web-contents-send]: web-contents.md#webcontentssendchannel-arg1-arg2- From eba65eb4d30f40b6d0ea3db32117ac36194720d4 Mon Sep 17 00:00:00 2001 From: Weiqiang Lin <23leo@163.com> Date: Thu, 9 Feb 2017 17:34:45 +0800 Subject: [PATCH 08/16] Class: Menu to zh-CN --- docs-translations/zh-CN/api/menu.md | 481 +++++++++++++++------------- 1 file changed, 253 insertions(+), 228 deletions(-) diff --git a/docs-translations/zh-CN/api/menu.md b/docs-translations/zh-CN/api/menu.md index 07736d4bbd2b..0baddba1da9c 100644 --- a/docs-translations/zh-CN/api/menu.md +++ b/docs-translations/zh-CN/api/menu.md @@ -1,215 +1,31 @@ -# 菜单 +# 类：菜单 -`menu` 类可以用来创建原生菜单，它可用作应用菜单和 -[context 菜单](https://developer.mozilla.org/en-US/docs/Mozilla/Tech/XUL/PopupGuide/ContextMenus). +> 创建原生的应用菜单和 context 菜单。 -这个模块是一个主进程的模块，并且可以通过 `remote` 模块给渲染进程调用. - -每个菜单有一个或几个菜单项 [menu items](menu-item.md)，并且每个菜单项可以有子菜单. - -下面这个例子是在网页(渲染进程)中通过 [remote](remote.md) 模块动态创建的菜单，并且右键显示: - -```html - - -``` - -例子，在渲染进程中使用模板api创建应用菜单: - -```javascript -var template = [ - { - label: 'Edit', - submenu: [ - { - label: 'Undo', - accelerator: 'CmdOrCtrl+Z', - role: 'undo' - }, - { - label: 'Redo', - accelerator: 'Shift+CmdOrCtrl+Z', - role: 'redo' - }, - { - type: 'separator' - }, - { - label: 'Cut', - accelerator: 'CmdOrCtrl+X', - role: 'cut' - }, - { - label: 'Copy', - accelerator: 'CmdOrCtrl+C', - role: 'copy' - }, - { - label: 'Paste', - accelerator: 'CmdOrCtrl+V', - role: 'paste' - }, - { - label: 'Select All', - accelerator: 'CmdOrCtrl+A', - role: 'selectall' - } - ] - }, - { - label: 'View', - submenu: [ - { - label: 'Reload', - accelerator: 'CmdOrCtrl+R', - click: function (item, focusedWindow) { - if (focusedWindow) focusedWindow.reload() - } - }, - { - label: 'Toggle Full Screen', - accelerator: (function () { - return (process.platform === 'darwin') ? 'Ctrl+Command+F' : 'F11' - })(), - click: function (item, focusedWindow) { - if (focusedWindow) focusedWindow.setFullScreen(!focusedWindow.isFullScreen()) - } - }, - { - label: 'Toggle Developer Tools', - accelerator: (function () { - if (process.platform === 'darwin') { - return 'Alt+Command+I' - } else { - return 'Ctrl+Shift+I' - } - })(), - click: function (item, focusedWindow) { - if (focusedWindow) focusedWindow.toggleDevTools() - } - } - ] - }, - { - label: 'Window', - role: 'window', - submenu: [ - { - label: 'Minimize', - accelerator: 'CmdOrCtrl+M', - role: 'minimize' - }, - { - label: 'Close', - accelerator: 'CmdOrCtrl+W', - role: 'close' - } - ] - }, - { - label: 'Help', - role: 'help', - submenu: [ - { - label: 'Learn More', - click: function () { require('electron').shell.openExternal('http://electron.atom.io') } - } - ] - } -] - -if (process.platform === 'darwin') { - var name = require('electron').remote.app.getName() - template.unshift({ - label: name, - submenu: [ - { - label: 'About ' + name, - role: 'about' - }, - { - type: 'separator' - }, - { - label: 'Services', - role: 'services', - submenu: [] - }, - { - type: 'separator' - }, - { - label: 'Hide ' + name, - accelerator: 'Command+H', - role: 'hide' - }, - { - label: 'Hide Others', - accelerator: 'Command+Alt+H', - role: 'hideothers' - }, - { - label: 'Show All', - role: 'unhide' - }, - { - type: 'separator' - }, - { - label: 'Quit', - accelerator: 'Command+Q', - click: function () { app.quit() } - } - ] - }) - // Window menu. - template[3].submenu.push( - { - type: 'separator' - }, - { - label: 'Bring All to Front', - role: 'front' - } - ) -} - -var menu = Menu.buildFromTemplate(template) -Menu.setApplicationMenu(menu) -``` - -## 类: Menu +进程： [Main](../glossary.md#main-process) ### `new Menu()` -创建一个新的菜单. +创建一个新的菜单。 -## 方法 +### 静态方法 -`菜单` 类有如下方法: +`菜单` 类有如下静态方法： -### `Menu.setApplicationMenu(menu)` +#### `Menu.setApplicationMenu(menu)` * `menu` Menu -在 macOS 上设置应用菜单 `menu` . -在windows 和 linux，是为每个窗口都在其顶部设置菜单 `menu`. +在 macOS 上设置应用菜单 `menu`。 +在 windows 和 linux，是为每个窗口都在其顶部设置菜单 `menu`。 -### `Menu.sendActionToFirstResponder(action)` _macOS_ +**注意：** 这个API必须在 `app` 模块的 `ready` 事件后调用。 + +#### `Menu.getApplicationMenu()` + +返回 `Menu` - 应用程序菜单，设置、 `null` 、或未设置。 + +#### `Menu.sendActionToFirstResponder(action)` _macOS_ * `action` String @@ -217,19 +33,21 @@ Menu.setApplicationMenu(menu) 查看更多 macOS 的原生 action [macOS Cocoa Event Handling Guide](https://developer.apple.com/library/mac/documentation/Cocoa/Conceptual/EventOverview/EventArchitecture/EventArchitecture.html#//apple_ref/doc/uid/10000060i-CH3-SW7) . -### `Menu.buildFromTemplate(template)` +#### `Menu.buildFromTemplate(template)` -* `template` Array +* `template` MenuItemConstructorOptions[] -一般来说，`template` 只是用来创建 [MenuItem](menu-item.md) 的数组 `参数` . +返回 `Menu` -你也可以向 `template` 元素添加其它东西，并且他们会变成已经有的菜单项的属性. +一般来说，`template` 只是用来创建 [MenuItem](menu-item.md) 的数组 `参数`。 -##实例方法 +你也可以向 `template` 元素添加其它东西，并且他们会变成已经有的菜单项的属性。 + +### 实例方法 `menu` 对象有如下实例方法 -### `menu.popup([browserWindow, x, y, positioningItem])` +#### `menu.popup([browserWindow, x, y, positioningItem])` * `browserWindow` BrowserWindow (可选) - 默认为 `null`. * `x` Number (可选) - 默认为 -1. @@ -239,31 +57,239 @@ Menu.setApplicationMenu(menu) 在 `browserWindow` 中弹出 context menu .你可以选择性地提供指定的 `x, y` 来设置菜单应该放在哪里,否则它将默认地放在当前鼠标的位置. -### `menu.append(menuItem)` +#### `menu.append(menuItem)` * `menuItem` MenuItem -添加菜单项. +添加菜单项。 -### `menu.insert(pos, menuItem)` +#### `menu.insert(pos, menuItem)` * `pos` Integer * `menuItem` MenuItem -在制定位置添加菜单项. +在指定位置添加菜单项。 -### `menu.items()` +### 实例属性 -获取一个菜单项数组. +`menu` 对象拥有以下属性： + +#### `menu.items()` + +获取一个菜单项数组。 + +## 例子 + +`Menu` 类只能在主进程中使用，但你也可以 +在渲染过程中通过 [`remote`](remote.md) 模块使用它。 + +### 主进程 + +在主进程中创建应用程序菜单的示例 +简单模板API： + +```javascript +const {app, Menu} = require('electron') + +const template = [ + { + label: 'Edit', + submenu: [ + { + role: 'undo' + }, + { + role: 'redo' + }, + { + type: 'separator' + }, + { + role: 'cut' + }, + { + role: 'copy' + }, + { + role: 'paste' + }, + { + role: 'pasteandmatchstyle' + }, + { + role: 'delete' + }, + { + role: 'selectall' + } + ] + }, + { + label: 'View', + submenu: [ + { + role: 'reload' + }, + { + role: 'forcereload' + }, + { + role: 'toggledevtools' + }, + { + type: 'separator' + }, + { + role: 'resetzoom' + }, + { + role: 'zoomin' + }, + { + role: 'zoomout' + }, + { + type: 'separator' + }, + { + role: 'togglefullscreen' + } + ] + }, + { + role: 'window', + submenu: [ + { + role: 'minimize' + }, + { + role: 'close' + } + ] + }, + { + role: 'help', + submenu: [ + { + label: 'Learn More', + click () { require('electron').shell.openExternal('http://electron.atom.io') } + } + ] + } +] + +if (process.platform === 'darwin') { + template.unshift({ + label: app.getName(), + submenu: [ + { + role: 'about' + }, + { + type: 'separator' + }, + { + role: 'services', + submenu: [] + }, + { + type: 'separator' + }, + { + role: 'hide' + }, + { + role: 'hideothers' + }, + { + role: 'unhide' + }, + { + type: 'separator' + }, + { + role: 'quit' + } + ] + }) + // Edit menu. + template[1].submenu.push( + { + type: 'separator' + }, + { + label: 'Speech', + submenu: [ + { + role: 'startspeaking' + }, + { + role: 'stopspeaking' + } + ] + } + ) + // Window menu. + template[3].submenu = [ + { + label: 'Close', + accelerator: 'CmdOrCtrl+W', + role: 'close' + }, + { + label: 'Minimize', + accelerator: 'CmdOrCtrl+M', + role: 'minimize' + }, + { + label: 'Zoom', + role: 'zoom' + }, + { + type: 'separator' + }, + { + label: 'Bring All to Front', + role: 'front' + } + ] +} + +const menu = Menu.buildFromTemplate(template) +Menu.setApplicationMenu(menu) +``` + +### 渲染进程 + +以下是通过使用 [`remote`](remote.md) 模块在网页（渲染进程）中动态创建菜单的示例 +，并在用户点击右键时显示： + +```html + + +``` ## macOS Application 上的菜单的注意事项 -相对于windows 和 linux, macOS 上的应用菜单是完全不同的style，这里是一些注意事项，来让你的菜单项更原生化. +相对于 windows 和 linux, macOS 上的应用菜单是完全不同的 style，这里是一些注意事项，来让你的菜单项更原生化。 ### 标准菜单 -在 macOS 上，有很多系统定义的标准菜单，例如 `Services` and -`Windows` 菜单.为了让你的应用更标准化，你可以为你的菜单的 `role` 设置值，然后 electron 将会识别他们并且让你的菜单更标准: +在 macOS 上，有很多系统定义的标准菜单，例如 `Services` and +`Windows` 菜单.为了让你的应用更标准化，你可以为你的菜单的 `role` 设置值，然后 Electron 将会识别他们并且让你的菜单更标准： * `window` * `help` @@ -271,29 +297,29 @@ Menu.setApplicationMenu(menu) ### 标准菜单项行为 -macOS 为一些菜单项提供了标准的行为方法，例如 `About xxx`, -`Hide xxx`, and `Hide Others`. 为了让你的菜单项的行为更标准化，你应该为菜单项设置 `role` 属性. +macOS 为一些菜单项提供了标准的行为方法，例如 `About xxx`， +`Hide xxx`,和 `Hide Others`. 为了让你的菜单项的行为更标准化，你应该为菜单项设置 `role` 属性。 ### 主菜单名 -在 macOS ，无论你设置的什么标签，应用菜单的第一个菜单项的标签始终未你的应用名字.想要改变它的话，你必须通过修改应用绑定的 `Info.plist` 文件来修改应用名字.更多信息参考[About Information -Property List Files][AboutInformationPropertyListFiles] . +在 macOS ，无论你设置的什么标签，应用菜单的第一个菜单项的标签始终未你的应用名字。想要改变它的话，你必须通过修改应用绑定的 `Info.plist` 文件来修改应用名字，更多信息参考 [About Information +Property List Files][AboutInformationPropertyListFiles] 。 ## 为制定浏览器窗口设置菜单 (*Linux* *Windows*) -浏览器窗口的[`setMenu` 方法][setMenu] 能够设置菜单为特定浏览器窗口的类型. +浏览器窗口的 [`setMenu` 方法][setMenu] 能够设置菜单为特定浏览器窗口的类型。 ## 菜单项位置 -当通过 `Menu.buildFromTemplate` 创建菜单的时候，你可以使用 `position` and `id` 来放置菜单项. +当通过 `Menu.buildFromTemplate` 创建菜单的时候，你可以使用 `position` and `id` 来放置菜单项。 -`MenuItem` 的属性 `position` 格式为 `[placement]=[id]`，`placement` 取值为 `before`, `after`, 或 `endof` 和 `id`， `id` 是菜单已经存在的菜单项的唯一 ID: +`MenuItem` 的属性 `position` 格式为 `[placement]=[id]`，`placement` 取值为 `before`, `after`, 或 `endof` 和 `id`， `id` 是菜单已经存在的菜单项的唯一 ID： -* `before` - 在对应引用id菜单项之前插入. 如果引用的菜单项不存在，则将其插在菜单末尾. -* `after` - 在对应引用id菜单项之后插入. 如果引用的菜单项不存在，则将其插在菜单末尾. -* `endof` - 在逻辑上包含对应引用id菜单项的集合末尾插入. 如果引用的菜单项不存在, 则将使用给定的id创建一个新的集合，并且这个菜单项将插入. +* `before` - 在对应引用id菜单项之前插入。如果引用的菜单项不存在，则将其插在菜单末尾。 +* `after` - 在对应引用id菜单项之后插入。如果引用的菜单项不存在，则将其插在菜单末尾。 +* `endof` - 在逻辑上包含对应引用id菜单项的集合末尾插入。如果引用的菜单项不存在, 则将使用给定的id创建一个新的集合，并且这个菜单项将插入。 -当一个菜档项插入成功了，所有的没有插入的菜单项将一个接一个地在后面插入.所以如果你想在同一个位置插入一组菜单项，只需要为这组菜单项的第一个指定位置. +当一个菜档项插入成功了，所有的没有插入的菜单项将一个接一个地在后面插入。所以如果你想在同一个位置插入一组菜单项，只需要为这组菜单项的第一个指定位置。 ### 例子 @@ -346,5 +372,4 @@ Property List Files][AboutInformationPropertyListFiles] . ``` [AboutInformationPropertyListFiles]: https://developer.apple.com/library/ios/documentation/general/Reference/InfoPlistKeyReference/Articles/AboutInformationPropertyListFiles.html -[setMenu]: -https://github.com/electron/electron/blob/master/docs/api/browser-window.md#winsetmenumenu-linux-windows +[setMenu]: https://github.com/electron/electron/blob/master/docs/api/browser-window.md#winsetmenumenu-linux-windows From e267a0dd4194e626889cc24d49fd6b115f5bc96b Mon Sep 17 00:00:00 2001 From: Weiqiang Lin <23leo@163.com> Date: Thu, 9 Feb 2017 17:57:27 +0800 Subject: [PATCH 09/16] Class: MenuItem to zh-CN --- docs-translations/zh-CN/api/menu-item.md | 93 ++++++++++++++++++------ 1 file changed, 71 insertions(+), 22 deletions(-) diff --git a/docs-translations/zh-CN/api/menu-item.md b/docs-translations/zh-CN/api/menu-item.md index 6d5d59d934e4..c2091674a52a 100644 --- a/docs-translations/zh-CN/api/menu-item.md +++ b/docs-translations/zh-CN/api/menu-item.md @@ -1,29 +1,40 @@ # 菜单项 -菜单项模块允许你向应用或[menu][1]添加选项。 -查看[menu][1]例子。 +## 类：菜单项 -## 类：MenuItem -使用下面的方法创建一个新的 `MenuItem` +> 向原生的应用菜单和 context 菜单添加菜单项。 + +进程： [Main](../glossary.md#main-process) + +查看 [`Menu`](menu.md) 的示。 + +### `new MenuItem(options)` -###new MenuItem(options) * `options` Object - * `click` Function - 当菜单项被点击的时候，使用 `click(menuItem,browserWindow)` 调用 - * `role` String - 定义菜单项的行为，在指定 `click` 属性时将会被忽略 - * `type` String - 取值 `normal`，`separator`，`checkbox`or`radio` - * `label` String - * `sublabel` String - * `accelerator` [Accelerator][2] - * `icon` [NativeImage][3] - * `enabled` Boolean - * `visible` Boolean - * `checked` Boolean - * `submenu` Menu - 应当作为 `submenu` 菜单项的特定类型，当它作为 `type: 'submenu'` 菜单项的特定类型时可以忽略。如果它的值不是 `Menu`，将自动转为 `Menu.buildFromTemplate`。 - * `id` String - 标志一个菜单的唯一性。如果被定义使用，它将被用作这个菜单项的参考位置属性。 - * `position` String - 定义给定的菜单的具体指定位置信息。 + * `click` Function (可选) - 当菜单项被点击的时候，使用 `click(menuItem,browserWindow)` 调用。 + * `menuItem` MenuItem + * `browserWindow` BrowserWindow + * `event` Event + * `role` String (可选) - 定义菜单项的行为，在指定 `click` 属性时将会被忽略。 + * `type` String (可选) - 取值 `normal`, `separator`, `submenu`, `checkbox` or `radio`。 + * `label` String - (可选) + * `sublabel` String - (可选) + * `accelerator` [Accelerator](accelerator.md) (可选) + * `icon` ([NativeImage](native-image.md) | String) (可选) + * `enabled` Boolean (可选) - 如果为 false，菜单项将显示为灰色不可点击。 + unclickable. + * `visible` Boolean (可选) - 如果为 false，菜单项将完全隐藏。 + * `checked` Boolean (可选) - 只为 `checkbox` 或 `radio` 类型的菜单项。 + * `submenu` (MenuItemConstructorOptions[] | Menu) (可选) - 应当作为 `submenu` 菜单项的特定类型，当它作为 `type: 'submenu'` 菜单项的特定类型时可以忽略。如果它的值不是 `Menu`，将自动转为 `Menu.buildFromTemplate`。 + * `id` String (可选) - 标志一个菜单的唯一性。如果被定义使用，它将被用作这个菜单项的参考位置属性。 + * `position` String (可选) - 定义菜单的具体指定位置信息。 -在创建菜单项时，如果有匹配的方法，建议指定 `role` 属性，不需要人为操作它的行为，这样菜单使用可以给用户最好的体验。 +在创建菜单项时，如果有匹配的方法，建议指定 `role` 属性， +而不是试图手动实现在一个 `click` 函数中的行为。 +内置的 `role` 行为将提供最好的原生体验。 +当使用 `role' 时，`label' 和 `accelerator` 是可选的，默认为 +到每个平台的适当值。 `role`属性值可以为： @@ -32,9 +43,19 @@ * `cut` * `copy` * `paste` +* `pasteandmatchstyle` * `selectall` +* `delete` * `minimize` - 最小化当前窗口 * `close` - 关闭当前窗口 +* `quit`- 退出应用程序 +* `reload` - 正常重新加载当前窗口 +* `forcereload` - 忽略缓存并重新加载当前窗口 +* `toggledevtools` - 在当前窗口中切换开发者工具 +* `togglefullscreen`- 在当前窗口中切换全屏模式 +* `resetzoom` - 将对焦页面的缩放级别重置为原始大小 +* `zoomin` - 将聚焦页面缩小10％ +* `zoomout` - 将聚焦页面放大10％ 在 macOS 上，`role` 还可以有以下值： @@ -42,16 +63,44 @@ * `hide` - 匹配 `hide` 行为 * `hideothers` - 匹配 `hideOtherApplications` 行为 * `unhide` - 匹配 `unhideAllApplications` 行为 +* `startspeaking` - 匹配 `startSpeaking` 行为 +* `stopspeaking` - 匹配 `stopSpeaking` 行为 * `front` - 匹配 `arrangeInFront` 行为 +* `zoom` - 匹配 `performZoom` 行为 * `window` - "Window" 菜单项 * `help` - "Help" 菜单项 * `services` - "Services" 菜单项 +当在 macOS 上指定 `role' 时，`label` 和 `accelerator` 是影响MenuItem的唯一的选项 +所有其他选项将被忽略。 +### 实例属性 +`MenuItem` 对象拥有以下属性： +#### `menuItem.enabled` +一个布尔值表示是否启用该项，此属性可以动态改变。 - [1]:https://github.com/heyunjiang/electron/blob/master/docs-translations/zh-CN/api/menu.md - [2]:https://github.com/heyunjiang/electron/blob/master/docs/api/accelerator.md - [3]:https://github.com/heyunjiang/electron/blob/master/docs/api/native-image.md \ No newline at end of file +#### `menuItem.visible` + +一个布尔值表示是否可见，此属性可以动态改变。 + +#### `menuItem.checked` + +一个布尔值表示是否选中该项，此属性可以动态改变。 + +`checkbox` 菜单项将在选中和未选中切换 `checked` 属性。 + +`radio` 菜单项将在选中切换 `checked` 属性，并且 +将关闭同一菜单中所有相邻项目的属性。 + +您可以为其他行为添加一个 `click` 函数。 + +#### `menuItem.label` + +一个表示菜单项可见标签的字符串 + +#### `menuItem.click` + +当 MenuItem 接收到点击事件时触发的函数 From 50fbd5266a1c5078a33220d8ba751593967c9c0e Mon Sep 17 00:00:00 2001 From: Weiqiang Lin <23leo@163.com> Date: Sun, 12 Feb 2017 22:00:09 +0800 Subject: [PATCH 10/16] powerMonitor to zh-CN --- docs-translations/zh-CN/api/power-monitor.md | 26 +++++++++++--------- 1 file changed, 15 insertions(+), 11 deletions(-) diff --git a/docs-translations/zh-CN/api/power-monitor.md b/docs-translations/zh-CN/api/power-monitor.md index 7395a8b3b47f..39bbaa6efe5f 100644 --- a/docs-translations/zh-CN/api/power-monitor.md +++ b/docs-translations/zh-CN/api/power-monitor.md @@ -1,12 +1,19 @@ # powerMonitor -`power-monitor`模块是用来监听能源区改变的.只能在主进程中使用.在 `app` 模块的 `ready` 事件触发之后就不能使用这个模块了. +> 监视电源状态更改。 + +进程： [Main](../glossary.md#main-process) + +在 `app` 模块的 `ready` 事件触发之后就不能使用这个模块了。 例如: ```javascript -app.on('ready', function () { - require('electron').powerMonitor.on('suspend', function () { +const electron = require('electron') +const {app} = electron + +app.on('ready', () => { + electron.powerMonitor.on('suspend', () => { console.log('The system is going to sleep') }) }) @@ -14,23 +21,20 @@ app.on('ready', function () { ## 事件 -`power-monitor` 模块可以触发下列事件: +`powerMonitor` 模块可以触发下列事件： ### Event: 'suspend' -在系统挂起的时候触发. +在系统挂起的时候触发。 ### Event: 'resume' -在系统恢复继续工作的时候触发. -Emitted when system is resuming. +在系统恢复继续工作的时候触发。 ### Event: 'on-ac' -在系统使用交流电的时候触发. -Emitted when the system changes to AC power. +在系统使用交流电的时候触发。 ### Event: 'on-battery' -在系统使用电池电源的时候触发. -Emitted when system changes to battery power. \ No newline at end of file +在系统使用电池电源的时候触发。 From 6a0738aa88b21cae5955adb9f671d4d7324e5c9e Mon Sep 17 00:00:00 2001 From: Weiqiang Lin <23leo@163.com> Date: Sun, 12 Feb 2017 22:07:24 +0800 Subject: [PATCH 11/16] powerSaveBlocker to zh-CN --- .../zh-CN/api/power-save-blocker.md | 44 ++++++++++--------- 1 file changed, 24 insertions(+), 20 deletions(-) diff --git a/docs-translations/zh-CN/api/power-save-blocker.md b/docs-translations/zh-CN/api/power-save-blocker.md index 67b1396d868c..da6ffbdb8002 100644 --- a/docs-translations/zh-CN/api/power-save-blocker.md +++ b/docs-translations/zh-CN/api/power-save-blocker.md @@ -1,13 +1,15 @@ # powerSaveBlocker -`powerSaveBlocker` 模块是用来阻止应用系统进入睡眠模式的，因此这允许应用保持系统和屏幕继续工作. +> 阻止系统进入低功耗（睡眠）模式。 + +进程： [Main](../glossary.md#main-process) 例如: ```javascript -const powerSaveBlocker = require('electron').powerSaveBlocker +const {powerSaveBlocker} = require('electron') -var id = powerSaveBlocker.start('prevent-display-sleep') +const id = powerSaveBlocker.start('prevent-display-sleep') console.log(powerSaveBlocker.isStarted(id)) powerSaveBlocker.stop(id) @@ -15,34 +17,36 @@ powerSaveBlocker.stop(id) ## 方法 -`powerSaveBlocker` 模块有如下方法: +`powerSaveBlocker` 模块有如下方法： ### `powerSaveBlocker.start(type)` -* `type` String - 强行保存阻塞类型. - * `prevent-app-suspension` - 阻止应用挂起. - 保持系统活跃，但是允许屏幕不亮. 用例: - 下载文件或者播放音频. - * `prevent-display-sleep`- 阻止应用进入休眠. 保持系统和屏幕活跃，屏幕一直亮. 用例: 播放音频. +* `type` String - 强行保存阻塞类型。 + * `prevent-app-suspension` - 阻止应用挂起。 + 保持系统活跃，但是允许屏幕不亮。例如： + 下载文件或者播放音频。 + * `prevent-display-sleep`- 阻止应用进入休眠。保持系统和屏幕活跃，屏幕一直亮。例如：播放音频。 -开始阻止系统进入睡眠模式.返回一个整数，这个整数标识了保持活跃的blocker. +返回 `Integer` - 分配给此阻断器的 blocker ID -**注意:** `prevent-display-sleep` 有更高的优先级 -`prevent-app-suspension`. 只有最高优先级生效. 换句话说, `prevent-display-sleep` 优先级永远高于 -`prevent-app-suspension`. +开始阻止系统进入睡眠模式。返回一个整数，这个整数标识了保持活跃的blocker ID。 -例如, A 请求调用了 `prevent-app-suspension`, B请求调用了 `prevent-display-sleep`. `prevent-display-sleep` -将一直工作，直到B停止调用. 在那之后, `prevent-app-suspension` -才起效. +**注意：** `prevent-display-sleep` 有更高的优先级 +`prevent-app-suspension`。只有最高优先级生效，换句话说, `prevent-display-sleep` 优先级永远高于 +`prevent-app-suspension`。 + +例如, A 请求调用了 `prevent-app-suspension`，B请求调用了 `prevent-display-sleep`。`prevent-display-sleep` +将一直工作，直到B停止调用。在那之后，`prevent-app-suspension` +才起效。 ### `powerSaveBlocker.stop(id)` -* `id` Integer - 通过 `powerSaveBlocker.start` 返回的保持活跃的 blocker id. +* `id` Integer - 通过 `powerSaveBlocker.start` 返回保持活跃的 blocker id. -让指定blocker 停止活跃. +让指定 blocker 停止活跃。 ### `powerSaveBlocker.isStarted(id)` -* `id` Integer - 通过 `powerSaveBlocker.start` 返回的保持活跃的 blocker id. +* `id` Integer - 通过 `powerSaveBlocker.start` 返回保持活跃的 blocker id. -返回 boolean， 是否对应的 `powerSaveBlocker` 已经启动. \ No newline at end of file +返回 boolean，对应的 `powerSaveBlocker` 是否已经启动。 From 9fd9b39448f24dc84efeea1076205d09a22f0522 Mon Sep 17 00:00:00 2001 From: Weiqiang Lin <23leo@163.com> Date: Sun, 12 Feb 2017 22:35:03 +0800 Subject: [PATCH 12/16] protocol to -zh-CN --- docs-translations/zh-CN/api/protocol.md | 217 +++++++++++++++++------- 1 file changed, 157 insertions(+), 60 deletions(-) diff --git a/docs-translations/zh-CN/api/protocol.md b/docs-translations/zh-CN/api/protocol.md index 44c5a0a05fc1..e188bc0fcdf9 100644 --- a/docs-translations/zh-CN/api/protocol.md +++ b/docs-translations/zh-CN/api/protocol.md @@ -1,8 +1,10 @@ # 协议 -`protocol` 模块可以注册一个自定义协议，或者使用一个已经存在的协议. +> 注册一个自定义协议，或者使用一个已经存在的协议。 -例子，使用一个与 `file://` 功能相似的协议 : +进程： [Main](../glossary.md#main-process) + +例如使用一个与 `file://` 功能相似的协议： ```javascript const {app, protocol} = require('electron') @@ -18,70 +20,112 @@ app.on('ready', () => { }) ``` -**注意:** 这个模块只有在 `app` 模块的 `ready` 事件触发之后才可使用. +**注意：** 这个模块只有在 `app` 模块的 `ready` 事件触发之后才可使用。 ## 方法 -`protocol` 模块有如下方法: +`protocol` 模块有如下方法： -### `protocol.registerStandardSchemes(schemes)` +### `protocol.registerStandardSchemes(schemes[, options])` -* `schemes` Array - 将一个自定义的方案注册为标准的方案. +* `schemes` String[] - 将一个自定义的方案注册为标准的方案。 +* `options` Object (可选) + * `secure` Boolean (可选) - `true` 将方案注册为安全。 + 默认值 `false`。 一个标准的 `scheme` 遵循 RFC 3986 的 -[generic URI syntax](https://tools.ietf.org/html/rfc3986#section-3) 标准. 这包含了 `file:` 和 `filesystem:`. +[generic URI syntax](https://tools.ietf.org/html/rfc3986#section-3) 标准。例如 `http` 和 +`https` 是标准方案，而 `file` 不是。 + +注册一个 `scheme` 作为标准，将允许相对和绝对的资源 +在服务时正确解析。 否则该方案将表现得像 +`file` 协议，但无法解析相对 URLs。 + +例如，当你加载以下页面与自定义协议无法 +注册为标准 `scheme`，图像将不会加载，因为 +非标准方案无法识别相对 URLs： + +```html + + + +``` + +注册方案作为标准将允许通过访问文件 +[FileSystem API][file-system-api]。 否则渲染器将抛出一个安全性 +错误。 + +默认情况下 web storage apis（localStorage，sessionStorage，webSQL，indexedDB，cookies） +对于非标准方案禁用。所以一般来说如果你想注册一个 +自定义协议替换 `http` 协议，您必须将其注册为标准方案： + +```javascript +const {app, protocol} = require('electron') + +protocol.registerStandardSchemes(['atom']) +app.on('ready', () => { + protocol.registerHttpProtocol('atom', '...') +}) +``` + +**注意：** 这个方法只有在 `app` 模块的 `ready` 事件触发之后才可使用。 ### `protocol.registerServiceWorkerSchemes(schemes)` -* `schemes` Array - 将一个自定义的方案注册为处理 service workers. +* `schemes` String[] - 将一个自定义的方案注册为处理 service workers。 ### `protocol.registerFileProtocol(scheme, handler[, completion])` * `scheme` String * `handler` Function + * `request` Object + * `url` String + * `referrer` String + * `method` String + * `uploadData` [UploadData[]](structures/upload-data.md) + * `callback` Function + * `filePath` String (可选) * `completion` Function (可选) + * `error` Error -注册一个协议，用来发送响应文件.当通过这个协议来发起一个请求的时候，将使用 `handler(request, callback)` 来调用 -`handler` .当 `scheme` 被成功注册或者完成(错误)时失败，将使用 `completion(null)` 调用 `completion`. - -* `request` Object - * `url` String - * `referrer` String - * `method` String - * `uploadData` Array (可选) -* `callback` Function - -`uploadData` 是一个 `data` 对象数组: - -* `data` Object - * `bytes` Buffer - 被发送的内容. - * `file` String - 上传的文件路径. +注册一个协议，用来发送响应文件。当通过这个协议来发起一个请求的时候，将使用 `handler(request，callback)` 来调用 +`handler`。当 `scheme` 被成功注册或者完成(错误)时失败，将使用 `completion(null)` 调用 `completion`。 为了处理请求，调用 `callback` 时需要使用文件路径或者一个带 `path` 参数的对象, 例如 `callback(filePath)` 或 -`callback({path: filePath})`. +`callback({path: filePath})`。 -当不使用任何参数调用 `callback` 时，你可以指定一个数字或一个带有 `error` 参数的对象，来标识 `request` 失败.你可以使用的 error number 可以参考 -[net error list][net-error]. +当不使用任何参数调用 `callback` 时，你可以指定一个数字或一个带有 `error` 参数的对象，来标识 `request` 失败。你可以使用的 error number 可以参考 +[net error list][net-error]。 -默认 `scheme` 会被注册为一个 `http:` 协议，它与遵循 "generic URI syntax" 规则的协议解析不同，例如 `file:` ，所以你或许应该调用 `protocol.registerStandardSchemes` 来创建一个标准的 scheme. +默认 `scheme` 会被注册为一个 `http:` 协议，它与遵循 "generic URI syntax" 规则的协议解析不同，例如 `file:`，所以你或许应该调用 `protocol.registerStandardSchemes` 来创建一个标准的 scheme。 ### `protocol.registerBufferProtocol(scheme, handler[, completion])` * `scheme` String * `handler` Function + * `request` Object + * `url` String + * `referrer` String + * `method` String + * `uploadData` [UploadData[]](structures/upload-data.md) + * `callback` Function + * `buffer` (Buffer | [MimeTypedBuffer](structures/mime-typed-buffer.md)) (optional) * `completion` Function (可选) + * `error` Error -注册一个 `scheme` 协议，用来发送响应 `Buffer` . +注册一个 `scheme` 协议，用来发送响应 `Buffer`。 -这个方法的用法类似 `registerFileProtocol`，除非使用一个 `Buffer` 对象，或一个有 `data`, -`mimeType`, 和 `charset` 属性的对象来调用 `callback` . +这个方法的用法类似 `registerFileProtocol`，除非使用一个 `Buffer` 对象，或一个有 `data`、 +`mimeType` 和 `charset` 属性的对象来调用 `callback`。 例子: ```javascript -protocol.registerBufferProtocol('atom', function (request, callback) { +const {protocol} = require('electron') + +protocol.registerBufferProtocol('atom', (request, callback) => { callback({mimeType: 'text/html', data: new Buffer('
Response
')}) -}, function (error) { +}, (error) => { if (error) console.error('Failed to register protocol') }) ``` @@ -90,90 +134,143 @@ protocol.registerBufferProtocol('atom', function (request, callback) { * `scheme` String * `handler` Function + * `request` Object + * `url` String + * `referrer` String + * `method` String + * `uploadData` [UploadData[]](structures/upload-data.md) + * `callback` Function + * `data` String (可选) * `completion` Function (可选) + * `error` Error -注册一个 `scheme` 协议，用来发送响应 `String` . +注册一个 `scheme` 协议，用来发送响应 `String`。 -这个方法的用法类似 `registerFileProtocol`，除非使用一个 `String` 对象，或一个有 `data`, -`mimeType`, 和 `charset` 属性的对象来调用 `callback` . +这个方法的用法类似 `registerFileProtocol`，除非使用一个 `String` 对象，或一个有 `data`、 +`mimeType` 和 `charset` 属性的对象来调用 `callback`。 ### `protocol.registerHttpProtocol(scheme, handler[, completion])` * `scheme` String * `handler` Function + * `request` Object + * `url` String + * `referrer` String + * `method` String + * `uploadData` [UploadData[]](structures/upload-data.md) + * `callback` Function + * `redirectRequest` Object + * `url` String + * `method` String + * `session` Object (可选) + * `uploadData` Object (可选) + * `contentType` String - MIME type of the content. + * `data` String - Content to be sent. * `completion` Function (可选) + * `error` Error 注册一个 `scheme` 协议，用来发送 HTTP 请求作为响应. -这个方法的用法类似 `registerFileProtocol`，除非使用一个 `redirectRequest` 对象，或一个有 `url`, `method`, -`referrer`, `uploadData` 和 `session` 属性的对象来调用 `callback` . +这个方法的用法类似 `registerFileProtocol`，除非使用一个 `redirectRequest` 对象，或一个有 `url`、 `method`、 +`referrer`、 `uploadData` 和 `session` 属性的对象来调用 `callback`。 -* `redirectRequest` Object - * `url` String - * `method` String - * `session` Object (可选) - * `uploadData` Object (可选) +默认这个 HTTP 请求会使用当前 session。如果你想使用不同的session值，你应该设置 `session` 为 `null`。 -默认这个 HTTP 请求会使用当前 session .如果你想使用不同的session值，你应该设置 `session` 为 `null`. - -POST 请求应当包含 `uploadData` 对象. - -* `uploadData` object - * `contentType` String - 内容的 MIME type. - * `data` String - 被发送的内容. +POST 请求应当包含 `uploadData` 对象。 ### `protocol.unregisterProtocol(scheme[, completion])` * `scheme` String * `completion` Function (可选) + * `error` Error -注销自定义协议 `scheme`. +注销自定义协议 `scheme`。 ### `protocol.isProtocolHandled(scheme, callback)` * `scheme` String * `callback` Function + * `error` Error -将使用一个布尔值来调用 `callback` ，这个布尔值标识了是否已经存在 `scheme` 的句柄了. +将使用一个布尔值来调用 `callback` ，这个布尔值标识了是否已经存在 `scheme` 的句柄了。 ### `protocol.interceptFileProtocol(scheme, handler[, completion])` * `scheme` String * `handler` Function + * `request` Object + * `url` String + * `referrer` String + * `method` String + * `uploadData` [UploadData[]](structures/upload-data.md) + * `callback` Function + * `filePath` String * `completion` Function (可选) + * `error` Error -拦截 `scheme` 协议并且使用 `handler` 作为协议的新的句柄来发送响应文件. +拦截 `scheme` 协议并且使用 `handler` 作为协议的新的句柄来发送响应文件。 ### `protocol.interceptStringProtocol(scheme, handler[, completion])` * `scheme` String * `handler` Function + * `request` Object + * `url` String + * `referrer` String + * `method` String + * `uploadData` [UploadData[]](structures/upload-data.md) + * `callback` Function + * `data` String (可选) * `completion` Function (可选) + * `error` Error -拦截 `scheme` 协议并且使用 `handler` 作为协议的新的句柄来发送响应 `String`. +拦截 `scheme` 协议并且使用 `handler` 作为协议的新的句柄来发送响应 `String`。 ### `protocol.interceptBufferProtocol(scheme, handler[, completion])` * `scheme` String * `handler` Function + * `request` Object + * `url` String + * `referrer` String + * `method` String + * `uploadData` [UploadData[]](structures/upload-data.md) + * `callback` Function + * `buffer` Buffer (可选) * `completion` Function (可选) + * `error` Error -拦截 `scheme` 协议并且使用 `handler` 作为协议的新的句柄来发送响应 `Buffer`. +拦截 `scheme` 协议并且使用 `handler` 作为协议的新的句柄来发送响应 `Buffer`。 ### `protocol.interceptHttpProtocol(scheme, handler[, completion])` * `scheme` String * `handler` Function -* `completion` Function (optional) + * `request` Object + * `url` String + * `referrer` String + * `method` String + * `uploadData` [UploadData[]](structures/upload-data.md) + * `callback` Function + * `redirectRequest` Object + * `url` String + * `method` String + * `session` Object (可选) + * `uploadData` Object (可选) + * `contentType` String - MIME type of the content. + * `data` String - Content to be sent. +* `completion` Function (可选) + * `error` Error -拦截 `scheme` 协议并且使用 `handler` 作为协议的新的句柄来发送新的响应 HTTP 请求. -Intercepts `scheme` protocol and uses `handler` as the protocol's new handler -which sends a new HTTP request as a response. +拦截 `scheme` 协议并且使用 `handler` 作为协议的新的句柄来发送新的响应 HTTP 请求。 ### `protocol.uninterceptProtocol(scheme[, completion])` * `scheme` String -* `completion` Function -取消对 `scheme` 的拦截，使用它的原始句柄进行处理. +* `completion` Function (可选) + * `error` Error + +取消对 `scheme` 的拦截，使用它的原始句柄进行处理。 [net-error]: https://code.google.com/p/chromium/codesearch#chromium/src/net/base/net_error_list.h +[file-system-api]: https://developer.mozilla.org/en-US/docs/Web/API/LocalFileSystem From c9dd59eb865c40357d2b9d862a53befe8a7693b2 Mon Sep 17 00:00:00 2001 From: Weiqiang Lin <23leo@163.com> Date: Sun, 12 Feb 2017 22:36:08 +0800 Subject: [PATCH 13/16] session to zh-CN --- docs-translations/zh-CN/api/session.md | 57 +++++++++++++++++--------- 1 file changed, 38 insertions(+), 19 deletions(-) diff --git a/docs-translations/zh-CN/api/session.md b/docs-translations/zh-CN/api/session.md index 927b9c16ab68..be02c26bc2cd 100644 --- a/docs-translations/zh-CN/api/session.md +++ b/docs-translations/zh-CN/api/session.md @@ -1,46 +1,64 @@ # session -`session` 模块可以用来创建一个新的 `Session` 对象. +> 管理浏览器会话，Cookie，缓存，代理设置等。 -你也可以通过使用 [`webContents`](web-contents.md) 的属性 `session` 来使用一个已有页面的 `session` ，`webContents` 是[`BrowserWindow`](browser-window.md) 的属性. +进程： [Main](../glossary.md#main-process) + +`session` 模块可以用来创建一个新的 `Session` 对象。 + +你也可以通过使用 [`webContents`](web-contents.md) 的属性 `session` 来使用一个已有页面的 `session` ，`webContents` 是[`BrowserWindow`](browser-window.md) 的属性。 ```javascript -const BrowserWindow = require('electron').BrowserWindow +const {BrowserWindow} = require('electron') -var win = new BrowserWindow({ width: 800, height: 600 }) +let win = new BrowserWindow({width: 800, height: 600}) win.loadURL('http://github.com') -var ses = win.webContents.session +const ses = win.webContents.session +console.log(ses.getUserAgent()) ``` ## 方法 -`session` 模块有如下方法: +`session` 模块有如下方法： -### session.fromPartition(partition) +### `session.fromPartition(partition[, options])` * `partition` String +* `options` Object + * `cache` Boolean - 是否启用缓存。 -从字符串 `partition` 返回一个新的 `Session` 实例. +从字符串 `partition` 返回一个新的 `Session` 实例。 -如果 `partition` 以 `persist:` 开头，那么这个page将使用一个持久的 session，这个 session 将对应用的所有 page 可用.如果没前缀，这个 page 将使用一个历史 session.如果 `partition` 为空，那么将返回应用的默认 session . +返回 `Session` - 一个来自 `partition` 字符串的会话实例。当存在时 +`Session` 与同一个 `partition`，它会被返回；否则一个新 +`Session` 实例将使用 `options` 创建。 + +如果 `partition` 以 `persist:` 开头，那么这个 page 将使用一个持久的 session，这个 session 将对应用的所有 page 可用。如果没前缀，这个 page 将使用一个历史 session。如果 `partition` 为空，那么将返回应用的默认 session。 + +要用 `options` 创建一个 `Session`，你必须确保 `Session` 与 +`partition` 从来没有被使用过。没有办法改变现有 `Session` 对象的 `options'。 ## 属性 -`session` 模块有如下属性: +`session` 模块有如下属性： ### session.defaultSession -返回应用的默认 session 对象. +返回应用的默认 `Session` 对象。 ## Class: Session -可以在 `session` 模块中创建一个 `Session` 对象 : +> 获取和设置会话的属性。 + +进程: [Main](../glossary.md#main-process) + +可以在 `session` 模块中创建一个 `Session` 对象： ```javascript -const session = require('electron').session - -var ses = session.fromPartition('persist:name') +const {session} = require('electron') +const ses = session.fromPartition('persist:name') +console.log(ses.getUserAgent()) ``` ### 实例事件 @@ -55,12 +73,13 @@ var ses = session.fromPartition('persist:name') 当 Electron 将要从 `webContents` 下载 `item` 时触发. -调用 `event.preventDefault()` 可以取消下载，并且在进程的下个 tick中，这个 `item` 也不可用. +调用 `event.preventDefault()` 可以取消下载，并且在进程的下个 tick 中，这个 `item` 也不可用。 ```javascript -session.defaultSession.on('will-download', function (event, item, webContents) { +const {session} = require('electron') +session.defaultSession.on('will-download', (event, item, webContents) => { event.preventDefault() - require('request')(item.getURL(), function (data) { + require('request')(item.getURL(), (data) => { require('fs').writeFileSync('/somewhere', data) }) }) @@ -68,7 +87,7 @@ session.defaultSession.on('will-download', function (event, item, webContents) { ### 实例方法 -实例 `Session` 有以下方法: +实例 `Session` 有以下方法： #### `ses.cookies` From dddb6458dae65f1ffd8dc77026abef7a85b0fb52 Mon Sep 17 00:00:00 2001 From: Weiqiang Lin <23leo@163.com> Date: Sun, 12 Feb 2017 22:38:24 +0800 Subject: [PATCH 14/16] systemPreferences to zh-CN --- docs-translations/zh-CN/api/system-preferences.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs-translations/zh-CN/api/system-preferences.md b/docs-translations/zh-CN/api/system-preferences.md index 7182e33e7614..7ac9b5a7c058 100644 --- a/docs-translations/zh-CN/api/system-preferences.md +++ b/docs-translations/zh-CN/api/system-preferences.md @@ -1,6 +1,6 @@ # systemPreferences -> 获取系统偏好设置. +> 获取系统偏好设置。 可使用的进程: [主进程](../tutorial/quick-start.md#main-process) @@ -15,20 +15,20 @@ console.log(systemPreferences.isDarkMode()) ### Event: 'accent-color-changed' _Windows_ -返回: +返回： * `event` Event * `newColor` String - 用户给系统颜色设置的新的 RGBA 色值。 ### Event: 'color-changed' _Windows_ -返回: +返回： * `event` Event ### Event: 'inverted-color-scheme-changed' _Windows_ -返回: +返回： * `event` Event * `invertedColorScheme` Boolean - 如果一个反色的配色方案正在被使用，比如一个高对比度的主题，则返回 `true` ，否则返回 `false` 。 @@ -37,7 +37,7 @@ console.log(systemPreferences.isDarkMode()) ### `systemPreferences.isDarkMode()` _macOS_ -返回 `Boolean` - 系统是否处于深色模式. +返回 `Boolean` - 系统是否处于深色模式。 ### `systemPreferences.isSwipeTrackingFromScrollEventsEnabled()` _macOS_ From b7551b5d8496f67838d7c3ded687178d25a9022e Mon Sep 17 00:00:00 2001 From: Weiqiang Lin <23leo@163.com> Date: Sun, 12 Feb 2017 22:51:36 +0800 Subject: [PATCH 15/16] Class: Tray to zh-CN --- docs-translations/zh-CN/api/tray.md | 236 +++++++++++++++------------- 1 file changed, 131 insertions(+), 105 deletions(-) diff --git a/docs-translations/zh-CN/api/tray.md b/docs-translations/zh-CN/api/tray.md index 80b8dc12f749..8ecbcac7b54e 100644 --- a/docs-translations/zh-CN/api/tray.md +++ b/docs-translations/zh-CN/api/tray.md @@ -1,205 +1,231 @@ -# Tray +# Class：Tray -> 通过 `Tray` 向系统的通知区添加一个带有右键菜单的图标. +> 将图标和上下文菜单添加到系统的通知区域。 + +可使用的进程: [主进程](../tutorial/quick-start.md#main-process) + +`Tray` 是一个 [事件发出者][event-emitter]。 ```javascript -const electron = require('electron') -const app = electron.app -const Menu = electron.Menu -const Tray = electron.Tray +const {app, Menu, Tray} = require('electron') -var appIcon = null -app.on('ready', function () { - appIcon = new Tray('/path/to/my/icon') - var contextMenu = Menu.buildFromTemplate([ - { label: 'Item1', type: 'radio' }, - { label: 'Item2', type: 'radio' }, - { label: 'Item3', type: 'radio', checked: true }, - { label: 'Item4', type: 'radio' } +let tray = null +app.on('ready', () => { + tray = new Tray('/path/to/my/icon') + const contextMenu = Menu.buildFromTemplate([ + {label: 'Item1', type: 'radio'}, + {label: 'Item2', type: 'radio'}, + {label: 'Item3', type: 'radio', checked: true}, + {label: 'Item4', type: 'radio'} ]) - appIcon.setToolTip('This is my application.') - appIcon.setContextMenu(contextMenu) + tray.setToolTip('This is my application.') + tray.setContextMenu(contextMenu) }) - ``` __平台限制:__ -* 在 Linux， 如果支持应用指示器则使用它，否则使用 `GtkStatusIcon` 代替. -* 在 Linux ，配置了只有有了应用指示器的支持, 你必须安装 `libappindicator1` 来让 tray icon 执行. -* 应用指示器只有在它拥有 context menu 时才会显示. -* 当在linux 上使用了应用指示器，将忽略点击事件. -* 在 Linux，为了让单独的 `MenuItem` 起效，需要再次调用 `setContextMenu` .例如: +* 在 Linux， 如果支持应用指示器则使用它，否则使用 `GtkStatusIcon` 代替。 +* 在 Linux ，配置了只有有了应用指示器的支持, 你必须安装 `libappindicator1` 来让 tray icon 执行。 +* 应用指示器只有在它拥有 context menu 时才会显示。 +* 当在linux 上使用了应用指示器，将忽略点击事件。 +* 在 Linux，为了让单独的 `MenuItem` 起效，需要再次调用 `setContextMenu` 。例如： ```javascript -contextMenu.items[2].checked = false -appIcon.setContextMenu(contextMenu) +const {app, Menu, Tray} = require('electron') + +let appIcon = null +app.on('ready', () => { + appIcon = new Tray('/path/to/my/icon') + const contextMenu = Menu.buildFromTemplate([ + {label: 'Item1', type: 'radio'}, + {label: 'Item2', type: 'radio'} + ]) + + // Make a change to the context menu + contextMenu.items[1].checked = false + + // Call this again for Linux because we modified the context menu + appIcon.setContextMenu(contextMenu) +}) ``` -如果想在所有平台保持完全相同的行为，不应该依赖点击事件，而是一直将一个 context menu 添加到 tray icon. -## Class: Tray - -`Tray` 是一个 [事件发出者][event-emitter]. +如果想在所有平台保持完全相同的行为，不应该依赖点击事件，而是一直将一个 context menu 添加到 tray icon。 ### `new Tray(image)` -* `image` [NativeImage](native-image.md) +* `image` ([NativeImage](native-image.md) | String) -创建一个与 `image` 相关的 icon. +创建一个与 `image` 相关的 icon。 -## 事件 +### Instance Events -`Tray` 模块可发出下列事件: +`Tray` 模块可发出下列事件： -**注意:** 一些事件只能在特定的os中运行，已经标明. - -### Event: 'click' +#### Event: 'click' * `event` Event * `altKey` Boolean * `shiftKey` Boolean * `ctrlKey` Boolean * `metaKey` Boolean -* `bounds` Object - tray icon 的 bounds. - * `x` Integer - * `y` Integer - * `width` Integer - * `height` Integer +* `bounds` [Rectangle](structures/rectangle.md) - tray icon 的 bounds -当tray icon被点击的时候发出事件. +当 tray icon 被点击的时候发出事件。 -__注意:__ `bounds` 只在 macOS 和 Windows 上起效. - -### Event: 'right-click' _macOS_ _Windows_ +#### Event: 'right-click' _macOS_ _Windows_ * `event` Event * `altKey` Boolean * `shiftKey` Boolean * `ctrlKey` Boolean * `metaKey` Boolean -* `bounds` Object - tray icon 的 bounds. - * `x` Integer - * `y` Integer - * `width` Integer - * `height` Integer +* `bounds` [Rectangle](structures/rectangle.md) - tray icon 的 bounds -当tray icon被鼠标右键点击的时候发出事件. +当 tray icon 被鼠标右键点击的时候发出事件。 -### Event: 'double-click' _macOS_ _Windows_ +#### Event: 'double-click' _macOS_ _Windows_ * `event` Event * `altKey` Boolean * `shiftKey` Boolean * `ctrlKey` Boolean * `metaKey` Boolean -* `bounds` Object - tray icon 的 bounds. - * `x` Integer - * `y` Integer - * `width` Integer - * `height` Integer +* `bounds` [Rectangle](structures/rectangle.md) - tray icon 的 bounds -当tray icon被双击的时候发出事件. +当 tray icon 被双击的时候发出事件。 -### Event: 'balloon-show' _Windows_ +#### Event: 'balloon-show' _Windows_ -当tray 气泡显示的时候发出事件. +当 tray 气泡显示的时候发出事件。 -### Event: 'balloon-click' _Windows_ +#### Event: 'balloon-click' _Windows_ -当tray 气泡被点击的时候发出事件. +当 tray 气泡被点击的时候发出事件。 -### Event: 'balloon-closed' _Windows_ +#### Event: 'balloon-closed' _Windows_ -当tray 气泡关闭的时候发出事件，因为超时或人为关闭. +当 tray 气泡关闭的时候发出事件，因为超时或人为关闭。 -### Event: 'drop' _macOS_ +#### Event: 'drop' _macOS_ -当tray icon上的任何可拖动项被删除的时候发出事件. +当 tray icon 上的任何可拖动项被删除的时候发出事件。 -### Event: 'drop-files' _macOS_ +#### Event: 'drop-files' _macOS_ * `event` * `files` Array - 已删除文件的路径. -当tray icon上的可拖动文件被删除的时候发出事件. +当 tray icon 上的可拖动文件被删除的时候发出事件。 -### Event: 'drag-enter' _macOS_ +#### Event: 'drag-enter' _macOS_ -当一个拖动操作进入tray icon的时候发出事件. +当一个拖动操作进入 tray icon 的时候发出事件。 -### Event: 'drag-leave' _macOS_ +#### Event: 'drag-leave' _macOS_ -当一个拖动操作离开tray icon的时候发出事件. -Emitted when a drag operation exits the tray icon. +当一个拖动操作离开 tray icon 的时候发出事件。 -### Event: 'drag-end' _macOS_ +#### Event: 'drag-end' _macOS_ -当一个拖动操作在tray icon上或其它地方停止拖动的时候发出事件. +当一个拖动操作在 tray icon 上或其它地方停止拖动的时候发出事件。 -## 方法 +### 方法 -`Tray` 模块有以下方法: +`Tray` 模块有以下方法： -**Note:** 一些方法只能在特定的os中运行，已经标明. +#### `tray.destroy()` -### `Tray.destroy()` +立刻删除 tray icon。 -立刻删除 tray icon. +#### `tray.setImage(image)` -### `Tray.setImage(image)` +* `image` ([NativeImage](native-image.md) | String) + +让 `image` 与 tray icon 关联起来。 + +#### `tray.setPressedImage(image)` _macOS_ * `image` [NativeImage](native-image.md) -让 `image` 与 tray icon 关联起来. +当在 macOS 上按压 tray icon 的时候，让 `image` 与 tray icon 关联起来。 -### `Tray.setPressedImage(image)` _macOS_ - -* `image` [NativeImage](native-image.md) - -当在 macOS 上按压 tray icon 的时候， 让 `image` 与 tray icon 关联起来. - -### `Tray.setToolTip(toolTip)` +#### `tray.setToolTip(toolTip)` * `toolTip` String -为 tray icon 设置 hover text. +为 tray icon 设置 hover text。 -### `Tray.setTitle(title)` _macOS_ +#### `tray.setTitle(title)` _macOS_ * `title` String -在状态栏沿着 tray icon 设置标题. +在状态栏沿着 tray icon 设置标题。 -### `Tray.setHighlightMode(highlight)` _macOS_ +#### `tray.setHighlightMode(mode)` _macOS_ -* `highlight` Boolean +* `mode` String - Highlight mode with one of the following values: + * `selection` - Highlight the tray icon when it is clicked and also when + its context menu is open. This is the default. + * `always` - Always highlight the tray icon. + * `never` - Never highlight the tray icon. -当 tray icon 被点击的时候，是否设置它的背景色变为高亮(blue).默认为 true. +设置 tray icon 的背景色变为高亮（blue）。 -### `Tray.displayBalloon(options)` _Windows_ +**注意：** 你可以使用 `highlightMode` 和一个 [`BrowserWindow`](browser-window.md) +通过在窗口可见性时切换 `'never'` 和 `'always'` 模式变化。 + +```javascript +const {BrowserWindow, Tray} = require('electron') + +const win = new BrowserWindow({width: 800, height: 600}) +const tray = new Tray('/path/to/my/icon') + +tray.on('click', () => { + win.isVisible() ? win.hide() : win.show() +}) +win.on('show', () => { + tray.setHighlightMode('always') +}) +win.on('hide', () => { + tray.setHighlightMode('never') +}) +``` + +#### `tray.displayBalloon(options)` _Windows_ * `options` Object - * `icon` [NativeImage](native-image.md) - * `title` String - * `content` String + * `icon` ([NativeImage](native-image.md) | String) - (可选) + * `title` String - (可选) + * `content` String - (可选) -展示一个 tray balloon. +展示一个 tray balloon。 -### `Tray.popUpContextMenu([menu, position])` _macOS_ _Windows_ +#### `tray.popUpContextMenu([menu, position])` _macOS_ _Windows_ * `menu` Menu (optional) * `position` Object (可选) - 上托位置. * `x` Integer * `y` Integer -从 tray icon 上托出 context menu . 当划过 `menu` 的时候， `menu` 显示，代替 tray 的 context menu . +从 tray icon 上托出 context menu。当划过 `menu` 的时候， `menu` 显示，代替 tray 的 context menu。 -`position` 只在 windows 上可用，默认为 (0, 0) . +`position` 只在 windows 上可用，默认为 (0, 0)。 -### `Tray.setContextMenu(menu)` +#### `tray.setContextMenu(menu)` * `menu` Menu -为这个 icon 设置 context menu . +为这个 icon 设置 context menu。 -[event-emitter]: http://nodejs.org/api/events.html#events_class_events_eventemitter +#### `tray.getBounds()` _macOS_ _Windows_ + +返回 [`Rectangle`](structures/rectangle.md) + +这个 tray icon 的 `bounds` 对象。 + +#### `tray.isDestroyed()` + +返回 `Boolean` - tray icon 是否销毁。 + +[event-emitter]: https://nodejs.org/api/events.html#events_class_eventemitter From e262f6c63ebbf0baf86670de9bb69274dd648cc1 Mon Sep 17 00:00:00 2001 From: Weiqiang Lin <23leo@163.com> Date: Sun, 12 Feb 2017 23:12:33 +0800 Subject: [PATCH 16/16] webContents to zh-CN --- docs-translations/zh-CN/api/web-contents.md | 409 +++++++++++--------- 1 file changed, 230 insertions(+), 179 deletions(-) diff --git a/docs-translations/zh-CN/api/web-contents.md b/docs-translations/zh-CN/api/web-contents.md index 838fefc5cb0a..b13628533ee1 100644 --- a/docs-translations/zh-CN/api/web-contents.md +++ b/docs-translations/zh-CN/api/web-contents.md @@ -1,30 +1,64 @@ # webContents +> 渲染和控制网页。 + +可使用的进程: [主进程](../tutorial/quick-start.md#main-process) + `webContents` 是一个 [事件发出者](http://nodejs.org/api/events.html#events_class_events_eventemitter). - 它负责渲染并控制网页，也是 [`BrowserWindow`](browser-window.md) 对象的属性.一个使用 `webContents` 的例子: ```javascript -const BrowserWindow = require('electron').BrowserWindow +const {BrowserWindow} = require('electron') -var win = new BrowserWindow({width: 800, height: 1500}) +let win = new BrowserWindow({width: 800, height: 1500}) win.loadURL('http://github.com') -var webContents = win.webContents +let contents = win.webContents +console.log(contents) ``` +## 方法 + +这些方法可以从 `webContents` 模块访问： + +```javascript +const {webContents} = require('electron') +console.log(webContents) +``` + +### `webContents.getAllWebContents()` + +返回 `WebContents[]` - 所有 `WebContents` 实例的数组。这将包含Web内容 +适用于所有 windows，webviews，打开的 devtools 和 devtools 扩展背景页面。 + +### `webContents.getFocusedWebContents()` + +返回 `WebContents` - 在此应用程序中焦点的 Web 内容，否则返回`null`。 + +### `webContents.fromId(id)` + +* `id` Integer + +返回 `WebContents` - 一个给定 ID 的 WebContents 实例。 + +## Class: WebContents + +> 渲染和控制浏览器窗口实例的内容。 + +可使用的进程: [主进程](../tutorial/quick-start.md#main-process) + ## 事件 -`webContents` 对象可发出下列事件: +`webContents` 对象可发出下列事件： ### Event: 'did-finish-load' -当导航完成时发出事件，`onload` 事件也完成. +当导航完成时发出事件，`onload` 事件也完成。 ### Event: 'did-fail-load' -返回: +返回： * `event` Event * `errorCode` Integer @@ -32,28 +66,28 @@ var webContents = win.webContents * `validatedURL` String * `isMainFrame` Boolean -这个事件类似 `did-finish-load` ，但是是在加载失败或取消加载时发出, 例如， `window.stop()` 请求结束.错误代码的完整列表和它们的含义都可以在 [这里](https://code.google.com/p/chromium/codesearch#chromium/src/net/base/net_error_list.h) 找到. +这个事件类似 `did-finish-load` ，但是是在加载失败或取消加载时发出, 例如， `window.stop()` 请求结束。错误代码的完整列表和它们的含义都可以在 [这里](https://code.google.com/p/chromium/codesearch#chromium/src/net/base/net_error_list.h) 找到。 ### Event: 'did-frame-finish-load' -返回: +返回： * `event` Event * `isMainFrame` Boolean -当一个 frame 导航完成的时候发出事件. +当一个 frame 导航完成的时候发出事件。 ### Event: 'did-start-loading' -当 tab 的spinner 开始 spinning的时候. +当 tab 的spinner 开始 spinning的时候。 ### Event: 'did-stop-loading' -当 tab 的spinner 结束 spinning的时候. +当 tab 的spinner 结束 spinning的时候。 ### Event: 'did-get-response-details' -返回: +返回： * `event` Event * `status` Boolean @@ -65,12 +99,12 @@ var webContents = win.webContents * `headers` Object * `resourceType` String -当有关请求资源的详细信息可用的时候发出事件. -`status` 标识了 socket链接来下载资源. +当有关请求资源的详细信息可用的时候发出事件。 +`status` 标识了 socket 链接来下载资源。 ### Event: 'did-get-redirect-request' -返回: +返回： * `event` Event * `oldURL` String @@ -81,112 +115,129 @@ var webContents = win.webContents * `referrer` String * `headers` Object -当在请求资源时收到重定向的时候发出事件. +当在请求资源时收到重定向的时候发出事件。 ### Event: 'dom-ready' -返回: +返回： * `event` Event -当指定 frame 中的 文档加载完成的时候发出事件. +当指定 frame 中的 文档加载完成的时候发出事件。 ### Event: 'page-favicon-updated' -返回: +返回： * `event` Event * `favicons` Array - Array of URLs -当 page 收到图标 url 的时候发出事件. +当 page 收到图标 url 的时候发出事件。 ### Event: 'new-window' -返回: +返回： * `event` Event * `url` String * `frameName` String -* `disposition` String - 可为 `default`, `foreground-tab`, `background-tab`, - `new-window` 和 `other`. -* `options` Object - 创建新的 `BrowserWindow`时使用的参数. +* `disposition` String - 可为 `default`、 `foreground-tab`、 `background-tab`、 + `new-window` 和 `other`。 +* `options` Object - 创建新的 `BrowserWindow`时使用的参数。 +* `additionalFeatures` String[] - 非标准功能（功能未处理 +   由 Chromium 或 Electron ）赋予 `window.open()`。 -当 page 请求打开指定 url 窗口的时候发出事件.这可以是通过 `window.open` 或一个外部连接如 `` 发出的请求. +当 page 请求打开指定 url 窗口的时候发出事件.这可以是通过 `window.open` 或一个外部连接如 `` 发出的请求。 -默认指定 `url` 的 `BrowserWindow` 会被创建. +默认指定 `url` 的 `BrowserWindow` 会被创建。 -调用 `event.preventDefault()` 可以用来阻止打开窗口. +调用 `event.preventDefault()` 可以用来阻止打开窗口。 + +调用 `event.preventDefault()` 将阻止 Electron 自动创建 +新 `BrowserWindow`。 如果调用 `event.preventDefault()` 并手动创建一个新的 +`BrowserWindow`，那么你必须设置 `event.newGuest` 来引用新的 `BrowserWindow` +实例，如果不这样做可能会导致意外的行为。例如： + +```javascript +myBrowserWindow.webContents.on('new-window', (event, url) => { + event.preventDefault() + const win = new BrowserWindow({show: false}) + win.once('ready-to-show', () => win.show()) + win.loadURL(url) + event.newGuest = win +}) +``` ### Event: 'will-navigate' -返回: +返回： * `event` Event * `url` String -当用户或 page 想要开始导航的时候发出事件.它可在当 `window.location` 对象改变或用户点击 page 中的链接的时候发生. +当用户或 page 想要开始导航的时候发出事件。它可在当 `window.location` 对象改变或用户点击 page 中的链接的时候发生。 -当使用 api(如 `webContents.loadURL` 和 `webContents.back`) 以编程方式来启动导航的时候，这个事件将不会发出. +当使用 api（如 `webContents.loadURL` 和 `webContents.back`） 以编程方式来启动导航的时候，这个事件将不会发出。 -它也不会在页内跳转发生， 例如点击锚链接或更新 `window.location.hash`.使用 `did-navigate-in-page` 事件可以达到目的. +它也不会在页内跳转发生，例如点击锚链接或更新 `window.location.hash`。使用 `did-navigate-in-page` 事件可以达到目的。 -调用 `event.preventDefault()` 可以阻止导航. +调用 `event.preventDefault()` 可以阻止导航。 ### Event: 'did-navigate' -返回: +返回： * `event` Event * `url` String -当一个导航结束时候发出事件. +当一个导航结束时候发出事件。 -页内跳转时不会发出这个事件，例如点击锚链接或更新 `window.location.hash`.使用 `did-navigate-in-page` 事件可以达到目的. +页内跳转时不会发出这个事件，例如点击锚链接或更新 `window.location.hash`。使用 `did-navigate-in-page` 事件可以达到目的。 ### Event: 'did-navigate-in-page' -返回: +返回： * `event` Event * `url` String -当页内导航发生的时候发出事件. +当页内导航发生的时候发出事件。 -当页内导航发生的时候，page 的url 改变，但是不会跳出界面.例如当点击锚链接时或者 DOM 的 `hashchange` 事件发生. +当页内导航发生的时候，page 的url 改变，但是不会跳出界面。例如当点击锚链接时或者 DOM 的 `hashchange` 事件发生。 ### Event: 'crashed' -当渲染进程崩溃的时候发出事件. +当渲染进程崩溃的时候发出事件。 ### Event: 'plugin-crashed' -返回: +返回： * `event` Event * `name` String * `version` String -当插件进程崩溃时候发出事件. +当插件进程崩溃时候发出事件。 ### Event: 'destroyed' -当 `webContents` 被删除的时候发出事件. +当 `webContents` 被删除的时候发出事件。 ### Event: 'devtools-opened' -当开发者工具栏打开的时候发出事件. +当开发者工具栏打开的时候发出事件。 ### Event: 'devtools-closed' -当开发者工具栏关闭时候发出事件. +当开发者工具栏关闭时候发出事件。 ### Event: 'devtools-focused' -当开发者工具栏获得焦点或打开的时候发出事件. +当开发者工具栏获得焦点或打开的时候发出事件。 ### Event: 'certificate-error' -返回: +返回： * `event` Event * `url` URL @@ -196,13 +247,13 @@ var webContents = win.webContents * `issuerName` String * `callback` Function -当验证证书或 `url` 失败的时候发出事件. +当验证证书或 `url` 失败的时候发出事件。 -使用方法类似 [`app` 的 `certificate-error` 事件](app.md#event-certificate-error). +使用方法类似 [`app` 的 `certificate-error` 事件](app.md#event-certificate-error)。 ### Event: 'select-client-certificate' -返回: +返回： * `event` Event * `url` URL @@ -211,13 +262,13 @@ var webContents = win.webContents * `issuerName` String - Issuer's Common Name * `callback` Function -当请求客户端证书的时候发出事件. +当请求客户端证书的时候发出事件。 -使用方法类似 [`app` 的 `select-client-certificate` 事件](app.md#event-select-client-certificate). +使用方法类似 [`app` 的 `select-client-certificate` 事件](app.md#event-select-client-certificate)。 ### Event: 'login' -返回: +返回： * `event` Event * `request` Object @@ -234,33 +285,33 @@ var webContents = win.webContents 当 `webContents` 想做基本验证的时候发出事件. -使用方法类似 [the `login` event of `app`](app.md#event-login). +使用方法类似 [the `login` event of `app`](app.md#event-login)。 ### Event: 'found-in-page' -返回: +返回： * `event` Event * `result` Object * `requestId` Integer - * `finalUpdate` Boolean - 标识是否还有更多的值可以查看. - * `activeMatchOrdinal` Integer (可选) - 活动匹配位置 - * `matches` Integer (可选) - 匹配数量. - * `selectionArea` Object (可选) - 协调首个匹配位置. + * `finalUpdate` Boolean - 标识是否还有更多的值可以查看。 + * `activeMatchOrdinal` Integer (可选) - 活动匹配位置。 + * `matches` Integer (可选) - 匹配数量。 + * `selectionArea` Object (可选) - 协调首个匹配位置。 -当使用 [`webContents.findInPage`] 进行页内查找并且找到可用值得时候发出事件. +当使用 [`webContents.findInPage`] 进行页内查找并且找到可用值得时候发出事件。 ### Event: 'media-started-playing' -当媒体开始播放的时候发出事件. +当媒体开始播放的时候发出事件。 ### Event: 'media-paused' -当媒体停止播放的时候发出事件. +当媒体停止播放的时候发出事件。 ### Event: 'did-change-theme-color' -当page 的主题色时候发出事件.这通常由于引入了一个 meta 标签 : +当page 的主题色时候发出事件。这通常由于引入了一个 meta 标签： ```html @@ -268,7 +319,7 @@ var webContents = win.webContents ### Event: 'cursor-changed' -返回: +返回： * `event` Event * `type` String @@ -282,9 +333,9 @@ var webContents = win.webContents `row-resize`, `m-panning`, `e-panning`, `n-panning`, `ne-panning`, `nw-panning`, `s-panning`, `se-panning`, `sw-panning`, `w-panning`, `move`, `vertical-text`, `cell`, `context-menu`, `alias`, `progress`, `nodrop`, `copy`, `none`, -`not-allowed`, `zoom-in`, `zoom-out`, `grab`, `grabbing`, `custom`. +`not-allowed`, `zoom-in`, `zoom-out`, `grab`, `grabbing`, `custom`。 -如果 `type` 参数值为 `custom`, `image` 参数会在一个`NativeImage` 中控制自定义鼠标图片, 并且 `scale` 会控制图片的缩放比例. +如果 `type` 参数值为 `custom`、 `image` 参数会在一个`NativeImage` 中控制自定义鼠标图片，并且 `scale` 会控制图片的缩放比例。 ## 实例方法 @@ -298,8 +349,8 @@ var webContents = win.webContents * `userAgent` String - 产生请求的用户代理 * `extraHeaders` String - 以 "\n" 分隔的额外头 -在窗口中加载 `url` , `url` 必须包含协议前缀, -比如 `http://` 或 `file://`. 如果加载想要忽略 http 缓存，可以使用 `pragma` 头来达到目的. +在窗口中加载 `url` 、 `url` 必须包含协议前缀， +比如 `http://` 或 `file://`。如果加载想要忽略 http 缓存，可以使用 `pragma` 头来达到目的。 ```javascript const options = {'extraHeaders': 'pragma: no-cache\n'} @@ -310,11 +361,11 @@ webContents.loadURL(url, options) * `url` URL -初始化一个指定 `url` 的资源下载，不导航跳转. `session` 的 `will-download` 事件会触发. +初始化一个指定 `url` 的资源下载，不导航跳转。 `session` 的 `will-download` 事件会触发。 ### `webContents.getURL()` -返回当前page 的 url. +返回当前 page 的 url。 ```javascript var win = new BrowserWindow({width: 800, height: 600}) @@ -325,85 +376,85 @@ var currentURL = win.webContents.getURL() ### `webContents.getTitle()` -返回当前page 的 标题. +返回当前 page 的标题。 ### `webContents.isLoading()` -返回一个布尔值，标识当前页是否正在加载. +返回一个布尔值，标识当前页是否正在加载。 ### `webContents.isWaitingForResponse()` -返回一个布尔值，标识当前页是否正在等待主要资源的第一次响应. +返回一个布尔值，标识当前页是否正在等待主要资源的第一次响应。 ### `webContents.stop()` -停止还为开始的导航. +停止还为开始的导航。 ### `webContents.reload()` -重载当前页. +重载当前页。 ### `webContents.reloadIgnoringCache()` -重载当前页，忽略缓存. +重载当前页，忽略缓存。 ### `webContents.canGoBack()` -返回一个布尔值，标识浏览器是否能回到前一个page. +返回一个布尔值，标识浏览器是否能回到前一个page。 ### `webContents.canGoForward()` -返回一个布尔值，标识浏览器是否能前往下一个page. +返回一个布尔值，标识浏览器是否能前往下一个page。 ### `webContents.canGoToOffset(offset)` * `offset` Integer -返回一个布尔值，标识浏览器是否能前往指定 `offset` 的page. +返回一个布尔值，标识浏览器是否能前往指定 `offset` 的page。 ### `webContents.clearHistory()` -清除导航历史. +清除导航历史。 ### `webContents.goBack()` -让浏览器回退到前一个page. +让浏览器回退到前一个page。 ### `webContents.goForward()` -让浏览器回前往下一个page. +让浏览器回前往下一个page。 ### `webContents.goToIndex(index)` * `index` Integer -让浏览器回前往指定 `index` 的page. +让浏览器回前往指定 `index` 的page。 ### `webContents.goToOffset(offset)` * `offset` Integer -导航到相对于当前页的偏移位置页. +导航到相对于当前页的偏移位置页。 ### `webContents.isCrashed()` -渲染进程是否崩溃. +渲染进程是否崩溃。 ### `webContents.setUserAgent(userAgent)` * `userAgent` String -重写本页用户代理. +重写本页用户代理。 ### `webContents.getUserAgent()` -返回一个 `String` ，标识本页用户代理信息. +返回一个 `String` ，标识本页用户代理信息。 ### `webContents.insertCSS(css)` * `css` String -为当前页插入css. +为当前页插入css。 ### `webContents.executeJavaScript(code[, userGesture, callback])` @@ -412,99 +463,99 @@ var currentURL = win.webContents.getURL() * `callback` Function (可选) - 脚本执行完成后调用的回调函数. * `result` -评估 page `代码`. +评估 page `代码`。 -浏览器窗口中的一些 HTML API ，例如 `requestFullScreen`，只能被用户手势请求.设置 `userGesture` 为 `true` 可以取消这个限制. +浏览器窗口中的一些 HTML API ，例如 `requestFullScreen`，只能被用户手势请求。设置 `userGesture` 为 `true` 可以取消这个限制。 ### `webContents.setAudioMuted(muted)` * `muted` Boolean -减缓当前页的 audio 的播放速度. +减缓当前页的 audio 的播放速度。 ### `webContents.isAudioMuted()` -返回一个布尔值，标识当前页是否减缓了 audio 的播放速度. +返回一个布尔值，标识当前页是否减缓了 audio 的播放速度。 ### `webContents.undo()` -执行网页的编辑命令 `undo` . +执行网页的编辑命令 `undo`。 ### `webContents.redo()` -执行网页的编辑命令 `redo` . +执行网页的编辑命令 `redo`。 ### `webContents.cut()` -执行网页的编辑命令 `cut` . +执行网页的编辑命令 `cut`。 ### `webContents.copy()` -执行网页的编辑命令 `copy` . +执行网页的编辑命令 `copy`。 ### `webContents.paste()` -执行网页的编辑命令 `paste` . +执行网页的编辑命令 `paste`。 ### `webContents.pasteAndMatchStyle()` -执行网页的编辑命令 `pasteAndMatchStyle` . +执行网页的编辑命令 `pasteAndMatchStyle`。 ### `webContents.delete()` -执行网页的编辑命令 `delete` . +执行网页的编辑命令 `delete`。 ### `webContents.selectAll()` -执行网页的编辑命令 `selectAll` . +执行网页的编辑命令 `selectAll`。 ### `webContents.unselect()` -执行网页的编辑命令 `unselect` . +执行网页的编辑命令 `unselect`。 ### `webContents.replace(text)` * `text` String -执行网页的编辑命令 `replace` . +执行网页的编辑命令 `replace`。 ### `webContents.replaceMisspelling(text)` * `text` String -执行网页的编辑命令 `replaceMisspelling` . +执行网页的编辑命令 `replaceMisspelling`。 ### `webContents.insertText(text)` * `text` String -插入 `text` 到获得了焦点的元素. +插入 `text` 到获得了焦点的元素。 ### `webContents.findInPage(text[, options])` -* `text` String - 查找内容, 不能为空. +* `text` String - 查找内容，不能为空。 * `options` Object (可选) - * `forward` Boolean - 是否向前或向后查找, 默认为 `true`. - * `findNext` Boolean - 当前操作是否是第一次查找或下一次查找, - 默认为 `false`. - * `matchCase` Boolean - 查找是否区分大小写, - 默认为 `false`. - * `wordStart` Boolean -是否仅以首字母查找. - 默认为 `false`. - * `medialCapitalAsWordStart` Boolean - 是否结合 `wordStart`,如果匹配是大写字母开头，后面接小写字母或无字母，那么就接受这个词中匹配.接受几个其它的合成词匹配, 默认为 `false`. + * `forward` Boolean - 是否向前或向后查找，默认为 `true`。 + * `findNext` Boolean - 当前操作是否是第一次查找或下一次查找， + 默认为 `false`。 + * `matchCase` Boolean - 查找是否区分大小写， + 默认为 `false`。 + * `wordStart` Boolean -是否仅以首字母查找， + 默认为 `false`。 + * `medialCapitalAsWordStart` Boolean - 是否结合 `wordStart`，如果匹配是大写字母开头，后面接小写字母或无字母，那么就接受这个词中匹配。接受几个其它的合成词匹配，默认为 `false`。 -发起请求，在网页中查找所有与 `text` 相匹配的项，并且返回一个 `Integer` 来表示这个请求用的请求Id.这个请求结果可以通过订阅 - [`found-in-page`](web-contents.md#event-found-in-page) 事件来取得. +发起请求，在网页中查找所有与 `text` 相匹配的项，并且返回一个 `Integer` 来表示这个请求用的请求 Id。这个请求结果可以通过订阅 + [`found-in-page`](web-contents.md#event-found-in-page) 事件来取得。 ### `webContents.stopFindInPage(action)` * `action` String - 指定一个行为来接替停止 - [`webContents.findInPage`] 请求. - * `clearSelection` - 转变为一个普通的 selection. - * `keepSelection` - 清除 selection. - * `activateSelection` - 获取焦点并点击 selection node. + [`webContents.findInPage`] 请求。 + * `clearSelection` - 转变为一个普通的 selection。 + * `keepSelection` - 清除 selection。 + * `activateSelection` - 获取焦点并点击 selection node。 -使用给定的 `action` 来为 `webContents` 停止任何 `findInPage` 请求. +使用给定的 `action` 来为 `webContents` 停止任何 `findInPage` 请求。 ```javascript webContents.on('found-in-page', function (event, result) { @@ -518,42 +569,42 @@ const requestId = webContents.findInPage('api') * `callback` Function -检查是否有任何 ServiceWorker 注册了，并且返回一个布尔值，来作为 `callback`响应的标识. +检查是否有任何 ServiceWorker 注册了，并且返回一个布尔值，来作为 `callback`响应的标识。 ### `webContents.unregisterServiceWorker(callback)` * `callback` Function -如果存在任何 ServiceWorker ，则全部注销，并且当JS承诺执行行或JS拒绝执行而失败的时候，返回一个布尔值，它标识了相应的 `callback`. +如果存在任何 ServiceWorker，则全部注销，并且当JS承诺执行行或JS拒绝执行而失败的时候，返回一个布尔值，它标识了相应的 `callback`。 ### `webContents.print([options])` * `options` Object (可选) - * `silent` Boolean - 不需要请求用户的打印设置. 默认为 `false`. - * `printBackground` Boolean - 打印背景和网页图片. 默认为 `false`. + * `silent` Boolean - 不需要请求用户的打印设置. 默认为 `false`。 + * `printBackground` Boolean - 打印背景和网页图片. 默认为 `false`。 -打印窗口的网页. 当设置 `silent` 为 `false` 的时候，Electron 将使用系统默认的打印机和打印方式来打印. +打印窗口的网页。当设置 `silent` 为 `false` 的时候，Electron 将使用系统默认的打印机和打印方式来打印。 -在网页中调用 `window.print()` 和 调用 `webContents.print({silent: false, printBackground: false})`具有相同的作用. +在网页中调用 `window.print()` 和 调用 `webContents.print({silent: false, printBackground: false})`具有相同的作用。 -**注意:** 在 Windows, 打印 API 依赖于 `pdf.dll`. 如果你的应用不使用任何的打印, 你可以安全删除 `pdf.dll` 来减少二进制文件的size. +**注意：** 在 Windows，打印 API 依赖于 `pdf.dll`。如果你的应用不使用任何的打印，你可以安全删除 `pdf.dll` 来减少二进制文件的size。 ### `webContents.printToPDF(options, callback)` * `options` Object - * `marginsType` Integer - 指定使用的 margin type. 默认 margin 使用 0, 无 margin 使用 1, 最小化 margin 使用 2. - * `pageSize` String - 指定生成的PDF文件的page size. 可以是 `A3`, - `A4`, `A5`, `Legal`, `Letter` 和 `Tabloid`. - * `printBackground` Boolean - 是否打印 css 背景. - * `printSelectionOnly` Boolean - 是否只打印选中的部分. - * `landscape` Boolean - landscape 为 `true`, portrait 为 `false`. + * `marginsType` Integer - 指定使用的 margin type。默认 margin 使用 0，无 margin 使用 1，最小化 margin 使用 2。 + * `pageSize` String - 指定生成的PDF文件的page size. 可以是 `A3`、 + `A4`、 `A5`、 `Legal`、`Letter` 和 `Tabloid`。 + * `printBackground` Boolean - 是否打印 css 背景。 + * `printSelectionOnly` Boolean - 是否只打印选中的部分。 + * `landscape` Boolean - landscape 为 `true`, portrait 为 `false`。 * `callback` Function -打印窗口的网页为 pdf ，使用 Chromium 预览打印的自定义设置. +打印窗口的网页为 pdf，使用 Chromium 预览打印的自定义设置。 -完成时使用 `callback(error, data)` 调用 `callback` . `data` 是一个 `Buffer` ，包含了生成的 pdf 数据. +完成时使用 `callback(error, data)` 调用 `callback` 。 `data` 是一个 `Buffer` ，包含了生成的 pdf 数据、 -默认，空的 `options` 被视为 : +默认，空的 `options` 被视为： ```javascript { @@ -587,7 +638,7 @@ win.webContents.on('did-finish-load', function () { * `path` String -添加指定的路径给开发者工具栏的 workspace.必须在 DevTools 创建之后使用它 : +添加指定的路径给开发者工具栏的 workspace。必须在 DevTools 创建之后使用它： ```javascript mainWindow.webContents.on('devtools-opened', function () { @@ -599,52 +650,52 @@ mainWindow.webContents.on('devtools-opened', function () { * `path` String -从开发者工具栏的 workspace 删除指定的路径. +从开发者工具栏的 workspace 删除指定的路径。 ### `webContents.openDevTools([options])` * `options` Object (可选) * `detach` Boolean - 在一个新窗口打开开发者工具栏 -打开开发者工具栏. +打开开发者工具栏。 ### `webContents.closeDevTools()` -关闭开发者工具栏. +关闭开发者工具栏。 ### `webContents.isDevToolsOpened()` -返回布尔值，开发者工具栏是否打开. +返回布尔值，开发者工具栏是否打开。 ### `webContents.isDevToolsFocused()` -返回布尔值，开发者工具栏视图是否获得焦点. +返回布尔值，开发者工具栏视图是否获得焦点。 ### `webContents.toggleDevTools()` -Toggles 开发者工具. +Toggles 开发者工具。 ### `webContents.inspectElement(x, y)` * `x` Integer * `y` Integer -在 (`x`, `y`) 开始检测元素. +在 (`x`, `y`) 开始检测元素。 ### `webContents.inspectServiceWorker()` -为 service worker 上下文打开开发者工具栏. +为 service worker 上下文打开开发者工具栏。 ### `webContents.send(channel[, arg1][, arg2][, ...])` * `channel` String * `arg` (可选) -通过 `channel` 发送异步消息给渲染进程，你也可发送任意的参数.参数应该在 JSON 内部序列化，并且此后没有函数或原形链被包括了. +通过 `channel` 发送异步消息给渲染进程，你也可发送任意的参数。参数应该在 JSON 内部序列化，并且此后没有函数或原形链被包括了。 -渲染进程可以通过使用 `ipcRenderer` 监听 `channel` 来处理消息. +渲染进程可以通过使用 `ipcRenderer` 监听 `channel` 来处理消息。 -例子，从主进程向渲染进程发送消息 : +例子，从主进程向渲染进程发送消息： ```javascript // 主进程. @@ -696,11 +747,11 @@ app.on('ready', function () { * `y` Float - 设置相对左上角的y轴偏移值 * `scale` Float - 可用空间内的模拟视图偏移 (不在适应视图模式) (默认: `1`) -使用给定的参数来开启设备模拟. +使用给定的参数来开启设备模拟。 ### `webContents.disableDeviceEmulation()` -使用 `webContents.enableDeviceEmulation` 关闭设备模拟. +使用 `webContents.enableDeviceEmulation` 关闭设备模拟。 ### `webContents.sendInputEvent(event)` @@ -713,14 +764,14 @@ app.on('ready', function () { `leftButtonDown`, `middleButtonDown`, `rightButtonDown`, `capsLock`, `numLock`, `left`, `right`. -向 page 发送一个输入 `event` . +向 page 发送一个输入 `event`。 -对键盘事件来说，`event` 对象还有如下属性 : +对键盘事件来说，`event` 对象还有如下属性： -* `keyCode` String (**必需**) - 特点是将作为键盘事件发送. 可用的 key codes [Accelerator](accelerator.md). +* `keyCode` String (**必需**) - 特点是将作为键盘事件发送。可用的 key codes [Accelerator](accelerator.md)。 -对鼠标事件来说，`event` 对象还有如下属性 : +对鼠标事件来说，`event` 对象还有如下属性： * `x` Integer (**required**) * `y` Integer (**required**) @@ -731,7 +782,7 @@ app.on('ready', function () { * `movementY` Integer * `clickCount` Integer -对鼠标滚轮事件来说，`event` 对象还有如下属性 : +对鼠标滚轮事件来说，`event` 对象还有如下属性： * `deltaX` Integer * `deltaY` Integer @@ -746,13 +797,13 @@ app.on('ready', function () { * `callback` Function -开始订阅 提交 事件和捕获数据帧，当有 提交 事件时，使用 `callback(frameBuffer)` 调用 `callback`. +开始订阅 提交 事件和捕获数据帧，当有提交事件时，使用 `callback(frameBuffer)` 调用 `callback`。 -`frameBuffer` 是一个包含原始像素数据的 `Buffer`,像素数据是按照 32bit BGRA 格式有效存储的，但是实际情况是取决于处理器的字节顺序的(大多数的处理器是存放小端序的，如果是在大端序的处理器上，数据是 32bit ARGB 格式). +`frameBuffer` 是一个包含原始像素数据的 `Buffer`，像素数据是按照 32bit BGRA 格式有效存储的，但是实际情况是取决于处理器的字节顺序的（大多数的处理器是存放小端序的，如果是在大端序的处理器上，数据是 32bit ARGB 格式）。 ### `webContents.endFrameSubscription()` -停止订阅帧提交事件. +停止订阅帧提交事件。 ### `webContents.savePage(fullPath, saveType, callback)` @@ -764,7 +815,7 @@ app.on('ready', function () { * `callback` Function - `function(error) {}`. * `error` Error -如果保存界面过程初始化成功，返回 true. +如果保存界面过程初始化成功，返回 true。 ```javascript win.loadURL('https://github.com') @@ -778,25 +829,25 @@ win.webContents.on('did-finish-load', function () { ## 实例属性 -`WebContents` 对象也有下列属性: +`WebContents` 对象也有下列属性： ### `webContents.session` -返回这个 `webContents` 使用的 [session](session.md) 对象. +返回这个 `webContents` 使用的 [session](session.md) 对象。 ### `webContents.hostWebContents` -返回这个 `webContents` 的父 `webContents` . +返回这个 `webContents` 的父 `webContents`。 ### `webContents.devToolsWebContents` -获取这个 `WebContents` 的开发者工具栏的 `WebContents` . +获取这个 `WebContents` 的开发者工具栏的 `WebContents`。 -**注意:** 用户不可保存这个对象，因为当开发者工具栏关闭的时候它的值为 `null` . +**注意:** 用户不可保存这个对象，因为当开发者工具栏关闭的时候它的值为 `null`。 ### `webContents.debugger` -调试 API 为 [remote debugging protocol][rdp] 提供交替传送. +调试 API 为 [remote debugging protocol][rdp] 提供交替传送。 ```javascript try { @@ -822,42 +873,42 @@ win.webContents.debugger.sendCommand('Network.enable') #### `webContents.debugger.attach([protocolVersion])` -* `protocolVersion` String (可选) - 请求调试协议版本. +* `protocolVersion` String (可选) - 请求调试协议版本。 -添加 `webContents` 调试. +添加 `webContents` 调试。 #### `webContents.debugger.isAttached()` -返回一个布尔值，标识是否已经给 `webContents` 添加了调试. +返回一个布尔值，标识是否已经给 `webContents` 添加了调试。 #### `webContents.debugger.detach()` -删除 `webContents` 调试. +删除 `webContents` 调试。 #### `webContents.debugger.sendCommand(method[, commandParams, callback])` -* `method` String - 方法名, 应该是由远程调试协议定义的方法. -* `commandParams` Object (可选) - 请求参数为 JSON 对象. +* `method` String - 方法名, 应该是由远程调试协议定义的方法。 +* `commandParams` Object (可选) - 请求参数为 JSON 对象。 * `callback` Function (可选) - Response - * `error` Object - 错误消息，标识命令失败. - * `result` Object - 回复在远程调试协议中由 'returns'属性定义的命令描述. + * `error` Object - 错误消息，标识命令失败。 + * `result` Object - 回复在远程调试协议中由 'returns'属性定义的命令描述。 -发送给定命令给调试目标. +发送给定命令给调试目标。 ### Event: 'detach' * `event` Event -* `reason` String - 拆分调试器原因. +* `reason` String - 拆分调试器原因。 -在调试 session 结束时发出事件.这在 `webContents` 关闭时或 `webContents` 请求开发者工具栏时发生. +在调试 session 结束时发出事件.这在 `webContents` 关闭时或 `webContents` 请求开发者工具栏时发生。 ### Event: 'message' * `event` Event -* `method` String - 方法名. -* `params` Object - 在远程调试协议中由 'parameters' 属性定义的事件参数. +* `method` String - 方法名。 +* `params` Object - 在远程调试协议中由 'parameters' 属性定义的事件参数。 -每当调试目标发出事件时发出. +每当调试目标发出事件时发出。 [rdp]: https://developer.chrome.com/devtools/docs/debugger-protocol [`webContents.findInPage`]: web-contents.md#webcontentsfindinpagetext-options