XuqmGroup-AndroidSDK/sdk-webview

sdk-webview

XuqmGroup Android SDK WebView 模块。提供嵌入式 WebView 组件和独立页面，内置 JSBridge、文件选择、下载拦截。

依赖

implementation("com.xuqm:sdk-webview:VERSION")
implementation("com.xuqm:sdk-core:VERSION")  // 必须

使用

嵌入式组件

import com.xuqm.sdk.webview.XWebViewView
import com.xuqm.sdk.webview.XWebViewConfig

XWebViewView(
    config = XWebViewConfig(
        url = "https://example.com",
        title = "嵌入式网页",
    ),
)

独立页面

import com.xuqm.sdk.webview.openXWebView
import com.xuqm.sdk.webview.XWebViewConfig

openXWebView(XWebViewConfig(url = "https://example.com", title = "独立页面"))
// navigate("xwebview") 后使用 XWebViewScreen()

XWebViewConfig 参数

参数	类型	默认值	说明
url	String	""	初始加载地址
title	String	""	页面标题
hideToolbar	Boolean	false	隐藏顶栏
hideStatusBar	Boolean	false	隐藏状态栏
userAgent	String?	null	自定义 User-Agent
injectedJavaScript	String?	null	注入的 JS
jsBridgeName	String	"XWebViewBridge"	JS 桥接对象名
debugEnabled	Boolean	false	开启远程调试
downloadDestination	FileDownloadDestination	Sandbox	下载存储目标
downloadNotificationTitle	String?	null	通知栏下载进度
onMessage	(String) -> Unit?	null	H5 消息回调

JSBridge 通信

// H5 → Native
window.XWebViewBridge.postMessage(JSON.stringify({ type: 'login', token: '...' }))

// 监听下载进度
window.addEventListener('__xwvDownloadProgress', (e) => { ... })
window.addEventListener('__xwvDownloadDone', (e) => { ... })

文件选择与拍照

• <input type="file"> + accept="image/*" + capture → 系统相机
• <input type="file"> + .docx/.xlsx → 文件选择器
• getUserMedia() WebRTC → 自动请求 CAMERA 权限

公共 Downloads

downloadDestination = FileDownloadDestination.PublicDownloads 时，WebView 直接复用 common 文件能力：Android 10 及以上通过 MediaStore 写入系统 Downloads。该流程不会 申请 MANAGE_EXTERNAL_STORAGE，不会跳转“所有文件访问权限”设置页，也不会因未授予 该敏感权限而中断下载。Android 9 及以下仍遵循系统的 WRITE_EXTERNAL_STORAGE 运行时权限规则。只有启用下载通知且运行于 Android 13 及以上时，宿主才可能需要处理通知权限。