用途:在 SwiftUI 应用中嵌入并管理网页内容,使用面向 iOS 26、iPadOS 26、macOS 26、visionOS 26 的原生 WebKit-for-SwiftUI API。适用于应用内集成网页界面、自有关 HTML 内容、JavaScript 页面交互或自定义导航策略控制的场景。
选型:简单渲染 URL 用 WebView(url:),由 SwiftUI 状态驱动导航;需要直接加载请求、观察状态、调用 JavaScript 或自定义导航行为时创建 WebPage。每个可见 WebView 一次只能关联一个 WebPage。模态浏览用 SFSafariViewController(仅 iOS/iPadOS),macOS 或 visionOS 外部浏览用 openURL/默认浏览器,OAuth 或第三方登录用 ASWebAuthenticationSession,低于 iOS 26 或需要旧版 WebKit 功能时回退 WKWebView。
主要能力:WebPage 是 @MainActor 可观察类型,提供 load(URLRequest)、load(URL)、load(html:baseURL:) 等入口,以及 title、url、isLoading、estimatedProgress、currentNavigationEvent、backForwardList 等可观察属性;可通过 page.navigations 异步序列观察每次导航事件。WebPage.NavigationDeciding 可按请求或响应允许、取消或定制导航,常用于把自有域保留在应用内、外部域交给 openURL、拦截回调 URL 及调整 NavigationPreferences。callJavaScript(_:arguments:in:contentWorld:) 可对页面执行 JavaScript,应传入函数体而非包装声明,Swift 值优先通过 arguments 传入。WebPage.Configuration 与 URLSchemeHandler 支持捆绑 HTML、离线文档和自定义 scheme 资源。WebView 还提供返回/前进手势、页内查找、滚动位置等修饰符。
限制与提醒:该 API 未提供 WKScriptMessageHandler 的明显直接替代,JS 到原生信令需用导航或回调 URL 变通并注明。避免用嵌入式 WebView 做 OAuth,避免对正常远程内容滥用自定义 scheme,注意 WebPage 主线程隔离,callJavaScript 返回值需防御性转换,navigations 循环要用 try/catch。参考资料在 references/loading-and-observation.md、navigation-and-javascript.md、local-content-and-custom-schemes.md、migration-and-fallbacks.md。