社区引导:欢迎加入 KMP&CMP 鸿蒙社区,一起把鸿蒙的系统能力带给每一个跨端开发者。
仓库地址:https://atomgit.com/oh-tpc/kmp-ohos-doc-portal
Kotlin 版本:2.2.21-1.0.0(KMP OpenHarmony 适配版)
KMP/CMP 鸿蒙社区:https://atomgit.com/CPF-KMP-CMP
参考框架:https://atomgit.com/oh-tpc

0. 环境与实测设备
| 项 | 版本/型号 |
|---|---|
| DevEco Studio | 26.0.0.821(内置 hvigor / ohpm / SDK) |
| 构建 SDK | HarmonyOS 6.0.0(API 20),compatibleSdkVersion 6.0.0(20) |
| Kotlin | 2.2.21-1.0.0(KMP OpenHarmony 适配版,含 ohosArm64 / ohosX64 目标) |
| 实测设备 1 | DevEco PC 形态模拟器(2in1 免费窗口桌面,OpenHarmony 7.0.0.105,x86_64,127.0.0.1:5557) |
| 实测设备 2 | DevEco 手机模拟器 Mate 90 Pro(OpenHarmony 7.0.0.105,API 26,x86_64,127.0.0.1:5555) |
| 示例仓库 | kmp-ohos-doc-portal(docportal 核心库 + example 示例工程) |
Demo 是一个单页文档门户:顶部按钮区、文档信息区、编辑区、最近文件列表、KMP 自检区、决策日志区。所有"该不该做"的判断都由一份 Kotlin 核心库给出,ArkTS 只负责执行文件 IO 与授权 API 调用。
1. 痛点:文档 App 的"打开",是三条管线加一张时间表
做文档类应用的人对这条链路都不陌生:用户双击一个 .txt,系统用 ohos.want.action.viewData 把应用拉起,Want 里塞着一个 URI 和几个 flags;或者用户在应用里点"打开",走文件选择器;再或者,应用自己的"最近文件"列表里点一条历史记录。
三条入口,打开的是同一个文件,但授权语义完全不同:
| 入口 | 授权来源 | 写权限 | 授权寿命 | 恢复路径 |
|---|---|---|---|---|
| 双击文件关联 | 系统授予,flags 声明读写 | 看 FLAG_AUTH_WRITE_URI_PERMISSION(0x2) | 随进程死亡 | 必须进程活着时 persist |
| 文件选择器 | DocumentViewPicker 返回即带 | 默认可写 | 随进程死亡 | 同上 |
| 最近文件 | 上次进程 persist 过才有 | 与上次一致 | 持久授权休眠,activatePermission 激活 | 激活 + 校验通过即直接打开 |
这张表里最要紧的是最后一列的隐含前提:临时授权随进程死亡,把 TEMPORARY 变成 PERSISTED 的唯一手段是 fileShare.persistPermission,而它只能在上次进程还活着的时候调用——死后无法补救。换句话说,"要不要 persist"不是一条可以延后的优化建议,而是打开动作自带的、有截止时间的必答题。
于是文档 App 里真正难管的不是"打开"这个动作,而是打开之后的一整张时间表:打开时裁决要不要持久化授权 → 编辑时管住脏标记 → 保存时只允许脏会话落盘 → 进程死亡前把最近文件快照写进沙箱 → 重启后把快照拆成"可恢复"和"授权丢失"两组。这五个阶段环环相扣,任何一环判断错了,用户感知就是"文件突然打不开了"或者"保存按钮点不动"。
如果用 KMP 做跨端开发,这个问题还多一个维度:这些裁决逻辑如果散落在 ArkTS 层,那它就只属于鸿蒙端,未来扩到其他端要重写一遍,而且没有任何单元测试能覆盖它——因为裁决逻辑和文件系统、授权 API 纠缠在一起,离开设备就没法测。
所以这个库的边界画得很清楚:把文档生命周期的全部裁决逻辑收进一份纯 Kotlin 的 commonMain 核心库,让它在 JVM 上就能被 12 个单元测试反复捶打;文件 IO 和 fileShare 这类天然平台私有的部分,留在 ArkTS 宿主,通过 C 桥把结果喂回核心。核心只回答"该不该做",宿主负责"怎么做"。
这条边界是整个设计里最重要的一条线,后面所有内容都围绕它展开。
2. 效果展示
先看效果。Demo 的操作链路:点「示例文档」在应用沙箱里创建一份文档并模拟双击拉起(复刻文件关联的完整 Want 链路)→ 自动完成打开裁决与授权持久化 → 编辑 → 保存 → 强杀进程 → 重启后从「最近文件」一键恢复。
PC 形态模拟器(2in1 免费窗口)上的三步:

