这次我没有把“碰一碰”当成一个更快的分享按钮而是把它放进一个素材看板里手机里的照片碰到平板指定卡片文件要落到正确位置即使底层事件重复回调也只能真正提交一次。一、问题不是把文件传过去而是传到“哪一格”HarmonyOS 7 的碰一碰·精准分享把普通文件分享又往前推了一步。官方介绍里很关键的一点是手机触碰电脑或平板屏幕时系统可以结合触碰位置让分享内容更准确地落到目标窗口或目标区域。这个能力真正有意思的地方不只是少点两次按钮而是业务终于可以把“空间位置”参与到分享逻辑里。我这次做了一个叫TapBoard的 Demo。场景很简单平板上是一块家装素材看板有Card-01、Card-02、Card-03三个投递区域。手机选中livingroom_07.jpg后在目标区域进行精准碰一碰。测试记录里本次投递 ID 是KNOCK-20260930-041业务层最终命中targetSlot Card-03 hit (742, 416)如果只看演示效果这件事像是“拿到坐标以后做一次 if 判断”。真正接进页面后我很快遇到两个工程问题。一个是坐标不能直接等于业务目标。页面可能有标题栏、滚动偏移、缩放和安全区系统给出的目标信息要经过归一化才能映射到业务卡片。另一个更隐蔽事件回调不能天然被当成“只发生一次”。如果业务把每次回调都直接转成一次上传或数据库写入一次物理交互出现重复事件时就可能在目标卡片里落两份相同素材。所以这篇不讲“怎么做一个分享按钮”只处理两件事坐标怎么路由投递怎么幂等。二、我先把系统回调和业务对象隔了一层Share Kit 当前提供了knockShare事件注册能力接口层会回传SharableTarget。我没有让页面到处直接读取系统对象而是在入口处先转换成自己的快照。这段代码解决什么问题把系统回调转换成稳定的业务快照让后续路由和去重不依赖 UI。import { harmonyShare } from hms.collaboration.harmonyShare export interface TargetSnapshot { eventKey: string deliveryId: string targetSlot: string hitX: number hitY: number createdAt: number } export class KnockShareService { private callback?: CallbackharmonyShare.SharableTarget register(capability: harmonyShare.SendCapabilityRegistry, onTarget: (target: harmonyShare.SharableTarget) void): void { this.callback (target) onTarget(target) harmonyShare.on(knockShare, capability, this.callback) } unregister(capability: harmonyShare.SendCapabilityRegistry): void { if (this.callback) { harmonyShare.off(knockShare, capability, this.callback) this.callback undefined } } }这里我只在服务层保留注册和注销。页面出现时注册、离开时解除避免页面重新进入以后叠加多个监听。真正的TargetSnapshot不是官方接口对象而是 TapBoard 自己的业务结构。项目里我会通过一个normalizeTarget()把系统目标信息转换成eventKey、坐标和目标槽位等字段。这样以后系统能力升级变化也集中在适配层。这种分层还有一个现实收益测试时我可以直接构造TargetSnapshot不用每次都拿两台设备真的碰一下。三、坐标路由不是比大小而是把窗口状态一起算进去第一版我犯过一个很典型的错误页面里写死三个矩形然后拿触碰坐标直接判断。只要平板窗口大小固定它确实能工作。但一旦页面发生滚动、分栏比例变化或者窗口尺寸变化同一个视觉位置对应的内容坐标就可能不同。后来我把命中判断单独封成TargetRouter。这段代码解决什么问题把原始触碰点换算成内容坐标再寻找真正命中的业务区域。export interface RectArea { id: string left: number top: number right: number bottom: number } export interface ViewportSnapshot { offsetX: number offsetY: number scale: number } export class TargetRouter { route(rawX: number, rawY: number, viewport: ViewportSnapshot, areas: RectArea[]): string | undefined { const x (rawX viewport.offsetX) / viewport.scale const y (rawY viewport.offsetY) / viewport.scale return areas.find(area x area.left x area.right y area.top y area.bottom )?.id } }这里最重要的不是这几个比较符号而是ViewportSnapshot。TapBoard 每次进入可投递状态前都会记录当前内容偏移和缩放值。收到回调时用同一份快照做坐标转换。否则触碰发生以后页面又滚动了一下再拿“当前”布局去算命中结果就可能漂移。测试数据里(742, 416)最终落到Card-03。这个数字是 Demo 为了调试固定的一组测试记录不代表系统坐标范围也不应该被写进正式业务逻辑。DevEco Studio 这张图里我把这一轮最关键的数据都保留下来了KNOCK-20260930-041、Card-03、742, 416以及底部 HiLog。这样文章里的问题和调试现场是连起来的不会出现正文讲 Card-03截图突然变成 Card-02。四、重复回调真正危险的是“副作用重复执行”坐标路由跑通以后我在联调日志里看到了同一次交互的两条回调记录。这里我没有急着判断“系统重复了”。在多设备交互里重复观察到相似事件可能来自页面监听重复注册、生命周期重入、业务层转发多次也可能来自测试流程本身。工程上更重要的问题是即使上游重复最终副作用也只能提交一次。TapBoard 的副作用包括把图片复制到业务目录写入看板数据库更新 Card-03 的素材计数上报一次投递成功事件。这四件事如果执行两遍用户看到的就是两张重复图片。所以我不拿时间戳做简单节流而是做事件幂等。这段代码解决什么问题同一个 eventKey 可以被观察多次但只能进入一次 commit。export class DeliveryDeduper { private seen: Setstring new Set() shouldCommit(eventKey: string): boolean { if (this.seen.has(eventKey)) { return false } this.seen.add(eventKey) return true } clear(): void { this.seen.clear() } } private commitDelivery(snapshot: TargetSnapshot): void { if (!this.deduper.shouldCommit(snapshot.eventKey)) { this.duplicateCallbacks return } this.deliveryId snapshot.deliveryId this.targetSlot snapshot.targetSlot this.hitX snapshot.hitX this.hitY snapshot.hitY this.state ROUTED this.committedCount }为什么不用 300 ms 防抖因为时间并不是“同一次业务操作”的可靠身份。两个合法投递可能刚好发生得很近而一个异常重复事件也可能隔得更久。能够代表业务身份的 key才适合做幂等。正式项目里eventKey还应该有过期策略不能让 Set 无限增长。如果投递最终需要落数据库我更愿意把deliveryId做成唯一键让内存去重和持久层唯一约束形成两层保险。五、状态机让我第一次看清“收到目标”和“真正提交”不是一回事最早页面只有一个success true。做到异常恢复时这个布尔值完全不够用了。现在 TapBoard 把一次精准投递拆成READY ↓ TARGET_DETECTED ↓ ROUTED ↓ COMMITTED如果没有命中任何业务区域就进入TARGET_DETECTED → OUT_OF_RANGE如果已经处理过同一个事件TARGET_DETECTED → DUPLICATE_IGNORED这两个状态虽然最终都“不写入素材”含义却完全不同。前者要提示用户重新碰到有效区域后者不应该打扰用户只需要写调试日志。这也是我做这类系统能力 Demo 时越来越在意的一点不要把底层回调直接等价成业务成功。“检测到碰一碰”只是输入事件“识别到 Card-03”是路由结果“文件真正写入 Card-03”才是业务提交。六、页面生命周期里最容易留下第二个监听精准分享页面如果只打开一次很多问题都看不出来。我专门做了一个回归动作进入投递页 → 返回 → 再进入 → 再返回 → 第三次进入后开始碰一碰。如果on()放在aboutToAppear()却没有对应off()最终一次物理动作可能触发多条页面回调。这个现象表面看起来就像“碰一碰重复触发”。因此我把监听生命周期明确成对aboutToAppear(): void { this.knockShareService.register( this.capability, (target) this.handleTarget(target) ) } aboutToDisappear(): void { this.knockShareService.unregister(this.capability) }这里还要注意如果业务要求离开页面后仍然接受投递那么监听就不应该绑在页面组件而要提升到应用级服务。生命周期边界一定由产品场景决定不是看到aboutToDisappear()就机械注销。七、我最后用“2 次回调、1 次提交”作为验收结果为了让幂等效果可见我没有把重复事件藏掉而是在调试页里直接显示重复回调次数2 实际提交投递次数1当前文件livingroom_07.jpg 1920 × 1080当前投递KNOCK-20260930-041 Card-03 742, 416 ROUTED手机运行图里也保留了同一组数据。底部日志能看到目标卡片识别、两次回调观察以及最后只有一次提交。这里我把手机页做成“精准投递调试”而不是一个纯展示型首页是因为这篇文章真正要证明的不是 UI 做得多漂亮而是路由和幂等在一次真实运行里有没有闭环。八、命中失败不能直接算“分享失败”这两个状态要拆开做到这里以后我又把测试场景故意改得更刁钻用户碰到了目标设备但触点落在三张卡片之间的空白区域。如果代码只有“成功 / 失败”两个结果这时候很难给出正确反馈。设备之间的精准分享事件已经建立文件本身也没有问题只是业务层没有找到合法落点。它更接近“目标区域无效”而不是“传输失败”。TapBoard 对这类情况单独记录OUT_OF_RANGE。页面提示也不再写“分享失败请重试”而是提示“未命中可投递区域请对准卡片重新操作”。看起来只差几个字实际能减少很多误判。用户不需要重新选择图片也不需要怀疑设备连接有问题只要重新选择投递位置。这类状态拆分对日志也很重要。如果线上统计里把OUT_OF_RANGE、用户取消、文件读取失败、对端拒绝全部记成FAILED最终看到的只是一个很高的失败率却不知道应该优化交互引导、文件兼容还是底层能力接入。我现在会至少区分OUT_OF_RANGE DUPLICATE_IGNORED PAYLOAD_INVALID COMMIT_FAILED USER_CANCELLED其中只有COMMIT_FAILED真正意味着业务副作用执行失败。另外坐标路由过程中还要处理“布局已经失效”的情况。比如精准碰一碰发生后应用立刻旋转屏幕或切换了分栏比例。如果当前布局版本和触发事件时记录的 viewport 版本不一致我宁愿放弃本次命中提示重新投递也不使用一个旧坐标硬算新布局。这比“尽量猜一个最近的卡片”更可靠因为精准投递场景最怕的就是看起来成功内容却落错位置。九、文件到达以后还要再做一次业务校验坐标命中只证明用户想把内容放到Card-03并不能证明收到的内容一定适合这个卡片。比如 TapBoard 的图片槽位只接受图片。如果未来业务同时支持文本、PDF、视频那么接收阶段必须检查 UTD / MIME 类型、数量和文件尺寸再决定是否提交。我的顺序是识别目标 → 路由到 Card-03 → 校验内容类型 → 校验业务容量 → 执行 commit不要在“碰到正确位置”以后就立刻往数据库写。还有一个边界是 Card-03 本身可能在接收前被删除。多设备交互天然存在时间差触点产生时目标有效不代表文件真正到达时目标仍然存在。正式项目最好在 commit 前重新查询一次业务实体。这也是为什么我的TargetSnapshot里保存的是目标 ID而不是直接保存一个页面组件引用。组件会销毁业务 ID 才能跨过异步过程重新确认。如果目标已经不存在我会让这一轮进入TARGET_EXPIRED而不是静默创建一个新的 Card-03。十、调试时我会同时保留“原始事件”和“业务结果”精准投递这类问题如果只看最后 UI很难还原过程。TapBoard 的调试日志会同时记录两条线。第一条是输入线knock event received raw target normalized hit(742,416)第二条是业务线slotCard-03 duplicateCallbacks2 committed1 stateROUTED两条线分开以后排查会快很多。如果原始事件只有一次业务日志却出现两次问题更可能在我们自己的转发或页面监听如果原始事件两次但 commit 一次说明幂等层生效如果命中坐标正确但目标槽位错误就继续查坐标转换。这类日志不要携带真实用户隐私内容。文件名在 Demo 里可以写livingroom_07.jpg正式产品里最好记录经过脱敏的任务 ID、文件类型、尺寸等排查所需字段而不是把用户文件完整路径和敏感数据直接打进线上日志。从这个角度看精准碰一碰的“炫酷交互”只占了整个实现很小的一部分。真正让它可上线的是事件可观察、目标可验证、副作用可幂等、失败能分类。十一、这类跨设备能力我现在会固定检查四个边界第一个边界是坐标系。系统目标、窗口坐标、内容坐标、缩放后的业务坐标必须明确不要在不同层里混用。第二个边界是监听生命周期。注册和注销必须成对页面级能力不要偷偷活成应用级单例。第三个边界是幂等。任何涉及文件复制、数据库写入、订单提交、卡片新增的回调都不要默认上游事件绝不会重复。第四个边界是失败可恢复。目标没有命中、文件读取失败、用户取消或对端离开时都应该保留足够状态让下一次交互重新开始而不是让页面卡在“处理中”。HarmonyOS 7 的精准碰一碰很适合做有空间含义的多设备协作。官方示例强调的是“碰到哪里传到哪里”我这次真正学到的是当位置进入业务以后坐标、状态和幂等就会一起进入工程问题。把这三件事处理好以后碰一碰才不只是一个很酷的交互而是一条可以放心落进产品里的投递链路。参考资料HarmonyOS 7 新能力一览https://developer.huawei.com/consumer/cn/features/Share Kit 手机与 PC/2in1 碰一碰分享https://developer.huawei.com/consumer/cn/doc/HarmonyOS-Guides/knock-share-pc-phonesShare Kit API 变更说明https://developer.huawei.com/consumer/en/doc/harmonyos-releases/js-apidiff-sharekit-6001