HarmonyOS 7 精准碰一碰实战：识别触碰坐标，素材精准插入指定位置

本文基于 HarmonyOS 7（API 26）官方论坛解读与开发指导整理。文中代码是为说明问题自写的完整示例；sharableTarget.getInfo()、receivableTarget.getInfo() 等接口名引自官方论坛解读，坐标字段等未逐字核实的写法已注明"以官方文档为准"；涉及真机表现的部分以真机实测为准，未做任何实测数据编造。

引子：碰一碰的最后一公里，是"碰哪传哪"

第一期V哥写碰一碰隔空传送时，落点是"传过去"------手机碰一下电脑，文件飞过去，接收方再自己决定放哪。好用，但差一口气：用户心里想的是"把这张图放到文档里光标那儿"，系统做的是"把图传到这台设备"。最后一公里的"放到哪"，还得用户手动拖。

HarmonyOS 7（API 26）把这最后一公里补上了 ：碰一碰·精准分享，手机轻触 PC/2in1 或平板屏幕时，系统自动识别触碰点的屏幕坐标，接收侧根据"碰到了哪里"决定插入位置------碰到文档编辑区就插图到光标附近，碰到列表某一条就追加到那条，碰到画布就落到画布坐标点（官方论坛解读）。

这期V哥把它拆开讲：精准分享与普通碰一碰的差别、双端新增的两个触点 API、发送端与接收端各自的实战逻辑，最后给工程落地建议。

一、定位：从"被发送"到"被投递"

普通碰一碰回答的问题是"传给谁"，精准分享回答的是"传到哪"。官方的表述很清楚：手机与 PC/2in1、手机与平板触发轻碰事件时，接收设备侧可从回调事件中获取轻碰的位置------基于屏幕左上角为初始点的坐标信息，据此执行不同的业务逻辑。

这意味着分享的粒度从"设备"细化到了"窗口里的位置"。内容不再是"被发送"，而是"被精准投递"：文档编辑器碰一下插图到光标处、白板工具碰一下素材落到触点坐标、看板应用碰一下卡片追加到指定列。

一条硬边界先记住：API 26 版本及以上的电脑设备才支持精准碰一碰。老设备上碰一碰还是普通分享，你的代码要做降级，不能假设坐标一定拿得到。

二、双端各新增一个触点 API

相比 HarmonyOS 6，API 26 新增了两个触点监听接口，发送端和接收端各一个：

端	接口	干什么
发送端	`sharableTarget.getInfo()`	未手动选择文件时，获取触碰点位置，按位置匹配要分享的内容
接收端	`receivableTarget.getInfo()`	获取触碰点位置，决定"指定位置插入"还是"列表末尾追加"

两个接口的分工体现了精准分享的设计思想：发送端按位置选内容，接收端按位置定落点。碰到相册的某张图就传那张图；碰到文档的某个区域就插到那个区域。两端都对坐标，分享才是"碰哪传哪"。

三、发送端实战：按触点匹配内容，匹配不上就终止

发送端的典型链路：用户没手动选文件，直接拿手机碰目标屏幕。系统回调触发后，sharableTarget.getInfo() 拿到触碰点位置，应用按位置匹配图片------匹配不到就直接终止分享流程，而不是随便传一张。

typescript 复制代码

// 发送端：按触点位置匹配要分享的图片
// 接口名 sharableTarget.getInfo() 引自官方论坛解读；
// 返回结构以官方开发指导为准
import { shareKit } from '@kit.ShareKit'; // 示意导入，以官方文档为准

onKnockEvent(sharableTarget: knockShare.SharableTarget): void {
  // V哥注：未手动选择文件时，才走"按触点匹配"的逻辑
  const info = sharableTarget.getInfo();
  const img = this.matchImageByPosition(info);
  if (!img) {
    // 匹配不到就终止，别把不相干的内容推过去
    this.abortShare('触点位置没有匹配到图片');
    return;
  }
  this.startShare(img);
}

这个"匹配不上就终止"的官方建议很关键：精准分享的价值在"准"，宁可让用户重碰一次，也别把错误位置的内容塞过去------用户对"传错位置"的容忍度，远低于"再碰一次"。

四、接收端实战：拿到坐标，决定插入还是追加

接收端的链路：轻碰回调里用 receivableTarget.getInfo() 拿触碰点位置，坐标基于屏幕左上角。应用把屏幕坐标映射到自己窗口内的业务坐标，再二选一：指定位置插入 （编辑器光标处、画布触点）或列表末尾追加（落在列表容器时）。

typescript 复制代码

// 接收端：按触点位置决定插入策略
onKnockReceive(receivableTarget: knockShare.ReceivableTarget): void {
  const info = receivableTarget.getInfo();
  // 坐标基于屏幕左上角；screenX/screenY 字段名以官方文档为准
  const x = info.coordinate?.screenX;
  const y = info.coordinate?.screenY;
  // 屏幕坐标 → 窗口内业务坐标的映射由应用完成
  const local = this.mapToContentArea(x, y);
  if (this.isInsideEditor(local)) {
    this.insertImageAtCursor(local);   // 指定位置插入
  } else if (this.isInsideList(local)) {
    this.appendToListEnd(local);       // 列表末尾追加
  }
}

映射这一步是接收端的工作量所在：屏幕坐标到窗口、窗口到内容区（考虑滚动偏移），V哥建议把映射函数单独封装，横竖屏、窗口缩放、折叠展开各自处理，别把坐标换算散落在业务代码里。

五、工程建议：两个官方 FAQ 级的坑

坑 1：云预览图超时。 官方"常见问题"第一条：应用用云端图片做预览图时，回调触发时可能来不及下载，导致超时失败。官方给的方案是预览图延迟更新------回调触发时先只发核心数据建立连接，卡片展示先用 Share Kit 提供的默认预览图，云端图下载完成后再更新。

坑 2：把精准当默认。 坐标只有 API 26+ 的电脑设备（以及配套的手机与平板组合）才给得出来。V哥的降级策略：拿不到坐标就退回普通碰一碰的"传过去"，功能可用性优先，精准只是增强。

json5 复制代码

// module.json5 侧的权限与声明以官方开发指导为准，
// 碰一碰分享的详细配置见官方指南，此处不臆造字段

适配场景上，官方点名的方向值得对照自查：办公协同（文档插图）、创意设计（画布投放）、教育课堂（课件素材）、游戏互动、智慧出行。工具类、编辑器类、白板类应用，这个能力的集成性价比最高。

参考与出处

本文涉及的机制、接口与交互规则来自以下官方材料，均为V哥动笔前逐条核验的原文出处：

最后一句：跨设备分享的上半场比的是"传得快"，下半场比的是"传得准"------一次轻碰带回一组坐标，内容就有了落点，"发过去了"和"放到这儿了"之间，隔着的就是这一代系统能力的差距。