<webview> 标签
最后更新于：2022-04-01 20:49:28
# `` 标签
使用 `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
.loadURL(url[, options])`
* `url` URL
* `options` Object (可选)
* `httpReferrer` String - 一个http类型的url.
* `userAgent` String -用于发起请求的用户代理.
* `extraHeaders` String - 额外的headers,用 "\n"分隔.
加载 webview 中的 `url`，`url` 必须包含协议前缀，例如 `http://` 或 `file://`.
### `.getURL()`
从 guest page 中返回 url.
### `.getTitle()`
从 guest page 中返回 title.
### `.isLoading()`
返回一个 guest page 是否仍在加载资源的布尔值.
### `.isWaitingForResponse()`
返回一个 guest page 是否正在等待page的主要资源做出回应的布尔值.
### `.stop()`
停止渲染.
### `.reload()`
重新加载 guest page.
### `.reloadIgnoringCache()`
忽视缓存，重新加载 guest page.
### `.canGoBack()`
返回一个 guest page 是否能够回退的布尔值.
### `.canGoForward()`
返回一个 guest page 是否能够前进的布尔值.
### `.canGoToOffset(offset)`
* `offset` Integer
返回一个 guest page 是否能够前进到 `offset` 的布尔值.
### `.clearHistory()`
清除导航历史.
### `.goBack()`
guest page 回退.
### `.goForward()`
guest page 前进.
### `.goToIndex(index)`
* `index` Integer
guest page 导航到指定的绝对位置.
### `.goToOffset(offset)`
* `offset` Integer
guest page 导航到指定的相对位置.
### `.isCrashed()`
返回一个 渲染进程是否崩溃 的布尔值.
### `.setUserAgent(userAgent)`
* `userAgent` String
重新设置用户代理.
### `.getUserAgent()`
返回用户代理名字，返回类型：`String`.
### `.insertCSS(css)`
* `css` String
插入css.
### `.executeJavaScript(code, userGesture, callback)`
* `code` String
* `userGesture` Boolean - 默认 `false`.
* `callback` Function (可选) - 回调函数.
* `result`
评估 `code` ，如果 `userGesture` 值为 true ，它将在这个page里面创建用户手势. HTML APIs ，如 `requestFullScreen`,它需要用户响应，那么将自动通过这个参数优化.
### `.openDevTools()`
为 guest page 打开开发工具调试窗口.
### `.closeDevTools()`
为 guest page 关闭开发工具调试窗口.
### `.isDevToolsOpened()`
返回一个 guest page 是否打开了开发工具调试窗口的布尔值.
### `.isDevToolsFocused()`
返回一个 guest page 是否聚焦了开发工具调试窗口的布尔值.
### `.inspectElement(x, y)`
* `x` Integer
* `y` Integer
开始检查 guest page 在 (`x`, `y`) 位置的元素.
### `.inspectServiceWorker()`
在 guest page 中为服务人员打开开发工具.
### `.setAudioMuted(muted)`
* `muted` Boolean
设置 guest page 流畅(muted).
### `.isAudioMuted()`
返回一个 guest page 是否流畅的布尔值.
### `.undo()`
在page中编辑执行 `undo` 命令.
### `.redo()`
在page中编辑执行 `redo` 命令.
### `.cut()`
在page中编辑执行 `cut` 命令.
### `.copy()`
在page中编辑执行 `copy` 命令.
### `.paste()`
在page中编辑执行 `paste` 命令.
### `.pasteAndMatchStyle()`
在page中编辑执行 `pasteAndMatchStyle` 命令.
### `.delete()`
在page中编辑执行 `delete` 命令.
### `.selectAll()`
在page中编辑执行 `selectAll` 命令.
### `.unselect()`
在page中编辑执行 `unselect` 命令.
### `.replace(text)`
* `text` String
在page中编辑执行 `replace` 命令.
### `.replaceMisspelling(text)`
* `text` String
在page中编辑执行 `replaceMisspelling` 命令.
### `.insertText(text)`
* `text` String
插入文本.
### `.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) 事件来取得.
### `.stopFindInPage(action)`
* `action` String - 指定一个行为来接替停止
[`.findInPage`](web-view-tag.md#webviewtagfindinpage) 请求.
* `clearSelection` - 转变为一个普通的 selection.
* `keepSelection` - 清除 selection.
* `activateSelection` - 聚焦并点击 selection node.
使用 `action` 停止 `findInPage` 请求.
### `.print([options])`
打印输出 `webview` 的 web page. 类似 `webContents.print([options])`.
### `.printToPDF(options, callback)`
以pdf格式打印输出 `webview` 的 web page. 类似 `webContents.printToPDF(options, callback)`.
### `.send(channel[, arg1][, arg2][, ...])`
* `channel` String
* `arg` (可选)
通过 `channel` 向渲染进程发出异步消息，你也可以发送任意的参数。
渲染进程通过`ipcRenderer` 模块监听 `channel` 事件来控制消息.
例子
[webContents.send](web-contents.md#webcontentssendchannel-args).
### `.sendInputEvent(event)`
* `event` Object
向 page 发送输入事件.
查看 [webContents.sendInputEvent](web-contents.md##webcontentssendinputeventevent)
关于 `event` 对象的相信介绍.
### `.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 编程方式开始导航时不会触发，例如 `.loadURL` 和 `.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
```
### 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
';