webkit-integration

SwiftUI 的 WebKit 集成

使用原生的 WebView 结构体和可观察类 WebPage，在 SwiftUI 应用中嵌入和控制网页内容。涵盖加载、导航、JavaScript 执行和视图自定义。

此技能的触发条件

• 用户想在 SwiftUI 应用中显示网页内容
• 用户需要在 Web 视图中加载 URL、HTML 字符串或数据块
• 用户询问如何从 SwiftUI 与 JavaScript 交互
• 用户需要控制嵌入式网页内容的导航（后退、前进、重新加载）
• 用户想自定义 Web 视图行为（手势、文本选择、链接预览）
• 用户需要捕获网页内容的快照或导出 PDF
• 用户询问如何拦截导航请求或处理自定义 URL 方案
• 用户想配置无痕浏览或自定义用户代理

决策树

What do you need?
|
+-- Display a URL or HTML content
|   +-- Simple, no interaction needed
|   |   +-- WebView(url:) --> see webview-basics.md
|   +-- Need loading state, reload, custom config
|       +-- WebPage + WebView(page) --> see webview-basics.md
|
+-- Navigate programmatically (back, forward, intercept)
|   +-- Back/forward list, navigation events
|   |   +-- see navigation.md
|   +-- Intercept or cancel navigation requests
|       +-- NavigationDeciding protocol --> see navigation.md
|
+-- Execute JavaScript or communicate with web content
|   +-- callJavaScript, arguments, content worlds
|       +-- see javascript-advanced.md
|
+-- Capture snapshots, export PDF, web archive
|   +-- page.snapshot(), page.pdf(), page.webArchiveData()
|       +-- see javascript-advanced.md
|
+-- Handle custom URL schemes
    +-- URLSchemeHandler protocol --> see javascript-advanced.md

API 可用性

API	最低操作系统版本	导入
WebView	iOS 26 / macOS 26	SwiftUI + WebKit
WebPage	iOS 26 / macOS 26	WebKit
WebPage.Configuration	iOS 26 / macOS 26	WebKit
NavigationDeciding	iOS 26 / macOS 26	WebKit
WKContentWorld	iOS 14 / macOS 11	WebKit
WKSnapshotConfiguration	iOS 11 / macOS 10.13	WebKit
WKPDFConfiguration	iOS 14 / macOS 11	WebKit

快速入门

最简单的用法

import SwiftUI
import WebKit

struct BrowserView: View {
    var body: some View {
        WebView(url: URL(string: "https://developer.apple.com")!)
    }
}

使用 WebPage 实现完整控制

import SwiftUI
import WebKit

struct ControlledBrowserView: View {
    @State private var page = WebPage()

    var body: some View {
        WebView(page)
            .onAppear {
                page.load(URLRequest(url: URL(string: "https://developer.apple.com")!))
            }
    }
}

常见错误

错误	问题	修复方法
需要控制导航时使用 WebView(url:)	无法访问后退/前进、重新加载或事件	使用 WebPage + WebView(page)
除 import SwiftUI 外忘记导入 WebKit	WebView 属于 SwiftUI，但 WebPage 需要 WebKit	始终同时导入两者
未观察 currentNavigationEvent	无法获取加载状态，错误也容易被忽略	使用 onChange(of: page.currentNavigationEvent)
页面加载完成前调用 callJavaScript	DOM 尚未就绪，脚本会执行失败	等待 .finished 导航事件
无痕浏览时使用持久化数据存储	用户数据会保存到磁盘	在 WebsiteDataStore 上使用 .nonPersistent()
未处理 decidePolicyFor(navigationAction:) 返回的 nil	本应取消的导航仍会继续	返回 nil 以取消，返回 NavigationPreferences 以允许
传递 JavaScript 时未绑定参数	容易受到注入攻击，且难以调试	对命名值使用 arguments: 参数

检查清单

• 需要简单显示之外的控制时使用 WebPage
• 已导入 SwiftUI 和 WebKit
• 已观察导航事件，以显示加载指示器并处理错误
• JavaScript 执行会等待页面加载完成
• 无痕浏览使用 .nonPersistent() 数据存储
• 导航拦截返回正确的值（允许时返回偏好设置，取消时返回 nil）
• JavaScript 参数通过 arguments: 参数传递，而非使用字符串插值
• 页面加载前已在配置中注册自定义 URL 方案处理程序
• 如有需要，使用 findNavigator(isPresented:) 启用页面内查找
• 已应用适当的手势和交互修饰符（后退/前进、缩放、文本选择）
• 如有需要，已自定义内容背景以便与视觉设计融合

参考文件

文件	内容
webview-basics.md	WebView 创建、WebPage 设置、配置、页面内查找、自定义修饰符
navigation.md	内容加载、后退/前进列表、导航事件、NavigationDeciding 协议
javascript-advanced.md	JavaScript 执行、内容世界、快照、PDF 导出、自定义 URL 方案

交叉引用

• 有关 Web 视图周边的 macOS 窗口管理，请参阅 macos/architecture-patterns/
• 有关承载 Web 视图的 导航架构，请参阅 ios/navigation-patterns/
• 有关网页内容周边的 Liquid Glass 设计，请参阅 design/liquid-glass/

References

• WebView (SwiftUI)
• WebPage
• WKContentWorld
• WKSnapshotConfiguration