了解适用于 SwiftUI 的 WebKit

大家好 我叫 Richard 是 WebKit 团队的工程师 WebKit 是 Safari 浏览器、 “邮件”以及 iOS、iPadOS、 visionOS 和 macOS 上 其他众多 App 的核心浏览器引擎 多年来 WebKit 一直助力开发者 打造丰富动态的体验 通过将网页的全部功能和 灵活性直接融入 App 充分利用 Apple 平台的优势 今年 我很高兴向大家介绍 适用于 SwiftUI 的 WebKit 借助全新的 SwiftUI API 现在将网页内容集成到 App 中 比以往任何时候都更加简便 我们相信大家一定会喜欢 使用适用于 SwiftUI 的 WebKit 将 WebKit 支持的强大网页体验与 SwiftUI 的易用性相结合 借助这个新的 API 显示精美的网页内容变得轻而易举 只需创建一个网页视图 并为它提供 URL 即可 这种简便方法在 WebKit 支持的 所有平台上均适用 现在可以轻松开始使用 WebKit 和 SwiftUI 下面我们来看看 可以用这个 API 构建 App 的一些超酷新方式 我们首先将了解加载和 显示网页内容的不同方式 包括加载本地资源 之后 我们将讨论 响应网页内容变化的 所有不同方法 以及如何主动对内容进行更改 最后 我们将介绍 如何使用现有和全新的 视图修饰符来自定 用户与网页内容的交互方式 例如启用页面内查找功能、 设置滚动位置 等等

今天的内容很多 我们现在就开始吧 为了展示这个新 API 可以实现的所有精彩功能 我将构建一个 App 来浏览 世界各地不同湖泊的信息 我将在这个 App 中 展示精美的网页内容 并向你展示如何 加载文章内容 以及如何观察导航 并与 JavaScript 通信 让你的 App 变得生动鲜活 我还将展示如何完全按照你的需求 自定网页内容的浏览体验 最后 我们将进行一些最终的润色 结合使用新的 和熟悉的视图修饰符 来增强 App 的 外观和交互性 我们来开始构建 App 吧 我已经设置了一些 SwiftUI 代码 因此我们可以专注于 集成新的 WebKit API 下面我先从基础开始 即显示网页内容 新的 WebView API 使 这一过程变得非常简单 这是一个全新的 SwiftUI 视图 旨在轻松显示任何网页内容 正如前面介绍的 要使用 WebView 只需为它提供一个 URL 它将自动加载 并显示相应内容 当然 你可能不想 仅使用 WebView 来显示单个 URL 在这个示例中 我们有一个 在两个 URL 之间切换的按钮 我们再次将 URL 提供给 WebView 现在 每当切换开关时 网页视图将自动加载并导航到新 URL 就这么简单 不过你可能想 对网页内容 做一些更有趣的事情 比如响应它的属性变化 这种情况下 只需创建一个 WebPage 然后将它连接到你的 WebView 因此 现在对网页内容 所做的任何更改 例如页面标题更改 都可以通过 WebPage 获得

WebPage 是一个 全新的 Observable 类 用于展示网页内容 它从设计之初 就能与 Swift 和 SwiftUI 完美配合

