diff --git a/docs-translations/zh-CN/api/clipboard.md b/docs-translations/zh-CN/api/clipboard.md new file mode 100644 index 000000000000..77aa6d65c0b3 --- /dev/null +++ b/docs-translations/zh-CN/api/clipboard.md @@ -0,0 +1,117 @@ +# clipboard + +`clipboard` 模块提供方法来供复制和粘贴操作 . +下面例子展示了如何将一个字符串写道 clipboard 上: + +```javascript +const clipboard = require('electron').clipboard; +clipboard.writeText('Example String'); +``` + +在 X Window 系统上, 有一个可选的 clipboard. 你可以为每个方法使用 `selection` 来控制它: + +```javascript +clipboard.writeText('Example String', 'selection'); +console.log(clipboard.readText('selection')); +``` + +## 方法 + +`clipboard` 模块有以下方法: + +**注意:** 测试 APIs 已经标明,并且在将来会被删除 . + +### `clipboard.readText([type])` + +* `type` String (可选) + +以纯文本形式从 clipboard 返回内容 . + +### `clipboard.writeText(text[, type])` + +* `text` String +* `type` String (可选) + +以纯文本形式向 clipboard 添加内容 . + +### `clipboard.readHtml([type])` + +* `type` String (可选) + +返回 clipboard 中的标记内容. + +### `clipboard.writeHtml(markup[, type])` + +* `markup` String +* `type` String (可选) + +向 clipboard 添加 `markup` 内容 . + +### `clipboard.readImage([type])` + +* `type` String (可选) + +从 clipboard 中返回 [NativeImage](native-image.md) 内容. + +### `clipboard.writeImage(image[, type])` + +* `image` [NativeImage](native-image.md) +* `type` String (可选) + +向 clipboard 中写入 `image` . + +### `clipboard.readRtf([type])` + +* `type` String (可选) + +从 clipboard 中返回 RTF 内容. + +### `clipboard.writeRtf(text[, type])` + +* `text` String +* `type` String (可选) + +向 clipboard 中写入 RTF 格式的 `text` . + +### `clipboard.clear([type])` + +* `type` String (可选) + +清空 clipboard 内容. + +### `clipboard.availableFormats([type])` + +* `type` String (可选) + +返回 clipboard 支持的格式数组 . + +### `clipboard.has(data[, type])` _Experimental_ + +* `data` String +* `type` String (可选) + +返回 clipboard 是否支持指定 `data` 的格式. + +```javascript +console.log(clipboard.has('

selection

