# 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` 或一個外部連接如 `<a target='_blank'>` 發出的請求. 默認指定 `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 - 標識是否還有更多的值可以查看. * `activeMatchOrdinal` Integer (可選) - 活動匹配位置 * `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 <meta name='theme-color' content='#ff0000'> ``` ### 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 <!-- index.html --> <html> <body> <script> require('electron').ipcRenderer.on('ping', function(event, message) { console.log(message); // Prints "whoooooooh!" }); </script> </body> </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