在 Compose 中封装 WebView

如需在 Jetpack Compose 中使用 WebView，您必须将其封装在 AndroidView 中。本指南介绍了常见的使用场景，以及如何在 Compose 中支持这些场景。

警告： 如果您有复杂的 WebView 使用情形，我们建议您不要迁移该布局以使用 Compose，直到 Compose WebView 等效项可用为止。如需了解详情并跟踪新 API 支持的进度，请关注此问题。

使用 AndroidView 封装 WebView

如需在 Compose 中使用 WebView，请使用 AndroidView 将其封装起来：

@Composable
fun SimpleWebView(
    initialUrl: String,
    modifier: Modifier = Modifier
) {
    AndroidView(
        modifier = modifier.fillMaxSize(),
        factory = { context ->
            WebView(context).apply {
                webViewClient = WebViewClient()
                settings.javaScriptEnabled = true
                loadUrl(initialUrl)			
            }
        }
    )
}
WrapWebViewInCompose.kt

这适用于在应用内显示简单网址。不过，WebView 处理的是与 Android View 生命周期和 Compose 生命周期分开的复杂状态生命周期。集成 Compose 可能会引入复杂的 WebView 场景，从而导致难以解决的 bug。以下部分介绍了可能需要特殊处理才能支持这些功能的用例。

保留 WebView 状态

在 Compose 中处理配置更改和导航是一项具有挑战性的任务，因为 WebView 是绑定到其宿主 Activity 的旧版 View，并且不建议其实例的生命周期长于 Activity 的生命周期。

因此，持久保存 WebView 状态的标准方法是允许 WebView 实例与 Activity 一起销毁和重新创建。您可以使用 Bundle 手动持久保存其内部导航历史记录和滚动状态。

注意： 对于仅包含 Compose activity 的应用，您最好通过在清单中处理配置变更来完全避免 activity 重新创建（请参阅处理配置变更）。直接处理更改可提高性能，并有助于保留 WebView 的内部状态。

@Composable
fun PersistentWebView(url: String) {
    val webViewStateBundle = rememberSaveable { Bundle() }

    AndroidView(
        factory = { context ->
            WebView(context).apply {
                webViewClient = WebViewClient()
                settings.javaScriptEnabled = true

                // Restore the state and history
                if (webViewStateBundle.containsKey("WEBVIEW_STATE")) {
                    restoreState(webViewStateBundle.getBundle("WEBVIEW_STATE")!!)
                } else {
                    loadUrl(url)
                }
            }
        },
        onRelease = { releasedWebView ->
            // Save navigation history before the instance is destroyed
            val bundle = Bundle()
            releasedWebView.saveState(bundle)
            webViewStateBundle.putBundle("WEBVIEW_STATE", bundle)
        },
        modifier = Modifier.fillMaxSize()
    )
}
WrapWebViewInCompose.kt

注意： 虽然此方法会保留导航历史记录和滚动状态，但在重新创建 Activity 时，DOM 状态会丢失。

处理返回导航

当 WebView 具有导航历史记录时，系统返回手势应在 WebView 内向后导航，而不是退出屏幕。

使用 Compose BackHandler API 拦截系统返回事件，并调用 WebView goBack() 函数：

// ...
@Composable
fun BackNavigationDemoScreen(onBack: () -> Unit) {
    // Hold a reference to the WebView to check its history state
    var webViewReference by remember { mutableStateOf<WebView?>(null) }

    // Intercept the system back press if the WebView has history
    BackHandler(enabled = true) {
        val webView = webViewReference
        if (webView != null && webView.canGoBack()) {
            webView.goBack() // Go back in history
        } else {
            onBack() // Exit screen
        }
    }

    Scaffold(
        topBar = {
            TopAppBar(
                title = { Text("Back Navigation Demo") },
                navigationIcon = {
                    IconButton(onClick = onBack) {
                        Icon(Icons.AutoMirrored.Filled.ArrowBack, contentDescription = "Back")
                    }
                }
            )
        }
    ) { padding ->
        Column(modifier = Modifier.fillMaxSize().padding(padding)) {
            AndroidView(
                modifier = Modifier.fillMaxSize(),
                factory = { context ->
                    WebView(context).apply {
                        settings.javaScriptEnabled = true

                        // Keeps link navigations internal to the WebView instead of opening Chrome
                        webViewClient = WebViewClient() 

                        loadUrl("https://developer.android.com")
                        webViewReference = this
                    }
                },
                onRelease = {
                    webViewReference = null
                }
            )
        }
    }
}
WrapWebViewInCompose.kt

