&lt;webview&gt; 標簽 · Electron 中文文檔

# `<webview>` 標簽使用 `webview` 標簽來把 'guest' 內容（例如 web pages ）嵌入到你的 Electron app 中. guest內容包含在 `webview` 容器中.一個嵌入你應用的page控制著guest內容如何布局擺放和表達含義. 與 `iframe` 不同, `webview` 和你的應用運行的是不同的進程. 它不擁有渲染進程的權限，并且應用和嵌入內容之間的交互全部都是異步的.因為這能保證應用的安全性不受嵌入內容的影響. ## 例子把一個 web page 嵌入到你的app，首先添加 `webview` 標簽到你的app待嵌入page(展示 guest content). 在一個最簡單的 `webview` 中，它包含了 web page 的文件路徑和一個控制 `webview` 容器展示效果的css樣式: ```html <webview id="foo" src="https://www.github.com/" style="display:inline-block; width:640px; height:480px"></webview> ``` 如果想隨時控制 guest 內容，可以添加 JavaScript 腳本來監聽 `webview` 事件使用 `webview` 方法來做出響應. 這里是2個事件監聽的例子：一個監聽 web page 準備加載，另一個監聽 web page 停止加載，并且在加載的時候顯示一條 "loading..." 信息: ```html <script> onload = function() { var webview = document.getElementById("foo"); var indicator = document.querySelector(".indicator"); var loadstart = function() { indicator.innerText = "loading..."; } var loadstop = function() { indicator.innerText = ""; } webview.addEventListener("did-start-loading", loadstart); webview.addEventListener("did-stop-loading", loadstop); } </script> ``` ## 標簽屬性 `webview` 標簽有下面一些屬性 : ### `src` ```html <webview src="https://www.github.com/"></webview> ``` 將一個可用的url做為這個屬性的初始值添加到頂部導航. 如果把當前頁的src添加進去將加載當前page. `src`同樣可以填 data urls，例如 `data:text/plain,Hello, world!`. ### `autosize` ```html <webview src="https://www.github.com/" autosize="on" minwidth="576" minheight="432"></webview> ``` 如果這個屬性的值為 "on" ， `webview` 容器將會根據屬性`minwidth`, `minheight`, `maxwidth`, 和 `maxheight` 的值在它們之間自適應. 只有在 `autosize` 開啟的時候這個約束才會有效. 當 `autosize` 開啟的時候， `webview` 容器的 size 只能在上面那四個屬性值之間. ### `nodeintegration` ```html <webview src="http://www.google.com/" nodeintegration></webview> ``` 如果設置了這個屬性， `webview` 中的 guest page 將整合node，并且擁有可以使用系統底層的資源，例如 `require` 和 `process` . ### `plugins` ```html <webview src="https://www.github.com/" plugins></webview> ``` 如果這個屬性的值為 "on" ， `webview` 中的 guest page 就可以使用瀏覽器插件。 ### `preload` ```html <webview src="https://www.github.com/" preload="./test.js"></webview> ``` 在 guest page 中的其他腳本執行之前預加載一個指定的腳本。規定預加載腳本的url須如 `file:` 或者 `asar:`，因為它在是 guest page 中通過通過 `require` 命令加載的。如果 guest page 沒有整合 node ，這個腳本將試圖使用真個 Node APIs ，但是在這個腳本執行完畢時，之前由node插入的全局對象會被刪除。 ### `httpreferrer` ```html <webview src="https://www.github.com/" httpreferrer="http://cheng.guru"></webview> ``` 為 guest page 設置 referrer URL。 ### `useragent` ```html <webview src="https://www.github.com/" useragent="Mozilla/5.0 (Windows NT 6.1; WOW64; Trident/7.0; AS; rv:11.0) like Gecko"></webview> ``` 在 guest page 加載之前為其設置用戶代理。如果頁面已經加載了，可以使用 `setUserAgent` 方法來改變用戶代理。 ### `disablewebsecurity` ```html <webview src="https://www.github.com/" disablewebsecurity></webview> ``` 如果這個屬性的值為 "on" ， guest page會禁用web安全控制. ### partition ```html <webview src="https://github.com" partition="persist:github"></webview> <webview src="http://electron.atom.io" partition="electron"></webview> ``` 為page設置session。如果初始值為 `partition` ,這個 page 將會為app中的所有 page 應用同一個持續有效的 session。如果沒有 `persist:` 前綴, 這個 page 將會使用一個歷史 session 。通過分配使用相同的 `partition`, 所有的page都可以分享相同的session。如果 `partition` 沒有設置，那app將使用默認的session. 這個值只能在在第一個渲染進程之前設置修改，之后修改的話會無效并且拋出一個DOM異常. ### `allowpopups` ```html <webview src="https://www.github.com/" allowpopups></webview> ``` 如果這個屬性的值為 "on" ，將允許 guest page 打開一個新窗口。 ### `blinkfeatures` ```html <webview src="https://www.github.com/" blinkfeatures="PreciseMemoryInfo, CSSVariables"></webview> ``` 這個屬性的值為一個用逗號分隔的列表，它的值指定特性被啟用。你可以從[setFeatureEnabledFromString][blink-feature-string]函數找到完整的支持特性。 ## 方法 `webview` 的方法集合: **注意:** webview 元素必須在使用這些方法之前加載完畢。 **例如** ```javascript webview.addEventListener("dom-ready", function() { webview.openDevTools(); }); ``` ### `<webview>.loadURL(url[, options])` * `url` URL * `options` Object (可選) * `httpReferrer` String - 一個http類型的url. * `userAgent` String -用于發起請求的用戶代理. * `extraHeaders` String - 額外的headers,用 "\n"分隔. 加載 webview 中的 `url`，`url` 必須包含協議前綴，例如 `http://` 或 `file://`. ### `<webview>.getURL()` 從 guest page 中返回 url. ### `<webview>.getTitle()` 從 guest page 中返回 title. ### `<webview>.isLoading()` 返回一個 guest page 是否仍在加載資源的布爾值. ### `<webview>.isWaitingForResponse()` 返回一個 guest page 是否正在等待page的主要資源做出回應的布爾值. ### `<webview>.stop()` 停止渲染. ### `<webview>.reload()` 重新加載 guest page. ### `<webview>.reloadIgnoringCache()` 忽視緩存，重新加載 guest page. ### `<webview>.canGoBack()` 返回一個 guest page 是否能夠回退的布爾值. ### `<webview>.canGoForward()` 返回一個 guest page 是否能夠前進的布爾值. ### `<webview>.canGoToOffset(offset)` * `offset` Integer 返回一個 guest page 是否能夠前進到 `offset` 的布爾值. ### `<webview>.clearHistory()` 清除導航歷史. ### `<webview>.goBack()` guest page 回退. ### `<webview>.goForward()` guest page 前進. ### `<webview>.goToIndex(index)` * `index` Integer guest page 導航到指定的絕對位置. ### `<webview>.goToOffset(offset)` * `offset` Integer guest page 導航到指定的相對位置. ### `<webview>.isCrashed()` 返回一個渲染進程是否崩潰的布爾值. ### `<webview>.setUserAgent(userAgent)` * `userAgent` String 重新設置用戶代理. ### `<webview>.getUserAgent()` 返回用戶代理名字，返回類型：`String`. ### `<webview>.insertCSS(css)` * `css` String 插入css. ### `<webview>.executeJavaScript(code, userGesture, callback)` * `code` String * `userGesture` Boolean - 默認 `false`. * `callback` Function (可選) - 回調函數. * `result` 評估 `code` ，如果 `userGesture` 值為 true ，它將在這個page里面創建用戶手勢. HTML APIs ，如 `requestFullScreen`,它需要用戶響應，那么將自動通過這個參數優化. ### `<webview>.openDevTools()` 為 guest page 打開開發工具調試窗口. ### `<webview>.closeDevTools()` 為 guest page 關閉開發工具調試窗口. ### `<webview>.isDevToolsOpened()` 返回一個 guest page 是否打開了開發工具調試窗口的布爾值. ### `<webview>.isDevToolsFocused()` 返回一個 guest page 是否聚焦了開發工具調試窗口的布爾值. ### `<webview>.inspectElement(x, y)` * `x` Integer * `y` Integer 開始檢查 guest page 在 (`x`, `y`) 位置的元素. ### `<webview>.inspectServiceWorker()` 在 guest page 中為服務人員打開開發工具. ### `<webview>.setAudioMuted(muted)` * `muted` Boolean 設置 guest page 流暢(muted). ### `<webview>.isAudioMuted()` 返回一個 guest page 是否流暢的布爾值. ### `<webview>.undo()` 在page中編輯執行 `undo` 命令. ### `<webview>.redo()` 在page中編輯執行 `redo` 命令. ### `<webview>.cut()` 在page中編輯執行 `cut` 命令. ### `<webview>.copy()` 在page中編輯執行 `copy` 命令. ### `<webview>.paste()` 在page中編輯執行 `paste` 命令. ### `<webview>.pasteAndMatchStyle()` 在page中編輯執行 `pasteAndMatchStyle` 命令. ### `<webview>.delete()` 在page中編輯執行 `delete` 命令. ### `<webview>.selectAll()` 在page中編輯執行 `selectAll` 命令. ### `<webview>.unselect()` 在page中編輯執行 `unselect` 命令. ### `<webview>.replace(text)` * `text` String 在page中編輯執行 `replace` 命令. ### `<webview>.replaceMisspelling(text)` * `text` String 在page中編輯執行 `replaceMisspelling` 命令. ### `<webview>.insertText(text)` * `text` String 插入文本. ### `<webview>.findInPage(text[, options])` * `text` String - 搜索內容,不能為空. * `options` Object (可選) * `forward` Boolean - 向前或向后, 默認為 `true`. * `findNext` Boolean - 是否查找的第一個結果, 默認為 `false`. * `matchCase` Boolean - 是否區分大小寫, 默認為 `false`. * `wordStart` Boolean - 是否只查找首字母. 默認為 `false`. * `medialCapitalAsWordStart` Boolean - 當配合 `wordStart`的時候,接受一個文字中的匹配項，要求匹配項是以大寫字母開頭后面跟小寫字母或者沒有字母。可以接受一些其他單詞內部匹配, 默認為 `false`. 發起一個請求來尋找頁面中的所有匹配 `text` 的地方并且返回一個 `Integer`來表示這個請求用的請求Id. 這個請求結果可以通過訂閱[`found-in-page`](web-view-tag.md#event-found-in-page) 事件來取得. ### `<webview>.stopFindInPage(action)` * `action` String - 指定一個行為來接替停止 [`<webview>.findInPage`](web-view-tag.md#webviewtagfindinpage) 請求. * `clearSelection` - 轉變為一個普通的 selection. * `keepSelection` - 清除 selection. * `activateSelection` - 聚焦并點擊 selection node. 使用 `action` 停止 `findInPage` 請求. ### `<webview>.print([options])` 打印輸出 `webview` 的 web page. 類似 `webContents.print([options])`. ### `<webview>.printToPDF(options, callback)` 以pdf格式打印輸出 `webview` 的 web page. 類似 `webContents.printToPDF(options, callback)`. ### `<webview>.send(channel[, arg1][, arg2][, ...])` * `channel` String * `arg` (可選) 通過 `channel` 向渲染進程發出異步消息，你也可以發送任意的參數。渲染進程通過`ipcRenderer` 模塊監聽 `channel` 事件來控制消息. 例子 [webContents.send](web-contents.md#webcontentssendchannel-args). ### `<webview>.sendInputEvent(event)` * `event` Object 向 page 發送輸入事件. 查看 [webContents.sendInputEvent](web-contents.md##webcontentssendinputeventevent) 關于 `event` 對象的相信介紹. ### `<webview>.getWebContents()` 返回和這個 `webview` 相關的 [WebContents](web-contents.md). ## DOM 事件 `webview` 可用下面的 DOM 事件: ### Event: 'load-commit' 返回: * `url` String * `isMainFrame` Boolean 加載完成觸發. 這個包含當前文檔的導航和副框架的文檔加載，但是不包含異步資源加載. ### Event: 'did-finish-load' 在導航加載完成時觸發，也就是tab 的 spinner停止spinning，并且加載事件處理. ### Event: 'did-fail-load' Returns: * `errorCode` Integer * `errorDescription` String * `validatedURL` String 類似 `did-finish-load` ，在加載失敗或取消是觸發，例如提出 `window.stop()`. ### Event: 'did-frame-finish-load' 返回: * `isMainFrame` Boolean 當一個 frame 完成加載時觸發. ### Event: 'did-start-loading' 開始加載時觸發. ### Event: 'did-stop-loading' 停止家在時觸發. ### Event: 'did-get-response-details' 返回: * `status` Boolean * `newURL` String * `originalURL` String * `httpResponseCode` Integer * `requestMethod` String * `referrer` String * `headers` Object 當獲得返回詳情的時候觸發. `status` 指示 socket 連接來下載資源. ### Event: 'did-get-redirect-request' 返回: * `oldURL` String * `newURL` String * `isMainFrame` Boolean 當重定向請求資源被接收的時候觸發. ### Event: 'dom-ready' 當指定的frame文檔加載完畢時觸發. ### Event: 'page-title-updated' 返回: * `title` String * `explicitSet` Boolean 當導航中的頁面title被設置時觸發. 在title通過文檔路徑異步加載時`explicitSet`為false. ### Event: 'page-favicon-updated' 返回: * `favicons` Array - Array of URLs. 當page收到了圖標url時觸發. ### Event: 'enter-html-full-screen' 當通過HTML API使界面進入全屏時觸發. ### Event: 'leave-html-full-screen' 當通過HTML API使界面退出全屏時觸發. ### Event: 'console-message' 返回: * `level` Integer * `message` String * `line` Integer * `sourceId` String 當客戶端輸出控制臺信息的時候觸發. 下面示例代碼將所有信息輸出到內置控制臺，沒有考慮到輸出等級和其他屬性。 ```javascript webview.addEventListener('console-message', function(e) { console.log('Guest page logged a message:', e.message); }); ``` ### Event: 'found-in-page' 返回: * `result` Object * `requestId` Integer * `finalUpdate` Boolean - 指明下面是否還有更多的回應. * `activeMatchOrdinal` Integer (可選) - 活動匹配位置 * `matches` Integer (optional) - 匹配數量. * `selectionArea` Object (optional) - 整合第一個匹配域. 在請求[`webview.findInPage`](web-view-tag.md#webviewtagfindinpage)結果有效時觸發. ```javascript webview.addEventListener('found-in-page', function(e) { if (e.result.finalUpdate) webview.stopFindInPage("keepSelection"); }); const rquestId = webview.findInPage("test"); ``` ### Event: 'new-window' 返回: * `url` String * `frameName` String * `disposition` String - 可以為 `default`, `foreground-tab`, `background-tab`, `new-window` 和 `other`. * `options` Object - 參數應該被用作創建新的 `BrowserWindow`. 在 guest page 試圖打開一個新的瀏覽器窗口時觸發. 下面示例代碼在系統默認瀏覽器中打開了一個新的url. ```javascript webview.addEventListener('new-window', function(e) { require('electron').shell.openExternal(e.url); }); ``` ### Event: 'will-navigate' 返回: * `url` String 當用戶或page嘗試開始導航時觸發. 它能在 `window.location` 變化或者用戶點擊連接的時候觸發. 這個事件在以 APIS 編程方式開始導航時不會觸發，例如 `<webview>.loadURL` 和 `<webview>.back`. 在頁面內部導航跳轉也將不回觸發這個事件，例如點擊錨鏈接或更新 `window.location.hash`.使用 `did-navigate-in-page` 來實現頁內跳轉事件. 使用 `event.preventDefault()` 并不會起什么用. ### Event: 'did-navigate' 返回: * `url` String 當導航結束時觸發. 在頁面內部導航跳轉也將不回觸發這個事件，例如點擊錨鏈接或更新 `window.location.hash`.使用 `did-navigate-in-page` 來實現頁內跳轉事件. ### Event: 'did-navigate-in-page' 返回: * `url` String 當頁內導航發生時觸發. 當業內導航發生時，page url改變了，但是不會跳出 page . 例如在錨鏈接被電擊或DOM `hashchange` 事件發生時觸發. ### Event: 'close' 在 guest page試圖關閉自己的時候觸發. 下面的示例代碼指示了在客戶端試圖關閉自己的時候將改變導航連接為`about:blank`. ```javascript webview.addEventListener('close', function() { webview.src = 'about:blank'; }); ``` ### Event: 'ipc-message' 返回: * `channel` String * `args` Array 在 guest page 向嵌入頁發送一個異步消息的時候觸發. 你可以很簡單的使用 `sendToHost` 方法和 `ipc-message` 事件在 guest page 和嵌入頁(embedder page)之間通信: ```javascript // In embedder page. webview.addEventListener('ipc-message', function(event) { console.log(event.channel); // Prints "pong" }); webview.send('ping'); ``` ```javascript // In guest page. var ipcRenderer = require('electron').ipcRenderer; ipcRenderer.on('ping', function() { ipcRenderer.sendToHost('pong'); }); ``` ### Event: 'crashed' 在渲染進程崩潰的時候觸發. ### Event: 'gpu-crashed' 在GPU進程崩潰的時候觸發. ### Event: 'plugin-crashed' 返回: * `name` String * `version` String 在插件進程崩潰的時候觸發. ### Event: 'destroyed' 在界面內容銷毀的時候觸發. ### Event: 'media-started-playing' 在媒體準備播放的時候觸發. ### Event: 'media-paused' 在媒體暫停播放或播放放畢的時候觸發. ### Event: 'did-change-theme-color' 在頁面的主體色改變的時候觸發. 在使用 meta 標簽的時候這就很常見了: ```html <meta name='theme-color' content='#ff0000'> ``` ### Event: 'devtools-opened' 在開發者工具打開的時候觸發. ### Event: 'devtools-closed' 在開發者工具關閉的時候觸發. ### Event: 'devtools-focused' 在開發者工具獲取焦點的時候觸發. [blink-feature-string]: https://code.google.com/p/chromium/codesearch#chromium/src/out/Debug/gen/blink/platform/RuntimeEnabledFeatures.cpp&sq=package:chromium&type=cs&l=527