文章/答案/技术大牛

发布

<网页视图> | <webview>

在独立的框架和过程中显示外部网页内容。

过程：渲染器

使用webview标签将“客人”内容（如网页）嵌入到您的Electron应用程序中。访客内容包含在webview容器中。您应用中的嵌入式页面控制着客人内容的布局和呈现方式。

与an不同的是iframe，它们webview运行在一个独立的进程中，而不是你的应用程序。它没有与您的网页相同的权限，您的应用程序和嵌入式内容之间的所有交互都将是异步的。这使您的应用程序免受嵌入式内容的影响。注意：主机页面在webview上调用的大多数方法都需要对主进程进行同步调用。

例

要在应用中嵌入网页，请将webview标记添加到应用的嵌入页面（这是显示访客内容的应用页面）。在其最简单的形式中，webview标签包含src控制webview容器外观的网页和CSS样式：

<webview id="foo" src="https://www.github.com/" style="display:inline-flex; width:640px; height:480px"></webview>

如果您想以任何方式控制访客内容，则可以编写监听webview事件并使用这些webview方法响应这些事件的JavaScript 。这里有两个事件监听器的示例代码：一个监听网页开始加载，另一个监听网页停止加载，并在加载时显示“加载...”消息：

<script>
  onload = () => {
    const webview = document.querySelector('webview')
    const indicator = document.querySelector('.indicator')

    const loadstart = () => {
      indicator.innerText = 'loading...'
    }

    const loadstop = () => {
      indicator.innerText = ''
    }

    webview.addEventListener('did-start-loading', loadstart)
    webview.addEventListener('did-stop-loading', loadstop)
  }
</script>

CSS样式注释

请注意，webview标签的样式在display:flex;内部使用，以确保子object元素webview在与传统和弹性盒布局（自v0.36.11以来）一起使用时填充其容器的整个高度和宽度。display:flex;除非指定display:inline-flex;内联布局，否则请勿覆盖默认的CSS属性。

webview有使用该hidden属性或使用隐藏的问题display: none;。它可能会导致其子browserplugin对象内出现不正常的呈现行为，并且在webview未隐藏时重新加载网页。推荐的方法是隐藏webview使用visibility: hidden。

<style>
  webview {
    display:inline-flex;
    width:640px;
    height:480px;
  }
  webview.hide {
    visibility: hidden;
  }
</style>

标签属性

该webview标签具有以下属性：

`src`

<webview src="https://www.github.com/"></webview>

返回可见的URL。写入此属性会启动顶级导航。

分配src自己的值将重新加载当前页面。

该src属性也可以接受数据URL，例如data:text/plain,Hello, world!。

`autosize`

<webview src="https://www.github.com/" autosize minwidth="576" minheight="432"></webview>

当该属性是存在于webview容器将自动被指定属性的范围内调整minwidth，minheight，maxwidth，和maxheight。这些约束不会影响webview除非autosize启用。当autosize被启用时，webview容器的大小不能超过的最大小于最小值或更大。

`nodeintegration`

<webview src="http://www.google.com/" nodeintegration></webview>

当该属性出现在客户页面webview将节点整合，并可以使用节点API，如require和process访问低级系统资源。节点集成在guest虚拟机页面默认处于禁用状态。

`plugins`

<webview src="https://www.github.com/" plugins></webview>

当此属性出现时，访客页面webview将能够使用浏览器插件。插件默认是禁用的。

`preload`

<webview src="https://www.github.com/" preload="./test.js"></webview>

指定将在其他脚本在宾客页面中运行之前加载的脚本。脚本URL的协议必须是file:或者asar:，因为它将require在引擎盖下的访客页面中加载。

当访客页面没有集成节点时，这个脚本仍然可以访问所有的Node API，但是在这个脚本完成执行后，由Node注入的全局对象将被删除。

注意：该选项将显示为preloadURL（不preload）在webPreferences指定的will-attach-webview事件中。

`httpreferrer`

