【鸿蒙心迹】碰哪传哪：HarmonyOS 7 碰一碰精准分享工程化落地——从读到坐标到插对位置的 5 个坑

摘要: HarmonyOS 7（API 26）的碰一碰·精准分享，让手机轻碰 PC 屏幕，素材就落到指定位置。但"读到坐标"只是 demo 的终点，生产环境还要过四道关：老机型坐标是 undefined、手抖一秒连碰三次、用户碰完又切了文档、同一张图被插两层。本文基于 API 26.0.0 环境与官方 Demo 链路，把接收端的能力降级、事件防抖、目标窗口二次校验、幂等写入，以及屏幕坐标到画布坐标的完整转换链一次讲透，附 5 个踩坑解法与分享状态机设计。

适用版本: HarmonyOS 7 / API 26.0.0 / DevEco Studio 6.x（Beta 阶段接口以当前 SDK 文档为准，接口名依据官方开发指南 knock-share-pc-phones-mutually 与 knock-file-share）

环境说明: 本文基于碰一碰精准分享接入真实项目的工程过程整理，坐标回调链路基于官方 Demo 验证；回调时延、防抖阈值等定量数据标注"待实测"，不编造数字。

开篇：读到坐标，只是 demo 的终点

“把手机上那张合同照片，放进电脑文档里，别放错页。”

2026 年 8 月，我在 HDC 上看到一个演示，印象很深：手机往 PC 屏幕上一放，图片直接落在触点位置的画布上。当时觉得路径被砍掉了一半，回来就把它接到了自己的文档协作项目里——从 SDK 对齐踩到现在，正好整理成这篇。

先说说旧流程有多绕。把手机里的参考图挪到 PC 的设计文档，路径是：手机打开照片 → 选分享方式 → PC 端等接收 → 切到正确的文档 → 找位置插入。五步，其中两步是纯等待，最烦的是最后一步：不管怎么传，文件永远落在"下载"或者系统默认位置，挪到正确位置全靠手动。

图：传统跨设备分享五步链路，落点由系统决定（下载目录/接收卡片）；精准分享压缩为"选内容 → 碰"，落点变成触点位置

碰一碰·精准分享改的就是这最后一步：系统自动识别手机触碰屏幕时的接触点坐标，应用根据坐标决定文件插到哪里、共享给谁。内容不再是被"发送"，而是被"精准投递"。

社区里已经有同学写过跑通最小闭环的文章——从基础分享、读坐标到把图插进去（木斯佳的《轻触即定位，把分享变成一次直觉操作》，11 万浏览）。那是我看的第一篇教程，本文不重复这条闭环，讲闭环之后的事：坐标拿到手之后，生产环境还要过能力降级、事件防抖、目标窗口校验、幂等写入四道关。这几关我每一关都卡过，最烦的一关卡了两天。

本文的工程链路和 5 个踩坑，全部来自这次接入过程。

---

一、从"传给谁"到"碰到哪"

普通碰一碰回答一个问题：传给谁？精准分享多回答一个：碰到哪？

图 1：精准分享与普通分享的差别在"转换到业务位置"这一步——普通分享到设备为止，精准分享落到业务区域为止。

先说三个能力边界，都是硬约束，理解它们比理解 API 更重要：

边界	说明
设备对	手机与 PC/2in1、手机与 Tablet 之间相互分享；手机必须是接触方之一
双向优先级（6.0.0(20) Beta5 起）	手机前台有可分享内容 → 手机发送、PC/2in1 接收；手机没有、PC/2in1 前台窗口有 → PC/2in1 发送、手机接收；双方都没有 → 走无内容分享逻辑
物理姿态	俯视夹角 ≤5°（手机基本平放在屏幕上）、侧视夹角 >35°、正视夹角 ≤25°、手机不能超出屏幕边缘；支持官方保护壳，过厚外壳影响感知

两条链路摆在一起对比：

