<webview>
标签
警告
Electron的 webview
标签基于 Chromium webview
,后者正在经历巨大的架构变化。 这将影响 webview
的稳定性,包括呈现、导航和事件路由。 We currently recommend to not use the webview
tag and to consider alternatives, like iframe
, a WebContentsView
, or an architecture that avoids embedded content altogether.
启用
默认情况下,Electron >= 5禁用 webview
标签。 在构造 BrowserWindow
时,需要通过设置 webviewTag
webPreferences选项来启用标签。 更多信息请参看 BrowserWindows 的构造器文档。
概览
在一个独立的 frame 和进程里显示外部 web 内容。
Process: Renderer
此类不从 'electron'
模块导出. 它只能作为 Electron API 中其他方法的返回值。
使用 webview
标签将'guest'内容 (例如网页) 嵌入到您的 Electron 应用中。 Guest 内容包含在 webview
容器内。 应用中的嵌入页面可以控制外来内容的布局和重绘。
与 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
事件的 JavaScript, 并使用 webview
方法响应这些事件。 下面是包含两个事件侦听器的示例代码: 一个侦听网页开始加载, 另一个用于网页停止加载, 并在加载时显示 "loading..." 消息:
<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>
内部实现
在内部 webview
与 过程外 iframes(OOPIF)一起实施。 webview
标签本质上是一个自定义元素,使用 shadow DOM 将 iframe
元素包裹在里面。
因此, webview
的行为与跨域 iframe
非常相似,例如:
- 在
webview
中单击时,页面焦点将从嵌入器移动到webview
。 - 您无法将键盘、鼠标和滚动事件侦听器添加到
webview
。 - 嵌入器框架和
webview
之间的所有反应都是异步的。
CSS 样式说明
请注意,webview
标签的样式使用 display:flex;
来确保 iframe
在传统和 flex 布局一起使用的情况下填充其 webview
容器的全部高度和宽度。 除非指定内联布局的 display:inline-flex;
,否则请不要 覆盖默认 display:flex;
CSS属性。
标签属性
webview
标签具有以下属性:
src
<webview src="https://www.github.com/"></webview>
表示可见网址的 string
。 写入此属性将启动顶级跳转
更改 src
的值将重新加载当前页面。
src
属性还可以接受数据 URL, 如 data:text/plain, Hello, world!
。
nodeintegration
<webview src="https://www.google.com/" nodeintegration></webview>
一个 boolean
。 当有此属性时, webview
中的访客页(guest page)将具有Node集成, 并且可以使用像 require
和 process
这样的node APIs 去访问低层系统资源。 Node 集成在访客页中默认是禁用的。
nodeintegrationinsubframes
<webview src="https://www.google.com/" nodeintegrationinsubframes></webview>
boolean
是一个实验选项,用于启动 NodeJS 中的 sub-frames 功能,比如在 webview
中的 iframes All your preloads will load for every iframe, you can use process.isMainFrame
to determine if you are in the main frame or not. Node 集成在访客页中默认是禁用的。
plugins
<webview src="https://www.github.com/" plugins></webview>
一个 boolean
。 When this attribute is present the guest page in webview
will be able to use browser plugins. 插件默认为禁用状态。
preload
<!-- 来自文件 -->
<webview src="https://www.github.com/" preload="./test.js"></webview>
<!-- 或从asar归档文件中加载 -->
<webview src="https://www.github.com/" preload="./app.asar/test.js"></webview>
A string
that specifies a script that will be loaded before other scripts run in the guest page. The protocol of script's URL must be file:
(even when using asar:
archives) because it will be loaded by Node's require
under the hood, which treats asar:
archives as virtual directories.
当访客页没有 node integration ,这个脚本仍然有能力去访问所有的 Node APIs, 但是当这个脚本执行执行完成之后,通过Node 注入的全局对象(global objects)将会被删除。
httpreferrer
<webview src="https://www.github.com/" httpreferrer="https://example.com/"></webview>
为访客页面设置 referrer URL 的 string
。
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>
A string
that sets the user agent for the guest page before the page is navigated to. Once the page is loaded, use the setUserAgent
method to change the user agent.
disablewebsecurity
<webview src="https://www.github.com/" disablewebsecurity></webview>
一个 boolean
。 When this attribute is present the guest page will have web security disabled. Web security is enabled by default.
This value can only be modified before the first navigation.
partition
<webview src="https://github.com" partition="persist:github"></webview>
<webview src="https://electronjs.org" partition="electron"></webview>
设置页面使用的会话的 string
。 如果 partition
以 persist:
开头, 该页面将使用持续的 session,并在所有页面生效,且使用同一个partition
. 如果没有 persist:
前缀, 页面将使用 in-memory session. 通过分配相同的 partition
, 多个页可以共享同一会话。 如果没有设置partition
,app 将会使用默认的session。
This value can only be modified before the first navigation, since the session of an active renderer process cannot change. Subsequent attempts to modify the value will fail with a DOM exception.
allowpopups
<webview src="https://www.github.com/" allowpopups></webview>
一个 boolean
。 如果该属性存在,访客页面将允许打开新窗口。 Popup 默认是禁用状态。
webpreferences
<webview src="https://github.com" webpreferences="allowRunningInsecureContent, javascript=no"></webview>
string
是一个由逗号分割的字符串列表,其中指定了要设置在 webview 上的 Web 首选项。 支持的首选项字符串的完整列表,请查看 BrowserWindow。
该字符串的格式与 window.open
中的功能字符串( the features string )相同。 只有自己名字的将被赋予 true
布尔值。 可以通过 =
来赋予其他值。 yes
和 1
会被解析成 true
,而 no
和 0
解析为 false
。
enableblinkfeatures
<webview src="https://www.github.com/" enableblinkfeatures="PreciseMemoryInfo, CSSVariables"></webview>
A string
which is a list of strings which specifies the blink features to be enabled separated by ,
. The full list of supported feature strings can be found in the RuntimeEnabledFeatures.json5 file.
disableblinkfeatures
<webview src="https://www.github.com/" disableblinkfeatures="PreciseMemoryInfo, CSSVariables"></webview>
A string
which is a list of strings which specifies the blink features to be disabled separated by ,
. The full list of supported feature strings can be found in the RuntimeEnabledFeatures.json5 file.
方法
webview
标签具有以下方法:
** 注意: **使用方法之前 webview 元素必须已被加载。
示例
const webview = document.querySelector('webview')
webview.addEventListener('dom-ready', () => {
webview.openDevTools()
})
<webview>.loadURL(url[, options])
url
URL
Returns Promise<void>
- The promise will resolve when the page has finished loading (see did-finish-load
), and rejects if the page fails to load (see did-fail-load
).
webview
中加载目标 url,url 地址必须包含协议前缀,例如:http://
或 file://
。
<webview>.downloadURL(url[, options])
url
string
Initiates a download of the resource at url
without navigating.
<webview>.getURL()
返回 string
- 访客页的URL。
<webview>.getTitle()
返回 string
- 访客页的标题。
<webview>.isLoading()
返回 boolean
- 访客页是否仍然在加载资源。
<webview>.isLoadingMainFrame()
Returns boolean
- Whether the main frame (and not just iframes or frames within it) is still loading.
<webview>.isWaitingForResponse()
返回 boolean
- 访客页面是否正在等待页面主资源的第一响应。
<webview>.stop()
停止任何待处理的导航。
<webview>.reload()
刷新访客页。
<webview>.reloadIgnoringCache()
刷新访客页并忽略缓存。
<webview>.canGoBack()
返回 boolean
- 访客页能否后退。