')); +``` + +### `clipboard.read(data[, type])` _Experimental_ + +* `data` String +* `type` String (可选) + +读取 clipboard 的 `data`. + +### `clipboard.write(data[, type])` + +* `data` Object + * `text` String + * `html` String + * `image` [NativeImage](native-image.md) +* `type` String (可选) + +```javascript +clipboard.write({text: 'test', html: "test"}); +``` +向 clipboard 写入 `data` . \ No newline at end of file diff --git a/docs-translations/zh-CN/api/crash-reporter.md b/docs-translations/zh-CN/api/crash-reporter.md new file mode 100644 index 000000000000..a4646401ad8f --- /dev/null +++ b/docs-translations/zh-CN/api/crash-reporter.md @@ -0,0 +1,61 @@ +# crashReporter + +`crash-reporter` 模块开启发送应用崩溃报告. + +下面是一个自动提交崩溃报告给服务器的例子 : + +```javascript +const crashReporter = require('electron').crashReporter; + +crashReporter.start({ + productName: 'YourName', + companyName: 'YourCompany', + submitURL: 'https://your-domain.com/url-to-submit', + autoSubmit: true +}); +``` + +## 方法 + +`crash-reporter` 模块有如下方法: + +### `crashReporter.start(options)` + +* `options` Object + * `companyName` String + * `submitURL` String - 崩溃报告发送的路径,以post方式. + * `productName` String (可选) - 默认为 `Electron`. + * `autoSubmit` Boolean - 是否自动提交. + 默认为 `true`. + * `ignoreSystemCrashHandler` Boolean - 默认为 `false`. + * `extra` Object - 一个你可以定义的对象,附带在崩溃报告上一起发送 . 只有字符串属性可以被正确发送,不支持嵌套对象. + +只可以在使用其它 `crashReporter` APIs 之前使用这个方法. + +**注意:** 在 OS X, Electron 使用一个新的 `crashpad` 客户端, 与 Windows 和 Linux 的 `breakpad` 不同. 为了开启崩溃点搜集,你需要在主进程和其它每个你需要搜集崩溃报告的渲染进程中调用 `crashReporter.start` API 来初始化 `crashpad`. + +### `crashReporter.getLastCrashReport()` + +返回最后一个崩溃报告的日期和 ID.如果没有过崩溃报告发送过来,或者还没有开始崩溃报告搜集,将返回 `null` . + +### `crashReporter.getUploadedReports()` + +返回所有上载的崩溃报告,每个报告包含了上载日期和 ID. + +## crash-reporter Payload + +崩溃报告将发送下面的数据给 `POST` 型的 `提交 URL` : + +* `ver` String - Electron 版本. +* `platform` String - 例如 'win32'. +* `process_type` String - 例如 'renderer'. +* `guid` String - 例如 '5e1286fc-da97-479e-918b-6bfb0c3d1c72' +* `_version` String - `package.json` 版本. +* `_productName` String - `crashReporter` `options` + 对象中的产品名字. +* `prod` String - 基础产品名字. 这种情况为 Electron. +* `_companyName` String - `crashReporter` `options` + 对象中的公司名字. +* `upload_file_minidump` File - 崩溃报告为文件. +* `crashReporter` 中的 `extra` 对象的所有等级和一个属性. + `options` object \ No newline at end of file diff --git a/docs-translations/zh-CN/api/desktop-capturer.md b/docs-translations/zh-CN/api/desktop-capturer.md new file mode 100644 index 000000000000..954520d05eaa --- /dev/null +++ b/docs-translations/zh-CN/api/desktop-capturer.md @@ -0,0 +1,64 @@ +# desktopCapturer + +`desktopCapturer` 模块可用来获取可用资源,这个资源可通过 `getUserMedia` 捕获得到. + +```javascript +// 在渲染进程中. +var desktopCapturer = require('electron').desktopCapturer; + +desktopCapturer.getSources({types: ['window', 'screen']}, function(error, sources) { + if (error) throw error; + for (var i = 0; i < sources.length; ++i) { + if (sources[i].name == "Electron") { + navigator.webkitGetUserMedia({ + audio: false, + video: { + mandatory: { + chromeMediaSource: 'desktop', + chromeMediaSourceId: sources[i].id, + minWidth: 1280, + maxWidth: 1280, + minHeight: 720, + maxHeight: 720 + } + } + }, gotStream, getUserMediaError); + return; + } + } +}); + +function gotStream(stream) { + document.querySelector('video').src = URL.createObjectURL(stream); +} + +function getUserMediaError(e) { + console.log('getUserMediaError'); +} +``` + +当调用 `navigator.webkitGetUserMedia` 时创建一个约束对象,如果使用 `desktopCapturer` 的资源,必须设置 `chromeMediaSource` 为 `"desktop"` ,并且 `audio` 为 `false`. + +如果你想捕获整个桌面的 audio 和 video,你可以设置 `chromeMediaSource` 为 `"screen"` ,和 `audio` 为 `true`. +当使用这个方法的时候,不可以指定一个 `chromeMediaSourceId`. + +## 方法 + +`desktopCapturer` 模块有如下方法: + +### `desktopCapturer.getSources(options, callback)` + +* `options` Object + * `types` Array - 一个 String 数组,列出了可以捕获的桌面资源类型, 可用类型为 `screen` 和 `window`. + * `thumbnailSize` Object (可选) - 建议缩略可被缩放的 size, 默认为 `{width: 150, height: 150}`. +* `callback` Function + +发起一个请求,获取所有桌面资源,当请求完成的时候使用 `callback(error, sources)` 调用 `callback` . + +`sources` 是一个 `Source` 对象数组, 每个 `Source` 表示了一个捕获的屏幕或单独窗口,并且有如下属性 : +* `id` String - 在 `navigator.webkitGetUserMedia` 中使用的捕获窗口或屏幕的 id . 格式为 `window:XX` 祸 + `screen:XX`,`XX` 是一个随机数. +* `name` String - 捕获窗口或屏幕的描述名 . 如果资源为屏幕,名字为 `Entire Screen` 或 `Screen `; 如果资源为窗口, 名字为窗口的标题. +* `thumbnail` [NativeImage](NativeImage.md) - 缩略图. + +**注意:** 不能保证 `source.thumbnail` 的 size 和 `options` 中的 `thumnbailSize` 一直一致. 它也取决于屏幕或窗口的缩放比例. \ No newline at end of file diff --git a/docs-translations/zh-CN/api/ipc-renderer.md b/docs-translations/zh-CN/api/ipc-renderer.md new file mode 100644 index 000000000000..beeaa6d76232 --- /dev/null +++ b/docs-translations/zh-CN/api/ipc-renderer.md @@ -0,0 +1,69 @@ +# ipcRenderer + +`ipcRenderer` 模块是一个 +[EventEmitter](https://nodejs.org/api/events.html) 类的实例. 它提供了有限的方法,你可以从渲染进程向主进程发送同步或异步消息. 也可以收到主进程的相应. + +查看 [ipcMain](ipc-main.md) 代码例子. + +## 消息监听 + +`ipcRenderer` 模块有下列方法来监听事件: + +### `ipcRenderer.on(channel, listener)` + +* `channel` String +* `listener` Function + +监听 `channel`, 当有新消息到达,使用 `listener(event, args...)` 调用 `listener` . + +### `ipcRenderer.once(channel, listener)` + +* `channel` String +* `listener` Function + +为这个事件添加一个一次性 `listener` 函数.这个 `listener` 将在下一次有新消息被发送到 `channel` 的时候被请求调用,之后就被删除了. + +### `ipcRenderer.removeListener(channel, listener)` + +* `channel` String +* `listener` Function + +从指定的 `channel` 中的监听者数组删除指定的 `listener` . + +### `ipcRenderer.removeAllListeners([channel])` + +* `channel` String (optional) + +删除所有的监听者,或者删除指定 `channel` 中的全部. + +## 发送消息 + +`ipcRenderer` 模块有如下方法来发送消息: + +### `ipcRenderer.send(channel[, arg1][, arg2][, ...])` + +* `channel` String +* `arg` (可选) + +通过 `channel` 向主进程发送异步消息,也可以发送任意参数.参数会被JSON序列化,之后就不会包含函数或原型链. + +主进程通过使用 `ipcMain` 模块来监听 `channel`,从而处理消息. + +### `ipcRenderer.sendSync(channel[, arg1][, arg2][, ...])` + +* `channel` String +* `arg` (可选) + +通过 `channel` 向主进程发送同步消息,也可以发送任意参数.参数会被JSON序列化,之后就不会包含函数或原型链. + +主进程通过使用 `ipcMain` 模块来监听 `channel`,从而处理消息, +通过 `event.returnValue` 来响应. + +__注意:__ 发送同步消息将会阻塞整个渲染进程,除非你知道你在做什么,否则就永远不要用它 . + +### `ipcRenderer.sendToHost(channel[, arg1][, arg2][, ...])` + +* `channel` String +* `arg` (可选) + +类似 `ipcRenderer.send` ,但是它的事件将发往 host page 的 `` 元素,而不是主进程. \ No newline at end of file diff --git a/docs-translations/zh-CN/api/native-image.md b/docs-translations/zh-CN/api/native-image.md new file mode 100644 index 000000000000..cb2569922b23 --- /dev/null +++ b/docs-translations/zh-CN/api/native-image.md @@ -0,0 +1,142 @@ +# nativeImage + +在 Electron 中, 对所有创建 images 的 api 来说, 你可以使用文件路径或 `nativeImage` 实例. 如果使用 `null` ,将创建一个空的image 对象. + +例如, 当创建一个 tray 或设置窗口的图标时候,你可以使用一个字符串的图片路径 : + +```javascript +var appIcon = new Tray('/Users/somebody/images/icon.png'); +var window = new BrowserWindow({icon: '/Users/somebody/images/window.png'}); +``` + +或者从剪切板中读取图片,它返回的是 `nativeImage`: + +```javascript +var image = clipboard.readImage(); +var appIcon = new Tray(image); +``` + +## 支持的格式 + +当前支持 `PNG` 和 `JPEG` 图片格式. 推荐 `PNG` ,因为它支持透明和无损压缩. + +在 Windows, 你也可以使用 `ICO` 图标的格式. + +## 高分辨率图片 + +如果平台支持 high-DPI,你可以在图片基础路径后面添加 `@2x` ,可以标识它为高分辨率的图片. + +例如,如果 `icon.png` 是一个普通图片并且拥有标准分辨率,然后 `icon@2x.png`将被当作高分辨率的图片处理,它将拥有双倍 DPI 密度. + +如果想同时支持展示不同分辨率的图片,你可以将拥有不同size 的图片放在同一个文件夹下,不用 DPI 后缀.例如 : + +```text +images/ +├── icon.png +├── icon@2x.png +└── icon@3x.png +``` + + +```javascript +var appIcon = new Tray('/Users/somebody/images/icon.png'); +``` + +也支持下面这些 DPI 后缀: + +* `@1x` +* `@1.25x` +* `@1.33x` +* `@1.4x` +* `@1.5x` +* `@1.8x` +* `@2x` +* `@2.5x` +* `@3x` +* `@4x` +* `@5x` + +## 模板图片 + +模板图片由黑色和清色(和一个 alpha 通道)组成. +模板图片不是单独使用的,而是通常和其它内容混合起来创建期望的最终效果. + +最常见的用力是将模板图片用到菜单栏图片上,所以它可以同时适应亮、黑不同的菜单栏. + +**注意:** 模板图片只在 OS X 上可用. + +为了将图片标识为一个模板图片,它的文件名应当以 `Template` 结尾. 例如: + +* `xxxTemplate.png` +* `xxxTemplate@2x.png` + +## 方法 + +`nativeImage` 类有如下方法: + +### `nativeImage.createEmpty()` + +创建一个空的 `nativeImage` 实例. + +### `nativeImage.createFromPath(path)` + +* `path` String + +从指定 `path` 创建一个新的 `nativeImage` 实例 . + +### `nativeImage.createFromBuffer(buffer[, scaleFactor])` + +* `buffer` [Buffer][buffer] +* `scaleFactor` Double (可选) + +从 `buffer` 创建一个新的 `nativeImage` 实例 .默认 `scaleFactor` 是 1.0. + +### `nativeImage.createFromDataURL(dataURL)` + +* `dataURL` String + +从 `dataURL` 创建一个新的 `nativeImage` 实例 . + +## 实例方法 + +`nativeImage` 有如下方法: + +```javascript +const nativeImage = require('electron').nativeImage; + +var image = nativeImage.createFromPath('/Users/somebody/images/icon.png'); +``` + +### `image.toPng()` + +返回一个 [Buffer][buffer] ,它包含了图片的 `PNG` 编码数据. + +### `image.toJpeg(quality)` + +* `quality` Integer (**必须**) - 在 0 - 100 之间. + +返回一个 [Buffer][buffer] ,它包含了图片的 `JPEG` 编码数据. + +### `image.toDataURL()` + +返回图片数据的 URL. + +### `image.isEmpty()` + +返回一个 boolean ,标识图片是否为空. + +### `image.getSize()` + +返回图片的 size. + +[buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer + +### `image.setTemplateImage(option)` + +* `option` Boolean + +将图片标识为模板图片. + +### `image.isTemplateImage()` + +返回一个 boolean ,标识图片是否是模板图片. \ No newline at end of file diff --git a/docs-translations/zh-CN/api/screen.md b/docs-translations/zh-CN/api/screen.md new file mode 100644 index 000000000000..0de4c975afbd --- /dev/null +++ b/docs-translations/zh-CN/api/screen.md @@ -0,0 +1,135 @@ +# screen + +`screen` 模块检索屏幕的 size,显示,鼠标位置等的信息.在 `app` 模块的`ready` 事件触发之前不可使用这个模块. + +`screen` 是一个 [EventEmitter](http://nodejs.org/api/events.html#events_class_events_eventemitter). + +**注意:** 在渲染进程 / 开发者工具栏, `window.screen` 是一个预设值的 DOM +属性, 所以这样写 `var screen = require('electron').screen` 将不会工作. +在我们下面的例子, 我们取代使用可变名字的 `electronScreen`. +一个例子,创建一个充满真个屏幕的窗口 : + +```javascript +const electron = require('electron'); +const app = electron.app; +const BrowserWindow = electron.BrowserWindow; + +var mainWindow; + +app.on('ready', function() { + var electronScreen = electron.screen; + var size = electronScreen.getPrimaryDisplay().workAreaSize; + mainWindow = new BrowserWindow({ width: size.width, height: size.height }); +}); +``` + +另一个例子,在次页外创建一个窗口: + +```javascript +const electron = require('electron'); +const app = electron.app; +const BrowserWindow = electron.BrowserWindow; + +var mainWindow; + +app.on('ready', function() { + var electronScreen = electron.screen; + var displays = electronScreen.getAllDisplays(); + var externalDisplay = null; + for (var i in displays) { + if (displays[i].bounds.x != 0 || displays[i].bounds.y != 0) { + externalDisplay = displays[i]; + break; + } + } + + if (externalDisplay) { + mainWindow = new BrowserWindow({ + x: externalDisplay.bounds.x + 50, + y: externalDisplay.bounds.y + 50 + }); + } +}); +``` + +## `Display` 对象 + +`Display` 对象表示了物力方式连接系统. 一个伪造的 `Display` 或许存在于一个无头系统中,或者一个 `Display` 相当于一个远程的、虚拟的 display. + +* `display` object + * `id` Integer - 与display 相关的唯一性标志. + * `rotation` Integer - 可以是 0, 1, 2, 3, 每个代表了屏幕旋转的度数 0, 90, 180, 270. + * `scaleFactor` Number - Output device's pixel scale factor. + * `touchSupport` String - 可以是 `available`, `unavailable`, `unknown`. + * `bounds` Object + * `size` Object + * `workArea` Object + * `workAreaSize` Object + +## 事件 + +`screen` 模块有如下事件: + +### Event: 'display-added' + +返回: + +* `event` Event +* `newDisplay` Object + +当添加了 `newDisplay` 时发出事件 + +### Event: 'display-removed' + +返回: + +* `event` Event +* `oldDisplay` Object + +当移出了 `oldDisplay` 时发出事件 + +### Event: 'display-metrics-changed' + +返回: + +* `event` Event +* `display` Object +* `changedMetrics` Array + +当一个 `display` 中的一个或更多的 metrics 改变时发出事件. +`changedMetrics` 是一个用来描述这个改变的数组.可能的变化为 `bounds`, +`workArea`, `scaleFactor` 和 `rotation`. + +## 方法 + +`screen` 模块有如下方法: + +### `screen.getCursorScreenPoint()` + +返回当前鼠标的绝对路径 . + +### `screen.getPrimaryDisplay()` + +返回最主要的 display. + +### `screen.getAllDisplays()` + +返回一个当前可用的 display 数组. + +### `screen.getDisplayNearestPoint(point)` + +* `point` Object + * `x` Integer + * `y` Integer + +返回离指定点最近的 display. + +### `screen.getDisplayMatching(rect)` + +* `rect` Object + * `x` Integer + * `y` Integer + * `width` Integer + * `height` Integer + +返回与提供的边界范围最密切相关的 display. \ No newline at end of file diff --git a/docs-translations/zh-CN/api/tray.md b/docs-translations/zh-CN/api/tray.md new file mode 100644 index 000000000000..d5647871ac77 --- /dev/null +++ b/docs-translations/zh-CN/api/tray.md @@ -0,0 +1,205 @@ +# Tray + +用一个 `Tray` 来表示一个图标,这个图标处于正在运行的系统的通知区 ,通常被添加到一个 context menu 上. + +```javascript +const electron = require('electron'); +const app = electron.app; +const Menu = electron.Menu; +const Tray = electron.Tray; + +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' } + ]); + appIcon.setToolTip('This is my application.'); + appIcon.setContextMenu(contextMenu); +}); + +``` + +__平台限制:__ + +* 在 Linux, 如果支持应用指示器则使用它,否则使用 `GtkStatusIcon` 代替. +* 在 Linux ,配置了只有有了应用指示器的支持, 你必须安装 `libappindicator1` 来让 tray icon 执行. +* 应用指示器只有在它拥有 context menu 时才会显示. +* 当在linux 上使用了应用指示器,将忽略点击事件. +* 在 Linux,为了让单独的 `MenuItem` 起效,需要再次调用 `setContextMenu` .例如: + +```javascript +contextMenu.items[2].checked = false; +appIcon.setContextMenu(contextMenu); +``` +如果想在所有平台保持完全相同的行为,不应该依赖点击事件,而是一直将一个 context menu 添加到 tray icon. + +## Class: Tray + +`Tray` 是一个 [事件发出者][event-emitter]. + +### `new Tray(image)` + +* `image` [NativeImage](native-image.md) + +创建一个与 `image` 相关的 icon. + +## 事件 + +`Tray` 模块可发出下列事件: + +**注意:** 一些事件只能在特定的os中运行,已经标明. + +### 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 + +当tray icon被点击的时候发出事件. + +__注意:__ `bounds` 只在 OS X 和 Windows 上起效. + +### Event: 'right-click' _OS X_ _Windows_ + +* `event` Event + * `altKey` Boolean + * `shiftKey` Boolean + * `ctrlKey` Boolean + * `metaKey` Boolean +* `bounds` Object - tray icon 的 bounds. + * `x` Integer + * `y` Integer + * `width` Integer + * `height` Integer + +当tray icon被鼠标右键点击的时候发出事件. + +### Event: 'double-click' _OS X_ _Windows_ + +* `event` Event + * `altKey` Boolean + * `shiftKey` Boolean + * `ctrlKey` Boolean + * `metaKey` Boolean +* `bounds` Object - tray icon 的 bounds. + * `x` Integer + * `y` Integer + * `width` Integer + * `height` Integer + +当tray icon被双击的时候发出事件. + +### Event: 'balloon-show' _Windows_ + +当tray 气泡显示的时候发出事件. + +### Event: 'balloon-click' _Windows_ + +当tray 气泡被点击的时候发出事件. + +### Event: 'balloon-closed' _Windows_ + +当tray 气泡关闭的时候发出事件,因为超时或人为关闭. + +### Event: 'drop' _OS X_ + +当tray icon上的任何可拖动项被删除的时候发出事件. + +### Event: 'drop-files' _OS X_ + +* `event` +* `files` Array - 已删除文件的路径. + +当tray icon上的可拖动文件被删除的时候发出事件. + +### Event: 'drag-enter' _OS X_ + +当一个拖动操作进入tray icon的时候发出事件. + +### Event: 'drag-leave' _OS X_ + +当一个拖动操作离开tray icon的时候发出事件. +Emitted when a drag operation exits the tray icon. + +### Event: 'drag-end' _OS X_ + +当一个拖动操作在tray icon上或其它地方停止拖动的时候发出事件. + +## 方法 + +`Tray` 模块有以下方法: + +**Note:** 一些方法只能在特定的os中运行,已经标明. + +### `Tray.destroy()` + +立刻删除 tray icon. + +### `Tray.setImage(image)` + +* `image` [NativeImage](native-image.md) + +让 `image` 与 tray icon 关联起来. + +### `Tray.setPressedImage(image)` _OS X_ + +* `image` [NativeImage](native-image.md) + +当在 OS X 上按压 tray icon 的时候, 让 `image` 与 tray icon 关联起来. + +### `Tray.setToolTip(toolTip)` + +* `toolTip` String + +为 tray icon 设置 hover text. + +### `Tray.setTitle(title)` _OS X_ + +* `title` String + +在状态栏沿着 tray icon 设置标题. + +### `Tray.setHighlightMode(highlight)` _OS X_ + +* `highlight` Boolean + +当 tray icon 被点击的时候,是否设置它的背景色变为高亮(blue).默认为 true. + +### `Tray.displayBalloon(options)` _Windows_ + +* `options` Object + * `icon` [NativeImage](native-image.md) + * `title` String + * `content` String + +展示一个 tray balloon. + +### `Tray.popUpContextMenu([menu, position])` _OS X_ _Windows_ + +* `menu` Menu (optional) +* `position` Object (可选) - 上托位置. + * `x` Integer + * `y` Integer + +从 tray icon 上托出 context menu . 当划过 `menu` 的时候, `menu` 显示,代替 tray 的 context menu . + +`position` 只在 windows 上可用,默认为 (0, 0) . + +### `Tray.setContextMenu(menu)` + +* `menu` Menu + +为这个 icon 设置 context menu . + +[event-emitter]: http://nodejs.org/api/events.html#events_class_events_eventemitter \ No newline at end of file diff --git a/docs-translations/zh-CN/api/web-contents.md b/docs-translations/zh-CN/api/web-contents.md new file mode 100644 index 000000000000..1b7011bb0fa8 --- /dev/null +++ b/docs-translations/zh-CN/api/web-contents.md @@ -0,0 +1,861 @@ +# webContents + +`webContents` 是一个 +[事件发出者](http://nodejs.org/api/events.html#events_class_events_eventemitter). + +它负责渲染并控制网页,也是 [`BrowserWindow`](browser-window.md) 对象的属性.一个使用 `webContents` 的例子: + +```javascript +const BrowserWindow = require('electron').BrowserWindow; + +var win = new BrowserWindow({width: 800, height: 1500}); +win.loadURL("http://github.com"); + +var webContents = win.webContents; +``` + +## 事件 + +`webContents` 对象可发出下列事件: + +### Event: 'did-finish-load' + +当导航完成时发出事件,`onload` 事件也完成. + +### Event: 'did-fail-load' + +返回: + +* `event` Event +* `errorCode` Integer +* `errorDescription` String +* `validatedURL` String + +这个事件类似 `did-finish-load` ,但是是在加载失败或取消加载时发出, 例如, `window.stop()` 请求结束.错误代码的完整列表和它们的含义都可以在 [here](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 导航完成的时候发出事件. + +### Event: 'did-start-loading' + +当 tab 的spinner 开始 spinning的时候. + +### Event: 'did-stop-loading' + +当 tab 的spinner 结束 spinning的时候. + +### Event: 'did-get-response-details' + +返回: + +* `event` Event +* `status` Boolean +* `newURL` String +* `originalURL` String +* `httpResponseCode` Integer +* `requestMethod` String +* `referrer` String +* `headers` Object + +当有关请求资源的详细信息可用的时候发出事件. +`status` 标识了 socket链接来下载资源. + +### Event: 'did-get-redirect-request' + +返回: + +* `event` Event +* `oldURL` String +* `newURL` String +* `isMainFrame` Boolean +* `httpResponseCode` Integer +* `requestMethod` String +* `referrer` String +* `headers` Object + +当在请求资源时收到重定向的时候发出事件. + +### Event: 'dom-ready' + +返回: + +* `event` Event + +当指定 frame 中的 文档加载完成的时候发出事件. + +### Event: 'page-favicon-updated' + +返回: + +* `event` Event +* `favicons` Array - Array of URLs + +当 page 收到图标 url 的时候发出事件. + +### Event: 'new-window' + +返回: + +* `event` Event +* `url` String +* `frameName` String +* `disposition` String - 可为 `default`, `foreground-tab`, `background-tab`, + `new-window` 和 `other`. +* `options` Object - 创建新的 `BrowserWindow`时使用的参数. + +当 page 请求打开指定 url 窗口的时候发出事件.这可以是通过 `window.open` 或一个外部连接如 `` 发出的请求. + +默认指定 `url` 的 `BrowserWindow` 会被创建. + +调用 `event.preventDefault()` 可以用来阻止打开窗口. + +### Event: 'will-navigate' + +返回: + +* `event` Event +* `url` String + +当用户或 page 想要开始导航的时候发出事件.它可在当 `window.location` 对象改变或用户点击 page 中的链接的时候发生. + +当使用 api(如 `webContents.loadURL` 和 `webContents.back`) 以编程方式来启动导航的时候,这个事件将不会发出. + +它也不会在页内跳转发生, 例如点击锚链接或更新 `window.location.hash`.使用 `did-navigate-in-page` 事件可以达到目的. + +调用 `event.preventDefault()` 可以阻止导航. + +### Event: 'did-navigate' + +返回: + +* `event` Event +* `url` String + +当一个导航结束时候发出事件. + +页内跳转时不会发出这个事件,例如点击锚链接或更新 `window.location.hash`.使用 `did-navigate-in-page` 事件可以达到目的. + +### Event: 'did-navigate-in-page' + +返回: + +* `event` Event +* `url` String + +当页内导航发生的时候发出事件. + +当页内导航发生的时候,page 的url 改变,但是不会跳出界面.例如当点击锚链接时或者 DOM 的 `hashchange` 事件发生. + +### Event: 'crashed' + +当渲染进程崩溃的时候发出事件. + +### Event: 'plugin-crashed' + +返回: + +* `event` Event +* `name` String +* `version` String + +当插件进程崩溃时候发出事件. + +### Event: 'destroyed' + +当 `webContents` 被删除的时候发出事件. + +### Event: 'devtools-opened' + +当开发者工具栏打开的时候发出事件. + +### Event: 'devtools-closed' + +当开发者工具栏关闭时候发出事件. + +### Event: 'devtools-focused' + +当开发者工具栏获得焦点或打开的时候发出事件. + +### Event: 'certificate-error' + +返回: + +* `event` Event +* `url` URL +* `error` String - The error code +* `certificate` Object + * `data` Buffer - PEM encoded data + * `issuerName` String +* `callback` Function + +当验证证书或 `url` 失败的时候发出事件. + +使用方法类似 [`app` 的 `certificate-error` 事件](app.md#event-certificate-error). + +### Event: 'select-client-certificate' + +返回: + +* `event` Event +* `url` URL +* `certificateList` [Objects] + * `data` Buffer - PEM encoded data + * `issuerName` String - Issuer's Common Name +* `callback` Function + +当请求客户端证书的时候发出事件. + +使用方法类似 [`app` 的 `select-client-certificate` 事件](app.md#event-select-client-certificate). + +### Event: 'login' + +返回: + +* `event` Event +* `request` Object + * `method` String + * `url` URL + * `referrer` URL +* `authInfo` Object + * `isProxy` Boolean + * `scheme` String + * `host` String + * `port` Integer + * `realm` String +* `callback` Function + +当 `webContents` 想做基本验证的时候发出事件. + +使用方法类似 [the `login` event of `app`](app.md#event-login). + +### Event: 'found-in-page' + +返回: + +* `event` Event +* `result` Object + * `requestId` Integer + * `finalUpdate` Boolean - 标识是否还有更多的值可以查看. + * `matches` Integer (可选) - 匹配数量. + * `selectionArea` Object (可选) - 协调首个匹配位置. + +当使用 [`webContents.findInPage`](web-contents.md#webcontentsfindinpage) 进行页内查找并且找到可用值得时候发出事件. + +### Event: 'media-started-playing' + +当媒体开始播放的时候发出事件. + +### Event: 'media-paused' + +当媒体停止播放的时候发出事件. + +### Event: 'did-change-theme-color' + +当page 的主题色时候发出事件.这通常由于引入了一个 meta 标签 : + +```html + +``` + +### Event: 'cursor-changed' + +返回: + +* `event` Event +* `type` String +* `image` NativeImage (可选) +* `scale` Float (可选) + +当鼠标的类型发生改变的时候发出事件. `type` 的参数可以是 `default`, +`crosshair`, `pointer`, `text`, `wait`, `help`, `e-resize`, `n-resize`, +`ne-resize`, `nw-resize`, `s-resize`, `se-resize`, `sw-resize`, `w-resize`, +`ns-resize`, `ew-resize`, `nesw-resize`, `nwse-resize`, `col-resize`, +`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`. + +如果 `type` 参数值为 `custom`, `image` 参数会在一个`NativeImage` 中控制自定义鼠标图片, 并且 `scale` 会控制图片的缩放比例. + +## 实例方法 + +`webContents` 对象有如下的实例方法: + +### `webContents.loadURL(url[, options])` + +* `url` URL +* `options` Object (可选) + * `httpReferrer` String - A HTTP Referrer url. + * `userAgent` String - 产生请求的用户代理 + * `extraHeaders` String - 以 "\n" 分隔的额外头 + +在窗口中加载 `url` , `url` 必须包含协议前缀, +比如 `http://` 或 `file://`. 如果加载想要忽略 http 缓存,可以使用 `pragma` 头来达到目的. + +```javascript +const options = {"extraHeaders" : "pragma: no-cache\n"} +webContents.loadURL(url, options) +``` + +### `webContents.downloadURL(url)` + +* `url` URL + +初始化一个指定 `url` 的资源下载,不导航跳转. `session` 的 `will-download` 事件会触发. + +### `webContents.getURL()` + +返回当前page 的 url. + +```javascript +var win = new BrowserWindow({width: 800, height: 600}); +win.loadURL("http://github.com"); + +var currentURL = win.webContents.getURL(); +``` + +### `webContents.getTitle()` + +返回当前page 的 标题. + +### `webContents.isLoading()` + +返回一个布尔值,标识当前页是否正在加载. + +### `webContents.isWaitingForResponse()` + +返回一个布尔值,标识当前页是否正在等待主要资源的第一次响应. + +### `webContents.stop()` + +停止还为开始的导航. + +### `webContents.reload()` + +重载当前页. + +### `webContents.reloadIgnoringCache()` + +重载当前页,忽略缓存. + +### `webContents.canGoBack()` + +返回一个布尔值,标识浏览器是否能回到前一个page. + +### `webContents.canGoForward()` + +返回一个布尔值,标识浏览器是否能前往下一个page. + +### `webContents.canGoToOffset(offset)` + +* `offset` Integer + +返回一个布尔值,标识浏览器是否能前往指定 `offset` 的page. + +### `webContents.clearHistory()` + +清除导航历史. + +### `webContents.goBack()` + +让浏览器回退到前一个page. + +### `webContents.goForward()` + +让浏览器回前往下一个page. + +### `webContents.goToIndex(index)` + +* `index` Integer + +让浏览器回前往指定 `index` 的page. + +### `webContents.goToOffset(offset)` + +* `offset` Integer + +导航到相对于当前页的偏移位置页. + +### `webContents.isCrashed()` + +渲染进程是否崩溃. + +### `webContents.setUserAgent(userAgent)` + +* `userAgent` String + +重写本页用户代理. + +### `webContents.getUserAgent()` + +返回一个 `String` ,标识本页用户代理信息. + +### `webContents.insertCSS(css)` + +* `css` String + +为当前页插入css. + +### `webContents.executeJavaScript(code[, userGesture, callback])` + +* `code` String +* `userGesture` Boolean (可选) +* `callback` Function (可选) - 脚本执行完成后调用的回调函数. + * `result` + +评估 page `代码`. + +浏览器窗口中的一些 HTML API ,例如 `requestFullScreen`,只能被用户手势请求.设置 `userGesture` 为 `true` 可以取消这个限制. + +### `webContents.setAudioMuted(muted)` + +* `muted` Boolean + +减缓当前也的 audio 的播放速度. + +### `webContents.isAudioMuted()` + +返回一个布尔值,标识当前页是否减缓了 audio 的播放速度. + +### `webContents.undo()` + +执行网页的编辑命令 `undo` . + +### `webContents.redo()` + +执行网页的编辑命令 `redo` . + +### `webContents.cut()` + +执行网页的编辑命令 `cut` . + +### `webContents.copy()` + +执行网页的编辑命令 `copy` . + +### `webContents.paste()` + +执行网页的编辑命令 `paste` . + +### `webContents.pasteAndMatchStyle()` + +执行网页的编辑命令 `pasteAndMatchStyle` . + +### `webContents.delete()` + +执行网页的编辑命令 `delete` . + +### `webContents.selectAll()` + +执行网页的编辑命令 `selectAll` . + +### `webContents.unselect()` + +执行网页的编辑命令 `unselect` . + +### `webContents.replace(text)` + +* `text` String + +执行网页的编辑命令 `replace` . + +### `webContents.replaceMisspelling(text)` + +* `text` String + +执行网页的编辑命令 `replaceMisspelling` . + +### `webContents.insertText(text)` + +* `text` String + +插入 `text` 到获得了焦点的元素. + +### `webContents.findInPage(text[, options])` + +* `text` String - 查找内容, 不能为空. +* `options` Object (可选) + * `forward` Boolean - 是否向前或向后查找, 默认为 `true`. + * `findNext` Boolean - 当前操作是否是第一次查找或下一次查找, + 默认为 `false`. + * `matchCase` Boolean - 查找是否区分大小写, + 默认为 `false`. + * `wordStart` Boolean -是否仅以首字母查找. + 默认为 `false`. + * `medialCapitalAsWordStart` Boolean - 是否结合 `wordStart`,如果匹配是大写字母开头,后面接小写字母或无字母,那么就接受这个词中匹配.接受几个其它的合成词匹配, 默认为 `false`. + +发起请求,在网页中查找所有与 `text` 相匹配的项,并且返回一个 `Integer` 来表示这个请求用的请求Id.这个请求结果可以通过订阅 + [`found-in-page`](web-contents.md#event-found-in-page) 事件来取得. + +### `webContents.stopFindInPage(action)` + +* `action` String - 指定一个行为来接替停止 + [`webContents.findInPage`](web-contents.md#webcontentfindinpage) 请求. + * `clearSelection` - 转变为一个普通的 selection. + * `keepSelection` - 清除 selection. + * `activateSelection` - 获取焦点并点击 selection node. + +使用给定的 `action` 来为 `webContents` 停止任何 `findInPage` 请求. + +```javascript +webContents.on('found-in-page', function(event, result) { + if (result.finalUpdate) + webContents.stopFindInPage("clearSelection"); +}); + +const requestId = webContents.findInPage("api"); +``` + +### `webContents.hasServiceWorker(callback)` + +* `callback` Function + +检查是否有任何 ServiceWorker 注册了,并且返回一个布尔值,来作为 `callback`响应的标识. + +### `webContents.unregisterServiceWorker(callback)` + +* `callback` Function + +如果存在任何 ServiceWorker ,则全部注销,并且当JS承诺执行行或JS拒绝执行而失败的时候,返回一个布尔值,它标识了相应的 `callback`. + +### `webContents.print([options])` + +* `options` Object (可选) + * `silent` Boolean - 不需要请求用户的打印设置. 默认为 `false`. + * `printBackground` Boolean - 打印背景和网页图片. 默认为 `false`. + +打印窗口的网页. 当设置 `silent` 为 `false` 的时候,Electron 将使用系统默认的打印机和打印方式来打印. + +在网页中调用 `window.print()` 和 调用 `webContents.print({silent: false, printBackground: false})`具有相同的作用. + +**注意:** 在 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`. +* `callback` Function + +打印窗口的网页为 pdf ,使用 Chromium 预览打印的自定义设置. + +完成时使用 `callback(error, data)` 调用 `callback` . `data` 是一个 `Buffer` ,包含了生成的 pdf 数据. + +默认,空的 `options` 被视为 : + +```javascript +{ + marginsType: 0, + printBackground: false, + printSelectionOnly: false, + landscape: false +} +``` + +```javascript +const BrowserWindow = require('electron').BrowserWindow; +const fs = require('fs'); + +var win = new BrowserWindow({width: 800, height: 600}); +win.loadURL("http://github.com"); + +win.webContents.on("did-finish-load", function() { + // Use default printing options + win.webContents.printToPDF({}, function(error, data) { + if (error) throw error; + fs.writeFile("/tmp/print.pdf", data, function(error) { + if (error) + throw error; + console.log("Write PDF successfully."); + }) + }) +}); +``` + +### `webContents.addWorkSpace(path)` + +* `path` String + +添加指定的路径给开发者工具栏的 workspace.必须在 DevTools 创建之后使用它 : + +```javascript +mainWindow.webContents.on('devtools-opened', function() { + mainWindow.webContents.addWorkSpace(__dirname); +}); +``` + +### `webContents.removeWorkSpace(path)` + +* `path` String + +从开发者工具栏的 workspace 删除指定的路径. + +### `webContents.openDevTools([options])` + +* `options` Object (可选) + * `detach` Boolean - 在一个新窗口打开开发者工具栏 + +打开开发者工具栏. + +### `webContents.closeDevTools()` + +关闭开发者工具栏. + +### `webContents.isDevToolsOpened()` + +返回布尔值,开发者工具栏是否打开. + +### `webContents.isDevToolsFocused()` + +返回布尔值,开发者工具栏视图是否获得焦点. + +### `webContents.toggleDevTools()` + +Toggles 开发者工具. + +### `webContents.inspectElement(x, y)` + +* `x` Integer +* `y` Integer + +在 (`x`, `y`) 开始检测元素. + +### `webContents.inspectServiceWorker()` + +为 service worker 上下文打开开发者工具栏. + +### `webContents.send(channel[, arg1][, arg2][, ...])` + +* `channel` String +* `arg` (可选) + +通过 `channel` 发送异步消息给渲染进程,你也可发送任意的参数.参数应该在 JSON 内部序列化,并且此后没有函数或原形链被包括了. + +渲染进程可以通过使用 `ipcRenderer` 监听 `channel` 来处理消息. + +例子,从主进程向渲染进程发送消息 : + +```javascript +// 主进程. +var window = null; +app.on('ready', function() { + window = new BrowserWindow({width: 800, height: 600}); + window.loadURL('file://' + __dirname + '/index.html'); + window.webContents.on('did-finish-load', function() { + window.webContents.send('ping', 'whoooooooh!'); + }); +}); +``` + +```html + + + + + + +``` + +### `webContents.enableDeviceEmulation(parameters)` + +`parameters` Object, properties: + +* `screenPosition` String - 指定需要模拟的屏幕 + (默认 : `desktop`) + * `desktop` + * `mobile` +* `screenSize` Object - 设置模拟屏幕 size (screenPosition == mobile) + * `width` Integer - 设置模拟屏幕 width + * `height` Integer - 设置模拟屏幕 height +* `viewPosition` Object - 在屏幕放置 view + (screenPosition == mobile) (默认: `{x: 0, y: 0}`) + * `x` Integer - 设置偏移左上角的x轴 + * `y` Integer - 设置偏移左上角的y轴 +* `deviceScaleFactor` Integer - 设置设备比例因子 (如果为0,默认为原始屏幕比例) (默认: `0`) +* `viewSize` Object - 设置模拟视图 size (空表示不覆盖) + * `width` Integer - 设置模拟视图 width + * `height` Integer - 设置模拟视图 height +* `fitToView` Boolean - 如果有必要的话,是否把模拟视图按比例缩放来适应可用空间 (默认: `false`) +* `offset` Object - 可用空间内的模拟视图偏移 (不在适应模式) (默认: `{x: 0, y: 0}`) + * `x` Float - 设置相对左上角的x轴偏移值 + * `y` Float - 设置相对左上角的y轴偏移值 +* `scale` Float - 可用空间内的模拟视图偏移 (不在适应视图模式) (默认: `1`) + +使用给定的参数来开启设备模拟. + +### `webContents.disableDeviceEmulation()` + +使用 `webContents.enableDeviceEmulation` 关闭设备模拟. + +### `webContents.sendInputEvent(event)` + +* `event` Object + * `type` String (**必需**) - 事件类型,可以是 `mouseDown`, + `mouseUp`, `mouseEnter`, `mouseLeave`, `contextMenu`, `mouseWheel`, + `mouseMove`, `keyDown`, `keyUp`, `char`. + * `modifiers` Array - 事件的 modifiers 数组, 可以是 + include `shift`, `control`, `alt`, `meta`, `isKeypad`, `isAutoRepeat`, + `leftButtonDown`, `middleButtonDown`, `rightButtonDown`, `capsLock`, + `numLock`, `left`, `right`. + +向 page 发送一个输入 `event` . + +对键盘事件来说,`event` 对象还有如下属性 : + +* `keyCode` String (**必需**) - 特点是将作为键盘事件发送. 可用的 key codes [Accelerator](accelerator.md). + + +对鼠标事件来说,`event` 对象还有如下属性 : + +* `x` Integer (**required**) +* `y` Integer (**required**) +* `button` String - button 按下, 可以是 `left`, `middle`, `right` +* `globalX` Integer +* `globalY` Integer +* `movementX` Integer +* `movementY` Integer +* `clickCount` Integer + +对鼠标滚轮事件来说,`event` 对象还有如下属性 : + +* `deltaX` Integer +* `deltaY` Integer +* `wheelTicksX` Integer +* `wheelTicksY` Integer +* `accelerationRatioX` Integer +* `accelerationRatioY` Integer +* `hasPreciseScrollingDeltas` Boolean +* `canScroll` Boolean + +### `webContents.beginFrameSubscription(callback)` + +* `callback` Function + +开始订阅 提交 事件和捕获数据帧,当有 提交 事件时,使用 `callback(frameBuffer)` 调用 `callback`. + +`frameBuffer` 是一个包含原始像素数据的 `Buffer`,像素数据是按照 32bit BGRA 格式有效存储的,但是实际情况是取决于处理器的字节顺序的(大多数的处理器是存放小端序的,如果是在大端序的处理器上,数据是 32bit ARGB 格式). + +### `webContents.endFrameSubscription()` + +停止订阅帧提交事件. + +### `webContents.savePage(fullPath, saveType, callback)` + +* `fullPath` String - 文件的完整路径. +* `saveType` String - 指定保存类型. + * `HTMLOnly` - 只保存html. + * `HTMLComplete` - 保存整个 page 内容. + * `MHTML` - 保存完整的 html 为 MHTML. +* `callback` Function - `function(error) {}`. + * `error` Error + +如果保存界面过程初始化成功,返回 true. + +```javascript +win.loadURL('https://github.com'); + +win.webContents.on('did-finish-load', function() { + win.webContents.savePage('/tmp/test.html', 'HTMLComplete', function(error) { + if (!error) + console.log("Save page successfully"); + }); +}); +``` + +## 实例属性 + +`WebContents` 对象也有下列属性: + +### `webContents.session` + +返回这个 `webContents` 使用的 [session](session.md) 对象. + +### `webContents.hostWebContents` + +返回这个 `webContents` 的父 `webContents` . + +### `webContents.devToolsWebContents` + +获取这个 `WebContents` 的开发者工具栏的 `WebContents` . + +**注意:** 用户不可保存这个对象,因为当开发者工具栏关闭的时候它的值为 `null` . + +### `webContents.debugger` + +调试 API 为 [remote debugging protocol][rdp] 提供交替传送. + +```javascript +try { + win.webContents.debugger.attach("1.1"); +} catch(err) { + console.log("Debugger attach failed : ", err); +}; + +win.webContents.debugger.on('detach', function(event, reason) { + console.log("Debugger detached due to : ", reason); +}); + +win.webContents.debugger.on('message', function(event, method, params) { + if (method == "Network.requestWillBeSent") { + if (params.request.url == "https://www.github.com") + win.webContents.debugger.detach(); + } +}) + +win.webContents.debugger.sendCommand("Network.enable"); +``` + +#### `webContents.debugger.attach([protocolVersion])` + +* `protocolVersion` String (可选) - 请求调试协议版本. + +添加 `webContents` 调试. + +#### `webContents.debugger.isAttached()` + +返回一个布尔值,标识是否已经给 `webContents` 添加了调试. + +#### `webContents.debugger.detach()` + +删除 `webContents` 调试. + +#### `webContents.debugger.sendCommand(method[, commandParams, callback])` + +* `method` String - 方法名, 应该是由远程调试协议定义的方法. +* `commandParams` Object (可选) - 请求参数为 JSON 对象. +* `callback` Function (可选) - Response + * `error` Object - 错误消息,标识命令失败. + * `result` Object - 回复在远程调试协议中由 'returns'属性定义的命令描述. + +发送给定命令给调试目标. + +#### Event: 'detach' + +* `event` Event +* `reason` String - 拆分调试器原因. + +在调试 session 结束时发出事件.这在 `webContents` 关闭时或 `webContents` 请求开发者工具栏时发生. + +#### Event: 'message' + +* `event` Event +* `method` String - 方法名. +* `params` Object - 在远程调试协议中由 'parameters' 属性定义的事件参数. + +每当调试目标发出事件时发出. + +[rdp]: https://developer.chrome.com/devtools/docs/debugger-protocol \ No newline at end of file diff --git a/docs-translations/zh-CN/api/web-frame.md b/docs-translations/zh-CN/api/web-frame.md new file mode 100644 index 000000000000..d278e9427131 --- /dev/null +++ b/docs-translations/zh-CN/api/web-frame.md @@ -0,0 +1,101 @@ +# webFrame + +`web-frame` 模块允许你自定义如何渲染当前网页 . + +例子,放大当前页到 200%. + +```javascript +var webFrame = require('electron').webFrame; + +webFrame.setZoomFactor(2); +``` + +## 方法 + +`web-frame` 模块有如下方法: + +### `webFrame.setZoomFactor(factor)` + +* `factor` Number - 缩放参数. + +将缩放参数修改为指定的参数值.缩放参数是百分制的,所以 300% = 3.0. + +### `webFrame.getZoomFactor()` + +返回当前缩放参数值. + +### `webFrame.setZoomLevel(level)` + +* `level` Number - 缩放水平 + +将缩放水平修改为指定的水平值. 原始 size 为 0 ,并且每次增长都表示放大 20% 或缩小 20%,默认限制为原始 size 的 300% 到 50% 之间 . + +### `webFrame.getZoomLevel()` + +返回当前缩放水平值. + +### `webFrame.setZoomLevelLimits(minimumLevel, maximumLevel)` + +* `minimumLevel` Number +* `maximumLevel` Number + +设置缩放水平的最大值和最小值. + +### `webFrame.setSpellCheckProvider(language, autoCorrectWord, provider)` + +* `language` String +* `autoCorrectWord` Boolean +* `provider` Object + +为输入框或文本域设置一个拼写检查 provider . + +`provider` 必须是一个对象,它有一个 `spellCheck` 方法,这个方法返回扫过的单词是否拼写正确 . + +例子,使用 [node-spellchecker][spellchecker] 作为一个 provider: + +```javascript +webFrame.setSpellCheckProvider("en-US", true, { + spellCheck: function(text) { + return !(require('spellchecker').isMisspelled(text)); + } +}); +``` + +### `webFrame.registerURLSchemeAsSecure(scheme)` + +* `scheme` String + +注册 `scheme` 为一个安全的 scheme. + + +安全的 schemes 不会引发混合内容 warnings.例如, `https` 和 +`data` 是安全的 schemes ,因为它们不能被活跃网络攻击而失效. + +### `webFrame.registerURLSchemeAsBypassingCSP(scheme)` + +* `scheme` String + +忽略当前网页内容的安全策略,直接从 `scheme` 加载. + +### `webFrame.registerURLSchemeAsPrivileged(scheme)` + +* `scheme` String + +通过资源的内容安全策略,注册 `scheme` 为安全的 scheme,允许注册 ServiceWorker并且支持 fetch API. + +### `webFrame.insertText(text)` + +* `text` String + +向获得焦点的原色插入内容 . + +### `webFrame.executeJavaScript(code[, userGesture])` + +* `code` String +* `userGesture` Boolean (可选) - 默认为 `false`. + +评估页面代码 . + +在浏览器窗口中,一些 HTML APIs ,例如 `requestFullScreen`,只可以通过用户手势来使用.设置`userGesture` 为 `true` 可以突破这个限制 . + +[spellchecker]: https://github.com/atom/node-spellchecker \ No newline at end of file