Skip to content

WebContents ​

WebContents 表示 WebView 里的那张网页。加载地址、后退前进、监听加载过程、在网页里执行脚本、和网页互发消息,都在它上面。

WebView 管视图本身:位置、大小、显示隐藏。WebContents 管网页:

想做的事用哪个例子
改位置和大小WebViewweb.frame = …,或者约束
显示、隐藏、透明度WebViewweb.isHidden = true
圆角、边框WebViewweb.layer.cornerRadius = 12
加载地址、后退前进WebContentsweb.webContents.loadURL(…)
监听加载过程WebContentsweb.webContents.addEventListener(…)

继承关系:EventTarget → WebContents

怎么用它显示网页、处理加载失败、限制跳转,见指南显示网页;和网页互发消息见让网页和 App 互发消息。

构造函数 ​

不能用 new 创建:new WebContents() 抛 TypeError: Illegal constructor: WebContents is created by the runtime, not by new。它随 WebView 一起创建,从 webView.webContents 得到。

实例属性 ​

属性说明
navigationHistory 只读后退和前进
ipc 只读应答网页用 ipcRenderer.invoke 发来的请求
session 只读这张网页的数据存在哪个存储分区里

实例方法 ​

加载和导航:

方法说明
loadURL()加载一个地址
loadFile()加载一个本地的网页文件
stop()停掉正在进行的加载
reload()重新加载当前的地址

读网页的状态:

方法说明
getURL()当前网页的地址
getTitle()当前网页的标题
isLoading()是不是正在加载
isCrashed()网页的进程是不是已经不在了

和网页交换数据:

方法说明
executeJavaScript()在网页里执行一段代码,取回结果
send()给网页的预加载脚本发一条消息

销毁:

方法说明
close()销毁这张网页,释放它占的内存
isDestroyed()是不是已经销毁

还有继承自 EventTarget 的 addEventListener()、removeEventListener()。

事件 ​

用 addEventListener 监听。事件名写错不会报错:它被当成自定义事件,永远不会被网页触发,所以写的时候对照下面的表。

事件什么时候派发
will-navigate网页自己要跳到别的地址,还没开始跳。可以取消
did-start-loading开始加载
did-navigate网页换成了一个新的文档
did-stop-loading不再加载。成功和失败都会派发
did-finish-load加载完
did-fail-load加载失败
page-title-updated标题变了
ipc-message网页的预加载脚本调了 ipcRenderer.send
preload-error预加载脚本执行时抛了异常
console-message网页调了 console 的方法,或者有异常没被捕获
render-process-gone网页的进程不在了
destroyed被 close() 销毁

will-navigate 是唯一能取消的事件。其余事件派发时事情已经发生,cancelable 是 false,调 preventDefault() 没有效果。

一次成功的加载,四个加载事件的顺序是 did-start-loading → did-navigate → did-stop-loading → did-finish-load。用户在网页里点链接跳到别的页面,这四个事件同样会来。

销毁之后 ​

调 close() 之后,除了 close() 和 isDestroyed(),其余方法都抛 TypeError: Object has been destroyed;loadURL() 返回一个以同样的错误拒绝的 Promise。销毁不能撤销,要再显示网页就新建一个 WebView。

值怎么传 ​

executeJavaScript() 的结果、消息的参数、invoke 的返回值,都按 JSON 传。

值传过去之后
数、字符串、布尔、null、数组、普通对象原样
对象的成员顺序和网页里一样。例外是 executeJavaScript 执行多条语句得到的对象:值是对的,顺序不保证
undefined单独一个值时还是 undefined;在对象里的那个成员没有了;在数组里变成 null
日期字符串,比如 '1970-01-01T00:00:00.000Z'
NaN、Infinitynull
函数消息里带了函数当场抛 TypeError;executeJavaScript 的结果是函数时被拒绝;结果是对象、里面有函数成员时,那个成员没有了
Map空对象 {}
DOM 节点executeJavaScript 的结果是 DOM 节点时被拒绝

本地网页的限制 ​

用 loadFile() 加载的网页,地址是 file:// 开头的。它和从服务器加载的网页有几处不同。

