webkit-integration

SwiftUI 向け WebKit 統合

ネイティブの WebView 構造体と監視可能な WebPage クラスを使用して、SwiftUI アプリに Web コンテンツを埋め込み、制御します。読み込み、ナビゲーション、JavaScript の実行、ビューのカスタマイズについて説明します。

このスキルが有効になる条件

• SwiftUI アプリ内に Web コンテンツを表示したい
• Web ビューで URL、HTML 文字列、またはデータの塊を読み込みたい
• SwiftUI からの JavaScript 連携について質問している
• 埋め込まれた Web コンテンツのナビゲーション（戻る、進む、再読み込み）を制御したい
• Web ビューの動作（ジェスチャ、テキスト選択、リンクのプレビュー）をカスタマイズしたい
• 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	最低 OS バージョン	インポート
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 と併せて import 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/ を参照してください
• Web コンテンツを取り巻くLiquid Glassデザインについては、design/liquid-glass/ を参照してください

References

• WebView (SwiftUI)
• WebPage
• WKContentWorld
• WKSnapshotConfiguration