此实现方式提供浏览器样式的导航行为。

嵌套滚动

在 Compose 中使用 WebView 时，不容易支持嵌套滚动。将 WebView 放置在可滚动的 Compose 容器（例如 LazyColumn）中时，WebView 可能会消耗所有滚动手势。由于 WebView 依赖于其自身的内部渲染引擎，因此目前无法正常地将其与 LazyColumn 嵌套使用。

如需跟踪 WebView 的官方嵌套滚动支持的进度，请参阅此问题。

无边框布局和窗口边衬区

使用全屏布局时，WebView 内容可能会显示在状态栏等系统栏下方。您可以使用 windowInsetsPadding 修饰符将整个 WebView 推送到安全区域：

@Composable
fun EdgeToEdgeDemo(url: String) {
    AndroidView(
        modifier = Modifier
            .fillMaxSize()
            .windowInsetsPadding(WindowInsets.systemBars),
        factory = { context ->
            WebView(context).apply {
                loadUrl(url)
            }
        }
    )
}
WrapWebViewInCompose.kt

如需详细了解边衬区，请参阅了解 WebView 中的窗口边衬区。

注意： 如果您控制网站内容，请使用 CSS 安全区域变量。WebView 引擎会根据设备的状态栏自动计算 env(safe-area-inset-top)。在 CSS 中使用此变量可在布局中添加安全边衬区。

将应用主题与 WebView 内容同步

当应用在浅色模式和深色模式之间切换时，如果处理得当，WebView 内容可以自动更新，而无需重新加载页面。

如果您拥有网页内容，则为了使颜色与应用的主题保持同步，请处理媒体查询 prefers-color-scheme，确保网页能够适应所选的主题。

如需让下拉菜单和弹出式窗口等原生元素能够检测并匹配应用主题，请将 DayNight 样式主题应用到 Activity.

<resources>

    <!-- ...
    <!-- Use a DayNight theme in your manifest to handle both modes automatically -->
    <style name="Theme.Webviewdemo.DayNight" parent="Theme.AppCompat.DayNight.NoActionBar" />
</resources>

@Composable
fun ThemeSyncDemo(onBack: () -> Unit) {
    val context = LocalContext.current
    AndroidView(
        modifier = Modifier.fillMaxSize(),
        factory = { _ ->
            WebView(context).apply {
                settings.javaScriptEnabled = true
                webViewClient = WebViewClient()
                val html = """
                            <html>
                            <head>
                                // ...


                                    @media (prefers-color-scheme: dark) {
                                        body {
                                            background-color: #212121;
                                            color: #ffffff;
                                        }
                                        select {
                                            border-color: #BB86FC;
                                            background: #212121;
                                            color: #ffffff;
                                        }
                                    }
                                </style>
                            </head>
                            // ...
                            </html>
                        """.trimIndent()
                loadDataWithBaseURL(null, html, "text/html", "UTF-8", null)
            }
        }
    )
} 
WrapWebViewInCompose.kt

如果网页没有深色主题，或者您不拥有网页内容，算法调暗功能可能有助于强制应用深色主题。已具有深色模式的现代网站会忽略此算法，而改用自己的内置样式。

在 Compose 中处理 Web 权限

当网页请求访问硬件或数据访问权限（例如摄像头、麦克风或位置信息）时，WebView会在其 WebChromeClient 中触发特定的回调。您必须处理这些回调，并确保授予相应的 Android 运行时权限。

处理摄像头和麦克风权限

当网页请求摄像头或麦克风访问权限（例如 WebRTC 或视频录制）时，WebView 会调用 WebChromeClient.onPermissionRequest。