维度	传统跨设备分享	碰一碰·精准分享
用户步骤	5 步（选 → 分享 → 等接收 → 切换 → 手动定位）	2 步（选 → 碰）
落点	系统默认（下载目录/接收卡片）	触点位置对应的业务位置
目标确定	接收后用户手动选	系统识别窗口 + 坐标，应用决策
失败反馈	笼统"传输失败"	分层错误码 + 明确拒绝原因
应用参与度	收到文件为止	把坐标翻译成业务指令

最后一行才是真差别：传统分享的应用"收文件"，精准分享的应用"收指令"。

还有一个容易忽略的前提：坐标能力依赖设备的近场感知硬件。较老机型（缺多天线传感器）或系统版本不够时，坐标参数直接是 undefined。也就是说"精准"是增强项，底座还是普通碰一碰，降级路径必须存在——这是第 7 节踩坑 1 的根因。

---

二、环境对齐：版本与设备声明

开始写代码之前，先把环境对齐。我最初是在 6.0.0(20) 的 SDK 上开干的，接收代码全写完发现坐标拿不到，排查了两天才发现：轻碰坐标是 API 26.0.0 新增的能力，旧 SDK 里连字段都没有。

三个对齐点：

1. SDK 与 DevEco：切到 API 26.0.0 Beta SDK、DevEco Studio 6.x；
2. 设备系统版本：接收端 PC/2in1/Tablet 的系统版本要支持该能力，发送端手机为 HarmonyOS NEXT 及以上；
3. 设备类型声明：要支持 Tablet 接收，module.json5 里必须显式声明 tablet，不声明就不会给平板设备分发。

// module.json5：设备形态声明，tablet 漏加则平板端不生效
{
  "module": {
    "name": "entry",
    "type": "entry",
    "deviceTypes": [
      "default",   // 手机
      "tablet",    // 平板（本能力新增）
      "2in1",      // 折叠电脑
      "pc"         // 鸿蒙电脑
    ]
  }
}

代码里建议再加一层运行时开关。静态版本判断覆盖不了所有设备组合，运行时能力检测才是调能力前的最后一道闸：

// 能力开关：静态版本判断 + 运行时检测，两个都过才走精准链路
import { deviceInfo } from '@kit.BasicServicesKit';

const isApi26 = deviceInfo.apiVersion >= 26;
const canPrecision = isApi26 && canIUse('SystemCapability/share/ShareKnockShare');

if (!canPrecision) {
  // 降级为普通碰一碰：只传不定位
  hilog.warn(0x0000, TAG, 'precision knock share unsupported, fallback to plain');
  return;
}

版本说明：能力检测的准确字符串以官方文档为准。Beta 阶段本地 SDK 若暂未包含，按 26.0.0 的接口写代码、先把运行时判断挂上，SDK 升级后不用改业务逻辑。

---

三、注册与触发：knock 事件的生命周期

发送侧的接入和普通碰一碰基本一致，四步：注册、触发、发送、清理。

1. 注册：在可分享的页面注册碰一碰事件（knockShare），声明这个页面有什么可分享内容；
2. 触发：手机与对端设备轻碰，系统发现设备后回调；
3. 发送：在回调里构造分享数据（uri、mime、大小、预览图）并发送；
4. 清理：离开可分享页面时解注册，不注册就会泄漏回调、页面关了还收事件。

// 发送侧：可分享页注册 knockShare，离开时解注册
import { share } from '@kit.ShareKit';

let knockShareInstance: share.KnockShareInstance | undefined;

// 进入可分享页面时注册
aboutToAppear() {
  let context = this.getUIContext().getHostContext();
  knockShareInstance = share.createKnockShareInstance(context, {
    onKnock: async (target: share.SharableTarget) => {
      // 在回调里构造数据并发送；先发核心数据建立连接，
      // 预览图（如大图缩略）可后续 updateShareData 延迟更新
      const shareData = new share.SharedData({
        utd: share.UniformDataType.IMAGE,
        uri: this.currentImageUri,
        thumbnailUri: await this.makeThumb(this.currentImageUri)
      });
      await target.share(shareData);
    }
  });
  await knockShareInstance.register();
}