<webview src="https://www.github.com/" httpreferrer="http://cheng.guru"></webview>

设置访客页面的引荐来源网址。

`useragent`

<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>

在页面导航到之前设置访客页面的用户代理。加载页面后，使用该setUserAgent方法更改用户代理。

`disablewebsecurity`

<webview src="https://www.github.com/" disablewebsecurity></webview>

当此属性出现时，访客页面将禁用网络安全。Web安全默认启用。

`partition`

<webview src="https://github.com" partition="persist:github"></webview>
<webview src="https://electron.atom.io" partition="electron"></webview>

设置页面使用的会话。如果partition开头persist:，页面将使用持续会话可用于应用程序中的所有页面partition。如果没有persist:前缀，页面将使用内存中会话。通过分配相同的内容partition，多个页面可以共享同一个会话。如果partition未设置，那么应用程序的默认会话将被使用。

此值只能在第一次导航之前修改，因为活动的渲染器进程的会话不能更改。随后尝试修改该值将会失败并出现DOM异常。

`allowpopups`

<webview src="https://www.github.com/" allowpopups></webview>

当此属性出现时，访客页面将被允许打开新窗口。弹出窗口默认是禁用的。

`webpreferences`

<webview src="https://github.com" webpreferences="allowRunningInsecureContent, javascript=no"></webview>

指定要在Web视图上设置的Web首选项的字符串列表，由<值>分隔,。在BrowserWindow中可以找到支持的首选项字符串的完整列表。

该字符串遵循与特征字符串相同的格式window.open。名称本身被赋予一个true布尔值。可以通过包含an =，然后是值来将首选项设置为其他值。特殊值yes和1被解释为true，而no与0被解释为false。

`blinkfeatures`

<webview src="https://www.github.com/" blinkfeatures="PreciseMemoryInfo, CSSVariables"></webview>

一个字符串列表，指定要使能的闪烁功能,。RuntimeEnabledFeatures.json5文件中可以找到支持的功能字符串的完整列表。

`disableblinkfeatures`

<webview src="https://www.github.com/" disableblinkfeatures="PreciseMemoryInfo, CSSVariables"></webview>

一个字符串列表，用于指定要禁用的闪烁功能,。RuntimeEnabledFeatures.json5文件中可以找到支持的功能字符串的完整列表。

`guestinstance`

<webview src="https://www.github.com/" guestinstance="3"></webview>

将webview链接到特定webContents的值。当webview第一次加载一个新的webContents被创建并且这个属性被设置为它的实例标识符。在新的或现有的web视图上设置此属性会将其连接到当前在其他webview中呈现的现有web内容。

现有的webview会看到该destroy事件，然后在加载新的url时创建一个新的webContents。

`disableguestresize`

<webview src="https://www.github.com/" disableguestresize></webview>

当这个属性出现webview时，当webview元素本身被调整大小时，内容将被阻止调整大小。

这可以结合webContents.setSize手动调整webview内容的大小以适应窗口大小的变化。与依靠webview元素边界来自动调整内容大小相比，这可以使调整速度更快。

const {webContents} = require('electron')

// We assume that `win` points to a `BrowserWindow` instance containing a
// `<webview>` with `disableguestresize`.

win.on('resize', () => {
  const [width, height] = win.getContentSize()
  for (let wc of webContents.getAllWebContents()) {
    // Check if `wc` belongs to a webview in the `win` window.
    if (wc.hostWebContents &&
        wc.hostWebContents.id === win.webContents.id) {
      wc.setSize({
        normal: {
          width: width,
          height: height
        }
      })
    }
  }
})

方法

该webview标签具有以下方法：

注意：在使用这些方法之前，必须加载webview元素。

例

const webview = document.querySelector('webview')
webview.addEventListener('dom-ready', () => {
  webview.openDevTools()
})

`<webview>.loadURL(url[, options])`

