<网页视图> | <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容器将自动被指定属性的范围内调整minwidthminheightmaxwidth,和maxheight。这些约束不会影响webview除非autosize启用。当autosize被启用时,webview容器的大小不能超过的最大小于最小值或更大。

nodeintegration

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

当该属性出现在客户页面webview将节点整合,并可以使用节点API,如requireprocess访问低级系统资源。节点集成在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 =,然后是值来将首选项设置为其他值。特殊值yes1被解释为true,而no0被解释为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 整数

在访客页面的位置(xy)开始检查元素。

<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.hashdid-navigate-in-page为此使用事件。

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

事件: ‘did-navigate’

返回:

  • url 字符串

导航完成时发射。

此事件不是用于页内导航的,例如单击锚链接或更新window.location.hashdid-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关注/打开时发出。