[鸿蒙从零到一] HarmonyOS Web 组件与 JSBridge 通信实战：从页面加载到安全协议
[鸿蒙从零到一] HarmonyOS Web 组件与 JSBridge 通信实战：从页面加载到安全协议
在 HarmonyOS 应用中，Web 组件适合承载已有 H5 页面、富文本内容、活动页和需要快速迭代的业务界面。但网页和 ArkTS 页面属于两套运行环境：网页使用 JavaScript，原生侧使用 ArkTS；如果只是把 URL 放进 Web 组件，双方并不会自动共享状态。
真正可维护的方案，是把 Web 组件当成一个有边界的通信端点，明确加载策略、消息格式、调用方向、生命周期和安全策略。本文以“原生页面打开一个网页订单详情，网页请求原生能力并接收结果”为例，逐步搭建一套轻量 JSBridge。
一、先理解 Web 组件的职责边界
Web 组件负责在 ArkUI 页面中展示网页，并提供网页加载、导航、脚本执行和事件监听等能力。它不是把网页代码直接编译成 ArkTS，也不是一个可以随意访问应用内部对象的容器。
常见职责可以这样分工：
- 网页负责展示内容、表单交互和与网页后端的协议。
- ArkTS 负责应用身份、系统能力、页面路由和本地数据访问。
- Bridge 负责把双方真正需要交换的数据转换成明确消息。
- 业务层负责校验消息来源、参数和调用结果。
如果网页只是静态帮助文档，可以不引入 Bridge；如果网页需要调用相册、定位、支付或原生页面跳转，就应先设计协议，再编写具体接口。把所有能力都暴露给网页，后续很难收紧权限，也难以定位问题。
二、创建 Web 组件与加载页面
Web 组件通常需要一个 WebviewController。控制器负责加载页面、执行脚本以及访问导航相关能力。示例中的 API 名称和参数请以当前 DevEco Studio 对应 SDK 的类型定义为准，不同版本可能会有细节差异。
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct OrderWebPage {
private controller: web_webview.WebviewController =
new web_webview.WebviewController()
build() {
Column() {
Web({
src: 'https://m.example.com/order/detail',
controller: this.controller
})
.width('100%')
.height('100%')
.javaScriptAccess(true)
.onPageBegin(() => {
console.info('order page begin')
})
.onPageEnd(() => {
console.info('order page ready')
})
.onErrorReceive((event) => {
console.error(`web load error: ${JSON.stringify(event)}`)
})
}
.width('100%')
.height('100%')
}
}加载外部地址前，应在模块配置中声明网络访问权限，并确认域名、证书和重定向策略符合应用的网络安全要求。调试阶段可以使用本地页面，但发布环境应使用 HTTPS，并对允许访问的域名做白名单管理。
页面加载事件适合更新加载状态、记录耗时和展示错误页。不要把一次加载完成误认为 Bridge 已经可以调用：网页脚本可能还在初始化，通信通道应在网页主动发送 ready 消息后才认为可用。
三、设计稳定的消息协议
Bridge 最容易失控的地方不是发送消息，而是消息没有统一格式。建议让每条消息都包含版本、动作名、请求标识和参数，并区分请求、响应和事件。
interface BridgeRequest {
type: 'request'
version: 1
requestId: string
action: string
payload: Record<string, string | number | boolean | null>
}
interface BridgeResponse {
type: 'response'
version: 1
requestId: string
ok: boolean
data?: unknown
error?: {
code: string
message: string
}
}requestId 用于把异步结果匹配回原始请求，不能使用时间戳加动作名这种容易碰撞的组合。version 让网页和应用可以平滑升级；ok、error.code 和 error.message 让调用方能稳定处理失败，而不是解析自然语言。
动作名建议采用有限集合，例如 getAppInfo、openNativePage、selectImage。不要允许网页把任意字符串当成方法名直接反射调用。参数也要按动作单独校验，不能因为外层是 JSON 就认为内容可信。
四、网页调用原生能力
一种常见做法是由网页调用原生注入的 JavaScript 方法，原生侧收到 JSON 后解析并分发。网页侧可以封装成 Promise，让业务代码不必关心 requestId。
const pending = new Map()
function callNative(action, payload = {}) {
const requestId = `${Date.now()}_${Math.random().toString(16).slice(2)}`
return new Promise((resolve, reject) => {
pending.set(requestId, { resolve, reject })
window.arkBridge.postMessage(JSON.stringify({
type: 'request',
version: 1,
requestId,
action,
payload
}))
})
}
function receiveNativeMessage(raw) {
const message = typeof raw === 'string' ? JSON.parse(raw) : raw
if (message.type !== 'response') return
const task = pending.get(message.requestId)
if (!task) return
pending.delete(message.requestId)
message.ok ? task.resolve(message.data) :
task.reject(new Error(message.error?.message || 'native call failed'))
}这里的 window.arkBridge.postMessage 代表双方约定的通信入口，具体注入方式依赖当前 Web 组件 SDK。无论采用脚本注入、网页消息回调还是自定义 URL 协议，都应该把底层差异收敛在 Bridge 适配层，业务代码只依赖 callNative。
原生侧的处理流程可以抽象为：读取原始消息、解析 JSON、校验公共字段、校验动作参数、执行能力、返回同一个 requestId。任何一步失败都返回结构化错误，不能让异常直接穿透到 Web 组件回调。
private async handleBridgeMessage(raw: string): Promise<void> {
let request: BridgeRequest
try {
request = JSON.parse(raw) as BridgeRequest
this.validateRequest(request)
} catch (error) {
console.error(`invalid bridge request: ${JSON.stringify(error)}`)
return
}
try {
const data = await this.dispatchAction(request.action, request.payload)
this.sendResponse({
type: 'response', version: 1, requestId: request.requestId,
ok: true, data
})
} catch (error) {
this.sendResponse({
type: 'response', version: 1, requestId: request.requestId,
ok: false,
error: { code: 'NATIVE_CALL_FAILED', message: this.toSafeMessage(error) }
})
}
}五、原生侧调用网页方法
反方向的调用也很常见，例如原生完成登录后通知网页刷新用户信息。原生侧可以通过控制器执行 JavaScript，但不要直接拼接用户输入到脚本字符串中。
private notifyWebLogin(token: string): void {
const safeToken = JSON.stringify(token)
const script = `window.appEvents && window.appEvents.onLogin(${safeToken})`
this.controller.runJavaScript(script, (result) => {
console.info(`login event delivered: ${JSON.stringify(result)}`)
})
}使用 JSON.stringify 做字符串字面量编码，可以避免引号、换行或脚本片段破坏 JavaScript 语法。更复杂的数据应先序列化为 JSON，再在网页侧解析。不要采用字符串拼接的方式拼出对象，也不要把服务端返回的 HTML 当作脚本执行。
原生调用必须等待网页 ready。可以维护一个待发送队列，在网页发送 ready 事件后刷新；页面重新加载时清空旧队列和旧请求，避免把上一页面的响应交给新页面。
六、处理生命周期与并发
Web 页面会经历加载、跳转、刷新和销毁，Bridge 不能只考虑“打开后点击按钮”的理想路径。建议把以下状态作为组件内部状态机管理：
idle：控制器已创建，但页面还未准备好。loading：页面正在加载，暂不处理业务调用。ready：网页已发送协议版本匹配的 ready 消息。failed：加载或协议协商失败，拒绝新的调用。destroyed：组件销毁，清理监听器、队列和超时任务。
每个请求都应设置超时和取消策略。页面跳转或销毁时，未完成 Promise 必须统一 reject，并清理 Map，否则长时间运行的应用会积累闭包和请求对象。对于高频事件，例如滚动、输入和进度通知，使用事件消息而不是为每个变化创建一个请求。
private readonly pending = new Map<string, (result: BridgeResponse) => void>()
private rejectAllPending(code: string): void {
this.pending.forEach((resolve, requestId) => {
resolve({
type: 'response', version: 1, requestId, ok: false,
error: { code, message: 'web page is no longer available' }
})
})
this.pending.clear()
}在 onPageBegin、错误回调和组件销毁阶段调用清理逻辑，并用日志记录请求数、超时数和失败码。线上问题通常不是“完全不能通信”，而是偶发超时、页面重载后响应错配或旧监听器重复触发。
七、安全边界不能省略
Web 组件会执行网页 JavaScript，因此安全策略必须和功能设计同时完成。重点包括：
- 只加载明确允许的 HTTPS 域名，限制不必要的跳转。
- Bridge 只暴露业务必需的动作，不暴露任意系统 API、文件路径或账号令牌。
- 对来源、协议版本、动作名、参数类型和参数长度逐项校验。
- 敏感操作在原生侧再次确认用户身份和业务状态，不能只相信网页传来的字段。
- 令牌不通过 URL、日志或错误消息传递；返回网页的数据遵循最小化原则。
- 外部网页和内嵌网页分开处理，第三方内容不要获得同等原生能力。
如果 Bridge 使用自定义 URL 拦截协议，必须严格校验 scheme、host、path 和参数，避免网页通过伪造 URL 触发敏感动作。对于脚本注入方式，应固定函数名和参数编码，拒绝直接执行来自网页的任意脚本。
安全校验不是单次上线检查。域名变更、网页前端升级、Bridge 增加新动作和 SDK 升级都应重新验证，尤其要覆盖错误页面、重定向页面和离线缓存页面。
八、错误处理与可观测性
网页端应区分网络错误、协议错误、业务错误和原生能力错误。原生端也应使用稳定错误码，例如：
BRIDGE_NOT_READY：网页尚未完成握手。INVALID_REQUEST：消息格式或参数不符合协议。ACTION_NOT_ALLOWED：当前网页来源不能调用该动作。NATIVE_PERMISSION_DENIED：系统权限或用户授权不足。NATIVE_TIMEOUT：原生能力在约定时间内没有完成。
日志中记录 requestId、action、耗时、结果码和页面地址摘要即可，不要记录完整 token、身份证号、手机号或用户输入。对异常数据做脱敏后再上报。开发环境可以保留详细堆栈，生产环境返回给网页的 message 应该是可理解但不泄露内部实现的安全文本。
九、封装成可测试的 Bridge 服务
不要把消息解析、业务分发和 Web 组件控制器全部写在页面 build() 中。可以拆成三个层次：
BridgeCodec：负责 JSON 编解码和公共字段校验。BridgeRouter：负责动作白名单、参数校验和业务调用。WebBridgeAdapter：负责和 Web 组件 API 对接、发送响应以及生命周期清理。
这样可以在不启动 Web 组件的情况下测试无效 JSON、未知动作、缺失 requestId、超长参数和重复响应。真正依赖控制器的部分只需要验证脚本调用、页面重载和销毁时机。
测试清单至少应包括：页面正常加载并握手、网页调用成功、原生调用失败、连续请求乱序返回、页面刷新、网络断开、超时、重复 ready、非法来源和组件销毁。若应用支持多窗口或横竖屏切换，还要确认控制器和 Bridge 状态不会被旧页面复用。
总结
HarmonyOS Web 组件解决的是网页承载问题，JSBridge 解决的是跨运行环境协作问题。工程上最重要的不是找到一个能“传字符串”的技巧，而是建立一条有版本、有 requestId、有超时、有错误码且有安全边界的通信协议。
从页面加载开始，先等待网页完成握手，再通过白名单分发能力；从原生调用网页开始，做好参数编码、生命周期清理和失败回调。把这些规则集中在适配层后，H5 和 ArkTS 就能各自保持清晰职责，业务页面也不会被大量平台细节绑架。
浙公网安备 33010602011771号