aboutToDisappear() {
  knockShareInstance?.unregister();
  knockShareInstance = undefined;
}

两个容易忽略的点：

• 预览图延迟更新：碰触回调里等大图缩略图生成完再发，会拖慢建立连接的时延。正确姿势是先用占位预览图发出核心数据，缩略图就绪后调 updateShareData 更新。这条在官方 best practice 里有专门小节，但 demo 里不写，真机上"卡片空白好几秒"的观感差距很明显。
• 双向优先级的实现含义：手机前台无可分享内容、PC 前台窗口有时，是 PC 发送、手机接收。如果你的应用 PC 端也要参与"被碰"，接收端代码不能只挂在"我是接收方"的假设上——同一套接收逻辑要能处理"我是发送方"和"我是接收方"两种回调。

---

四、接收坐标：接收端读 screenX / screenY

这是精准分享和普通碰一碰的唯一增量：接收端回调里多了一份接触点坐标。

PC/Tablet 接收侧从 receivableTarget.getInfo() 拿：

// PC/2in1/Tablet 接收侧：读接触点坐标
let receivableTarget = share.createReceivableTarget(context, {
  onReceive: async (info: share.ReceivableInfo) => {
    let receivableTargetInfo = info.getInfo();
    let screenX = receivableTargetInfo.coordinate?.screenX;
    let screenY = receivableTargetInfo.coordinate?.screenY;
    let uris = receivableTargetInfo.uri;

    if (screenX !== undefined && screenY !== undefined) {
      hilog.info(0x0000, TAG, `touched at (${screenX}, ${screenY})`);
      // 坐标进 AppStorage，供 UI 层做触点反馈
      AppStorage.setOrCreate('TouchPosX', screenX);
      AppStorage.setOrCreate('TouchPosY', screenY);
      AppStorage.setOrCreate('SharedUris', uris);
      await this.dispatchPrecisionInsert(screenX, screenY, uris);
    } else {
      // 关键防御：坐标可能为 undefined（见踩坑 1）
      hilog.warn(0x0000, TAG, 'no coordinate, fallback to plain receive');
      await this.dispatchPlainReceive(uris);
    }
  }
});

另一条通道是 want 参数：接收应用被碰触拉起时，onNewWant 的 want.parameters 里也带触点坐标（键名形如 ohos.extra.param.key.share.touch.x / touch.y，以当前 SDK 文档为准）。两条通道读到的坐标基准一致，都是屏幕左上角基准的物理像素。

这里要先说清楚坐标的"出身"：它是手机碰屏幕的接触点，换算到屏幕坐标系的值，不是你应用窗口里的布局坐标，更不是文档画布的坐标。从屏幕坐标到"插到哪里"之间还隔着一条转换链，下一节展开。

触点反馈：让"数据流入"被看见

坐标除了用来定位，还有一个低成本的体验点：在触点位置做一个涟漪动效，让用户直观感到"内容是从我碰的这个地方进来的"。

// 触点涟漪：在触碰坐标展开一次 800ms 动画
@Entry
@Component
struct TouchRipplePage {
  @StorageLink('TouchPosX') @Watch('onTouchPosChanged') touchX: number = 0;
  @StorageLink('TouchPosY') touchY: number = 0;
  @State rippleScale: number = 0;
  @State rippleOpacity: number = 1;
  @State showRipple: boolean = false;

  // 监听坐标更新触发动效
  onTouchPosChanged() {
    if (this.touchX > 0 && this.touchY > 0) {
      this.showRipple = true;
      this.rippleScale = 0;
      this.rippleOpacity = 1;
      this.getUIContext().animateTo({
        duration: 800,
        curve: Curve.EaseOut,
        onFinish: () => { this.showRipple = false; }
      }, () => {
        this.rippleScale = 10;
        this.rippleOpacity = 0;
      });
    }
  }

