Skip to content

WebView ​

WebView 表示一个显示网页的视图。把它加进界面,让它加载一个地址,网页就显示在它的范围里,用户可以在里面点链接、填表单。

WebView 只管视图本身:放在哪、多大、显示还是隐藏,都用视图的属性和方法。视图里的那张网页是 WebContents,从 webView.webContents 得到。加载地址、后退前进、监听加载过程、在网页里执行脚本、和网页互发消息,都在它上面。

这一组还有四个对象:

网页的 cookie、localStorage 和缓存存在哪里,由存储分区决定;读写 cookie 和清数据用 session。

继承关系:EventTarget → NSObject → UIResponder → UIView → WebView

怎么显示一张网页、处理加载失败、限制网页能去的地址,见指南显示网页。网页和 App 互发消息,见指南让网页和 App 互发消息。

构造函数 ​

WebView()

创建一个显示网页的视图。可以指定存储分区和预加载脚本,创建之后不能改。

实例属性 ​

还继承 UIView 的属性。WebView 常用的继承属性是 frame、isHidden、layer、translatesAutoresizingMaskIntoConstraints。

属性说明
webContents 只读视图里的那张网页

实例方法 ​

全部继承自 UIView,比如 addSubview()、removeFromSuperview()。

网页和 App 的关系 ​

每张网页在自己独立的进程里运行,和 App 的 JS 不在同一个进程。这决定了下面几件事:

  • 两边的变量互相访问不到。 网页里的 window、document 在 App 的 JS 里不存在;App 的 JS 里的对象、函数,网页里也没有。两边之间能传递的只有数据,按 JSON 传,见值怎么传。
  • 网页的脚本不占用 App 的时间。 网页里的脚本执行多久,都不影响 App 的界面响应。
  • 网页崩溃不会让 App 退出。 网页的进程崩溃或者被系统结束时,网页变成空白,App 照常运行,并在 webContents 上收到 render-process-gone 事件。

App 和网页之间有三种传递数据的方式:

方式方向用在什么时候
executeJavaScript()App 在网页里执行一段代码,取回结果App 主动读网页里的内容,或者改网页
预加载脚本和消息两个方向都可以网页要调用 App 的功能,或者 App 要通知网页
will-navigate 事件网页要跳转时,App 得到要去的地址,并可以拦住限制网页能去哪里,处理 tel:、自定义协议的链接

网页内容不受信任 ​

网页的内容来自服务器,网页里还可能引入第三方的脚本。App 不能假定网页里执行的代码是自己写的。运行时按这个前提划定了边界:

  • 运行时不会把 App 的任何能力自动提供给网页。 一张没有配预加载脚本的网页,没有任何办法调用 App 的 JS、读 App 的文件或存储。它能做的只有普通网页能做的事。
  • 消息通道是网页进入 App 的唯一入口。 只有建 WebView 时用 webPreferences.preload 指定了预加载脚本,网页里才有消息通道。App 收到消息后做什么,完全由 App 自己的监听器决定。
  • 预加载脚本和网页的脚本不隔离。 两者在同一个环境里执行。配了预加载脚本之后,网页里的任何脚本,包括第三方脚本,都可以调用预加载脚本提供的对象,可以修改这个对象的成员,也可以不经过预加载脚本直接往消息通道里发消息。所以预加载脚本里写的检查不能当作安全措施,检查必须写在 App 这一侧。
  • <iframe> 里的内容发不了消息。 预加载脚本只在主文档里执行,<iframe> 里发来的消息 App 不接收。

从网页来的数据有三处:消息的频道名和参数、executeJavaScript() 的结果、will-navigate 事件里的地址。这三处都要当作不可信的输入,用之前检查类型和取值范围。写法见在 App 这一侧检查每一条消息。

预加载脚本 ​

预加载脚本是建 WebView 时用 webPreferences.preload 指定的一个 JS 文件,和 App 一起打包。它在网页里执行,不在 App 的 JS 里执行,所以不能写进 main.js,也用不了 App 这边的任何对象。

什么时候执行每张网页开始加载时,在网页自己的任何脚本之前。那时还没有 <body>
在哪里执行只在主文档里。<iframe> 里不执行
换了网页重新执行一遍
能用什么网页里能用的一切(document、window),外加 ipcRenderer 和 contextBridge 两个名字
网页禁止了脚本(内容安全策略)照常执行。受限的只是网页自己的脚本
执行时抛了异常网页照常加载,webContents 上派发 preload-error

它和网页的脚本在同一个环境里执行,两者之间没有隔离。这带来四个结果:

  • 预加载脚本往 window 上挂的东西,网页看得到。
  • 用 contextBridge.exposeInMainWorld 挂上去的名字,网页不能换成别的对象,但能修改这个对象的成员。
  • ipcRenderer 和 contextBridge 这两个名字网页用不了,但网页可以不经过它们,直接往底下的消息通道里发消息,频道名和参数都由它决定。
  • 网页可以冒充 App,让预加载脚本里 ipcRenderer.on 登记的监听器收到假的消息。

所以预加载脚本适合用在 App 自己控制的网页上。App 这一侧收到的每条消息都要检查,预加载脚本收到的消息也不能当作一定来自 App。

存储分区 ​

存储分区是网页的 cookie、localStorage 和缓存存放的那一份数据。建 WebView 时用 webPreferences.partition 指定用哪一个。分区的数据存在 App 自己的存储空间里,别的 App 和 Safari 都读不到(来自 iOS 的定义,未在模拟器验证)。