你可以使用 WebPage 来载入、 控制网页内容以及 与网页内容通信 WebPage 可以完全独立使用 但与 WebView 结合使用时 你可以为网页内容打造丰富的体验 我们先来展示使用 WebPage 加载网页内容的一些不同方法 你可能想做的最常见事情之一 是将远程 URL 加载到你的网页中 只需将 load API 与 URL 请求一起使用即可 但 WebPage 不仅限于 加载 URL 你还可以通过 向 API 提供 HTML 字符串 和基准 URL 来直接加载 HTML 内容 当系统解析 HTML 中的相对 URL 时 会使用基准 URL WebPage 还支持直接加载 不同类型的数据 比如网页归档数据 只需向它提供要加载的数据、 它的 MIME 类型和字符编码 以及基准 URL 在我的 App 中 我将首先创建 一个 ArticleViewModel 类 用于表示一篇特定的文章 在这个类中 我将放置关联的 WebPage 和 LakeArticle 为了让 SwiftUI 能够轻松响应 页面和文章的任何变化 我将把这个类设为 Observable 现在 我已经设置好了类的基础 我将添加一个函数 用于将 lake 的 URL 实际加载到网页中 现在 让我们继续 讨论视图方面的内容 我将使用模型的 WebPage 创建一个 WebView 然后在视图首次出现时 调用模型的 loadArticle 函数 为了更美观 我还将使用 ignoreSafeArea 使页面一直延伸至 设备底部 现在 当你向 App 添加 新的文章 URL 并打开它时 它将在详细信息视图中 加载并显示内容 这是个非常好的开始 但为了让体验更加出色 我将在 App 中提供一些 预加载的文章 WebKit 开箱即能按预期处理 远程 URL 和数据加载 同时也支持加载 App 中捆绑的内容 或访问本地文件 你可以使用全新 URLSchemeHandler 协议来实现这一点 让我来介绍一下如何使用这个协议 当你实现自己的 Scheme Handler 时 任何指向这个方案 URL 的导航请求 都会通过这个处理程序 并使用你提供的数据 但在我们深入了解之前 让我们先了解一下什么是方案 方案是 URL 中冒号前的部分 本例中为 HTTPS 方案 WebKit 将处理常见的方案 例如 https、file 和 about 但对于自定方案 例如这个 lakes 方案 URLSchemeHandler 协议 使应用程序代码能够 处理 lakes 方案 URL 的 资源加载 要实现你自己的 自定方案处理程序 需创建一个符合 URLSchemeHandler 协议的类型 并实现这个协议的 reply 函数 返回包含 URLSchemeTask 结果的异步序列 这个函数还提供了 一个 URLRequest 参数 用于决定响应方式 创建事件序列时 首先需要生成 包含 URLResponse 的 URLSchemeTaskResult 生成 URLResponse 后 只需提供一些 Data 这适用于大多数情况 但有时需要 异步流式传输数据 得益于 AsyncSequence 返回类型 这也能轻松实现 这里我异步 获取单个响应 还会收到数据值的 AsyncSequence 然后将它添加到返回的序列中 如果 URL 方案任务中途被取消 函数内的任务也会自动取消 在我的 App 中 我想预先填充并加载 一些湖泊数据 让用户可以直接开始使用 为实现这项功能 我将在 App 中 放入 HTML 和 CSS 资源 然后使用刚创建的 自定方案处理程序 现在只需向 WebPage 注册 方案处理程序 为此 我将使用要处理的方案 创建一个 URLScheme 这里我还是使用 lakes 如果提供的是 WebKit 已处理的方案 构造器会返回 nil 然后创建 WebPage 配置 并将方案处理程序添加到 它的 urlSchemeHandlers 字典中 此外 还要确保 在创建 WebPage 时 传入配置 这样 现在可以创建一些 默认的 LakeArticle 值 并为这些值提供自定方案的 URL 以便从捆绑包中 保存的资源加载网页内容 而不是从网络获取 现在我们了解了如何 加载和导航到新页面 当页面载入完成后 我想在边栏填充目录 这可以通过观察网页内容的 导航事件实现 非常简单 现在 可以通过 WebPage 上的 新 Observable 属性 currentNavigationEvent 轻松访问导航状态 获得这个事件后 可以获取它的导航 ID 然后根据事件类型采取一些行动 现在 我知道导航事件的类型很多 因此我们来看看 不同的导航事件类型 导航由多个连续事件组成 导航始终始于 startedProvisionalNavigation 如果服务器重定向请求 可能会 收到 receivedServerRedirect 事件 当页面开始接收主框架的内容时 会收到 committed 事件 导航完成时 会收到 finish 事件 但并不总是能保证收到这个事件 导航也可能在任何时候失败 这时会发出 failed 或 failedProvisionalNavigation 事件 当新导航开始时 currentNavigationEvent 属性 现在会反映这个导航 通常需要能够持续响应 任何导航事件 例如用户点按链接时 或者调用 load 函数时