  build() {
    Stack() {
      // 业务内容区……
      if (this.showRipple) {
        Circle({ width: 50, height: 50 })
          .fill(Color.Transparent)
          .stroke('#2196F3')
          .strokeWidth(3)
          .position({ x: this.touchX - 25, y: this.touchY - 25 })
          .scale({ x: this.rippleScale, y: this.rippleScale })
          .opacity(this.rippleOpacity)
      }
    }
    .width('100%')
    .height('100%')
  }
}

图：碰触后应用在触点坐标处生成 800ms 放大涟漪，给用户"内容从我碰的这个地方流入"的可见反馈

这个动效本身十几行代码，但它解决的是"反馈断链"问题：用户碰了一下，如果没有可见反馈，他会以为没碰到、再碰一次——而第二次碰触就是下一节要讲的防抖问题。

---

五、屏幕坐标到业务位置：一条不能省一环节的转换链

我卡最久的坑就在这一步。

最直觉的写法是"屏幕坐标减窗口偏移，拿到应用内坐标，往那个位置插图"。在 100% 缩放、窗口没滚动、没旋转的演示环境下，它是对的——所以 demo 能过。真机一上，三种环境就翻车：窗口在第二块高缩放比显示器上、画布已经滚动了、窗口处于分屏状态。

完整的转换链是这样的：

图 2：屏幕坐标到业务坐标的完整转换链。演示环境只需要 B，生产环境六步一个不能少。

// 屏幕坐标 → 文档画布坐标
interface Point { x: number; y: number; }
interface WindowGeometry { left: number; top: number; scale: number; }
interface CanvasViewport {
  left: number; top: number;          // 画布视口在窗口内的偏移
  scrollX: number; scrollY: number;   // 画布内容滚动量
  rotation: number;                   // 画布旋转角度
}

function screenToDocument(point: Point, win: WindowGeometry, vp: CanvasViewport): Point {
  // 1. 减窗口原点  2. 减视口偏移  3. 除显示缩放
  const x = (point.x - win.left - vp.left) / win.scale;
  const y = (point.y - win.top - vp.top) / win.scale;
  // 4. 补偿滚动（内容在视口内滚过 scrollX/scrollY）
  // 5. 逆旋转变换（画布旋转时触点要逆旋转回文档坐标系）
  return inverseRotate({ x: x + vp.scrollX, y: y + vp.scrollY }, vp.rotation);
}

转换完坐标还没有"生效"，还要过区域命中判定：同一个物理点落在不同业务区域，对应的命令完全不同。画布区域是"插入新图层"，图层面板区域应该解释为"追加资源到面板"，只读预览区则应该明确拒绝并给出原因，而不是硬插。

这一步的设计意义比代码大：精准分享的触点是一个"指令入口"，应用要把触点映射成明确的业务命令，映射不了的区域要有兜底策略。我最后的做法是把接收端建模成"三问"——

1. 目标窗口还在吗？（窗口可能已被切换/关闭）
2. 触点落在哪个业务区域？（画布 / 面板 / 只读 / 空白）
3. 内容过了门禁吗？（格式、大小、权限、存储空间）

三问任何一问答不上来，就进入对应错误分支，不猜默认值。

---

六、幂等、撤销与状态机

跨设备链路有一个绕不开的特性：不确定成功。手机碰完 PC，图片插进去了，但结果回传前连接断了，手机端重试——PC 端再插一次，图层就重了。这类"半成功"状态在单端逻辑里不存在，跨设备是常态。

应对办法是给每次碰触分享一个稳定身份，接收端按身份去重：

