鸿蒙 PC Markdown 编辑器 Bridge 协议：原生外壳与 Web 内核的状态同步

鸿蒙 PC Markdown 编辑器 Bridge 协议原生外壳与 Web 内核的状态同步OhMarkdown把系统文件、标签和窗口放在 ArkUI把 CodeMirror和 Markdown渲染放在 ArkWeb。两端不能共享内存只能通过协议传递状态。若协议没有明确方向、类型、频率和身份连续输入会造成性能问题异步回调还可能写错标签。本文拆解双向 Bridge的接口、节流、命令快照、参数编码和失败降级。代码位于 https://gitcode.com/VON-/codex_md_oh对应提交3a9146e。两条方向各有职责Web到原生使用 JavaScript Proxy适合事件.javaScriptProxy({object:this.editorBridge,name:ohMarkdownBridge,methodList:[onReady,onState,onChange,onSnapshot,onCommand],controller:this.editorController})原生到 Web使用runJavaScript适合命令设置文档、激活会话、切换模式、查找、跳转、主题和导出。高频滚动留在 Web内部不跨 Bridge。代理对象只暴露白名单classEditorBridge{onReady():void{this.readyHandler();}onState(wordCount:number):void{this.stateHandler(wordCount);}onChange(wordCount:number,dirty:boolean):void{this.changeHandler(wordCount,dirty);}onSnapshot(content:string,revision:number):void{this.snapshotHandler(content,revision);}}Web不能访问任意 ArkTS方法。接口名与参数固定业务回调通过构造函数注入。methodList是运行时能力面TypeScript声明是 Web编译期契约两者都要同步审查。Ready 是初始化屏障ArkWeb页面加载期间原生不能假设OhMarkdownEditor已存在。onReady后privateonEditorReady():void{this.editorReadytrue;this.setEditorDocument(this.documentContent);this.setEditorMode();this.setEditorSyncScroll();this.setEditorTheme();if(!this.recoveryChecked){this.recoveryCheckedtrue;this.checkStartupRecords();}}原生重放权威状态。页面重载后不依赖旧 Web内存。runEditorScript在editorReadyfalse时返回调用失败会把 ready重置避免继续向失效页面发命令。状态与正文分开传普通输入只向原生发送字数和 dirtyfunctionflushToNative(content?:string):void{window.clearTimeout(bridgeTimer);if(pendingNativeChange){constwordCountlargeDocumentMode?-1:countWords(content??editor.state.sliceDoc());window.ohMarkdownBridge?.onChange(wordCount,pendingDirty);pendingNativeChangefalse;}}每键传全文会导致文档越大输入越慢。全文只在恢复快照、保存命令和标签切换主动捕获时传递。协议按数据成本拆分而不是一个onEverythingChanged。输入通知有长度相关防抖constdebounceMillisecondsdocumentLength1024*1024?600:160;window.clearTimeout(bridgeTimer);bridgeTimerwindow.setTimeout(flushToNative,debounceMilliseconds);普通文档160毫秒更新状态栏大于一兆延长到600毫秒。防抖只传轻状态恢复另用1.5秒节流全文。两类计时器不能混用状态栏允许停顿后更新恢复必须在持续输入中周期落盘。命令携带一致快照requestCommand:(command){flushToNative();if(commandsave){flushRecoverySnapshot();pendingSaveDocumenteditor.state.doc;}constcontentcommandsave?editor.state.sliceDoc():;window.ohMarkdownBridge?.onCommand(command,content);}CtrlS先刷新 dirty固定保存基线再发送当前正文。Open、Find、New不需要全文。命令和内容在同一回调中避免原生收到命令后再异步查询导致版本变化。恢复快照有 revisiononSnapshot(content, revision)让原生识别版本并保存格式。原生限制五兆、非负整数不能信任 Web输入。写入队列合并中间版本避免多个回调并行写沙箱。标签切换清除旧会话 Bridge和恢复定时器防止甲的延迟事件在乙激活后到达。长期更强协议应让每个回调显式携带 sessionId减少对“当前活动会话”的隐含依赖。原生到 Web 参数结构化编码this.runEditorScript(window.OhMarkdownEditor?.activateSession(${JSON.stringify(session.id)},${JSON.stringify(session.content)},${JSON.stringify(session.dirty)}));正文、查询和文件名可能包含引号、反斜杠与换行必须JSON.stringify。手工单引号拼接既会语法错误也有脚本注入风险。布尔和数字也统一生成合法字面量。接口只调用window.OhMarkdownEditor白名单不把任意脚本暴露给用户输入。字符串返回要 JSON 解码runJavaScript的字符串结果可能是 JSON字符串表示privatedecodeJavaScriptString(result:string):string{try{returnJSON.parse(result)asstring;}catch(_){returnresult;}}活动正文和导出 HTML都经过解码否则外层引号、\n和转义会写入文件。数字搜索结果用Number.parseInt布尔打印结果与true明确比较不把所有返回值混成一种解析。Web API 是窄能力集合OhMarkdownEditor?:{setSessionDocument(...):void;activateSession(...):void;closeSession(sessionId:string):void;getDocument():string;setMode(mode:ViewMode):void;find(...):number;replaceAll(...):number;jumpToOffset(offset:number):boolean;setTheme(theme:light|dark):void;exportHtml(title:string):string;}原生不直接查询 DOM类名或操作 CodeMirror内部字段。Web实现可以升级只要保持协议。主题和同步滚动只传意图不传 CSS或具体 scrollTop。失败降级捕获正文失败时保留原生最近documentContent不覆盖为空。runEditorScript失败将 editorReady置 false等待页面重新 ready重放。搜索失败只更新状态栏保存失败保留 dirty与恢复记录。错误日志不能包含正文和 URI。协议可观测应记录方法、耗时、长度、revision和错误类型不记录用户数据。安全配置缩小 Web 能力.javaScriptAccess(true).domStorageAccess(false).onlineImageAccess(false).fileAccess(false).geolocationAccess(false).zoomAccess(false)JavaScript是 CodeMirror必需其他不需要能力关闭。Web资源打成离线单 HTML不依赖网络。Bridge最小化与 ArkWeb权限收缩共同构成边界不能只靠 CSP。鸿蒙 PC 实际协同下图中原生文件面板、标签和状态栏与 Web编辑区同屏。标签切换、dirty、字数和模式都通过协议同步但用户不应感知运行时边界。测试应覆盖多行字符串、空值、emoji、大正文、页面重载、命令重复、旧定时器和接口不存在。协议测试比单一 UI截图更能发现序列化错误。版本演进当前双方随 HAP一起发布未显式交换协议版本。随着接口增长可在 onReady携带版本和能力列表原生只调用双方共同能力。不兼容时显示编辑器资源错误而不是静默返回空值。消息对象比位置参数更易扩展例如{ sessionId, revision, dirty, wordCount }。但对象通过 Proxy的支持与序列化成本需在 HarmonyOS环境验证。当前小接口保持直接类型避免无必要抽象。性能边界全文 Bridge会产生字符串序列化和内存副本。五兆以上禁用周期快照标签切换仍需捕获全文。未来增量同步可传 transaction changes原生按 revision应用丢包时请求完整快照校正。高频滚动、光标移动和预览 DOM绝不跨 Bridge。只有产品状态和持久化需要的数据穿越边界才能保持输入流畅。当前边界回调未显式携带 sessionId没有协议版本协商字符串解码运行时类型检查可加强大文档切换仍传全文ArkWeb重载只恢复原生已捕获正文不恢复完整 EditorState历史。结语OhMarkdown Bridge把事件和命令分向设计Web主动报告 ready、轻状态、恢复快照和命令原生发送文档、会话、模式、搜索与主题。轻状态防抖、全文受限、参数 JSON编码、返回按类型解析、失败保留旧值。混合鸿蒙 PC编辑器的可靠性取决于这份协议是否像文件格式一样被认真对待。边界清楚ArkUI和 ArkWeb才能各自发挥优势而不互相泄漏复杂度。