<网页视图> | <webview>

<webview> Tag

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

过程：渲染器

使用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 网址

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

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

<webview>.openDevTools()

打开访客页面的DevTools窗口。

<webview>.closeDevTools()

关闭访客页面的DevTools窗口。

<webview>.isDevToolsOpened()

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

<webview>.isDevToolsFocused()

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

<webview>.inspectElement(x, y)

• x 整数

在访客页面的位置（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 字符串 - 要搜索的内容不能为空。

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

<webview>.stopFindInPage(action)

• action字符串 - 指定结束<webview>.findInPage请求时要执行的操作。

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

<webview>.print([options])

• options 对象（可选）

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

<webview>.printToPDF(options, callback)

• options 目的

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

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

• rect 矩形（可选） - 要捕获的页面区域

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

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

• channel String

通过向渲染器进程发送异步消息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 字符串

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

事件：'did-finish-load'

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

事件：'did-fail-load'

返回：

• errorCode 整数

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

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

返回：

• isMainFrame 布尔

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

事件：'did-start-loading'

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

事件：'did-stop-loading'

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

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

返回：

• status 布尔

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

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

返回:

• oldURL 串

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

事件: ‘dom-ready’

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

事件: ‘page-title-updated’

返回:

• title 字符串

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

事件: ‘page-favicon-updated’

返回:

• favicons String [] - URL数组。

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

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

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

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

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

事件: ‘console-message’

返回:

• level 整数

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

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

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

事件: ‘found-in-page’

返回:

• result 目的

结果可用于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 串

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

以下示例代码在系统的默认浏览器中打开新的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会发生变化，但不会导致页面外的导航。发生这种情况的例子是当锚点链接被点击或DOM hashchange事件被触发时。

事件: ‘close’

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

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

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

事件: ‘ipc-message’

返回:

• channel 字符串

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

使用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 字符串

插件进程崩溃时触发。

事件: ‘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关注/打开时发出。