// 业务层分享上下文：transferId 是幂等键
interface PrecisionShareContext {
  transferId: string;        // 幂等键：本次碰触分享唯一
  sourceDeviceId: string;
  targetDeviceId: string;
  targetWindowId: string;    // 发送时识别的目标窗口
  screenPoint: { x: number; y: number };
  content: { uri: string; mimeType: string; size: number };
  sentAt: number;
}

interface InsertResult {
  code: 'OK' | 'DUPLICATE' | 'TARGET_INVALID' | 'UNSUPPORTED';
  operationId?: string;
  layerId?: string;
  undoToken?: string;        // 撤销令牌
  retryable: boolean;
}

// 幂等写入：transferId 查得到就直接返回第一次的结果
async function insertSharedImage(cmd: InsertCommand): Promise<InsertResult> {
  const cached = await transferStore.find(cmd.transferId);
  if (cached) return { ...cached, code: 'DUPLICATE' };

  const target = resolveTarget(cmd.targetWindowId);   // 三问之 1：窗口还在吗
  if (!target.ok) return { code: 'TARGET_INVALID', retryable: false };

  if (!contentGate(cmd.content)) {                    // 三问之 3：过门禁吗
    return { code: 'UNSUPPORTED', retryable: false };
  }

  const op = await target.document.insertImage(cmd);  // 真正写入
  const result: InsertResult = {
    code: 'OK',
    operationId: op.id,
    layerId: op.layerId,
    undoToken: op.undoToken,   // 给用户一个撤销入口
    retryable: false
  };
  await transferStore.save(cmd.transferId, result);
  return result;
}

两个设计决策值得单独说：

• transferId 是业务唯一键，不只是日志字段。"文档已写入、去重记录还没保存"之间有一个事务缝隙，进程在这期间恢复，靠日志查不出是否插过。把 transferId 直接作为文档操作的业务唯一键，进程恢复后仍能从文档层判断执行过没有。
• 撤销是标配，不是加分项。"碰一下"让操作成本极低，意味着误操作率上升，每个成功插入都要带 undoToken。轻预览 + 确认只用在高风险操作（覆盖选区、替换文件、外发），新增图层这类可撤销操作直接执行，入口短不等于权限大——碰一碰不能绕过登录、隐私和只读限制。

把整个接收流程建模成状态机，迟到回调的处理就有据可依了：

图 3：接收端分享状态机。终态不可再迁移——用户取消或窗口关闭后，迟到的图片准备回调不允许继续写入，这条规则挡掉了我遇到的"取消后图层还是被插进来"的 bug。

错误码也按层拆开了，每个分支一个独立错误码（窗口关闭、文档改变、区域只读、格式不支持、文件过大、权限拒绝、存储空间不足），用户看到的提示可以短，但日志必须能定位失败发生在哪一层——跨设备问题排查，日志定位不到层等于没排查。

---

七、5 个踩坑案例

1. 部分设备坐标是 undefined，精准链路直接哑火

现象：官方支持的机型组合里，个别老款平板接收时 coordinate 字段整个是 undefined，接收代码按"一定有坐标"写，应用直接走了无坐标分支却没有任何提示，用户碰完一脸懵。

排查：抓日志发现坐标不是"偶尔丢"，是特定机型 100% 丢——对照硬件规格，这批机型缺少多天线近场感知传感器。

解决：坐标非空校验前移到入口层，undefined 时不报错、不静默，降级为普通碰一碰（只传不定位），同时在 UI 上给一句轻提示"该设备不支持精准定位，已放入下载目录"。

// 入口层防御：坐标缺失时降级，而不是抛错或静默
if (screenX === undefined || screenY === undefined) {
  await this.dispatchPlainReceive(uris);
  this.getUIContext().getPromptAction().showToast({ message: '该设备不支持精准定位，内容已放入下载目录' });
  return;
}

经验：精准是增强项，底座是普通碰一碰。任何"增强能力"的接入，第一行代码就该是降级路径，而不是第一行报错。

2. 手抖一秒连碰三次，涟漪叠出鬼影