这可以通过 Swift 6.2 中的 新 Observations API 实现 我会使用 Observations 从 currentNavigationEvent 创建异步序列 然后使用 for-await 循环 观察当前事件的每次变化 这样 既能处理 出现的任何错误 也能在文章加载完成后 更新文章的各个部分 这样响应网页内容的导航变化 比以往任何时候 都更容易 除了 currentNavigationEvent WebPage 上还有许多其他属性 我们可以观察这些属性的变化情况 而且所有这些属性都能 与 SwiftUI 完美配合 例如 我希望详情视图的导航栏 显示文章的标题 只需将 navigationTitle 设置为 WebPage 的 title 属性即可 这真的很简单 除了页面标题外 还有很多有用的属性 例如当前 URL、 预估加载进度 以及页面的主题颜色等等 这些属性非常有用 但有时需要从页面获取 非标准属性的特定信息 这就需要更灵活的方式 而我们也让这变得很简单 你可以直接使用 新的 callJavaScript API 评估 JavaScript 以便与页面通信 只需像平常一样 编写 JavaScript 函数 然后在使用 callJavaScript 时传入这个函数 callJavaScript 的返回类型 是可选的 Any 值 因此应确保将它转换为适当的 Swift 类型 以便使用起来更容易 这让实现 parseSections 函数变得轻松 只需使用页面的 HTML 并获取 每个部分的所有 ID 和标题即可 我还会将结果转换为 Section 结构体数组 以便更容易处理

现在 App 一加载就会在边栏中显示 文章的各个部分 WebPage 还让你能够使用新的 WebPage.NavigationDeciding 协议 完全按照你的需求 自定导航策略 在我的 App 中 我将实现 自定导航策略 让网页内容的导航 按照我所期望的方式进行 如果页面中有 指向外部网站的链接 我绝对希望它 在默认浏览器中打开 而不是在我的 App 中载入 这可以通过创建新的 NavigationDecider 类型实现 这个类型符合 WebPage.NavigationDeciding 这个协议允许 为导航的不同阶段 指定不同策略 例如导航前、 收到响应时 和需要认证时 由于我想根据 URL 决定 是否允许导航 因此要为导航操作指定策略 这个函数提供了 导航中使用的 NavigationAction 以及可根据 请求调整的 NavigationPreferences 如果 url 方案是 lakes 或者 host 是 lakes.apple.com 我会允许导航 因为这意味着 链接是 App 自带的 而不是外部链接 否则 我不希望 App 中的 WebPage 继续导航 因此 我会取消导航并更新 ArticleViewModel 的 urlToOpen 属性 现在有了自定 NavigationDecider 我需要设置 WebPage 来使用它 回到 ArticleViewModel 我将创建新的 NavigationDecider 以及新的 urlToOpen 属性 然后更新 WebPage 以传入 NavigationDecider 这样 它便会使用之前指定的策略 现在 WebPage 已经配置完毕 还有最后一步 就是 将这些功能整合在一起

在 ArticleView 中 我将监听 模型 urlToOpen 属性的变化 如果属性为非 nil 值 我就知道导航已取消 因此我将使用 openURL SwiftUI 环境值 在默认浏览器中打开 URL 现在 导航完全按预期运行 接下来我们看看如何使用 不同的视图修饰符自定 用户与网页内容的交互方式 首先我们来配置滚动行为 让网页视图只能垂直回弹 默认情况下 网页视图在滚动超过 垂直或水平边缘时会回弹 即使内容小于网页视图也是如此 标准的 scrollBounceBehavior 修饰符 可以自定这个行为 并与 WebView 完美配合 要将水平轴配置为 仅在内容大于视图时回弹 可以为水平轴设置 .basedOnSize 值 这只是 WebView 支持的众多强大 滚动自定功能之一 不过不止这些 今年 visionOS 新增了 “Look to Scroll”功能 只需一个视图修饰符 即可轻松配置这个功能