这张图里有三个值得停留的信息点:授权行显示 READ_WRITE 且「可编辑:是」——它来自 flags & 0x2 的解析结果;编辑区已经填充了从 URI 回读的文档内容;最近文件列表出现「可恢复 读写」条目——说明 persistPermission 已经执行成功并回写了核心。打开这一步,裁决、回读、持久化三件事在同一个动作里全部完成。

第二张图的三处状态变化:脏标记从「已保存」变「已修改」、字数从 71 变 101、保存按钮从灰变亮——这三个状态全部由 Kotlin 核心计算,ArkTS 只是展示。
第三张是整个 Demo 的压轴:强杀进程重启后,最近文件里的条目依然标着「可恢复 读写」,点一下,文档内容原样回来,脏标记是干净的「已保存」——因为恢复走的是 loadContent,内容从磁盘回读,会话重新落位为干净状态。

手机模拟器(Mate 90 Pro)上同样的三步,验证这份核心在手机形态上行为一致:


手机端编辑区还有一个有意思的细节:第一行文字是 HarmonyOS document pedit ed on phone - dirty flag set by KMP core 与原文的混排——这是自动化输入在光标位置插入的结果,不是 Bug。它恰好证明了一件事:核心对"任意位置的内容变更"都能正确置脏。脏标记的比较是整份 content 对 savedContent,不关心变更发生在哪个字节,这也是为什么它比"监听 onChange 置一个布尔位"的写法更可靠——后者在程序化改写、撤销重做这类不经过键盘输入的场景下会漏记。