不过，在调用 grant() 之前，您必须请求以下 Android 运行时权限：

• Manifest.permission.CAMERA
• Manifest.permission.RECORD_AUDIO

首先，为 WebView 定义一个权限处理程序，用于跟踪从 WebView 请求的 PermissionRequest：

class WebViewPermissionHandler(
    private val launcher: ManagedActivityResultLauncher<Array<String>, Map<String, Boolean>>
) {
    var pendingRequest by mutableStateOf<PermissionRequest?>(null)
        private set

    fun handleRequest(request: PermissionRequest) {
        val isTrustedOrigin = request.origin.host == "www.trusted-domain.com" || request.origin.host == "app.local" // Always verify the origin before granting request


        if (!isTrustedOrigin) {
            Log.w("WebViewPermission", "Blocked and denied permission request from untrusted origin: ${request.origin.host}")
            request.deny()
            return
        }

        val androidPermissions = mutableListOf<String>()
        request.resources.forEach { resource ->
            when (resource) {
                PermissionRequest.RESOURCE_VIDEO_CAPTURE -> androidPermissions.add(Manifest.permission.CAMERA)
                PermissionRequest.RESOURCE_AUDIO_CAPTURE -> androidPermissions.add(Manifest.permission.RECORD_AUDIO)
            }
        }

        // Save the request and launch the Android system dialog
        pendingRequest = request
        launcher.launch(androidPermissions.toTypedArray())
    }

    fun onResult(results: Map<String, Boolean>) {
        val allGranted = results.values.all { it }
        Log.d("WebViewPermission", "Kotlin: All permissions granted? $allGranted")

        if (allGranted) {
            pendingRequest?.grant(arrayOf("/* list of permissions */"))
        } else {
            pendingRequest?.deny()
        }
        pendingRequest = null
    }
}
WrapWebViewInCompose.kt

接下来，创建一个可记住 WebViewPermissionHandler 的可组合项。使用 rememberLauncherForActivityResult 请求权限：

注意： 在生产环境中，权限处理程序还应处理所有部分权限授予和拒绝用例，并向用户提供界面反馈。如需了解详情，请参阅请求运行时权限。

@Composable
fun rememberWebViewPermissionHandler(): WebViewPermissionHandler {
    val handlerState = remember { mutableStateOf<WebViewPermissionHandler?>(null) }
    val launcher = rememberLauncherForActivityResult(
        ActivityResultContracts.RequestMultiplePermissions()
    ) { results ->
        handlerState.value?.onResult(results)
    }
    return remember {
        WebViewPermissionHandler(launcher).also { handlerState.value = it }
    }
}
WrapWebViewInCompose.kt

处理 onPermissionRequest 回调中的权限。这会启动权限启动器：

@Composable
fun WebViewPermissionScreen() {
    val permissionHandler = rememberWebViewPermissionHandler()

    AndroidView(
        factory = { context ->
            WebView(context).apply {
                settings.javaScriptEnabled = true

                webChromeClient = object : WebChromeClient() {
                    override fun onPermissionRequest(request: PermissionRequest) {
                        // Simply delegate to the handler
                        permissionHandler.handleRequest(request)
                    }
                }

		   // load a web page that needs permissions
            }
        },
        modifier = Modifier.fillMaxSize()
    )
}
WrapWebViewInCompose.kt

注意： 地理定位权限的处理方式与上述代码段中所示的模式相同。为了支持位置信息访问权限，请替换 onPermissionRequest，并启用 WebView.settings.setGeolocationEnabled(true)。WebChromeClient.onGeolocationPermissionsShowPrompt在调用回调之前，请确保您的应用请求了所需的运行时位置信息权限：Manifest.permission.ACCESS_FINE_LOCATION 和 Manifest.permission.ACCESS_COARSE_LOCATION。

嵌入式 WebView 的替代方案

如果您不想嵌入 WebView，Android 还提供了其他用于显示 Web 内容的选项，例如 Chrome 自定义标签页。请参阅在 Android 应用中使用 Web 内容，了解如何为您的使用情形（例如浏览或身份验证）选择正确的方法。