url 网址
options 对象（可选）
- httpReferrer 字符串（可选） - HTTP引荐网址。
- userAgent 字符串（可选） - 发起请求的用户代理。
- extraHeaders 字符串（可选） - 额外的标题由“\ n”分隔
- postData （UploadRawData [] | UploadFile [] | UploadFileSystem [] | UploadBlob []） - （可选）
- baseURLForDataURL字符串（可选） - 基础URL（带尾随路径分隔符）用于由数据URL加载的文件。只有当指定的url是数据url并需要加载其他文件时，才需要此选项。

url在webview中加载，url必须包含协议前缀，例如http://or file://。

`<webview>.getURL()`

返回String- 访客页面的URL。

`<webview>.getTitle()`

返回String- 访客页面的标题。

`<webview>.isLoading()`

返回Boolean- 访客页面是否仍在加载资源。

`<webview>.isWaitingForResponse()`

返回Boolean- 访客页面是否正在等待页面主资源的第一响应。

`<webview>.stop()`

停止任何挂起的导航。

`<webview>.reload()`

重新加载访客页面。

`<webview>.reloadIgnoringCache()`

重新加载访客页面并忽略缓存。

`<webview>.canGoBack()`

返回Boolean- 访客页面是否可以返回。

`<webview>.canGoForward()`

返回Boolean- 访客页面是否可以继续。

`<webview>.canGoToOffset(offset)`

offset 整数

返回Boolean- 访客页面是否可以访问offset。

`<webview>.clearHistory()`

清除导航历史记录。

`<webview>.goBack()`

使访客页面返回。

`<webview>.goForward()`

使访客页面前进。

`<webview>.goToIndex(index)`

index 整数

导航到指定的绝对索引。

`<webview>.goToOffset(offset)`

offset 整数

导航到“当前条目”的指定偏移量。

`<webview>.isCrashed()`

返回Boolean- 渲染器进程是否崩溃。

`<webview>.setUserAgent(userAgent)`

userAgent String

覆盖访客页面的用户代理。

`<webview>.getUserAgent()`

返回String- 访客页面的用户代理。

`<webview>.insertCSS(css)`

css String

将CSS注入到访客页面中。

`<webview>.executeJavaScript(code, userGesture, callback)`

code String
userGesture布尔值 - 默认值false。
callback 功能（可选） - 脚本执行后调用。
- result 任何

code在页面中进行评估。如果userGesture已设置，它将在页面中创建用户手势上下文。像requestFullScreen需要用户操作的HTML API 可以利用此选项进行自动化。

`<webview>.openDevTools()`

打开访客页面的DevTools窗口。

`<webview>.closeDevTools()`

关闭访客页面的DevTools窗口。

`<webview>.isDevToolsOpened()`

返回Boolean- 访客页面是否连接了DevTools窗口。

`<webview>.isDevToolsFocused()`

返回Boolean- 访客页面的DevTools窗口是否关注。

`<webview>.inspectElement(x, y)`

x 整数
y 整数

在访客页面的位置（x，y）开始检查元素。

`<webview>.inspectServiceWorker()`

打开访客页面中存在的服务工作者上下文的DevTools。

`<webview>.setAudioMuted(muted)`

muted 布尔

设置访客页面静音。

`<webview>.isAudioMuted()`

返回Boolean- 访客页面是否已被静音。

`<webview>.undo()`

执行undo页面中的编辑命令。

`<webview>.redo()`

执行redo页面中的编辑命令。

`<webview>.cut()`

执行cut页面中的编辑命令。

`<webview>.copy()`

执行copy页面中的编辑命令。

`<webview>.paste()`

执行paste页面中的编辑命令。

`<webview>.pasteAndMatchStyle()`

执行pasteAndMatchStyle页面中的编辑命令。

`<webview>.delete()`

执行delete页面中的编辑命令。

`<webview>.selectAll()`

执行selectAll页面中的编辑命令。

`<webview>.unselect()`

执行unselect页面中的编辑命令。

`<webview>.replace(text)`

text String

执行replace页面中的编辑命令。

