161 行
6.2 KiB
Markdown
161 行
6.2 KiB
Markdown
# @xuqm/rn-xwebview
|
||
|
||
通用 React Native WebView 容器。`1.1.0` 只有三项正式入口：
|
||
|
||
- `<XWebViewHost />`：应用根部挂载一次的全屏页面 Host。
|
||
- `openWebView(config)`：从任意业务服务打开页面，返回该页面自己的 Handle。
|
||
- `<XWebViewView config={...} />`：不需要全屏导航栏时使用的内嵌浏览器内核。
|
||
|
||
SDK 不包含任何医网信、厂商、用户、平台、域名或业务 Bridge 定义。
|
||
|
||
## 安装
|
||
|
||
```bash
|
||
pnpm add @xuqm/rn-common @xuqm/rn-xwebview \
|
||
react-native-webview react-native-svg \
|
||
@react-native-clipboard/clipboard react-native-safe-area-context
|
||
```
|
||
|
||
`react-native-svg` 含原生 ViewManager，必须由宿主直接声明并完成 React Native
|
||
autolink；它不能只作为 `@xuqm/rn-xwebview` 的传递依赖。缺少该直接依赖时，使用
|
||
SDK 内置导航图标的页面会在运行期报告找不到 `RNSVGSvgViewAndroid`。
|
||
|
||
`@react-native-camera-roll/camera-roll` 是可选 peer；只有需要把下载图片登记到系统相册
|
||
时才安装。
|
||
|
||
## 最小集成
|
||
|
||
```tsx
|
||
import { XWebViewHost, openWebView } from '@xuqm/rn-xwebview'
|
||
|
||
export function App() {
|
||
return (
|
||
<>
|
||
<RootNavigation />
|
||
<XWebViewHost />
|
||
</>
|
||
)
|
||
}
|
||
|
||
const page = openWebView({
|
||
source: { uri: 'https://example.com' },
|
||
navigationBar: {
|
||
title: { text: '页面标题', mode: 'web' },
|
||
},
|
||
statusBar: {
|
||
translucent: true,
|
||
},
|
||
})
|
||
|
||
page.reload()
|
||
page.postMessage('hello')
|
||
page.suspend() // 临时展示宿主原生页面，WebView 实例和历史仍保留
|
||
page.resume()
|
||
page.close()
|
||
const result = await page.closed
|
||
```
|
||
|
||
Host 尚未挂载时请求最多等待 3 秒，超时以 `host_unavailable` 关闭。全局只能挂载一个
|
||
Host；Host 卸载会以 `host_unmounted` 关闭其全部页面。
|
||
|
||
## 分组配置
|
||
|
||
`openWebView` 与 `XWebViewView` 使用同一个 `XWebViewConfig`：
|
||
|
||
- `source`：`{uri, headers?}` 与 `{html, baseUrl?}` 二选一。
|
||
- `navigationBar`：标题、返回、关闭、菜单、纯色/渐变/图片背景或完整自定义渲染。
|
||
- `statusBar`：显隐、透明沉浸、背景和前景模式。
|
||
- `behavior`：Cookie、混合内容、外链决策、JS 注入、消息与生命周期回调。
|
||
- `permissions`：摄像头/麦克风白名单与可选宿主决策。
|
||
- `downloads`：自动/人工决策、目标目录、鉴权头、进度、完成和失败回调。
|
||
- `bridge`：由具体业务协议包提供；XWebView 只负责转发与页面上下文。
|
||
|
||
禁止恢复扁平的 `url/title/showTopBar` 双轨配置。
|
||
|
||
## 页面栈与系统返回
|
||
|
||
每次 `openWebView` 都生成独立页面和 Handle。页面栈只显示顶层页面，关闭后恢复下一层
|
||
页面及其导航状态。默认导航栏的左返回按钮常驻：存在网页历史时只执行网页后退，没有
|
||
历史时需要在 1 秒内再次点击才关闭当前页，第一次点击显示非阻塞提示。Android 物理
|
||
返回使用完全相同的规则。右侧关闭按钮常驻并立即关闭当前页。
|
||
|
||
宿主可以替换第一次返回时的提示；只有明确需要改变默认交互的宿主才应覆盖关闭模式或
|
||
间隔：
|
||
|
||
```tsx
|
||
const page = openWebView({
|
||
behavior: {
|
||
hardwareBack: {
|
||
onFirstClosePress: () => showToast('再按一次退出当前页面'),
|
||
},
|
||
},
|
||
source: { uri: 'https://example.com' },
|
||
})
|
||
```
|
||
|
||
宿主需要短暂展示原生页面时调用 `page.suspend()`，原生页面结束后调用
|
||
`page.resume()`；暂停不等于关闭，不触发 `closed`，也不创建第二份 WebView。
|
||
|
||
导航标题和显隐修改属于当前页面，不能污染下层页面。H5 隐藏原生导航栏但保留状态栏
|
||
时，Bridge 可以从页面上下文取得真实安全区高度。设置网络导航栏背景图片时，配置接收
|
||
后立即返回成功，图片由原生视图异步加载，不以图片探测或下载结果阻塞 H5 调用。
|
||
|
||
## 权限
|
||
|
||
SDK 不向 Manifest/Info.plist 注入敏感权限。宿主按启用能力声明，例如 Android：
|
||
|
||
```xml
|
||
<uses-permission android:name="android.permission.CAMERA" />
|
||
<uses-permission android:name="android.permission.RECORD_AUDIO" />
|
||
```
|
||
|
||
H5 调用 `getUserMedia` 时，XWebView 先检查页面配置和宿主决策，再在 Android 请求系统
|
||
权限，最后才继续 WebView 媒体请求。摄像头或麦克风必须同时启用能力并精确配置
|
||
`allowedOrigins`；当前文档跨域后不会沿用上一个 origin 的授权。未识别资源、未命中
|
||
白名单和 3 秒内未完成的自定义决策均拒绝：
|
||
|
||
```tsx
|
||
permissions: {
|
||
allowedOrigins: ['https://example.com'],
|
||
camera: true,
|
||
microphone: true,
|
||
}
|
||
```
|
||
|
||
默认菜单包含刷新、复制链接和在系统浏览器中打开，不包含关闭页面；关闭始终使用右上角
|
||
常驻按钮。宿主可通过 `navigationBar.menu.items` 替换菜单，或通过
|
||
`navigationBar.render` 自定义返回、关闭和菜单的展示与点击行为。自定义导航栏若希望
|
||
保留 SDK 的统一返回规则，应调用渲染上下文的 `onBackPress()`。
|
||
|
||
## 下载与安全默认值
|
||
|
||
- 默认保存到 App 沙盒；`publicDownloads` 在 Android 使用沙盒落盘后登记到下载列表。
|
||
- URI 首屏 headers 自动复用于 HEAD 与文件下载，也可由 `downloads.headers` 补充。
|
||
- Cookie 默认共享，第三方 Cookie 默认关闭。
|
||
- 混合内容默认 `never`；生产页面不得改为 `always`。
|
||
- `http/https/about:blank` 在容器内打开；`tel/sms/mailto` 交给系统；`file/javascript/intent`
|
||
和未知 scheme 默认拒绝。
|
||
- Bridge 异常不会形成未处理 Promise；宿主可通过 `behavior.onBridgeError` 接收不含原始
|
||
payload 的错误信息。
|
||
|
||
## 迁移到 1.0.0
|
||
|
||
旧的 `XWebViewScreen`、`XWebViewControl`、`openXWebView(navigate, flatConfig)` 和
|
||
common 内的 WebView Bridge 已删除，不提供兼容壳。
|
||
|
||
迁移原则：
|
||
|
||
1. 根部挂载一次 `<XWebViewHost />`。
|
||
2. 扁平参数转换为上述分组配置。
|
||
3. 全局 Control 改为保存本次 `openWebView` 返回的页面 Handle。
|
||
4. 业务 Bridge 单独作为 `config.bridge` 注入，不进入 common 或 XWebView。
|
||
5. 内嵌页面直接使用 `<XWebViewView />`，不再直接包装 `react-native-webview`。
|
||
|
||
## 验证
|
||
|
||
```bash
|
||
pnpm --dir packages/xwebview typecheck
|
||
pnpm --dir packages/xwebview test
|
||
pnpm --dir packages/xwebview pack:check
|
||
```
|
