XuqmGroup-RNSDK/docs/XWebView-JSBridge.md

# XWebView Bridge 边界

> 最后更新：2026-07-26

XWebView 不是业务 JSBridge 协议。它只定义一个通用适配接口：

```ts
type XWebViewBridge = {
  injectedJavaScriptBeforeContentLoaded?: string
  onMessage(raw: string, context: XWebViewBridgePageContext): boolean | Promise<boolean>
  onPageClosed?(pageId: string): void
}
```

## 页面上下文

业务协议实现可以：

- 关闭当前页；
- 向当前页执行 JavaScript；
- 判断当前页是否为页面栈顶；
- 取得真实状态栏高度；
- 修改当前页导航栏标题/背景；
- 修改当前页导航栏与状态栏显隐。

协议实现不能：

- 访问或修改其他 WebView 页面；
- 从 XWebView 读取用户、token、平台、域名或厂商；
- 直接控制宿主导航器；
- 输出原始 Bridge payload；
- 在 common 中注册全局业务 handler。

## 消息所有权

XWebView 内部只消费 `__xwv` 命名空间：

- `download` / `blobdownload` / `bloberror`
- `permission`

其他消息先交给 `config.bridge`。Bridge 返回 `false` 时才继续交给
`behavior.onMessage`。Bridge 抛错由 `behavior.onBridgeError` 接收，不产生未处理
Promise。

## 业务协议接入

业务协议必须在自己的 SDK/插件中维护唯一方法表、请求解析、响应结构、错误码和兼容
测试，然后以 `XWebViewBridge` 适配到容器。XWebView 不提供 `getSession`、`navigate`、
`showToast`、签名、支付或任何假定宿主业务的内置方法。

医网信 H5 场景使用 `@szyx/sdk-h5-app/host`；其 V5 线协议不属于
`@xuqm/rn-xwebview` 的公开契约。