`<webview>.replaceMisspelling(text)`

text String

执行replaceMisspelling页面中的编辑命令。

`<webview>.insertText(text)`

text String

插入text到被聚焦的元素。

`<webview>.findInPage(text[, options])`

text 字符串 - 要搜索的内容不能为空。
options 对象（可选）
- forward布尔值 - （可选）是向前还是向后搜索，默认值为true。
- findNext布尔值 - （可选）操作是第一次请求还是后续操作，默认为false。
- matchCase布尔值 - （可选）搜索是否区分大小写，默认为false。
- wordStart布尔 - （可选）是否仅查看单词的开头。默认为false。
- medialCapitalAsWordStart布尔值 - （可选）结合使用时wordStart，如果匹配以大写字母后跟小写字母或非字母开头，则接受单词中间的匹配。接受其他几个词内匹配，默认为false。

开始请求查找text网页中的所有匹配项，并返回一个Integer表示请求使用的请求ID。请求的结果可以通过订阅found-in-page事件来获得。

`<webview>.stopFindInPage(action)`

action字符串 - 指定结束<webview>.findInPage请求时要执行的操作。
- clearSelection - 清除选择。
- keepSelection - 将选择转换为正常选择。
- activateSelection - 重点并单击选择节点。

停止使用提供的任何findInPagewebviewaction请求。

`<webview>.print([options])`

options 对象（可选）
- silent布尔（可选） - 不要求用户进行打印设置。默认是false。
- printBackground布尔（可选） - 还打印网页的背景颜色和图像。默认是false。
- deviceName字符串（可选） - 设置要使用的打印机设备名称。默认是''。

打印webview的网页。和...一样webContents.print([options])。

`<webview>.printToPDF(options, callback)`

options 目的
- marginsType整数 - （可选）指定要使用的边距类型。默认边距使用0，无边距使用1，最小边距使用2。
- pageSize字符串 - （可选）指定生成的PDF的页面大小。可以A3，A4，A5，Legal，Letter，Tabloid或包含对象height，并width在微米。
- printBackground 布尔值 - （可选）是否打印CSS背景。
- printSelectionOnly 布尔值 - （可选）是否仅打印选择。
- landscape布尔 - （可选）true横向，false纵向。
callback 功能
- error 错误
- data 缓冲

webview以PDF形式打印网页，与webContents.printToPDF(options, callback)。

`<webview>.capturePage([rect, ]callback)`

rect 矩形（可选） - 要捕获的页面区域
callback 功能
- image NativeImage

捕获该webview页面的快照。和...一样webContents.capturePage([rect, ]callback)。

`<webview>.send(channel[, arg1][, arg2][, ...])`

channel String
...args any[]

通过向渲染器进程发送异步消息channel，您还可以发送任意参数。渲染器进程可以通过channel使用ipcRenderer模块监听事件来处理消息。

有关示例，请参阅webContents.send。

`<webview>.sendInputEvent(event)`

event Object

将输入发送event到页面。

有关对象的详细说明，请参阅webContents.sendInputEvent event。

`<webview>.setZoomFactor(factor)`

factor 数字 - 缩放系数。

将缩放系数更改为指定的系数。缩放系数是缩放百分比除以100，所以300％= 3.0。

`<webview>.setZoomLevel(level)`

level 数字 - 缩放级别

将缩放级别更改为指定级别。原始大小为0，每个增量高于或低于分别代表缩小20％或更小，分别默认为原始大小的300％和50％。

`<webview>.showDefinitionForSelection()` macOS

显示用于搜索页面上所选单词的弹出式字典。

`<webview>.getWebContents()`

返回WebContents- 与此相关的网页内容webview。

DOM事件

以下DOM事件可用于webview标记：

事件：'load-commit'

url 字符串
isMainFrame 布尔

发生负载时触发。这包括在当前文档中的导航以及子帧文档级加载，但不包括异步资源加载。

事件：'did-finish-load'

