From fe248ac03f796fbc84be3abbef14de3b3b3de931 Mon Sep 17 00:00:00 2001 From: heyunjiang <598119677@qq.com> Date: Fri, 11 Mar 2016 16:05:02 +0800 Subject: [PATCH 1/5] add ipc-main first --- docs-translations/zh-CN/api/ipc-main.md | 85 +++++++++++++++++++++++++ 1 file changed, 85 insertions(+) create mode 100644 docs-translations/zh-CN/api/ipc-main.md diff --git a/docs-translations/zh-CN/api/ipc-main.md b/docs-translations/zh-CN/api/ipc-main.md new file mode 100644 index 000000000000..aef9c454a067 --- /dev/null +++ b/docs-translations/zh-CN/api/ipc-main.md @@ -0,0 +1,85 @@ +# ipcMain + +`ipcMain` 模块是类 +[EventEmitter](https://nodejs.org/api/events.html) 的实例.当在主进程中使用它的时候，它控制着由渲染进程(web page)发送过来的异步或同步消息.从渲染进程发送过来的消息将触发事件. + +## 发送消息 + +同样也可以从主进程向渲染进程发送消息，查看更多 [webContents.send][web-contents-send] . + +* 发送消息，事件名为 `channel`. +* 回应同步消息, 你可以设置 `event.returnValue`. +* 回应异步消息, 你可以使用 + `event.sender.send(...)`. + +一个例子，在主进程和渲染进程之间发送和处理消息: + +```javascript +// In main process. +const ipcMain = require('electron').ipcMain; +ipcMain.on('asynchronous-message', function(event, arg) { + console.log(arg); // prints "ping" + event.sender.send('asynchronous-reply', 'pong'); +}); + +ipcMain.on('synchronous-message', function(event, arg) { + console.log(arg); // prints "ping" + event.returnValue = 'pong'; +}); +``` + +```javascript +// In renderer process (web page). +const ipcRenderer = require('electron').ipcRenderer; +console.log(ipcRenderer.sendSync('synchronous-message', 'ping')); // prints "pong" + +ipcRenderer.on('asynchronous-reply', function(event, arg) { + console.log(arg); // prints "pong" +}); +ipcRenderer.send('asynchronous-message', 'ping'); +``` + +## 监听消息 + +`ipcMain` 模块有如下监听事件方法: + +### `ipcMain.on(channel, listener)` + +* `channel` String +* `listener` Function + +监听 `channel`, 当新消息到达，将通过 `listener(event, args...)` 调用 `listener`. + +### `ipcMain.once(channel, listener)` + +* `channel` String +* `listener` Function + +为事件添加一个一次性用的`listener` 函数.这个 `listener` 只有在下次的消息到达 `channel` 时被请求调用，之后就被删除了. + +### `ipcMain.removeListener(channel, listener)` + +* `channel` String +* `listener` Function + +为特定的 `channel` 从监听队列中删除特定的 `listener` 监听者. + +### `ipcMain.removeAllListeners([channel])` + +* `channel` String (可选) + +删除所有监听者，或特指的 `channel` 的所有监听者. + +## 事件对象 + +传递给 `callback` 的 `event` 对象有如下方法: + +### `event.returnValue` + +将此设置为在一个同步消息中返回的值. + +### `event.sender` + +返回发送消息的 `webContents` ，你可以调用 `event.sender.send` 来回复异步消息，更多信息 [webContents.send][web-contents-send]. + +[web-contents-send]: web-contents.md#webcontentssendchannel-arg1-arg2- \ No newline at end of file From 3e04884a578bbc62a1c25b4ebdfbcd76552d7f08 Mon Sep 17 00:00:00 2001 From: heyunjiang <598119677@qq.com> Date: Fri, 11 Mar 2016 17:25:38 +0800 Subject: [PATCH 2/5] add menu.md first --- docs-translations/zh-CN/api/menu.md | 351 ++++++++++++++++++++++++++++ 1 file changed, 351 insertions(+) create mode 100644 docs-translations/zh-CN/api/menu.md diff --git a/docs-translations/zh-CN/api/menu.md b/docs-translations/zh-CN/api/menu.md new file mode 100644 index 000000000000..3a4e7e5c24e9 --- /dev/null +++ b/docs-translations/zh-CN/api/menu.md @@ -0,0 +1,351 @@ +# 菜单 + +`menu` 类可以用来创建原生菜单，它可用作应用菜单和 +[context 菜单](https://developer.mozilla.org/en-US/docs/Mozilla/Tech/XUL/PopupGuide/ContextMenus). + +这个模块是一个主进程的模块，并且可以通过 `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() { + if (process.platform == 'darwin') + return 'Ctrl+Command+F'; + else + return '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 + +### `new Menu()` + +创建一个新的菜单. + +## 方法 + +`菜单` 类有如下方法: + +### `Menu.setApplicationMenu(menu)` + +* `menu` Menu + +在 OS X 上设置应用菜单 `menu` . +在windows 和 linux，是为每个窗口都在其顶部设置菜单 `menu`. + +### `Menu.sendActionToFirstResponder(action)` _OS X_ + +* `action` String + +发送 `action` 给应用的第一个响应器.这个用来模仿 Cocoa 菜单的默认行为，通常你只需要使用 `MenuItem` 的属性 `role`. + +查看更多 OS X 的原生 action [OS X 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)` + +* `template` Array + +一般来说，`template` 只是用来创建 [MenuItem](menu-item.md) 的数组 `参数` . + +你也可以向 `template` 元素添加其它东西，并且他们会变成已经有的菜单项的属性. + +### `Menu.popup([browserWindow, x, y, positioningItem])` + +* `browserWindow` BrowserWindow (可选) - 默认为 `null`. +* `x` Number (可选) - 默认为 -1. +* `y` Number (**必须** 如果x设置了) - 默认为 -1. +* `positioningItem` Number (可选) _OS X_ - 在指定坐标鼠标位置下面的菜单项的索引. 默认为 + -1. + +在 `browserWindow` 中弹出 context menu .你可以选择性地提供指定的 `x, y` 来设置菜单应该放在哪里,否则它将默认地放在当前鼠标的位置. + +### `Menu.append(menuItem)` + +* `menuItem` MenuItem + +添加菜单项. + +### `Menu.insert(pos, menuItem)` + +* `pos` Integer +* `menuItem` MenuItem + +在制定位置添加菜单项. + +### `Menu.items()` + +获取一个菜单项数组. + +## OS X Application 上的菜单的注意事项 + +相对于windows 和 linux, OS X 上的应用菜单是完全不同的style，这里是一些注意事项，来让你的菜单项更原生化. + +### 标准菜单 + +在 OS X 上，有很多系统定义的标准菜单，例如 `Services` and +`Windows` 菜单.为了让你的应用更标准化，你可以为你的菜单的 `role` 设置值，然后 electron 将会识别他们并且让你的菜单更标准: + +* `window` +* `help` +* `services` + +### 标准菜单项行为 + +OS X 为一些菜单项提供了标准的行为方法，例如 `About xxx`, +`Hide xxx`, and `Hide Others`. 为了让你的菜单项的行为更标准化，你应该为菜单项设置 `role` 属性. + +### 主菜单名 + +在 OS X ，无论你设置的什么标签，应用菜单的第一个菜单项的标签始终未你的应用名字.想要改变它的话，你必须通过修改应用绑定的 `Info.plist` 文件来修改应用名字.更多信息参考[About Information +Property List Files][AboutInformationPropertyListFiles] . + +## 为制定浏览器窗口设置菜单 (*Linux* *Windows*) + +浏览器窗口的[`setMenu` 方法][setMenu] 能够设置菜单为特定浏览器窗口的类型. + +## 菜单项位置 + +当通过 `Menu.buildFromTemplate` 创建菜单的时候，你可以使用 `position` and `id` 来放置菜单项. + +`MenuItem` 的属性 `position` 格式为 `[placement]=[id]`，`placement` 取值为 `before`, `after`, 或 `endof` 和 `id`， `id` 是菜单已经存在的菜单项的唯一 ID: + +* `before` - 在对应引用id菜单项之前插入. 如果引用的菜单项不存在，则将其插在菜单末尾. +* `after` - 在对应引用id菜单项之后插入. 如果引用的菜单项不存在，则将其插在菜单末尾. +* `endof` - 在逻辑上包含对应引用id菜单项的集合末尾插入. 如果引用的菜单项不存在, 则将使用给定的id创建一个新的集合，并且这个菜单项将插入. + +当一个菜档项插入成功了，所有的没有插入的菜单项将一个接一个地在后面插入.所以如果你想在同一个位置插入一组菜单项，只需要为这组菜单项的第一个指定位置. + +### 例子 + +模板: + +```javascript +[ + {label: '4', id: '4'}, + {label: '5', id: '5'}, + {label: '1', id: '1', position: 'before=4'}, + {label: '2', id: '2'}, + {label: '3', id: '3'} +] +``` + +菜单: + +``` +- 1 +- 2 +- 3 +- 4 +- 5 +``` + +模板: + +```javascript +[ + {label: 'a', position: 'endof=letters'}, + {label: '1', position: 'endof=numbers'}, + {label: 'b', position: 'endof=letters'}, + {label: '2', position: 'endof=numbers'}, + {label: 'c', position: 'endof=letters'}, + {label: '3', position: 'endof=numbers'} +] +``` + +菜单: + +``` +- --- +- a +- b +- c +- --- +- 1 +- 2 +- 3 +``` + +[AboutInformationPropertyListFiles]: https://developer.apple.com/library/ios/documentation/general/Reference/InfoPlistKeyReference/Articles/AboutInformationPropertyListFiles.html +[setMenu]: +https://github.com/atom/electron/blob/master/docs/api/browser-window.md#winsetmenumenu-linux-windows \ No newline at end of file From 29609b6e5d272bb71fbb9b4eccfe50cb08f3e9fb Mon Sep 17 00:00:00 2001 From: heyunjiang <598119677@qq.com> Date: Sun, 13 Mar 2016 14:15:11 +0800 Subject: [PATCH 3/5] add powerMonitor first --- docs-translations/zh-CN/api/power-monitor.md | 36 ++++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 docs-translations/zh-CN/api/power-monitor.md diff --git a/docs-translations/zh-CN/api/power-monitor.md b/docs-translations/zh-CN/api/power-monitor.md new file mode 100644 index 000000000000..3394b4a284e2 --- /dev/null +++ b/docs-translations/zh-CN/api/power-monitor.md @@ -0,0 +1,36 @@ +# powerMonitor + +`power-monitor`模块是用来监听能源区改变的.只能在主进程中使用.在 `app` 模块的 `ready` 事件触发之后就不能使用这个模块了. + +例如: + +```javascript +app.on('ready', function() { + require('electron').powerMonitor.on('suspend', function() { + console.log('The system is going to sleep'); + }); +}); +``` + +## 事件 + +`power-monitor` 模块可以触发下列事件: + +### 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 d96836e608ac33b501cb1d139313d97727d35197 Mon Sep 17 00:00:00 2001 From: heyunjiang <598119677@qq.com> Date: Sun, 13 Mar 2016 22:06:19 +0800 Subject: [PATCH 4/5] add power-save-blocker first --- .../zh-CN/api/power-save-blocker.md | 48 +++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 docs-translations/zh-CN/api/power-save-blocker.md diff --git a/docs-translations/zh-CN/api/power-save-blocker.md b/docs-translations/zh-CN/api/power-save-blocker.md new file mode 100644 index 000000000000..3a045eaea779 --- /dev/null +++ b/docs-translations/zh-CN/api/power-save-blocker.md @@ -0,0 +1,48 @@ +# powerSaveBlocker + +`powerSaveBlocker` 模块是用来阻止应用系统进入睡眠模式的，因此这允许应用保持系统和屏幕继续工作. + +例如: + +```javascript +const powerSaveBlocker = require('electron').powerSaveBlocker; + +var id = powerSaveBlocker.start('prevent-display-sleep'); +console.log(powerSaveBlocker.isStarted(id)); + +powerSaveBlocker.stop(id); +``` + +## 方法 + +`powerSaveBlocker` 模块有如下方法: + +### `powerSaveBlocker.start(type)` + +* `type` String - 强行保存阻塞类型. + * `prevent-app-suspension` - 阻止应用挂起. + 保持系统活跃，但是允许屏幕不亮. 用例: + 下载文件或者播放音频. + * `prevent-display-sleep`- 阻止应用进入休眠. 保持系统和屏幕活跃，屏幕一直亮. 用例: 播放音频. + +开始阻止系统进入睡眠模式.返回一个整数，这个整数标识了保持活跃的blocker. + +**注意:** `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. + +让指定blocker 停止活跃. + +### `powerSaveBlocker.isStarted(id)` + +* `id` Integer - 通过 `powerSaveBlocker.start` 返回的保持活跃的 blocker id. + +返回 boolean， 是否对应的 `powerSaveBlocker` 已经启动. \ No newline at end of file From 06a8db8a66c4ccb07bf1c329d4ee6f71ba56a1f5 Mon Sep 17 00:00:00 2001 From: heyunjiang <598119677@qq.com> Date: Mon, 14 Mar 2016 15:43:04 +0800 Subject: [PATCH 5/5] add protocol && session first --- docs-translations/zh-CN/api/protocol.md | 183 +++++++++ docs-translations/zh-CN/api/session.md | 481 ++++++++++++++++++++++++ 2 files changed, 664 insertions(+) create mode 100644 docs-translations/zh-CN/api/protocol.md create mode 100644 docs-translations/zh-CN/api/session.md diff --git a/docs-translations/zh-CN/api/protocol.md b/docs-translations/zh-CN/api/protocol.md new file mode 100644 index 000000000000..a7dab97c5d56 --- /dev/null +++ b/docs-translations/zh-CN/api/protocol.md @@ -0,0 +1,183 @@ +# 协议 + +`protocol` 模块可以注册一个自定义协议，或者使用一个已经存在的协议. + +例子，使用一个与 `file://` 功能相似的协议 : + +```javascript +const electron = require('electron'); +const app = electron.app; +const path = require('path'); + +app.on('ready', function() { + var protocol = electron.protocol; + protocol.registerFileProtocol('atom', function(request, callback) { + var url = request.url.substr(7); + callback({path: path.normalize(__dirname + '/' + url)}); + }, function (error) { + if (error) + console.error('Failed to register protocol') + }); +}); +``` + +**注意:** 这个模块只有在 `app` 模块的 `ready` 事件触发之后才可使用. + +## 方法 + +`protocol` 模块有如下方法: + +### `protocol.registerStandardSchemes(schemes)` + +* `schemes` Array - 将一个自定义的方案注册为标准的方案. + +一个标准的 `scheme` 遵循 RFC 3986 的 +[generic URI syntax](https://tools.ietf.org/html/rfc3986#section-3) 标准. 这包含了 `file:` 和 `filesystem:`. + +### `protocol.registerServiceWorkerSchemes(schemes)` + +* `schemes` Array - 将一个自定义的方案注册为处理 service workers. + +### `protocol.registerFileProtocol(scheme, handler[, completion])` + +* `scheme` String +* `handler` Function +* `completion` Function (可选) + +注册一个协议，用来发送响应文件.当通过这个协议来发起一个请求的时候，将使用 `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 - 上传的文件路径. + +为了处理请求，调用 `callback` 时需要使用文件路径或者一个带 `path` 参数的对象, 例如 `callback(filePath)` 或 +`callback({path: filePath})`. + +当不使用任何参数调用 `callback` 时，你可以指定一个数字或一个带有 `error` 参数的对象，来标识 `request` 失败.你可以使用的 error number 可以参考 +[net error list][net-error]. + +默认 `scheme` 会被注册为一个 `http:` 协议，它与遵循 "generic URI syntax" 规则的协议解析不同，例如 `file:` ，所以你或许应该调用 `protocol.registerStandardSchemes` 来创建一个标准的 scheme. + +### `protocol.registerBufferProtocol(scheme, handler[, completion])` + +* `scheme` String +* `handler` Function +* `completion` Function (可选) + +注册一个 `scheme` 协议，用来发送响应 `Buffer` . + +这个方法的用法类似 `registerFileProtocol`，除非使用一个 `Buffer` 对象，或一个有 `data`, +`mimeType`, 和 `charset` 属性的对象来调用 `callback` . + +例子: + +```javascript +protocol.registerBufferProtocol('atom', function(request, callback) { + callback({mimeType: 'text/html', data: new Buffer('
Response
')}); +}, function (error) { + if (error) + console.error('Failed to register protocol') +}); +``` + +### `protocol.registerStringProtocol(scheme, handler[, completion])` + +* `scheme` String +* `handler` Function +* `completion` Function (可选) + +注册一个 `scheme` 协议，用来发送响应 `String` . + +这个方法的用法类似 `registerFileProtocol`，除非使用一个 `String` 对象，或一个有 `data`, +`mimeType`, 和 `charset` 属性的对象来调用 `callback` . + +### `protocol.registerHttpProtocol(scheme, handler[, completion])` + +* `scheme` String +* `handler` Function +* `completion` Function (可选) + +注册一个 `scheme` 协议，用来发送 HTTP 请求作为响应. + +这个方法的用法类似 `registerFileProtocol`，除非使用一个 `redirectRequest` 对象，或一个有 `url`, `method`, +`referrer`, `uploadData` 和 `session` 属性的对象来调用 `callback` . + +* `redirectRequest` Object + * `url` String + * `method` String + * `session` Object (可选) + * `uploadData` Object (可选) + +默认这个 HTTP 请求会使用当前 session .如果你想使用不同的session值，你应该设置 `session` 为 `null`. + +POST 请求应当包含 `uploadData` 对象. + +* `uploadData` object + * `contentType` String - 内容的 MIME type. + * `data` String - 被发送的内容. + +### `protocol.unregisterProtocol(scheme[, completion])` + +* `scheme` String +* `completion` Function (可选) + +注销自定义协议 `scheme`. + +### `protocol.isProtocolHandled(scheme, callback)` + +* `scheme` String +* `callback` Function + +将使用一个布尔值来调用 `callback` ，这个布尔值标识了是否已经存在 `scheme` 的句柄了. + +### `protocol.interceptFileProtocol(scheme, handler[, completion])` + +* `scheme` String +* `handler` Function +* `completion` Function (可选) + +拦截 `scheme` 协议并且使用 `handler` 作为协议的新的句柄来发送响应文件. + +### `protocol.interceptStringProtocol(scheme, handler[, completion])` + +* `scheme` String +* `handler` Function +* `completion` Function (可选) + +拦截 `scheme` 协议并且使用 `handler` 作为协议的新的句柄来发送响应 `String`. + +### `protocol.interceptBufferProtocol(scheme, handler[, completion])` + +* `scheme` String +* `handler` Function +* `completion` Function (可选) + +拦截 `scheme` 协议并且使用 `handler` 作为协议的新的句柄来发送响应 `Buffer`. + +### `protocol.interceptHttpProtocol(scheme, handler[, completion])` + +* `scheme` String +* `handler` Function +* `completion` Function (optional) + +拦截 `scheme` 协议并且使用 `handler` 作为协议的新的句柄来发送新的响应 HTTP 请求. +Intercepts `scheme` protocol and uses `handler` as the protocol's new handler +which sends a new HTTP request as a response. + +### `protocol.uninterceptProtocol(scheme[, completion])` + +* `scheme` String +* `completion` Function +取消对 `scheme` 的拦截，使用它的原始句柄进行处理. + +[net-error]: https://code.google.com/p/chromium/codesearch#chromium/src/net/base/net_error_list.h \ No newline at end of file diff --git a/docs-translations/zh-CN/api/session.md b/docs-translations/zh-CN/api/session.md new file mode 100644 index 000000000000..b9664c08e652 --- /dev/null +++ b/docs-translations/zh-CN/api/session.md @@ -0,0 +1,481 @@ +# session + +`session` 模块可以用来创建一个新的 `Session` 对象. + +你也可以通过使用 [`webContents`](web-contents.md) 的属性 `session` 来使用一个已有页面的 `session` ，`webContents` 是[`BrowserWindow`](browser-window.md) 的属性. + +```javascript +const BrowserWindow = require('electron').BrowserWindow; + +var win = new BrowserWindow({ width: 800, height: 600 }); +win.loadURL("http://github.com"); + +var ses = win.webContents.session; +``` + +## 方法 + +`session` 模块有如下方法: + +### session.fromPartition(partition) + +* `partition` String + +从字符串 `partition` 返回一个新的 `Session` 实例. + +如果 `partition` 以 `persist:` 开头，那么这个page将使用一个持久的 session，这个 session 将对应用的所有 page 可用.如果没前缀，这个 page 将使用一个历史 session.如果 `partition` 为空，那么将返回应用的默认 session . + +## 属性 + +`session` 模块有如下属性: + +### session.defaultSession + +返回应用的默认 session 对象. + +## Class: Session + +可以在 `session` 模块中创建一个 `Session` 对象 : + +```javascript +const session = require('electron').session; + +var ses = session.fromPartition('persist:name'); +``` + +### 实例事件 + +实例 `Session` 有以下事件: + +#### Event: 'will-download' + +* `event` Event +* `item` [DownloadItem](download-item.md) +* `webContents` [WebContents](web-contents.md) + +当 Electron 将要从 `webContents` 下载 `item` 时触发. + +调用 `event.preventDefault()` 可以取消下载，并且在进程的下个 tick中，这个 `item` 也不可用. + +```javascript +session.defaultSession.on('will-download', function(event, item, webContents) { + event.preventDefault(); + require('request')(item.getURL(), function(data) { + require('fs').writeFileSync('/somewhere', data); + }); +}); +``` + +### 实例方法 + +实例 `Session` 有以下方法: + +#### `ses.cookies` + +`cookies` 赋予你全力来查询和修改 cookies. 例如: + +```javascript +// 查询所有 cookies. +session.defaultSession.cookies.get({}, function(error, cookies) { + console.log(cookies); +}); + +// 查询与指定 url 相关的所有 cookies. +session.defaultSession.cookies.get({ url : "http://www.github.com" }, function(error, cookies) { + console.log(cookies); +}); + +// 设置 cookie; +// may overwrite equivalent cookies if they exist. +var cookie = { url : "http://www.github.com", name : "dummy_name", value : "dummy" }; +session.defaultSession.cookies.set(cookie, function(error) { + if (error) + console.error(error); +}); +``` + +#### `ses.cookies.get(filter, callback)` + +* `filter` Object + * `url` String (可选) - 与获取 cookies 相关的 + `url`.不设置的话就是从所有 url 获取 cookies . + * `name` String (可选) - 通过 name 过滤 cookies. + * `domain` String (可选) - 获取对应域名或子域名的 cookies . + * `path` String (可选) - 获取对应路径的 cookies . + * `secure` Boolean (可选) - 通过安全性过滤 cookies. + * `session` Boolean (可选) - 过滤掉 session 或 持久的 cookies. +* `callback` Function + +发送一个请求，希望获得所有匹配 `details` 的 cookies, +在完成的时候，将通过 `callback(error, cookies)` 调用 `callback`. + +`cookies`是一个 `cookie` 对象. + +* `cookie` Object + * `name` String - cookie 名. + * `value` String - cookie值. + * `domain` String - cookie域名. + * `hostOnly` String - 是否 cookie 是一个 host-only cookie. + * `path` String - cookie路径. + * `secure` Boolean - 是否是安全 cookie. + * `httpOnly` Boolean - 是否只是 HTTP cookie. + * `session` Boolean - cookie 是否是一个 session cookie 或一个带截至日期的持久 + cookie . + * `expirationDate` Double (可选) - cookie的截至日期，数值为UNIX纪元以来的秒数. 对session cookies 不提供. + +#### `ses.cookies.set(details, callback)` + +* `details` Object + * `url` String - 与获取 cookies 相关的 + `url`. + * `name` String - cookie 名. 忽略默认为空. + * `value` String - cookie 值. 忽略默认为空. + * `domain` String - cookie的域名. 忽略默认为空. + * `path` String - cookie 的路径. 忽略默认为空. + * `secure` Boolean - 是否已经进行了安全性标识. 默认为 + false. + * `session` Boolean - 是否已经 HttpOnly 标识. 默认为 false. + * `expirationDate` Double - cookie的截至日期，数值为UNIX纪元以来的秒数. 如果忽略, cookie 变为 session cookie. +* `callback` Function + +使用 `details` 设置 cookie, 完成时使用 `callback(error)` 掉哟个 `callback` . + +#### `ses.cookies.remove(url, name, callback)` + +* `url` String - 与 cookies 相关的 + `url`. +* `name` String - 需要删除的 cookie 名. +* `callback` Function + +删除匹配 `url` 和 `name` 的 cookie, 完成时使用 `callback()`调用`callback`. + +#### `ses.getCacheSize(callback)` + +* `callback` Function + * `size` Integer - 单位 bytes 的缓存 size. + +返回 session 的当前缓存 size . + +#### `ses.clearCache(callback)` + +* `callback` Function - 操作完成时调用 + +清空 session 的 HTTP 缓存. + +#### `ses.clearStorageData([options, ]callback)` + +* `options` Object (可选) + * `origin` String - 应当遵循 `window.location.origin` 的格式 + `scheme://host:port`. + * `storages` Array - 需要清理的 storages 类型, 可以包含 : + `appcache`, `cookies`, `filesystem`, `indexdb`, `local storage`, + `shadercache`, `websql`, `serviceworkers` + * `quotas` Array - 需要清理的类型指标, 可以包含: + `temporary`, `persistent`, `syncable`. +* `callback` Function - 操作完成时调用. + +清除 web storages 的数据. + +#### `ses.flushStorageData()` + +将没有写入的 DOMStorage 写入磁盘. + +#### `ses.setProxy(config, callback)` + +* `config` Object + * `pacScript` String - 与 PAC 文件相关的 URL. + * `proxyRules` String - 代理使用规则. +* `callback` Function - 操作完成时调用. + +设置 proxy settings. + +当 `pacScript` 和 `proxyRules` 一同提供时，将忽略 `proxyRules`，并且使用 `pacScript` 配置 . + +`proxyRules` 需要遵循下面的规则: + +``` +proxyRules = schemeProxies[";"] +schemeProxies = ["="] +urlScheme = "http" | "https" | "ftp" | "socks" +proxyURIList = [","] +proxyURL = ["://"][":"] +``` + +例子: + +* `http=foopy:80;ftp=foopy2` - 为 `http://` URL 使用 HTTP 代理 `foopy:80` , 和为 `ftp://` URL + HTTP 代理 `foopy2:80` . +* `foopy:80` - 为所有 URL 使用 HTTP 代理 `foopy:80` . +* `foopy:80,bar,direct://` - 为所有 URL 使用 HTTP 代理 `foopy:80` , 如果 `foopy:80` 不可用，则切换使用 `bar`, 再往后就不使用代理了. +* `socks4://foopy` - 为所有 URL 使用 SOCKS v4 代理 `foopy:1080`. +* `http=foopy,socks5://bar.com` - 为所有 URL 使用 HTTP 代理 `foopy`, 如果 `foopy`不可用，则切换到 SOCKS5 代理 `bar.com`. +* `http=foopy,direct://` - 为所有http url 使用 HTTP 代理，如果 `foopy`不可用，则不使用代理. +* `http=foopy;socks=foopy2` - 为所有http url 使用 `foopy` 代理，为所有其他 url 使用 `socks4://foopy2` 代理. + +### `ses.resolveProxy(url, callback)` + +* `url` URL +* `callback` Function + +解析 `url` 的代理信息.当请求完成的时候使用 `callback(proxy)` 调用 `callback`. + +#### `ses.setDownloadPath(path)` + +* `path` String - 下载地址 + +设置下载保存地址，默认保存地址为各自 app 应用的 `Downloads`目录. + +#### `ses.enableNetworkEmulation(options)` + +* `options` Object + * `offline` Boolean - 是否模拟网络故障. + * `latency` Double - 每毫秒的 RTT + * `downloadThroughput` Double - 每 Bps 的下载速率. + * `uploadThroughput` Double - 每 Bps 的上载速率. + +通过给定配置的 `session` 来模拟网络. + +```javascript +// 模拟 GPRS 连接，使用的 50kbps 流量，500 毫秒的 rtt. +window.webContents.session.enableNetworkEmulation({ + latency: 500, + downloadThroughput: 6400, + uploadThroughput: 6400 +}); + +// 模拟网络故障. +window.webContents.session.enableNetworkEmulation({offline: true}); +``` + +#### `ses.disableNetworkEmulation()` + +停止所有已经使用 `session` 的活跃模拟网络. +重置为原始网络类型. + +#### `ses.setCertificateVerifyProc(proc)` + +* `proc` Function + +为 `session` 设置证书验证过程，当请求一个服务器的证书验证时，使用 `proc(hostname, certificate, callback)` 调用 `proc`.调用 `callback(true)` 来接收证书，调用 `callback(false)` 来拒绝验证证书. + +调用了 `setCertificateVerifyProc(null)` ，则将会回复到默认证书验证过程. + +```javascript +myWindow.webContents.session.setCertificateVerifyProc(function(hostname, cert, callback) { + if (hostname == 'github.com') + callback(true); + else + callback(false); +}); +``` + +#### `ses.setPermissionRequestHandler(handler)` + +* `handler` Function + * `webContents` Object - [WebContents](web-contents.md) 请求许可. + * `permission` String - 枚举了 'media', 'geolocation', 'notifications', 'midiSysex', 'pointerLock', 'fullscreen'. + * `callback` Function - 允许或禁止许可. + +为对应 `session` 许可请求设置响应句柄.调用 `callback(true)` 接收许可，调用 `callback(false)` 禁止许可. + +```javascript +session.fromPartition(partition).setPermissionRequestHandler(function(webContents, permission, callback) { + if (webContents.getURL() === host) { + if (permission == "notifications") { + callback(false); // denied. + return; + } + } + + callback(true); +}); +``` + +#### `ses.clearHostResolverCache([callback])` + +* `callback` Function (可选) - 操作结束调用. + +清除主机解析缓存. + +#### `ses.webRequest` + +在其生命周期的不同阶段，`webRequest` API 设置允许拦截并修改请求内容. + +每个 API 接收一可选的 `filter` 和 `listener`，当 API 事件发生的时候使用 `listener(details)` 调用 `listener`，`details` 是一个用来描述请求的对象.为 `listener` 使用 `null` 则会退定事件. + +`filter` 是一个拥有 `urls` 属性的对象，这是一个 url 模式数组，这用来过滤掉不匹配指定 url 模式的请求.如果忽略 `filter` ，那么所有请求都将可以成功匹配. + +所有事件的 `listener` 都有一个回调事件，当 `listener` 完成它的工作的时候，它将使用一个 `response` 对象来调用. + +```javascript +// 将所有请求的代理都修改为下列 url. +var filter = { + urls: ["https://*.github.com/*", "*://electron.github.io"] +}; + +session.defaultSession.webRequest.onBeforeSendHeaders(filter, function(details, callback) { + details.requestHeaders['User-Agent'] = "MyAgent"; + callback({cancel: false, requestHeaders: details.requestHeaders}); +}); +``` + +#### `ses.webRequest.onBeforeRequest([filter, ]listener)` + +* `filter` Object +* `listener` Function + +当一个请求即将开始的时候，使用 `listener(details, callback)` 调用 `listener`. + +* `details` Object + * `id` Integer + * `url` String + * `method` String + * `resourceType` String + * `timestamp` Double + * `uploadData` Array (可选) +* `callback` Function + +`uploadData` 是一个 `data` 数组对象: + +* `data` Object + * `bytes` Buffer - 被发送的内容. + * `file` String - 上载文件路径. + +`callback` 必须使用一个 `response` 对象来调用: + +* `response` Object + * `cancel` Boolean (可选) + * `redirectURL` String (可选) - 原始请求阻止发送或完成，而不是重定向. + +#### `ses.webRequest.onBeforeSendHeaders([filter, ]listener)` + +* `filter` Object +* `listener` Function + +一旦请求报文头可用了,在发送 HTTP 请求的之前，使用 `listener(details, callback)` 调用 `listener`.这也许会在服务器发起一个tcp 连接，但是在发送任何 http 数据之前发生. + +* `details` Object + * `id` Integer + * `url` String + * `method` String + * `resourceType` String + * `timestamp` Double + * `requestHeaders` Object +* `callback` Function + +必须使用一个 `response` 对象来调用 `callback` : + +* `response` Object + * `cancel` Boolean (可选) + * `requestHeaders` Object (可选) - 如果提供了,将使用这些 headers 来创建请求. + +#### `ses.webRequest.onSendHeaders([filter, ]listener)` + +* `filter` Object +* `listener` Function + +在一个请求正在发送到服务器的时候，使用 `listener(details)` 来调用 `listener` ，之前 `onBeforeSendHeaders` 修改部分响应可用，同时取消监听. + +* `details` Object + * `id` Integer + * `url` String + * `method` String + * `resourceType` String + * `timestamp` Double + * `requestHeaders` Object + +#### `ses.webRequest.onHeadersReceived([filter,] listener)` + +* `filter` Object +* `listener` Function + +当 HTTP 请求报文头已经到达的时候，使用 `listener(details, callback)` 调用 `listener` . + +* `details` Object + * `id` String + * `url` String + * `method` String + * `resourceType` String + * `timestamp` Double + * `statusLine` String + * `statusCode` Integer + * `responseHeaders` Object +* `callback` Function + +必须使用一个 `response` 对象来调用 `callback` : + +* `response` Object + * `cancel` Boolean + * `responseHeaders` Object (可选) - 如果提供, 服务器将假定使用这些头来响应. + +#### `ses.webRequest.onResponseStarted([filter, ]listener)` + +* `filter` Object +* `listener` Function + +当响应body的首字节到达的时候，使用 `listener(details)` 调用 `listener`.对 http 请求来说，这意味着状态线和响应头可用了. + +* `details` Object + * `id` Integer + * `url` String + * `method` String + * `resourceType` String + * `timestamp` Double + * `responseHeaders` Object + * `fromCache` Boolean - 标识响应是否来自磁盘 + cache. + * `statusCode` Integer + * `statusLine` String + +#### `ses.webRequest.onBeforeRedirect([filter, ]listener)` + +* `filter` Object +* `listener` Function + +当服务器的重定向初始化正要启动时，使用 `listener(details)` 调用 `listener`. + +* `details` Object + * `id` String + * `url` String + * `method` String + * `resourceType` String + * `timestamp` Double + * `redirectURL` String + * `statusCode` Integer + * `ip` String (可选) - 请求的真实服务器ip 地址 + * `fromCache` Boolean + * `responseHeaders` Object + +#### `ses.webRequest.onCompleted([filter, ]listener)` + +* `filter` Object +* `listener` Function + +当请求完成的时候，使用 `listener(details)` 调用 `listener`. + +* `details` Object + * `id` Integer + * `url` String + * `method` String + * `resourceType` String + * `timestamp` Double + * `responseHeaders` Object + * `fromCache` Boolean + * `statusCode` Integer + * `statusLine` String + +#### `ses.webRequest.onErrorOccurred([filter, ]listener)` + +* `filter` Object +* `listener` Function + +当一个错误发生的时候，使用 `listener(details)` 调用 `listener`. + +* `details` Object + * `id` Integer + * `url` String + * `method` String + * `resourceType` String + * `timestamp` Double + * `fromCache` Boolean + * `error` String - 错误描述. \ No newline at end of file