现象：测试同学手抖，一秒内碰了三次，接收端涟漪动画叠成鬼影，日志里 onNewWant 高频触发，连续碰 20 次后应用内存明显上涨，疑似文件描述符句柄累积。

排查：每次碰触都会走完整"建链 → 接收 → 落盘 → 回调"流程，三次碰触就是三份独立的接收任务并行，没有任何去重。

解决：在入口层加时间戳防抖——连续两次碰触事件间隔小于 1000ms，直接丢弃后到的事件并打日志。防抖必须放在最外层入口（回调分发之前），放在业务层去拦，链路资源已经建出来了，拦不住句柄累积。

经验：物理触发的入口，防抖是入口层职责，不是业务层职责。碰一碰的"碰"是物理动作，人手抖是设计常态不是异常。

3. 用户碰完又切了文档，素材插进了旧文档

现象：测试时我在 PC 上碰完之后顺手切了文档（想看看效果再切回来），素材插进了切换前的旧文档。用户视角：“我明明是想插给现在这个文档的。”

排查：发送侧记录的是碰触那一刻识别到的 targetWindowId，接收端拿来就用，中间隔了 1-2 秒，足够用户切走窗口。

解决：接收端不信任发送时的窗口，写入前按 targetWindowId 二次校验——窗口是否还存在、是否仍是前台业务窗口、文档版本是否变化。任一不满足走 TARGET_INVALID，提示"目标文档已变化，请重新碰触"。这一条直接改变了我的状态机设计：RECEIVED 到 VALIDATING 之间必须重新解析目标，而不是复用发送侧的上下文。

经验：跨设备分享里，发送时的世界状态和接收时的世界状态是两次采样。任何"发送时识别的目标"，接收端都要重新验证一遍，不能默认世界没变。

4. 同一张图被插了两个图层

现象：弱网模拟（故意掐断回传链路）下复现：图片插入成功，结果回传超时，发送端按失败重试，PC 端又插了一次——画布上同一张图两层。

排查：回传链路断在"文档已写入、去重记录未落库"的缝隙里。第一次执行时去重记录还没存，重试进来查不到，就当成新请求处理了。

解决：transferId 从日志字段升级为文档操作的业务唯一键（见第六节），写入和去重记录用同一个事务落库；重试进来先查 transferId，命中直接返回第一次的结果和 DUPLICATE 码，用户端显示"已插入"。

经验：跨设备链路一定存在"不确定成功"，幂等不是优化项，是默认项。单端逻辑里靠"请求不重发"假设成立的逻辑，跨设备全部不成立。

5. 高缩放比显示器上插入点整体偏移

现象：外接 2 倍缩放比的显示器，触点位置稳定偏左偏上，偏移量不固定，看起来"时准时不准"。

排查：最初转换链只减了窗口原点偏移，没除显示缩放，也没处理画布滚动——窗口在 2 倍缩放的副屏上时，屏幕像素和窗口逻辑坐标是 2 倍关系；画布滚动后偏移量还叠加滚动量，所以"时准时不准"（滚动到不同位置偏移不同）。

解决：把第五节的六步转换链补全（减窗口原点 → 减视口偏移 → 除缩放 → 补偿滚动 → 逆旋转），并在 CI 里加了一个转换链的单测矩阵：1 倍/1.5 倍/2 倍缩放 × 有滚动/无滚动 × 0°/90° 旋转，12 个组合全覆盖。

经验：屏幕坐标不等于画布坐标，这个认知在单显示器、1 倍缩放的开发机上永远不疼。多显示器和高缩放比是 PC 端的基本盘，转换链一步不能省，单测矩阵一个组合不能少。

---

八、体验细节与适用边界

体验细节（定性，具体参数待实测）