在 visionOS 上 当使用新的 webViewScrollInputBehavior 修饰符时 WebView 支持新的 look ScrollInputKind 默认情况下 WebView 中 会停用“Look to Scroll”功能 由于我们想在 App 中启用这个功能 因此我将使用修饰符并 将它的行为设置为启用注视类型 其中一些文章很长 因此我们想让用户 能方便地 找到所需内容 为了让用户 能轻松搜索文章 我们来添加页面内查找功能支持 现有的 findNavigator 修饰符已能 与 WebView 完美配合 因此支持页面内查找功能 非常简单 要显示查找导航器 我将在 App 的工具栏中 添加一个按钮 在 iOS 和 iPadOS 上 查找导航器 会在屏幕键盘可见时显示 或位于网页视图底部 在 macOS 和 visionOS 上 它显示在网页视图顶部 我觉得这个 App 现在已经很完整了 下面我们来打造出色的滚动体验 让它使用起来更加方便 浏览文章的另一种简单方式 是在边栏中选择一个部分 让网页视图滚动到那个部分 我需要将网页视图的滚动位置 与所选部分同步 让用户知道自己的位置 首先我来添加一些功能 当用户轻点边栏中的某个部分时 网页视图会滚动到那个部分 要滚动到某个部分 我需要确定它的位置 这可以通过之前设置的 JavaScript 函数来实现 为了运行这个脚本 我将再次使用 callJavaScript 不过这次还会提供参数字典 这个字典中的键在 JavaScript 中 表示为局部变量 值会转换为 JavaScript 值 这种方式非常强大 且易于使用 能创建可重复使用的 通用 JavaScript 函数 在 ArticleView 中 我要添加一些状态 来控制滚动位置和部分 通过使用新的 webViewScrollPosition 修饰符 可以将滚动位置与 WebView 相关联 现在 我需要做的就是 在部分发生变化时设置滚动位置 只需对滚动位置使用 scrollTo 方法 并为它提供这个部分的计算位置 现在可以通过边栏滚动到某个部分 我还希望边栏 随滚动更新 新的 WebView onScrollGeometryChange 修饰符 让你能实现 这一点和更多功能 每当 WebView 滚动几何结构的 任何部分发生变化时 比如内容偏移或大小发生变化时 修饰符将使用你提供的转换 并在转换后的值 发生变化时调用闭包 在闭包中 我将计算 最接近新滚动偏移的部分 并更新所选部分 就像这样 所选部分和滚动位置 现在将完全同步 到目前为止“Lakes App”已完成 我觉得进展非常顺利 我结合了 WebPage 和 WebView 来加载和显示文章 甚至用一些默认文章 预先填充了 App 我还通过在边栏显示 目录和同步滚动位置 增强了用户体验 今天我们介绍了很多内容 现在让我们来复习一下所学的内容 适用于 SwiftUI 的 WebKit 是一个简单而强大的 API 支持将网页内容无缝集成到 App 中 提供加载和自定 网页内容外观的能力 URLSchemeHandling 让你能有效地 管理本地网页资源 此外 还有一组强大的视图修饰符 比如 webViewScrollPosition 和 findNavigator 让你能自定 WebView 的用户体验 这些只是适用于 SwiftUI 的 WebKit 的部分功能 强烈建议参考开发者文档 获取更全面的信息 当然 由于这是 SwiftUI 网页内容在所有平台上 都会看起来很棒

如果你已在 SwiftUI App 中 使用 UIKit 或 AppKit WebKit API 或者正在从头开发 App 现在是尝试迁移到新 API 的好时机 也请务必查看 Swift 和 SwiftUI 的新功能 例如新的 Observations API 最后 在尝试这个新 API 后 请分享你的反馈 包括你认为缺失的 任何更改或功能 希望大家加入我们 一起迎接 WebKit 这个美妙的新时代