显示网页
这一篇讲怎么用 WebView 在 App 里显示网页:加载地址和本地文件、处理加载失败、后退前进、限制网页能去的地址、提前加载、销毁和崩溃之后恢复。加载和事件都在 WebContents 上,后退前进在 NavigationHistory 上。
网页要调用 App 的功能、App 要通知网页,见另一篇让网页和 App 互发消息。
推荐的做法
- 用约束让
WebView占满安全区。 安全区是屏幕上不会被刘海、状态栏和底部横条挡住的那一块。要让网页铺到状态栏下面,见让网页伸到状态栏和底部横条下面。 - 要知道自己发起的那一次加载的结果,用
loadURL()返回的 Promise。 要连同用户点链接引起的加载一起处理时,监听事件。 - 用
will-navigate限制网页能去的地址。 配了预加载脚本的WebView尤其需要:网页一旦跳到别的站点,那个站点的脚本同样拿得到消息通道。 - 不用的网页调
close()。 一张简单的网页在模拟器上实测占 60 MB 左右。理由见内存和引用。 - 用
https://。 明文的http://地址会被系统拦截,只有http://localhost例外。
第一张网页
从空白 App 开始,显示一张占满安全区的网页,并把加载过程打到控制台。
application.addEventListener('sceneconnect', (e) => {
// 建窗口和页面。每个 App 都要有这几行
const win = new UIWindow(e.scene);
const page = new UIViewController();
page.view.backgroundColor = 'systemBackground';
win.rootViewController = page;
win.makeKeyAndVisible();
// 1. 建一个 WebView,用约束让它占满安全区
const web = new WebView();
web.translatesAutoresizingMaskIntoConstraints = false;
page.view.addSubview(web);
const safe = page.view.safeAreaLayoutGuide;
NSLayoutConstraint.activateConstraints([
web.topAnchor.constraintEqualToAnchor(safe.topAnchor),
web.bottomAnchor.constraintEqualToAnchor(safe.bottomAnchor),
web.leadingAnchor.constraintEqualToAnchor(safe.leadingAnchor),
web.trailingAnchor.constraintEqualToAnchor(safe.trailingAnchor),
]);
// 2. 网页的事都在 webContents 上
const contents = web.webContents;
contents.addEventListener('did-navigate', (event) => {
console.log('到了', event.url, '状态码', event.httpResponseCode);
});
contents.addEventListener('page-title-updated', (event) => {
console.log('标题', event.title);
});
contents.addEventListener('did-fail-load', (event) => {
console.log('加载失败', event.errorCode, event.validatedURL);
});
// 3. 加载。返回的 Promise 在加载完时兑现
contents.loadURL('https://example.com/').then(() => {
console.log('加载完', contents.getURL());
});
});效果
- 屏幕上显示 example.com 的网页。它占满安全区:上边在状态栏下面,下边在底部横条上面。
- 链接可以点。网页内容超出视图时可以滚动(滚动未在模拟器验证)。
- 控制台输出
到了 https://example.com/ 状态码 200、加载完 https://example.com/、标题 Example Domain。后两行谁先谁后不固定。
三步分别是:建 WebView 并放到页面上、在 webContents 上监听事件、加载。下面各节沿用这里的 page、web 和 contents。单独试某一节时,先写下面三行,再接着写那一节的代码:
const page = new UIViewController();
const web = new WebView();
const contents = web.webContents;知道加载到哪一步了
contents.addEventListener('did-start-loading', () => console.log('开始加载'));
contents.addEventListener('did-navigate', (e) => console.log('换到了', e.url));
contents.addEventListener('did-stop-loading', () => console.log('不再加载'));
contents.addEventListener('did-finish-load', () => console.log('加载完'));
contents.loadURL('https://example.com/');效果
- 四个事件各来一次,顺序是
did-start-loading→did-navigate→did-stop-loading→did-finish-load。 loadURL调用之后立刻读contents.isLoading()是true,did-stop-loading之后是false。- 用户在网页里点链接跳到别的页面,这四个事件同样会来。
显示加载指示用 did-start-loading 和 did-stop-loading 这一对。
处理加载失败
加载失败时,loadURL 返回的 Promise 被拒绝,同时派发 did-fail-load 事件。两处带的信息相同。只关心自己发起的这一次加载时用 Promise;要连同用户点链接引起的加载失败一起处理时,监听事件。
try {
await contents.loadURL('https://no-such-host.invalid/');
} catch (err) {
const failure = /** @type {Error & { code: number }} */ (err);
console.log(failure.name, failure.code);
}效果
- 控制台输出
NetworkError -1003。 - 网页停在原来那一页,不会变成空白,也不显示错误页。要告诉用户加载失败,得自己显示提示。
- 同时派发一次
did-fail-load,它的errorCode是-1003,validatedURL是https://no-such-host.invalid/。
只监听事件、不接 Promise 也可以。失败时不会多出一条未处理的拒绝。
服务器返回 404、500 不算失败:错误页照常加载完,Promise 兑现。状态码从 did-navigate 事件的 httpResponseCode 读。
contents.addEventListener('did-navigate', (e) => {
if (e.httpResponseCode >= 400) console.log('服务器返回了', e.httpResponseCode);
});效果:加载一个返回 404 的地址时,控制台输出 服务器返回了 404。
显示网页的标题
contents.addEventListener('page-title-updated', (e) => {
page.title = e.title;
});效果
- 网页的标题变化时,页面的标题跟着变。
- 换页的瞬间会先收到一次空串,新页面的标题到了再收到一次。
注意:不要在
did-finish-load里或者loadURL兑现之后直接读getTitle()。标题和「加载完」谁先到不固定,这时可能还读到空串。要标题就监听page-title-updated。
后退、前进、刷新
const history = contents.navigationHistory;
if (history.canGoBack()) history.goBack();
if (history.canGoForward()) history.goForward();
contents.reload();效果
goBack()回到上一张网页,goForward()回到后退之前的那一张。每次都会派发一轮加载事件。- 不能后退时调
goBack()什么都不发生,不报错。 reload()重新加载当前的地址。
WebView 没有从屏幕左边缘右滑后退的手势。要后退,在界面上放一个按钮调 goBack()。
停掉正在进行的加载
const loading = contents.loadURL('https://example.com/big');
contents.stop();
loading.catch((err) => console.log(err.name, err.code));效果
- 控制台输出
AbortError -999。 - 网页停在原来那一页。
连着调两次 loadURL 时,后一次会取代前一次:前一次的 Promise 以 AbortError 拒绝,后一次照常兑现。
只允许网页跳到自己的域名
网页自己要跳到别的地址时(用户点了链接、脚本改了 location、提交了表单),先派发 will-navigate。在监听器里调 preventDefault(),这次跳转就不发生。
contents.addEventListener('will-navigate', (e) => {
if (!e.url.startsWith('https://my.app/')) {
e.preventDefault();
console.log('拦住了', e.url, e.navigationType);
}
});效果
- 网页里点一个指向
https://other.site/的链接:控制台输出拦住了 https://other.site/ linkActivated,网页留在原地,一个加载事件都不派发。 - 点指向
https://my.app/下面的链接:照常跳转。 - 自己调
contents.loadURL(...)、reload()、后退、前进不派发这个事件,所以不会被这段代码拦住。
服务器重定向、只改 # 后面的部分、history.pushState()、<iframe> 里的跳转也不派发。全部情况见 will-navigate。
处理电话、邮件和自定义协议的链接
网页不认识 tel:、mailto: 和 App 自己定的协议(比如 myapp://)。不处理的话,点这类链接会加载失败。在 will-navigate 里拦下来,自己处理。
contents.addEventListener('will-navigate', (e) => {
if (e.url.startsWith('tel:') || e.url.startsWith('mailto:')) {
e.preventDefault();
application.openURL(e.url); // 交给系统:拨号、写邮件
} else if (e.url.startsWith('myapp://')) {
e.preventDefault();
console.log('网页让 App 做一件事', e.url);
}
});效果
- 点
tel:10086的链接:e.url是tel:10086,网页留在原地,不派发did-fail-load。系统弹出拨号确认(未在模拟器验证,模拟器不能拨号)。 - 点
myapp://share?id=1的链接:控制台输出网页让 App 做一件事 myapp://share?id=1。 - 不拦
tel:链接时:派发did-fail-load,errorCode是-1002。
自定义协议的地址是网页给的,属于不可信的输入:按它做事之前,检查它是不是 App 认识的那几种。
要先查一下再决定放不放行
放不放行在监听器返回的那一刻就定了,不能 await 之后再调 preventDefault()。需要异步判断时,先拦住,查完再自己加载。
/** App 自己的检查。这里用一个固定的名单代替
* @param {string} url */
async function isAllowed(url) {
return url.startsWith('https://my.app/');
}
contents.addEventListener('will-navigate', async (e) => {
e.preventDefault(); // 先拦住。这一句要在第一个 await 之前
const allowed = await isAllowed(e.url);
if (allowed) contents.loadURL(e.url);
});效果
- 网页先留在原地。
isAllowed兑现true之后才开始跳转。 loadURL发起的加载不派发will-navigate,所以不会再进这个监听器。
加载打进 App 包里的网页
协议、帮助这类不需要联网的页面,可以把网页文件和 App 一起打包,用 loadFile() 加载。相对路径从 App 包的根目录开始算。App 包是安装到设备上的那个目录,里面是 App 的程序和打包进去的资源文件,只能读不能写。
await contents.loadFile('JS/web/help.html');
console.log(contents.getURL());
// 带上 ? 和 # 后面的部分
await contents.loadFile('JS/web/help.html', { query: { topic: 'fees' }, hash: 'refund' });效果
- 不联网也能显示。网页旁边的样式表、脚本、图片用相对路径引用,照常加载。
- 控制台输出一个
file:///开头、以/JS/web/help.html结尾的地址。 - 第二次加载时,网页里
location.search是?topic=fees,location.hash是#refund。 - 文件不存在时 Promise 以
NetworkError拒绝,code是-1100。
注意:本地网页里
<script type="module">不执行,fetch也读不了本地文件。用到这两样的网页(比如 Vite 默认的打包结果)不能这样加载,见本地网页的限制。
显示一段 HTML
服务器下发的协议、帮助文章是一段 HTML 字符串时,把它写成 data: 地址,用 loadURL() 加载。不用先写进文件。
const article = new WebView({ webPreferences: { javascript: false } });
const html = '<!doctype html><meta name="viewport" content="width=device-width">' +
'<h1>用户协议</h1><p>……</p><img src="logo.png">';
await article.webContents.loadURL('data:text/html;charset=utf-8,' + encodeURIComponent(html), {
baseURLForDataURL: 'https://example.com/legal/',
});效果
- 显示这段 HTML。图片按
baseURLForDataURL找:https://example.com/legal/logo.png。这张远程图片未在模拟器验证;按相对路径找 App 包里的图片验过,见loadURL()。 javascript: false:内容里混进了<script>也不会执行。内容是自己写的、需要脚本时,去掉这一项。- 不带
baseURLForDataURL时,HTML 里的相对路径找不到东西;绝对地址照常加载。未在模拟器验证。
加载 App 下载下来的网页
loadFile 也接受绝对路径。App 把网页下载或写到自己的目录里之后,可以直接加载。
const dir = application.fileSystem.documents + '/pages';
await application.fileSystem.makeDirectory(dir);
await application.fileSystem.writeText(dir + '/notice.html', '<h1>公告</h1>');
await contents.loadFile(dir + '/notice.html');效果
- 屏幕上显示「公告」。
- 网页能用相对路径引用同一个目录和它的子目录下的文件。目录以外的文件引用不到:真机上那张图片加载不出来。模拟器不受这条限制,在模拟器上能加载不代表真机上可以。
读网页里的内容
executeJavaScript() 在网页里执行一段代码,把结果带回来。
const title = await contents.executeJavaScript('document.title');
const count = await contents.executeJavaScript('document.querySelectorAll("a").length');
const status = await contents.executeJavaScript('fetch("/api/ping").then((r) => r.status)');
console.log(title, count, status);效果
- 控制台输出网页的标题、链接的个数和那次请求的状态码。
- 第三句的结果是 Promise,会等它兑现再带回来。
- 网页里抛了异常,这边的 Promise 被拒绝:
executeJavaScript('throw new Error("boom")')的错误说明是Error: boom。 - 这段代码不受网页的内容安全策略限制:网页禁止了脚本时照常执行。
代码是一个表达式时,结果是 Promise 会等。写成多条语句(var a = 1; a + 1)时取最后那个值,但不等 Promise。要在多条语句里用 await,包成一个立即执行的异步函数:
const text = await contents.executeJavaScript(`(async () => {
const response = await fetch('/api/user');
return (await response.json()).name;
})()`);效果:text 是接口返回的 name。
结果按 JSON 传回来,见值怎么传。结果是网页给的,用之前检查类型和取值范围。
先加载,要用的时候再显示
WebView 不加进界面也能加载。提前建好几张,要显示哪张就把哪张加进界面。
// 提前加载两张。它们还不在界面里,所以要自己拿着引用
const pages = {
help: new WebView(),
terms: new WebView(),
};
pages.help.webContents.loadURL('https://example.com/help');
pages.terms.webContents.loadURL('https://example.com/terms');
// 之后要显示帮助页时
/** @param {WebView} view */
function show(view) {
view.frame = page.view.bounds;
page.view.addSubview(view);
}
show(pages.help);效果
- 两张网页在后台加载,包括网络请求。屏幕上没有变化。
- 调
show(pages.help)时,帮助页立刻显示出来,不用再等加载。
不在界面里的网页有两点不同:
- 网页里读
document.visibilityState是'hidden'。 - 系统会放慢它的定时器:间隔 100 毫秒的
setInterval大约每秒只执行一次。
想让网页在显示之前就照常运行,把它加进界面再设 isHidden = true。隐藏的视图不显示、不接收触摸,但网页认为自己是可见的,定时器照常。
注意:还没加进界面的
WebView要自己拿着引用,像上面存进pages那样。没有任何引用的WebView会被回收,网页跟着销毁。加进界面之后不用管。
让几张网页共用或者隔离登录状态
网页的 cookie、localStorage 和缓存存在一个存储分区里。建 WebView 时用 partition 指定用哪一个。
// 这两张共用一份数据:在一张里登录,另一张也是登录状态
const shop = new WebView({ webPreferences: { partition: 'persist:shop' } });
const cart = new WebView({ webPreferences: { partition: 'persist:shop' } });
// 这一张用另一份,和上面两张互不相干
const guest = new WebView({ webPreferences: { partition: 'guest' } });效果
shop和cart读写的是同一份 cookie 和localStorage。App 退出再打开,数据还在。guest看不到它们的数据。App 退出之后guest的数据就没了。
App 自己读写分区里的 cookie、退出登录时清数据,用 session。
销毁一张网页
一张网页占的内存不小,不用了就用 close() 销毁。
contents.addEventListener('destroyed', () => console.log('销毁了'));
contents.close();
console.log(contents.isDestroyed());
web.removeFromSuperview();效果
- 控制台输出
true,然后输出销毁了。 - 网页从屏幕上消失,它占的内存被释放。
web还是一个视图,只是里面空了。不用了就和别的视图一样,从界面上移除。- 之后再调
contents.getURL()等方法会抛TypeError: Object has been destroyed。 - 销毁不能撤销。要再显示网页,新建一个
WebView。 - 销毁时还在进行的
loadURL,它的 Promise 以AbortError被拒绝。
网页崩溃之后恢复
每张网页在自己独立的进程里运行。这个进程可能崩溃,也可能在内存紧张时被系统结束。这时网页变成空白,App 不受影响。运行时不会自动重新加载,要不要恢复由 App 决定。
contents.addEventListener('render-process-gone', () => {
contents.reload();
});效果
- 网页的进程被结束时,网页重新加载,恢复显示。
- 在
render-process-gone的回调里读contents.isCrashed()是true,重新加载之后变回false。 - 重新加载得到的是一张新加载的网页。网页里原来的状态(填到一半的表单、脚本里的变量)不会恢复。
- 进程不在的那一刻还没完成的
loadURL,它的 Promise 被拒绝。
让网页伸到状态栏和底部横条下面
第一个例子里网页只占安全区。要让网页铺满整个屏幕,把约束接到 page.view 自己的边上,并在网页里用 CSS 避开被挡住的部分。
NSLayoutConstraint.activateConstraints([
web.topAnchor.constraintEqualToAnchor(page.view.topAnchor),
web.bottomAnchor.constraintEqualToAnchor(page.view.bottomAnchor),
web.leadingAnchor.constraintEqualToAnchor(page.view.leadingAnchor),
web.trailingAnchor.constraintEqualToAnchor(page.view.trailingAnchor),
]);网页那一侧要写 <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">,再用 env(safe-area-inset-top) 这一组 CSS 值留出边距。
效果
- 网页的背景伸到状态栏和底部横条下面。
- 在 iPhone Air 上,网页里
env(safe-area-inset-top)是 68px,env(safe-area-inset-bottom)是 34px,和窗口的safeAreaInsets(68 pt、34 pt)相等。 - 网页只占安全区时,这两个值是 0。
视图这边的其他变化(大小、深浅色、移出界面)网页里怎么感知,见网页感知得到什么。
参见
WebView:视图本身,以及存储分区、网页里哪些功能和浏览器不一样。WebContents:加载、事件、执行脚本的全部成员。NavigationHistory:后退和前进。- 让网页和 App 互发消息
session:读写网页的 cookie、清数据。- Auto Layout:让网页占满安全区用的约束。