我这次没把“碰一碰”做成普通文件分享而是做了一个会议现场的“精准投递看板”手机拍完 PPT直接碰到平板上对应嘉宾的卡片区域图片就落到那个嘉宾下面。整个功能最有意思的地方不是传输速度而是系统已经把“传给哪台设备”进一步推进到了“传到哪个窗口、哪个位置”。一、先看结果一张照片为什么会准确落到“嘉宾B”我做这个 Demo 时先定了一条非常具体的验收规则手机里有一张会议照片平板看板上有嘉宾 A、B、C 三个区域。手机触碰到嘉宾 B 的区域后接收端必须同时满足三件事文件成功到达目标设备目标窗口被正确识别触碰坐标最终映射为guest_b图片插入嘉宾 B 的素材列表。只有这三件事都成立我才把这次操作记为“投递成功”。为什么要这么较真因为普通跨设备分享只回答“内容有没有送过去”而 HarmonyOS 7 的碰一碰·精准分享强调的是碰到哪里就传到哪里。官方新能力说明中提到手机轻触电脑或平板屏幕后系统可以识别目标窗口与触碰坐标再据此决定内容的插入位置或分享对象。这意味着应用侧不能再把所有接收事件都塞进一个统一入口。我们需要真正理解“落点”。二、我没有从传输 API 开始而是先画了目标区域第一版我犯的错很典型我先考虑“怎么把图片传过来”页面只做了一个大接收区域。结果功能确实跑通了但它跟普通分享几乎没有区别。用户碰屏幕左边、右边、中间最后都进入同一个列表。后来我把逻辑反过来先定义目标界面里的可投递区域再接系统事件。在会议看板里我定义了三个区域interface TargetRegion { id: string name: string x: number y: number width: number height: number } const targetRegions: TargetRegion[] [ { id: guest_a, name: 嘉宾A, x: 80, y: 120, width: 280, height: 360 }, { id: guest_b, name: 嘉宾B, x: 380, y: 120, width: 280, height: 360 }, { id: guest_c, name: 嘉宾C, x: 680, y: 120, width: 280, height: 360 } ]这段代码解决的不是 UI 布局而是让业务第一次拥有明确的投递坐标系。当区域有了 ID后面日志、数据结构、列表刷新、异常恢复都能围绕这个 ID 展开。否则我们只能一直说“左边那个卡片”“第二个区域”维护起来非常痛苦。三、精准分享真正有价值的数据是目标窗口和触碰坐标普通文件接收事件我最关心的是 URI、MIME 类型和文件大小。精准投递场景不一样。我会把下面这些字段看成一组targetWindowId用户碰到的目标窗口targetPointX/targetPointY触碰位置uri本次投递的素材mimeType素材类型timestamp事件时间。注意这里的接口对象我在业务层做了自己的包装。系统侧精准分享事件和能力接入方式需要以当前官方开发指南为准而业务代码不要直接把所有平台字段散到页面里。我最后让页面只消费一个内部模型interface PrecisionSharePayload { targetWindowId: string targetPointX: number targetPointY: number uri: string mimeType: string timestamp: number } function handleSharePayload(payload: PrecisionSharePayload) { if (payload.targetWindowId ! SessionBoard) { this.showFallback(当前触碰位置不属于投递看板) return } const regionId mapPointToRegion( payload.targetPointX, payload.targetPointY, targetRegions ) this.deliverToRegion(regionId, payload.uri) }这里有一个非常关键的判断窗口要先匹配再算坐标。如果应用有多个窗口或多个可接收页面只看 X、Y 没有意义。同样的坐标在不同窗口里可能对应完全不同的内容。四、落点映射不要写成一堆 if先把它做成纯函数我第一版为了快写的是这种逻辑if x 360 就 Aelse if x 660 就 B……很快就出问题了。页面改了左右边距映射逻辑忘了跟着改结果视觉上碰的是嘉宾 B程序却判成嘉宾 A。后来我把映射逻辑抽成纯函数只认区域数据function mapPointToRegion( x: number, y: number, regions: TargetRegion[] ): string | undefined { return regions.find(region { const inX x region.x x region.x region.width const inY y region.y y region.y region.height return inX inY })?.id }这段代码解决的是布局变化导致业务判断漂移的问题。我的实际做法是ArkUI 布局完成后把真实区域位置同步给映射层而不是在业务代码里长期保存一组拍脑袋的常量。示例里的数值只是为了把逻辑讲清楚。在 DevEco 调试时我会同时盯四个值targetWindow、x/y、regionId、最终insertAsset结果。图里红色标注的“落点映射”和“投递结果”就是我排查这条链最常看的两个节点。如果前面窗口与坐标都正确但regionId错了说明是本地映射问题如果regionId正确最后列表没变化问题就在数据写入或视图刷新。五、不要让“文件传过来了”掩盖“内容放错位置”这是我这次遇到最隐蔽的问题。有一次调试时文件接收完全成功日志也没有报错但图片总是出现在第一个嘉宾区域。第一感觉会怀疑跨端分享事件不准最后排查发现问题非常普通我的列表更新方法默认index 0。这让我意识到精准分享的验收不能只看传输结果。所以我把运行页面做成现在这种结构上方显示待投递素材中间直接展示三个目标区域下面再把系统返回的窗口、坐标和业务映射结果全部摊开。这张图里红圈直接圈住嘉宾 B同时把x846, y512和guest_b放在同一屏。这样调试人员不用在日志和 UI 之间来回猜。我现在定义一次成功投递需要满足系统事件收到targetWindowId正确坐标落入合法区域regionId与视觉区域一致素材数据写入成功对应区域完成局部刷新。前四步是“找到地方”后两步才是“真正放进去”。六、素材写入我会做成幂等不然连续碰两次很容易重复“碰一碰”是一个非常自然的动作也意味着用户很可能在没有明确反馈时再碰一次。如果应用每收到一次事件就无条件插入很容易出现重复素材。所以我会给每次投递计算一个业务键。最简单可以用uri regionId timestamp bucket更稳妥则使用系统事件 ID 或业务侧生成的 transferId。这段代码解决的是重复事件导致同一素材插入两次private delivered new Setstring() private async deliverToRegion(regionId: string | undefined, uri: string) { if (!regionId) { this.showFallback(没有找到有效投递区域) return } const key ${regionId}:${uri} if (this.delivered.has(key)) { console.info(ignore duplicated share: ${key}) return } await this.boardRepository.insertAsset(regionId, uri) this.delivered.add(key) this.refreshRegion(regionId) }这里我故意把refreshRegion()放到数据写入成功之后。这样 UI 不会先出现图片、几百毫秒后又因为写入失败消失。真实项目里还应该考虑进程重启后的幂等所以Set只是演示。正式实现可以把 transferId 或内容摘要存进本地数据库。七、边界区域比中心区域更值得测精准投递看起来是“坐标题”最容易出问题的地方恰好不是区域中心而是边界。我后来专门做了四类测试1. 两个卡片之间的间隙如果触碰点落在间隙不应该强行猜一个最近区域。我的策略是进入待确认状态让用户选择目标。2. 卡片滚动以后的位置页面有滚动时屏幕坐标和内容坐标可能不是同一套。映射前要确认使用的是哪个坐标系不能拿屏幕绝对坐标直接和列表 item 的局部坐标比较。3. 窗口尺寸改变PC / Tablet 的窗口可能变化固定区域数据必须随着布局重新计算。精准分享不是一次布局算完就永久有效。4. 接收时页面不在前台如果目标页面还没构建完成事件不能直接丢掉。我的做法是先缓存本次 payload页面恢复后再做区域映射但必须设置过期时间避免很久以前的事件突然插进当前页面。这些问题都很“工程”但正是它们决定了精准分享最终像不像一个可靠产品能力。八、我最后增加了一张投递详情页专门给调试和验收用普通用户其实不需要看到一堆坐标和 regionId但开发、测试需要。所以我做了一张只在调试版本开放的详情页里面直接展示系统返回字段、区域映射结果、写入索引和完整事件时间线。这张图里我最关心三个位置。第一是targetPointX / targetPointY它是系统层给应用的空间证据第二是regionId guest_b这是应用自己的业务判断第三是“写入完成并刷新视图”这是用户最终看到结果的那一步。把三层信息放到同一页问题定位特别直接系统坐标错了查接入和设备侧坐标对、regionId 错查布局映射regionId 对、内容没出现查数据与状态刷新。这比一句“碰一碰偶尔不准”有价值得多。九、从“分享”变成“投递”产品设计也得跟着换思路做完这个 Demo我觉得精准碰一碰真正有意思的地方不是传输动作更酷而是它改变了应用对“目标”的理解。以前的分享目标通常是某个联系人、某个应用、某台设备。现在多了一层某个窗口里的某个位置。这给很多业务带来新的可能。会议场景里照片可以直接落到对应嘉宾家装场景里建材照片可以碰到户型图里的某个房间教学场景里学生素材可以直接投到老师大屏的指定题目区域设计协作里也可以把手机里的参考图精准送到某个画板或素材槽。但应用侧也要承担更多责任目标区域必须稳定、反馈必须足够快、失败必须能恢复、重复事件必须可控。我现在会把这条链总结为设备触碰 → 目标窗口识别 → 坐标获取 → 区域映射 → 素材写入 → 局部刷新 → 结果反馈。如果只做到“设备之间碰一下就传文件”其实还没有把“精准”两个字用起来。HarmonyOS 7 的碰一碰·精准分享把系统感知能力往业务 UI 里推进了一步。开发者真正要做的是把系统提供的窗口和触碰位置稳定地翻译成自己的业务对象。这次会议看板 Demo 对我最大的价值也正是在这里我不再把跨端分享看成一个传输接口而是把它看成一次带空间落点语义的业务事件。参考资料HarmonyOS 7 新能力碰一碰·精准分享https://developer.huawei.com/consumer/cn/features/官方开发指南入口https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/knock-share-pc-phones-mutually
我这次没把“碰一碰”做成普通文件分享而是做了一个会议现场的“精准投递看板”手机拍完 PPT直接碰到平板上对应嘉宾的卡片区域图片就落到那个嘉宾下面。整个功能最有意思的地方不是传输速度而是系统已经把“传给哪台设备”进一步推进到了“传到哪个窗口、哪个位置”。一、先看结果一张照片为什么会准确落到“嘉宾B”我做这个 Demo 时先定了一条非常具体的验收规则手机里有一张会议照片平板看板上有嘉宾 A、B、C 三个区域。手机触碰到嘉宾 B 的区域后接收端必须同时满足三件事文件成功到达目标设备目标窗口被正确识别触碰坐标最终映射为guest_b图片插入嘉宾 B 的素材列表。只有这三件事都成立我才把这次操作记为“投递成功”。为什么要这么较真因为普通跨设备分享只回答“内容有没有送过去”而 HarmonyOS 7 的碰一碰·精准分享强调的是碰到哪里就传到哪里。官方新能力说明中提到手机轻触电脑或平板屏幕后系统可以识别目标窗口与触碰坐标再据此决定内容的插入位置或分享对象。这意味着应用侧不能再把所有接收事件都塞进一个统一入口。我们需要真正理解“落点”。二、我没有从传输 API 开始而是先画了目标区域第一版我犯的错很典型我先考虑“怎么把图片传过来”页面只做了一个大接收区域。结果功能确实跑通了但它跟普通分享几乎没有区别。用户碰屏幕左边、右边、中间最后都进入同一个列表。后来我把逻辑反过来先定义目标界面里的可投递区域再接系统事件。在会议看板里我定义了三个区域interface TargetRegion { id: string name: string x: number y: number width: number height: number } const targetRegions: TargetRegion[] [ { id: guest_a, name: 嘉宾A, x: 80, y: 120, width: 280, height: 360 }, { id: guest_b, name: 嘉宾B, x: 380, y: 120, width: 280, height: 360 }, { id: guest_c, name: 嘉宾C, x: 680, y: 120, width: 280, height: 360 } ]这段代码解决的不是 UI 布局而是让业务第一次拥有明确的投递坐标系。当区域有了 ID后面日志、数据结构、列表刷新、异常恢复都能围绕这个 ID 展开。否则我们只能一直说“左边那个卡片”“第二个区域”维护起来非常痛苦。三、精准分享真正有价值的数据是目标窗口和触碰坐标普通文件接收事件我最关心的是 URI、MIME 类型和文件大小。精准投递场景不一样。我会把下面这些字段看成一组targetWindowId用户碰到的目标窗口targetPointX/targetPointY触碰位置uri本次投递的素材mimeType素材类型timestamp事件时间。注意这里的接口对象我在业务层做了自己的包装。系统侧精准分享事件和能力接入方式需要以当前官方开发指南为准而业务代码不要直接把所有平台字段散到页面里。我最后让页面只消费一个内部模型interface PrecisionSharePayload { targetWindowId: string targetPointX: number targetPointY: number uri: string mimeType: string timestamp: number } function handleSharePayload(payload: PrecisionSharePayload) { if (payload.targetWindowId ! SessionBoard) { this.showFallback(当前触碰位置不属于投递看板) return } const regionId mapPointToRegion( payload.targetPointX, payload.targetPointY, targetRegions ) this.deliverToRegion(regionId, payload.uri) }这里有一个非常关键的判断窗口要先匹配再算坐标。如果应用有多个窗口或多个可接收页面只看 X、Y 没有意义。同样的坐标在不同窗口里可能对应完全不同的内容。四、落点映射不要写成一堆 if先把它做成纯函数我第一版为了快写的是这种逻辑if x 360 就 Aelse if x 660 就 B……很快就出问题了。页面改了左右边距映射逻辑忘了跟着改结果视觉上碰的是嘉宾 B程序却判成嘉宾 A。后来我把映射逻辑抽成纯函数只认区域数据function mapPointToRegion( x: number, y: number, regions: TargetRegion[] ): string | undefined { return regions.find(region { const inX x region.x x region.x region.width const inY y region.y y region.y region.height return inX inY })?.id }这段代码解决的是布局变化导致业务判断漂移的问题。我的实际做法是ArkUI 布局完成后把真实区域位置同步给映射层而不是在业务代码里长期保存一组拍脑袋的常量。示例里的数值只是为了把逻辑讲清楚。在 DevEco 调试时我会同时盯四个值targetWindow、x/y、regionId、最终insertAsset结果。图里红色标注的“落点映射”和“投递结果”就是我排查这条链最常看的两个节点。如果前面窗口与坐标都正确但regionId错了说明是本地映射问题如果regionId正确最后列表没变化问题就在数据写入或视图刷新。五、不要让“文件传过来了”掩盖“内容放错位置”这是我这次遇到最隐蔽的问题。有一次调试时文件接收完全成功日志也没有报错但图片总是出现在第一个嘉宾区域。第一感觉会怀疑跨端分享事件不准最后排查发现问题非常普通我的列表更新方法默认index 0。这让我意识到精准分享的验收不能只看传输结果。所以我把运行页面做成现在这种结构上方显示待投递素材中间直接展示三个目标区域下面再把系统返回的窗口、坐标和业务映射结果全部摊开。这张图里红圈直接圈住嘉宾 B同时把x846, y512和guest_b放在同一屏。这样调试人员不用在日志和 UI 之间来回猜。我现在定义一次成功投递需要满足系统事件收到targetWindowId正确坐标落入合法区域regionId与视觉区域一致素材数据写入成功对应区域完成局部刷新。前四步是“找到地方”后两步才是“真正放进去”。六、素材写入我会做成幂等不然连续碰两次很容易重复“碰一碰”是一个非常自然的动作也意味着用户很可能在没有明确反馈时再碰一次。如果应用每收到一次事件就无条件插入很容易出现重复素材。所以我会给每次投递计算一个业务键。最简单可以用uri regionId timestamp bucket更稳妥则使用系统事件 ID 或业务侧生成的 transferId。这段代码解决的是重复事件导致同一素材插入两次private delivered new Setstring() private async deliverToRegion(regionId: string | undefined, uri: string) { if (!regionId) { this.showFallback(没有找到有效投递区域) return } const key ${regionId}:${uri} if (this.delivered.has(key)) { console.info(ignore duplicated share: ${key}) return } await this.boardRepository.insertAsset(regionId, uri) this.delivered.add(key) this.refreshRegion(regionId) }这里我故意把refreshRegion()放到数据写入成功之后。这样 UI 不会先出现图片、几百毫秒后又因为写入失败消失。真实项目里还应该考虑进程重启后的幂等所以Set只是演示。正式实现可以把 transferId 或内容摘要存进本地数据库。七、边界区域比中心区域更值得测精准投递看起来是“坐标题”最容易出问题的地方恰好不是区域中心而是边界。我后来专门做了四类测试1. 两个卡片之间的间隙如果触碰点落在间隙不应该强行猜一个最近区域。我的策略是进入待确认状态让用户选择目标。2. 卡片滚动以后的位置页面有滚动时屏幕坐标和内容坐标可能不是同一套。映射前要确认使用的是哪个坐标系不能拿屏幕绝对坐标直接和列表 item 的局部坐标比较。3. 窗口尺寸改变PC / Tablet 的窗口可能变化固定区域数据必须随着布局重新计算。精准分享不是一次布局算完就永久有效。4. 接收时页面不在前台如果目标页面还没构建完成事件不能直接丢掉。我的做法是先缓存本次 payload页面恢复后再做区域映射但必须设置过期时间避免很久以前的事件突然插进当前页面。这些问题都很“工程”但正是它们决定了精准分享最终像不像一个可靠产品能力。八、我最后增加了一张投递详情页专门给调试和验收用普通用户其实不需要看到一堆坐标和 regionId但开发、测试需要。所以我做了一张只在调试版本开放的详情页里面直接展示系统返回字段、区域映射结果、写入索引和完整事件时间线。这张图里我最关心三个位置。第一是targetPointX / targetPointY它是系统层给应用的空间证据第二是regionId guest_b这是应用自己的业务判断第三是“写入完成并刷新视图”这是用户最终看到结果的那一步。把三层信息放到同一页问题定位特别直接系统坐标错了查接入和设备侧坐标对、regionId 错查布局映射regionId 对、内容没出现查数据与状态刷新。这比一句“碰一碰偶尔不准”有价值得多。九、从“分享”变成“投递”产品设计也得跟着换思路做完这个 Demo我觉得精准碰一碰真正有意思的地方不是传输动作更酷而是它改变了应用对“目标”的理解。以前的分享目标通常是某个联系人、某个应用、某台设备。现在多了一层某个窗口里的某个位置。这给很多业务带来新的可能。会议场景里照片可以直接落到对应嘉宾家装场景里建材照片可以碰到户型图里的某个房间教学场景里学生素材可以直接投到老师大屏的指定题目区域设计协作里也可以把手机里的参考图精准送到某个画板或素材槽。但应用侧也要承担更多责任目标区域必须稳定、反馈必须足够快、失败必须能恢复、重复事件必须可控。我现在会把这条链总结为设备触碰 → 目标窗口识别 → 坐标获取 → 区域映射 → 素材写入 → 局部刷新 → 结果反馈。如果只做到“设备之间碰一下就传文件”其实还没有把“精准”两个字用起来。HarmonyOS 7 的碰一碰·精准分享把系统感知能力往业务 UI 里推进了一步。开发者真正要做的是把系统提供的窗口和触碰位置稳定地翻译成自己的业务对象。这次会议看板 Demo 对我最大的价值也正是在这里我不再把跨端分享看成一个传输接口而是把它看成一次带空间落点语义的业务事件。参考资料HarmonyOS 7 新能力碰一碰·精准分享https://developer.huawei.com/consumer/cn/features/官方开发指南入口https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/knock-share-pc-phones-mutually