导航完成后会触发，即选项卡的旋转器将停止旋转，并onload发送事件。

事件：'did-fail-load'

errorCode 整数
errorDescription 串
validatedURL 串
isMainFrame 布尔

这个事件就像是did-finish-load，但是当加载失败或被取消时被触发，例如window.stop()被调用。

事件：'did-frame-finish-load'

isMainFrame 布尔

当一个框架完成导航时触发。

事件：'did-start-loading'

对应于选项卡的旋钮开始旋转时的时间点。

事件：'did-stop-loading'

对应于制表符的旋转器停止旋转的时间点。

事件：'did-get-response-details'

status 布尔
newURL 串
originalURL 串
httpResponseCode 整数
requestMethod 串
referrer 串
headers 目的
resourceType 串

有关请求资源的详细信息可用时触发。status指示套接字连接以下载资源。

事件: ‘did-get-redirect-request’

oldURL 串
newURL 串
isMainFrame 布尔

在请求资源时收到重定向时触发。

事件: ‘dom-ready’

加载给定帧中的文档时触发。

事件: ‘page-title-updated’

title 字符串
explicitSet 布尔

导航期间设置页面标题时触发。explicitSet从文件url合成标题时，它是错误的。

事件: ‘page-favicon-updated’

favicons String [] - URL数组。

当页面收到图标网址时触发。

事件：'enter-html-full-screen'

当页面进入由HTML API触发的全屏时触发。

事件: ‘leave-html-full-screen’

当页面离开由HTML API触发的全屏时触发。

事件: ‘console-message’

level 整数
message 串
line 整数
sourceId 串

访客窗口记录控制台消息时触发。

以下示例代码将所有日志消息转发到嵌入式控制台，而不考虑日志级别或其他属性。

const webview = document.querySelector('webview')
webview.addEventListener('console-message', (e) => {
  console.log('Guest page logged a message:', e.message)
})

事件: ‘found-in-page’

result 目的
- requestId 整数
- activeMatchOrdinal 整数 - 活动比赛的位置。
- matches 整数 - 匹配数。
- selectionArea 对象 - 第一个匹配区域的坐标。
- finalUpdate 布尔

结果可用于webview.findInPage请求时触发。

const webview = document.querySelector('webview')
webview.addEventListener('found-in-page', (e) => {
  webview.stopFindInPage('keepSelection')
})

const requestId = webview.findInPage('test')
console.log(requestId)

事件: ‘new-window’

url 串
frameName 串
disposition字符串-可以是default，foreground-tab，background-tab，new-window，save-to-disk和other。
options对象 - 应该用于创建新选项的选项BrowserWindow。

访客页面尝试打开新的浏览器窗口时触发。

以下示例代码在系统的默认浏览器中打开新的URL。

const {shell} = require('electron')
const webview = document.querySelector('webview')

webview.addEventListener('new-window', (e) => {
  const protocol = require('url').parse(e.url).protocol
  if (protocol === 'http:' || protocol === 'https:') {
    shell.openExternal(e.url)
  }
})

事件: ‘will-navigate’

url 字符串

当用户或页面想要开始导航时发射。当window.location对象发生更改或用户单击页面中的链接时可能会发生这种情况。

当导航以API <webview>.loadURL和类似的API编程启动时，此事件不会发出<webview>.back。

它也不会在页内导航期间发出，例如单击锚链接或更新window.location.hash。did-navigate-in-page为此使用事件。

呼叫event.preventDefault()确实不产生任何影响。

事件: ‘did-navigate’

url 字符串

导航完成时发射。

此事件不是用于页内导航的，例如单击锚链接或更新window.location.hash。did-navigate-in-page为此使用事件。

事件: ‘did-navigate-in-page’

isMainFrame 布尔
url 字符串

发生页内导航时发出。

当页内导航发生时，页面URL会发生变化，但不会导致页面外的导航。发生这种情况的例子是当锚点链接被点击或DOM hashchange事件被触发时。

事件: ‘close’