本地网页
用相对路径引用样式表、普通脚本、图片可以
地址里的 ? 和 #可以,网页里读得到
localStorage、cookie可以
<script type="module">不执行
fetch、XMLHttpRequest 读本地文件失败
来源(origin)所有本地网页都是同一个:file://。它们的 localStorage 互通
能读哪些文件包里的网页:整个 App 包。别处的网页:它所在的目录和子目录。模拟器不执行这条限制,要在真机上试

本地网页请求 https:// 的接口不受影响,受限的只是读本地文件。

静态页面和用传统方式(一个普通的 <script>)打包的网页适合用 loadFile()。用到模块脚本的单页应用(比如 Vite 默认的打包结果)现在还不能从本地加载。

示例 ​

js
const web = new WebView();
const contents = web.webContents;
contents.addEventListener('did-fail-load', (e) => {
  console.log('加载失败', e.errorCode, e.validatedURL);
});
await contents.loadURL('https://example.com/');
console.log(contents.getURL(), contents.isLoading());

结果:加载成功时输出 https://example.com/ false。加载失败时先输出 加载失败 和错误码,await 那一行抛出拒绝的错误。

与 Electron 的对照 ​

Electron这里差别
contents.on('did-fail-load', (event, errorCode, errorDescription, validatedURL) => …)contents.addEventListener('did-fail-load', (e) => …)数据在 e 上,字段名相同
contents.on('will-navigate', (details) => details.preventDefault())contents.addEventListener('will-navigate', (e) => e.preventDefault())多一个 navigationType;没有 frame、initiator
did-navigate 的 httpStatusText没有系统不提供
render-process-gone 的 details.reason没有系统不说原因
did-fail-load 的 errorCode(-105 等)errorCode(-1003 等)数不同
contents.executeJavaScript(code)相同多条语句的代码不等 Promise、带回的对象不保证成员顺序;结果按 JSON 传(日期是字符串,Map 是 {})
contents.on('ipc-message', (event, channel, ...args) => …)contents.addEventListener('ipc-message', (e) => …)e.channel、e.args
contents.send(channel, ...args)、contents.ipc.handle(channel, listener)相同
contents.session相同见 session
contents.loadFile(filePath, { query, search, hash })相同相对路径的起点是 App 包。本地网页的限制比 Electron 多,见本地网页的限制
contents.navigationHistory.goBack()相同
contents.loadURL(url, { baseURLForDataURL })相同第二个参数只支持 baseURLForDataURL
contents.on('console-message', (details) => …)contents.addEventListener('console-message', (e) => …)没有 frame;没被捕获的异常也会派发
contents.close() / isDestroyed() / 'destroyed'相同

对应的 iOS API ​

ObjC(WKWebView)JS
[webView loadRequest:]contents.loadURL(url)
[webView loadHTMLString:html baseURL:base]contents.loadURL('data:text/html;charset=utf-8,' + encodeURIComponent(html), { baseURLForDataURL: base })
[webView loadFileURL:allowingReadAccessToURL:]contents.loadFile(filePath)。可读的目录由运行时按文件的位置定
webView.URLcontents.getURL()
webView.titlecontents.getTitle(),page-title-updated 事件
webView.loadingcontents.isLoading(),did-start-loading / did-stop-loading 事件
[webView stopLoading]contents.stop()
[webView reload]contents.reload()
webView.canGoBack / canGoForwardcontents.navigationHistory.canGoBack() / canGoForward()
[webView goBack] / [webView goForward]contents.navigationHistory.goBack() / goForward()
[webView evaluateJavaScript:completionHandler:]、callAsyncJavaScript:…contents.executeJavaScript(code)
WKScriptMessageHandlerWithReply预加载脚本里的 ipcRenderer;App 这边的 ipc-message 事件和 ipc.handle
webView:decidePolicyForNavigationAction:decisionHandler:will-navigate 事件,decisionHandler(.cancel) 对应 e.preventDefault()
navigationAction.navigationType事件的 navigationType
webView:didCommitNavigation:did-navigate 事件
webView:didFinishNavigation:did-finish-load 事件
webView:didFailNavigation:withError:、webView:didFailProvisionalNavigation:withError:did-fail-load 事件
webViewWebContentProcessDidTerminate:render-process-gone 事件
释放 WKWebViewcontents.close()

参见 ​