• 触觉 + 动效 + 涟漪三件套：碰触确认的反馈要叠加，任何一环缺失，用户都会"再碰一次"来确认，而再碰一次就是坑 2 的防抖压力。
• 姿态失败要有提示：手机没放平（俯视夹角超 5°）时系统不触发，用户会以为功能坏了。接入方可以在可分享页面放一句姿态引导（“把手机平放在屏幕上”），这个成本极低，但能挡掉一类"功能没反应"的反馈。
• 轻预览的阈值：新增图层这类可撤销操作直接插入不打断；覆盖、替换、外发必须先预览确认。阈值划在哪，看操作的可撤销成本，不看内容大小。

适用边界

适合	不适合
素材从手机到 PC/平板画布、文档、面板的定向投递	大批量文件传输（一次碰传几十个文件没有定向收益）
触点位置本身有业务含义的场景（画布、文档、白板的坐标可解释）	接收端是纯列表/纯文本的无坐标语义场景（退回普通分享更简单）
单机对（手机 ↔ 一台 PC/2in1/Tablet）	一对多扇出（碰一次投多个接收端，当前能力不覆盖，见 002 构想篇的分档）
内容可轻预览、可撤销的操作	不可逆操作（外发、删除、覆盖），这类操作碰一碰入口不应直接触发

性能与实测口径

回调时延、防抖阈值、大文件（视频）传输耗时等定量数据，我在真机上还没有跑完整轮，发布时统一标注"待实测"。已确认的定性结论：小图（1-3MB）从碰触到插入的链路体感在秒级以内，体感瓶颈不在传输而在缩略图生成和 UI 渲染——所以预览图延迟更新（第三节）值得做。

---

九、总结与评论引导

回看整个接入过程，"读到坐标"那一行代码不到五行，但它周围的四道关占掉了八成工作量：

1. 能力降级：精准是增强项，undefined 必须有降级路径（坑 1）；
2. 入口防抖：物理触发的入口，防抖放最外层（坑 2）；
3. 目标二次校验：发送时的世界状态不是接收时的世界状态（坑 3）；
4. 幂等与撤销：不确定成功是常态，transferId 是默认项（坑 4），再加一条转换链完整（坑 5）。

这套东西不只是碰一碰的——任何"跨设备 + 位置敏感 + 可重试"的链路（拖拽跨屏、多端协同编辑、近场交互）都会撞上同样的四道关，状态机和错误码分层可以直接复用。

还在构思阶段、还没找到落地场景的同学，我另写了一篇构想文，把"碰哪传哪"拆成五个可以直接立项的跨设备协作场景（办公协同、创意设计、教育课堂、游戏互动、智慧出行），每个都带了用户旅程和边界分析，见下一篇。

你的真机跑通坐标回调了吗？拿到的 screenX/screenY 在你们的应用里是怎么落到业务位置的？评论区聊聊，手抖防抖你们设的多少毫秒。

---

边界与已知限制

限制项	具体表现	规避方式
能力降级	老机型回调的坐标为 undefined	坐标缺失时降级为普通分享
事件防抖	手抖一秒连碰三次会产生重复投递	一次物理碰触只产生一次投递 + 内容指纹去重
窗口校验	多显示器/多窗口下可能命中错误窗口	校验 targetWindowId，不匹配则交还系统
目标变更	用户碰完又切了文档	投递前二次校验目标窗口与位置
幂等写入	同一内容被插两层	写入前做指纹比对
版本依赖	依赖 API 26 的 Beta 能力	明确标注版本，低版本不启用该路径
实测缺口	部分时延数据标注"待实测"	不做数字编造，补齐后再更新

小结

碰一碰精准分享从 demo 走到生产，要过四道关：能力降级、事件防抖、目标二次校验、幂等写入。demo 只演示"读到坐标"，而真实用户会手抖、会切窗口、会在不支持的机型上碰。

把这四道关做成状态机，而不是散落在回调里的 if 判断，是这个能力能否上线的分水岭。

评论区交流: 精准分享的坐标转换链你们做了几步？手抖防抖阈值设多少？