页面上还有一块「KMP 自检」区,8 条 PASS 不是摆设——它是核心库 runChecks() 的输出,在一台独立的探针引擎上把脏标记、只读拒绝、持久化回写、恢复分组、JSON 往返这些关键语义全部现场验证一遍。这意味着读者拉下仓库跑起来,第一眼就能确认核心逻辑在这台设备上是否成立。
还有一个容易忽视的观察点藏在截图的「决策日志」区里。宿主把每一次裁决的原始结论都按时间戳记录下来,比如打开时能看到「双击文件关联拉起,Want 携带 URI 与 flags」「临时授权随进程失效,需要 persistUriPermission」「磁盘回读成功:71 字符」「persistPermission OK」这样一条完整链路。调试这类问题时,日志比断点好用得多——因为 Want 拉起是系统行为,断点打在 onNewWant 里经常被系统超时打断,而日志能把整条时间线完整留下来。Demo 里日志区上限 30 条、新的在上,就是为了在长链路里保持最新的上下文可见。
3. 分层架构:谁该做什么
┌──────────────────────────────────────────────────────────────┐
│ Kotlin commonMain(唯一决策层,纯 Kotlin,零平台依赖) │
│ DocPortalEngine 打开裁决 / 会话生命周期 / 最近文件 LRU / 恢复裁决 │
│ DocPortalTypes OpenVia / PermMode / PermState / 会话快照 │
│ DocPortalJson 无依赖 JSON 编解码(C 桥与沙箱持久化的统一格式) │
├──────────────────────────────────────────────────────────────┤
│ Kotlin/Native → C ABI(11 个导出符号,libohos_docportal.so) │
│ ohosArm64(真机) · ohosX64(Windows x86_64 模拟器) │
├──────────────────────────────────────────────────────────────┤
│ ArkTS 宿主(只执行,不决策) │
│ EntryAbility Want.uri + flags 解析(文件关联拉起入口) │
│ DocStore fs URI 读写 / fileShare 授权三件套 / 选择器 │
│ NativeDocPortal NAPI 桥封装 │
│ Index.ets 最近文件 / 编辑器 / 决策日志 / KMP 自检 │
└──────────────────────────────────────────────────────────────┘
数据流是一条单向路径:系统事件(Want/选择器)→ ArkTS 执行 IO 与授权调用 → 结果穿过 C 桥喂给 Kotlin → Kotlin 裁决 → JSON 回给 ArkTS 渲染。
两条铁律:
- Kotlin 层不持有任何平台对象。
docportal的commonMain里 import 不到任何@ohos.*、@kit.*,它连文件系统都不知道存在。这保证了 12 个 JVM 单元测试不需要任何设备; - ArkTS 层不做任何业务判断。宿主拿到的
OpenDecision里已经写清了persistPermission(要不要调 persist API)和canEdit(编辑器能不能启用),宿主只翻译成执行动作。
两边通过枚举名字符串(DOUBLE_CLICK、READ_WRITE、TEMPORARY……)和 JSON 对齐契约,跨 C 桥不丢语义。
4. 核心代码分析
4.1 打开裁决:一个函数回答三个问题
open() 是整个库的入口,它要同时回答:要不要持久化授权、能不能编辑、以及从哪来的(这决定给用户看什么提示):
public fun open(
uri: String,
name: String,
via: OpenVia,
permMode: PermMode,
permState: PermState,
nowMs: Long,
): OpenResult {
require(uri.isNotBlank()) { "uri must not be blank" }
val notes = mutableListOf<String>()
// 裁决一:临时授权必须趁进程活着做 persist,死后无法补救
val persistPermission = when {
permState == PermState.PERSISTED -> {
notes.add("授权已持久化,无需重复申请")
false
}
else -> {
notes.add("临时授权随进程失效,需要 persistUriPermission")
true
}
}
// 裁决二:写授权决定编辑器开关
val canEdit = when (permMode) {
PermMode.READ_WRITE -> true
PermMode.READ_ONLY -> {
notes.add("只读授权,仅可预览")
false
}
}
// 裁决三:来源决定给用户的提示语
if (via == OpenVia.RECENT) {
notes.add("从最近文件恢复")
} else if (via == OpenVia.DOUBLE_CLICK) {
notes.add("双击文件关联拉起,Want 携带 URI 与 flags")
}
// 同 URI 复用既有会话,避免重复拉起覆盖用户未保存的编辑
val existing = sessions[uri]
val session: DocSession
if (existing != null) {
session = existing
notes.add("同 URI 会话已存在,复用会话")
} else {
session = DocSession(
meta = DocMeta(uri, name, via, permMode, permState, nowMs),
content = "",
savedContent = "",
)
sessions[uri] = session
}
// 打开即登记最近文件(persisted 取决于授权状态)
trackRecent(uri, name, permMode, persisted = permState == PermState.PERSISTED, nowMs, null)
return OpenResult(session, OpenDecision(persistPermission, canEdit, notes))
}
值得展开的是持久化裁决的紧迫性。permState == TEMPORARY 时核心给出 persistPermission = true,这不是一个可以延后的建议——URI 的临时授权随着应用进程死亡而失效,一旦错过,重启后这条 URI 就只能重新走选择器。所以宿主侧收到这个裁决后的动作是同步执行的:先调 fileShare.persistPermission,成功后立刻调 confirmPermissionPersisted(uri, nowMs) 把结果回写核心。回写这个动作很重要,下一节讲恢复裁决时会说为什么。
另一个细节是重复打开复用会话:sessions[uri] 命中时不新建会话,只追加一条"同 URI 会话已存在,复用会话"的备注。这在双击拉起场景特别有用——用户双击同一个文件两次,系统会送来两次 Want,如果每次都重建会话,用户未保存的编辑内容就被无声覆盖了。
4.2 脏标记与保存:savedContent 双份的意义
会话数据结构里,content 和 savedContent 是两个独立的字段:
public fun edit(uri: String, text: String): EditResult {
val session = sessions[uri] ?: return EditResult(
// 会话不存在:构造只读影子会话承载数据,核心裁决拒绝
DocSession(DocMeta(uri, uri, OpenVia.PICKER, PermMode.READ_ONLY, PermState.TEMPORARY, 0L), text, text),
rejected = true,
note = "会话不存在,拒绝编辑",
)
if (session.meta.permMode == PermMode.READ_ONLY) {
return EditResult(session, rejected = true, note = "只读授权,编辑被核心拒绝")
}
val updated = session.copy(content = text)
sessions[uri] = updated
return EditResult(updated, rejected = false, note = null)
}
public fun save(uri: String, nowMs: Long): SaveResult {
val session = sessions[uri] ?: error("no session for $uri")
if (!session.dirty) error("nothing to save for $uri")
val saved = session.copy(
meta = session.meta.copy(lastSavedAtMs = nowMs),
savedContent = session.content,
)
sessions[uri] = saved
touchRecent(uri) { it.copy(lastSavedAtMs = nowMs) }
return SaveResult(saved)
}
dirty 的定义是 content != savedContent。这个设计有两个直接收益:
第一,保存的幂等性由数据结构保证。save() 对未脏会话直接抛错——不是返回一个"成功但啥也没做",而是让调用方明确知道这次保存请求是多余的。Demo 页面的保存按钮本身就用 dirty 状态控制可用性,双保险。
第二,"回读即干净"是免费获得的。宿主从磁盘读完内容后调 loadContent(uri, text),实现是 copy(content = text, savedContent = text)——一次赋值同时填两份,会话天然落在干净状态。重启恢复、双击打开两条路径都受益,不需要额外的"标记为已保存"调用。
注意保存的执行顺序在宿主侧是有讲究的:先 fs.open(uri).write(content) 真正落盘,落盘成功后才调核心 save() 清脏。如果反过来,清了脏但磁盘写入失败,用户会以为保存成功而实际丢数据。裁决归核心,事务顺序归宿主,这条边界在文章开头说的铁律里没有明说,但它是铁律的推论。
4.3 最近文件:LRU 加一张"生死簿"
最近文件用 LinkedHashMap 实现 LRU:trackRecent 先 remove(uri) 再重新 put,天然把命中的条目移到尾部;超容量时从 keys.first()(头部,最旧)淘汰。所有会话动作(打开、回读、保存)都会 touchRecent 刷新位置和 lastSavedAtMs。
真正有分量的是每个条目上的 persisted: Boolean 字段——它是一张"生死簿":
public fun confirmPermissionPersisted(uri: String, nowMs: Long) {
touchRecent(uri) { it.copy(persisted = true, lastSavedAtMs = it.lastSavedAtMs ?: nowMs) }
sessions[uri]?.let {
sessions[uri] = it.copy(meta = it.meta.copy(permState = PermState.PERSISTED))
}
}
public fun validateRecentForRestore(): RecentValidation {
val restorable = mutableListOf<RecentEntry>()
val lost = mutableListOf<RecentEntry>()
for (entry in recent.values) {
if (entry.persisted) restorable.add(entry) else lost.add(entry)
}
return RecentValidation(restorable, lost)
}
persisted 只有唯一写入点:宿主调 fileShare.persistPermission 成功之后才调 confirmPermissionPersisted。这个顺序不能反——如果 persist API 失败了核心却记了 persisted = true,重启后用户会看到一个"可恢复"的条目,点下去才发现授权早没了,这比"老老实实标丢失"糟糕得多。
重启后的流程分两步:启动时宿主读沙箱 recent.json 喂给 loadRecentSnapshot,然后 validateRecentForRestore() 把列表拆成两组。「可恢复」组点下去走 activatePermission 重新激活(持久授权重启后处于休眠态,激活后本进程可用)加 checkPersistentPermission 校验;「授权丢失」组直接提示用户重新走选择器。裁决先行,UI 只是渲染分组结果。
快照的落盘时机也是个实际工程问题。Demo 的做法是在两处写沙箱 recent.json:每次打开成功后、每次保存成功后。为什么不只存一次?因为强杀进程是随时可能发生的——如果只在保存时落盘,用户"打开了三个文件但还没保存"的场景下,最近文件列表就会整页丢失;打开后即落盘,至少把"用户碰过哪些文件、授权该不该续"这个事实保住了。落盘内容就是 recentSnapshot() 的全量 JSON,读回来走 loadRecentSnapshot 按存储顺序逐条回填,再经过容量淘汰收敛到上限。整个快照协议和 C 桥的 JSON 是同一套编解码器,两处消费、一份实现。
还有一个容易忽略的细节:恢复走 RECENT 通道打开时,核心的裁决走的是"授权已持久化,无需重复申请"分支,宿主不应该再调一次 persist——重复 persist 虽然多数时候无害,但它是系统调用,没有意义的调用只会增加失败面。裁决里 persistPermission = false 这个返回值就是给宿主的"别调了"信号,宿主只需要忠实执行。
4.4 宿主侧:Want 解析、URI 规范与 fileShare 三件套
ArkTS 侧第一道关是 EntryAbility 的 Want 解析。文件关联拉起时,flags 的第 0 位是读授权、第 1 位是写授权:
const FLAG_AUTH_WRITE_URI_PERMISSION = 0x00000002;
private stashWantDoc(want: Want): void {
console.info(`[DocPortal] stashWantDoc uri=${want.uri ?? ''} flags=${want.flags ?? 0}`);
if (!want.uri) {
return;
}
const canWrite = ((want.flags ?? 0) & FLAG_AUTH_WRITE_URI_PERMISSION) !== 0;
// 先写 canWrite 再写 uri:页面用 @StorageLink+@Watch 监听 uri,
// @Watch 在赋值瞬间同步触发,两个键必须都就绪(踩坑见第 5 节)
AppStorage.setOrCreate('pendingDocWrite', canWrite);
AppStorage.setOrCreate('pendingDocUri', want.uri);
}
第二道关是 DocStore 里的 fileShare 三件套。这三个 API 就是文档授权时间表的全部执行手段:
// 持久化:进程内立刻生效,重启后需 activatePermission 重新激活
async persist(uri: string, operationMode: number): Promise<string> {
try {
await fileShare.persistPermission([{ uri: uri, operationMode: operationMode }]);
return `persistPermission OK (mode=${operationMode})`;
} catch (error) {
const err = error as BusinessError;
return `persistPermission FAIL ${err.code}: ${err.message}`;
}
}
// 重启后激活已持久化的授权
async activate(uri: string, operationMode: number): Promise<string> { /* 同构 */ }
// 校验持久授权是否仍然有效——注意本 SDK 中的实际 API 名(踩坑见第 5 节)
async check(uri: string, operationMode: number): Promise<boolean> {
const result: boolean[] =
await fileShare.checkPersistentPermission([{ uri: uri, operationMode: operationMode }]);
return result.length > 0 && result[0];
}
operationMode 用位掩码:fileShare.OperationMode.READ_MODE = 0b1、WRITE_MODE = 0b10,读写就是 0b11。persist、activate、check 三次调用必须用同一组掩码,掩码不一致是这类 API 静默失败的重灾区。
三条打开入口在宿主侧的汇合方式也值得一提。双击拉起走 onNewWant,选择器走 DocumentViewPicker.select()(返回的 URI 天然带读写授权),最近文件走恢复裁决——三个入口最终都收敛到同一个 openDoc(uri, name, via, permMode, permState) 函数,只有来源枚举和授权参数不同。这个"多入口单汇合"的结构是刻意为之的:三条管线的差异被压缩在入口参数上,从汇合点往后,整条打开链路只有一份实现、一份日志、一套裁决。如果三条管线各自写一遍打开逻辑,用不了两个迭代就会出现"选择器打开的能编辑、双击打开的不能编辑"这类不对齐问题——而这类问题在测试环境里往往复现不出来,因为测试同学只会走最常用的那条入口。
还有一个容易忽略的点:这份能力需要 ohos.permission.FILE_ACCESS_PERSIST 权限,要在 module.json5 的 requestPermissions 里声明。它是普通级权限,不用动态申请,但不声明直接调 persist 就是 201 错误。与它配套的文件关联声明写在 skills 里:ohos.want.action.viewData 动作加 entity.system.viewed 实体,uris 过滤器用 {"scheme": "file", "type": "text/plain"}(SDK 20 写法,见第 5 节坑 7)。这两处配置齐了,文件管理器里双击 .txt 才会在打开方式里列出你的应用。
4.5 C 桥:11 个导出符号与一条自检通道
Kotlin/Native 侧用 @CName 导出 C 符号,配 version-script 收敛导出面:
@CName("DocPortalOpen")
public fun openNative(
uri: String, name: String, via: String,
permMode: String, permState: String, atMs: Long,
): CPointer<ByteVar> = response {
val viaEnum = OpenVia.entries.firstOrNull { it.name == via } ?: OpenVia.PICKER
val modeEnum = PermMode.entries.firstOrNull { it.name == permMode } ?: PermMode.READ_ONLY
val stateEnum = PermState.entries.firstOrNull { it.name == permState } ?: PermState.TEMPORARY
DocPortalExamples.open(uri, name, viaEnum, modeEnum, stateEnum, atMs).openResultJson()
}
桥面统一走 JSON 字符串(入参出参都是),每个导出函数用 response {} 包一层异常兜底——任何 Kotlin 异常都被序列化成 {"error":...} 返回给 ArkTS,不会把 native 崩溃传导给 UI 线程。枚举名在桥面做一次容错解析,解析不到落到安全默认值,这让新旧版本的核心库和宿主可以错峰升级。
runChecks() 是另一条值得单独说的通道。它在设备页面上渲染的 8 条 PASS,对应的是仓库里 12 个 JVM 单元测试的核心断言子集——也就是说,单元测试验证过的语义,在真机上还能再验一遍。这在"跨端逻辑是否真的跨端一致"这个问题上给了最直接的证据:同一份 commonMain 代码,JVM 测试全过,设备自检也全过。
5. 踩坑与边界条件
这一节是本文最值钱的部分,全部来自实测,按踩到的顺序排列。
坑 1:Want 里的裸沙箱路径会被系统静默丢弃。 最初模拟双击拉起时,直接把应用沙箱路径拼成 file:///data/app/el2/100/base/.../meeting_notes.txt 放进 want.uri,结果 onNewWant 收到的 want.uri 是空字符串,flags 和 type 都完好。排查用了很久,最后对齐规范:跨应用传递的 file URI 必须是 file://<bundleName>/data/storage/... 形式,用 fileUri.getUriFromPath() 从沙箱路径生成。改成规范形式后 uri 原样到达。系统对这个不合规 URI 不报错、只丢弃,属于典型的静默失败。
坑 2:@StorageLink + @Watch 的同步竞态。 页面用 @Watch 监听 AppStorage 的 pendingDocUri 来接收热启动的 Want。最初 stashWantDoc 先写 uri 再写 canWrite,结果 @Watch 回调在 uri 赋值的同一瞬间同步触发,回调里读到的 pendingDocWrite 还是初始值 false,所有文档都被裁决成 READ_ONLY。修复:先写辅助键、最后写触发键。这类"赋值即回调"的同步语义在 ArkTS 状态管理里很容易踩,跨键组合状态时尤其要小心写入顺序。
坑 3:对 JSON.parse 结果用展开运算符,进程直接被杀。 恢复裁决的 JSON 从桥面回来后,写了 this.recent = [...verdict.restorable, ...verdict.lostPermission],真机直接白屏退出。faultlog 里的栈指向 stateMgmt.js 的 forEachUpdateFunction,错误消息是 Callable is false,框架随后以 Kill Reason: Js Error 杀掉进程。换成 concat 后问题消失。教训:ArkTS 里对 JSON.parse 的产物做展开运算要当心,合并数组一律 concat。
坑 4:ForEach 的数据源必须是真数组。 同一类问题换个马甲:核心返回的最近文件列表 JSON 是 {"entries":[...]} 包装结构,ArkTS 侧直接 JSON.parse(...) as RecentItem[] 塞给 ForEach,页面一渲染就崩,错误是 the data source dose not have forEach function。解法是显式定义包装接口、解包 .entries 再赋值。跨桥 JSON 的形状契约要在 ArkTS 侧用 interface 声明清楚,不能靠 as 强转蒙混。
坑 5:checkPermission 在文档里叫这个名字,在 SDK 里不是。 华为文档写的是 fileShare.checkPermission,实际 SDK(API 20)里的实名是 checkPersistentPermission(since 17)。用错名字编译期就报 arkts-no-any-unknown(方法不存在返回 any),算是运气好的失败方式。此外它返回的是 Array<boolean>,与传入 policies 一一对应,别忘了判空。
坑 6:应用沙箱 URI 的持久授权校验受限。 实测发现,对应用自有沙箱文件(file://<bundleName>/data/storage/...)调用 persistPermission 可以成功,但重启后 checkPersistentPermission 依然返回 false。也就是说这套持久化体系的设计意图是面向 file://docs/... 这类公共文档路径的,应用自有文件本来就不依赖授权(fs 直接可开)。Demo 对此的处理是:check 失败不阻断恢复,沙箱自有文件直接走 fs.open;真实文档 App 里这个分支应该转成"重新授权"提示。这个边界没有写进 API 文档,只有踩过才知道。
坑 7:API 20 的 module.json5 不认 utd。 文件关联 skills 里的 uris 如果按新版文档写 { "utd": "general.plain-text" },hvigor schema 校验直接报 must have required property 'scheme'。API 20 的写法是旧式 MIME 过滤:{ "scheme": "file", "type": "text/plain" }。utd 是更高版本才进 schema 的字段,跨版本写配置时要以 targetSdkVersion 的 schema 为准。
坑 8:bundleName 会被签名 profile 锁定。 示例工程 app.json5 里写的 bundleName 是 com.example.docportal,但因为复用了另一个工程的调试签名 profile(绑定 com.example.hm_webview_demo),打出来的 HAP 在 pack.info 里包名就是 hm_webview_demo。这就是为什么 aa start -b 偶尔报"ability does not exist"——包名对不上。多工程复用签名材料时,实际包名以签名 profile 为准,aa start 的 -b 参数要与之一致。
坑 9(构建环境类,一笔带过):Windows 上 ohpm 对本地依赖(libentry.so 类型声明)默认建 symlink,在受限策略环境下无法遍历,需删掉后用目录复制替代;工程路径含中文时 Gradle test worker 会报 ClassNotFoundException,KMP 工程请放纯 ASCII 路径;Windows x86_64 模拟器要求 HAP 里带 x86_64 ABI 的 so,只编 arm64-v8a 会报 install parse native so failed。
6. 结论与可直接复用的建议
把第 5 节的踩坑归拢一下,可以发现它们分布在三个层面:协议层(Want URI 规范、跨桥 JSON 形状、flags 掩码)、状态管理层(@Watch 同步竞态、ForEach 数据源)、环境层(SDK 实名差异、签名锁定包名、构建策略限制)。协议层和状态层的坑靠"跨桥契约显式化"就能大量避免——这正是把裁决收进 Kotlin 核心的附带收益:桥面收窄到 11 个 JSON 出入口,契约只要声明一次。环境层的坑没有捷径,只能实测一遍记一遍,第 5 节就是为这个目的存在的。
回头看,这个三方库解决的问题可以浓缩成一句话:把文档授权这张"时间表"从各端 UI 代码里抽出来,交给一份可以离开设备做单元测试的 Kotlin 核心。12 个 JVM 测试覆盖打开裁决、脏标记、保存幂等、持久化回写、恢复分组、LRU 容量、JSON 往返;设备上的 8 条自检再把这些语义现场重放一遍。双端(PC 形态、手机形态)实测行为一致。
如果你也要做文档类应用,几条可以直接搬走的建议:
- 裁决与执行分离,是这类库能不能被测试的分水岭。核心库收枚举、出决策,不 import 任何平台 API——这一条做到了,逻辑就能上 JVM 测试;做不到,就只能上真机手点。
- 授权持久化的调用窗口是"打开时、进程活着时",收到
persistPermission = true的裁决要立刻执行并回写。拖延到用户第一次保存之后,中途被杀进程就漏了。 - 最近文件的落盘时机是"每次会话动作之后",不只是保存。我们最终在打开和保存后都写沙箱
recent.json,保证强杀进程后快照尽量新鲜。 - Want 传 URI 用
fileUri.getUriFromPath()生成规范形式,裸路径会被静默丢弃,这类问题没有报错可查,只能靠日志。 - 跨桥 JSON 在 ArkTS 侧用显式 interface 接,数组别用 spread,
concat稳妥;ForEach数据源确保是真数组。 - persist/activate/check 三个 API 的 operationMode 掩码保持一致,并且确认
module.json5里声明了FILE_ACCESS_PERSIST。 - 模拟器上无法真双击文件,用
startAbility带viewDataaction + uri + flags 的显式 Want 复刻同一条链路即可,语义完全一致。
仓库里的示例工程可以直接跑:example/ 下 gradlew prepareOhos prepareOhosX64 生成双 ABI 的 so,DevEco 打开 example/ohosApp 签名后一键运行。核心库 docportal/ 独立发布,任何 KMP 鸿蒙工程都可以引过去接自己的文件管线——毕竟,裁决逻辑是同一套,文件从哪来不重要。
转载自 CSDN-专业IT技术社区
原文链接:https://blog.csdn.net/csdn_codechina/article/details/170921472