partition 的值数据存在哪App 退出之后
不写,或者空串默认的那一份。所有不写 partition 的网页共用还在
'persist:名字'名字对应的那一份。同名的网页共用还在
'名字'(不带 persist:)名字对应的那一份,只在内存里。同名的网页共用没了

不同分区之间互相看不到数据。partition 只能在建 WebView 时指定,之后不能改。

分区里的 cookie 可以由 App 读写,数据可以由 App 清掉,见 session。

网页的 cookie 和 fetch 的 cookie 是分开的两份:在网页里登录,不会让 fetch 带上登录状态,反过来也一样。

网页里哪些功能和浏览器里不一样 ​

网页里的功能在 WebView 里
点链接、提交表单、脚本跳转正常。App 可以用 will-navigate 拦住
localStorage、cookie正常,存在存储分区里
明文的 http:// 地址被系统拦截,加载失败。http://localhost 除外
打开新窗口(window.open、target="_blank" 的链接)什么都不发生,网页留在原地。脚本触发的是实测结果;用户真实点击 target="_blank" 的链接未在模拟器验证
下载文件(地址指向压缩包这类不能显示的内容)不下载。加载失败,派发 did-fail-load,errorCode 是 102
alert()、confirm()、prompt()不显示对话框。未在模拟器验证
选择文件(<input type="file">)、相机、麦克风、定位未在模拟器验证
从屏幕左边缘右滑后退没有。后退用 navigationHistory.goBack()

从本地文件加载的网页另有几条限制,见本地网页的限制。

网页感知得到什么 ​

视图这边的变化,网页里用标准的 Web 接口都能感知到。

视图这边发生的事网页里看到什么
视图的宽高变了window.innerWidth / innerHeight 跟着变,派发 resize。1 pt 对应 CSS 的 1px
视图伸到安全区外面env(safe-area-inset-*) 给出被挡住的宽度,需要 viewport-fit=cover
系统切换深浅色,或者视图被强制成深色或浅色prefers-color-scheme 跟着变,matchMedia 的 change 事件会派发
设 isHidden没有变化。 不派发 visibilitychange
从界面上拿掉(removeFromSuperview)visibilityState 变成 'hidden',派发 visibilitychange
加回界面visibilityState 变回 'visible',派发 visibilitychange
App 退到后台、回到前台visibilityState 变成 'hidden'、变回 'visible'(未在模拟器验证)

不在界面里的网页,系统会放慢它的定时器:间隔 100 毫秒的 setInterval 大约每秒只执行一次。

内存和引用 ​

一张网页占用的内存不小:模拟器上实测一张简单的网页占 60 MB 左右。内存紧张时,系统可以结束网页的进程。

不再使用的网页,调 webContents.close() 销毁。销毁之后网页的进程退出,内存释放;WebView 还是一个视图,只是里面空了,再把它从界面上拿掉。

不调 close() 时:

WebView 的状态会怎样
在界面里一直存在,网页一直占着内存。界面拿着它,不用自己拿着引用
不在界面里(还没加进去,或者拿掉了)代码也没有保存引用时会被回收,网页跟着销毁,进程退出(实测)。回收发生在什么时候不确定,所以不要依赖它来释放内存;要留着用,就自己拿着引用

示例 ​

占满屏幕的网页 ​

从空白 App 开始,显示一张占满安全区的网页,并把加载过程打到控制台。

js
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。后两行谁先谁后不固定。

用独立的分区 ​

js
const shop = new WebView({ webPreferences: { partition: 'persist:shop' } });
const guest = new WebView({ webPreferences: { partition: 'guest' } });
console.log(shop.webContents.session.isPersistent(), guest.webContents.session.isPersistent());

结果:输出 true false。shop 的数据在 App 退出之后还在,guest 的只在内存里。

与 Electron 的对照 ​

Electron这里差别
new WebContentsView({ webPreferences })new WebView({ webPreferences })只支持 partition、preload 和 javascript
view.setBounds({ x, y, width, height })web.frame = new CGRect(x, y, width, height)也可以用约束
win.contentView.addChildView(view)page.view.addSubview(web)
view.webContentsweb.webContents相同
webPreferences.preload相同相对路径的起点是 App 包。不隔离,相当于 contextIsolation: false
webPreferences.javascript相同默认 true

WebContents、ipcRenderer 这些对象各自的对照在它们的页面上。

对应的 iOS API ​

ObjC(WKWebView)JS
[[WKWebView alloc] initWithFrame:configuration:]new WebView()
configuration.websiteDataStorewebPreferences.partition
WKUserScript(文档开始时注入,只进主文档)webPreferences.preload
释放 WKWebViewcontents.close()

参见 ​

  • 显示网页:加载、处理失败、限制跳转、本地网页的完整写法。
  • 让网页和 App 互发消息:预加载脚本和消息的完整写法。
  • WebContents:视图里的那张网页。加载和事件都在它上面。
  • 视图:WebView 的摆放、显示隐藏、圆角都用它的成员。
  • Auto Layout:例子里让网页占满安全区用的约束。
  • 外观特征:强制深浅色,网页的 prefers-color-scheme 会跟着变。
  • session:读写网页的 cookie、清掉网页留下的数据。
  • fetch:只要数据、不需要显示网页时用它。它的 cookie 和网页的不通。