HarmonyOS 7.0 / API 26 碰一碰分享链路排查设备发现、参数校验和失败提示如何做稳先把问题说清楚碰一碰失败时用户很难知道是设备没发现、参数不完整还是接收端处理失败。 这类问题看起来像一个新能力适配问题真正写代码时会变成三件事什么时候能用、失败时怎么退、结果怎么验证。我这篇不按功能介绍来写而是按排查顺序写。先确定 HarmonyOS 7.0 / API 26 的能力边界再做两个能复现的场景最后把处理逻辑收口成一个小封装。这样以后换到别的页面或者别的设备形态也能沿用同一套判断方式。官方能力点先对齐检查项这篇怎么落地系统版本面向 HarmonyOS 7.0 / API 26 的能力适配思路底线满足 HarmonyOS 5.0.0 及以上活动要求文章方向HarmonyOS 新能力、多设备应用开发、性能稳定性或上架质量核心特性碰一碰旧版本差异旧写法容易把分享数据直接塞进跳转参数失败时只给一个通用 toast。新处理重点API 26 多设备场景要把发现、校验、接收、回执和降级分享拆成可诊断步骤。这里最容易踩坑的是把“能调通”当成“能上线”。能调通只说明主路径没问题真正上线前还要看失败路径、降级路径、日志字段和多设备边界。验证环境和复现口径这篇按 HarmonyOS 7.0 / API 26 的开发口径来拆不写成泛泛的概念介绍。为了避免方案只停在文字上我把验证范围先定死版本口径HarmonyOS 7.0 / API 26兼容活动要求里的 HarmonyOS 5.0.0 及以上技术分享范围。验证入口先用一个独立 controller 跑状态流再接到 ArkUI 页面。复现方式主路径跑一次重复进入跑一次能力不可用或中断场景再跑一次。回归标准状态顺序不能乱失败原因必须能在日志里看到页面不能出现旧任务回写新状态。如果这四点做不到就算文章里把特性名称写得再新也不能算真正解决开发问题。问题是怎么发生的旧写法容易把分享数据直接塞进跳转参数失败时只给一个通用 toast。这个写法短期看很快但只要遇到状态变化就会暴露问题。比如设备能力变化、窗口尺寸变化、任务中断、用户重复点击、后台恢复、审核材料检查这些都不是主路径能覆盖的。我一般会把它拆成四个阶段第一阶段先判断版本、设备和上下文不直接执行重逻辑。第二阶段把任务状态写清楚避免重复进入。第三阶段执行过程中保留取消、降级和失败原因。第四阶段回到页面以后用日志和可见状态验收。案例一主路径可复现发送端参数里缺少资源 id接收端必须拒绝并回传可理解的失败原因。这类场景的关键不是多写 if而是让状态机挡住错误顺序。下面这个小封装保留了 stage、reason、traceId 和 updatedAt排查时能看到每一步发生了什么。type Stage idle | checking | running | fallback | done | failed; interface TouchShareGuardState { stage: Stage; reason?: string; traceId: string; updatedAt: number; } class TouchShareGuard { private current: TouchShareGuardState { stage: idle, traceId: trace- Date.now(), updatedAt: Date.now() }; start(scene: string): TouchShareGuardState { if (this.current.stage running) { return this.fail(已有任务正在执行拒绝重复进入); } this.current { stage: checking, traceId: scene - Date.now(), updatedAt: Date.now() }; return this.current; } run(): TouchShareGuardState { if (this.current.stage ! checking) { return this.fail(状态顺序不对先检查再执行); } this.current.stage running; this.current.updatedAt Date.now(); return this.current; } fallback(reason: string): TouchShareGuardState { this.current.stage fallback; this.current.reason reason; this.current.updatedAt Date.now(); return this.current; } done(): TouchShareGuardState { this.current.stage done; this.current.updatedAt Date.now(); return this.current; } private fail(reason: string): TouchShareGuardState { this.current.stage failed; this.current.reason reason; this.current.updatedAt Date.now(); return this.current; } }这段代码不依赖页面组件所以可以先用普通 ArkTS/TypeScript 思路验证状态流再接到 ArkUI 页面里。页面只负责展示状态不应该直接决定任务能不能继续。案例二失败和降级路径附近设备发现超时后页面要给二维码或链接分享兜底而不是让用户反复碰。失败路径一定要有明确的 reason。没有 reason 的失败提示开发阶段不好排查上线后用户也不知道该重试、切换设备还是返回上一页。const flow new TouchShareGuard(); console.info(case-a-start, JSON.stringify(flow.start(case-a))); console.info(case-a-run, JSON.stringify(flow.run())); console.info(case-a-done, JSON.stringify(flow.done())); const conflict new TouchShareGuard(); conflict.start(case-b); conflict.run(); console.info(case-b-repeat, JSON.stringify(conflict.start(case-b-repeat))); console.info(case-b-fallback, JSON.stringify(conflict.fallback(能力不可用进入降级链路)));预期日志大概是这样case-a-start stagechecking case-a-run stagerunning case-a-done stagedone case-b-repeat stagefailed reason已有任务正在执行拒绝重复进入 case-b-fallback stagefallback reason能力不可用进入降级链路为什么我选状态机而不是到处写布尔值方案好处问题多个 boolean 字段写起来快很容易出现 isLoadingtrue 但 error 也存在的矛盾状态只靠页面生命周期页面代码少多窗口、后台恢复和异步回调容易串线小状态机封装状态顺序清楚日志也好查一开始要多写一点结构我更倾向第三种。HarmonyOS 7.0 / API 26 的新能力越来越多很多能力都不是一次性调用就结束而是有环境判断、执行过程、降级策略和验证结果。状态机不是为了显得复杂是为了让排查变得可控。接到 ArkUI 页面时注意什么页面层建议只做三件事显示当前 stage让用户知道是在检查、执行、降级还是失败。根据 reason 给出下一步操作比如重试、切换设备、继续普通模式。在 aboutToDisappear 或页面切换时处理取消和回收避免旧任务回写新页面。一个比较稳的写法是把能力判断和任务控制放在 controller 里页面只订阅结果。这样后面换成折叠屏、平板、鸿蒙电脑窗口页面结构变了核心策略也不用跟着重写。验收清单验收点通过标准重复点击不会并发创建两条互相覆盖的任务能力不可用能进入降级路径并给出明确提示页面退出旧任务不会继续回写已经销毁的页面多设备窗口窗口变化后状态不丢展示不乱日志回放能通过 traceId 找到完整链路最后总结碰一碰 这类 HarmonyOS 7.0 / API 26 能力文章和代码都不能只写主路径。真正有价值的是把问题怎么发生、怎么复现、怎么降级、怎么验证讲清楚。我的判断标准很简单如果这段方案以后换一个页面还能复用日志里也能查到失败原因那它才算工程上站得住。