访客页面尝试关闭时触发。

以下示例代码在guest虚拟机试图关闭自身时导航到webviewto about:blank。

const webview = document.querySelector('webview')
webview.addEventListener('close', () => {
  webview.src = 'about:blank'
})

事件: ‘ipc-message’

channel 字符串
args 数组

访客页面发送异步消息到嵌入页面时触发。

使用sendToHost方法和ipc-message事件，您可以轻松地在访客页面和嵌入页面之间进行通信：

// In embedder page.
const webview = document.querySelector('webview')
webview.addEventListener('ipc-message', (event) => {
  console.log(event.channel)
  // Prints "pong"
})
webview.send('ping')

// In guest page.
const {ipcRenderer} = require('electron')
ipcRenderer.on('ping', () => {
  ipcRenderer.sendToHost('pong')
})

事件: ‘crashed’

渲染器进程崩溃时触发。

事件: ‘gpu-crashed’

gpu进程崩溃时触发。

事件: ‘plugin-crashed’

name 字符串
version 字符串

插件进程崩溃时触发。

事件: ‘destroyed’

WebContents被销毁时触发。

事件: ‘media-started-playing’

媒体开始播放时发射。

事件：'media-paused'

媒体暂停播放或播放完毕时播放。

事件：'did-change-theme-color'

themeColor 字符串

页面主题颜色改变时发出。这通常是由于遇到元标记：

<meta name='theme-color' content='#ff0000'>

事件：'update-target-url'

url 字符串

鼠标移过链接或键盘将焦点移动到链接时发出。

事件：'devtools-opened'

DevTools打开时发出。

事件：'devtools-closed'

当DevTools关闭时发出。

事件：'devtools-focused'

在DevTools关注/打开时发出。

本文档系腾讯云开发者社区成员共同维护，如有问题请联系 cloudcommunity@tencent.com

最后更新于：2017-12-18

例

CSS样式注释

标签属性

src

autosize

nodeintegration

plugins

preload

httpreferrer

useragent

disablewebsecurity

partition

allowpopups

webpreferences

blinkfeatures

disableblinkfeatures

guestinstance

disableguestresize

方法

<webview>.loadURL(url[, options])

<webview>.getURL()

<webview>.getTitle()

<webview>.isLoading()

<webview>.isWaitingForResponse()

<webview>.stop()

<webview>.reload()

<webview>.reloadIgnoringCache()

<webview>.canGoBack()

<webview>.canGoForward()

<webview>.canGoToOffset(offset)

<webview>.clearHistory()

<webview>.goBack()

<webview>.goForward()

<webview>.goToIndex(index)

<webview>.goToOffset(offset)

<webview>.isCrashed()

<webview>.setUserAgent(userAgent)

<webview>.getUserAgent()

<webview>.insertCSS(css)

<webview>.executeJavaScript(code, userGesture, callback)

<webview>.openDevTools()

<webview>.closeDevTools()

<webview>.isDevToolsOpened()

<webview>.isDevToolsFocused()

<webview>.inspectElement(x, y)

<webview>.inspectServiceWorker()

<webview>.setAudioMuted(muted)

<webview>.isAudioMuted()

<webview>.undo()

<webview>.redo()

<webview>.cut()

<webview>.copy()

<webview>.paste()

<webview>.pasteAndMatchStyle()

<webview>.delete()

<webview>.selectAll()

<webview>.unselect()

<webview>.replace(text)

<webview>.replaceMisspelling(text)

<webview>.insertText(text)

<webview>.findInPage(text[, options])

<webview>.stopFindInPage(action)

<webview>.print([options])

<webview>.printToPDF(options, callback)

<webview>.capturePage([rect, ]callback)

<webview>.send(channel[, arg1][, arg2][, ...])

<webview>.sendInputEvent(event)

<webview>.setZoomFactor(factor)

<webview>.setZoomLevel(level)

<webview>.showDefinitionForSelection() macOS

<webview>.getWebContents()