引言

跨设备传内容这件事，理想状态是什么？大概就是——我手机上有个东西想给你，碰一下就过去了，不用加好友、不用扫码、不用等配对。

鸿蒙 Share Kit 的碰一碰分享做的就是这件事。两台手机轻碰一下，图片、链接、Wi-Fi 信息就传过去了；手机往 PC 屏幕上一放，文件就到了电脑里。整个过程没有中间步骤，靠的是设备间物理接触触发的分享机制。

本文面向希望为应用接入碰一碰分享能力的鸿蒙开发者，从手机间分享和手机与 PC/2in1 间分享两个维度，梳理这项能力的工作机制、卡片设计要点、异常处理策略，以及完整的开发流程。

---

一、手机与手机之间的碰一碰分享

1.1 基本流程

碰一碰分享的业务流程可以用四步概括：

1. 注册：应用在可分享的页面注册碰一碰事件（knockShare）。
2. 触发：用户将手机与对端设备轻碰，系统发现设备后触发回调。
3. 发送：应用在回调中构造分享数据并发送。
4. 清理：离开可分享页面时，解除事件注册。

使用前有几个前提条件：双端设备都要亮屏且解锁，华为分享服务需要处于开启状态（系统默认开启）。如果用户手动关闭了华为分享服务，轻碰时会收到系统通知提示开启。

还有一点需要了解：宿主应用无法直接获知分享结果。对端是接收了还是拒绝了，Share Kit 会通过系统通知告知用户，而不是通过回调返回给应用。如果任意一端设备不支持碰一碰能力，轻碰则完全没有响应。

环境要求方面，手机系统需要 HarmonyOS NEXT Release 及以上版本。可以用 canIUse 做运行时判断：

if (canIUse('SystemCapability.Collaboration.HarmonyShare')) {
  // 支持碰一碰分享
}

1.2 设备间的信任与安全

从 HarmonyOS NEXT 5.0.0.123 SP16 开始，碰一碰分享在发送端和接收端都会展示对方的身份信息，帮助用户确认”我在和谁传东西”：

• 如果对端已登录华为账号，会展示对方的账号昵称和头像。
• 如果对端未登录华为账号，则展示设备信息。

需要注意的是，如果发送端的系统版本低于 SP16，接收端将不会展示任何发送方信息。

---

二、分享卡片的设计：不只是技术问题

碰一碰触发后，对端设备会收到一张分享卡片。卡片的样式直接影响用户是否愿意接收，所以这部分值得认真对待。

2.1 三种卡片模板

Share Kit 根据你传入的字段组合，自动匹配不同的卡片模板：

纯图片布局——只有预览图，没有标题和描述。适合分享文件、图片等不需要文字说明的场景。构造分享数据时只传 thumbnailUri 即可触发这种布局。预览图支持最小宽高比 1:4，超出部分会被裁剪。

沉浸式大卡布局——预览图 + 标题 + 描述 + 应用图标，视觉冲击力最强。适合分享链接类内容。触发条件是同时传入 title、description、thumbnailUri，且预览图宽高比小于 1:1（即竖图）。标题最多显示 2 行，描述 1 行，超出部分以省略号截断。如果标题末尾有重要信息，建议控制在 20 个中文字符左右。

白卡上下布局——同样包含预览图、标题、描述和应用图标，但预览图只显示在卡片上方，不会铺满整张卡片。触发条件和沉浸式大卡一样，区别在于预览图宽高比大于 1:1（即横图）。

应用图标不需要额外配置，系统会自动获取。

2.2 预览图的质量建议

预览图太大会拖慢加载速度，太小则显示模糊。建议参考以下标准：

预览图来源	推荐比例	推荐分辨率
应用创作的海报	3:4	最小 600×800，最大 3000×4000
用户上传的图片	不限制	最大 3000×4000

2.3 预览图来不及下载怎么办

一个很实际的问题：如果应用使用的是云端存储的图片作为预览图，碰一碰回调触发时图片可能还没下载到本地，这就会导致超时失败。

Share Kit 对此提供了预览图延迟更新的能力。思路很简单——先发核心数据，建立连接，系统会用默认预览图填充卡片；等云端图片下载完成后，再调用 sharableTarget.updateShareData 更新预览图：

harmonyShare.on('knockShare', capabilityRegistry, (sharableTarget) => {
  // 先发送核心数据，不带预览图
  let shareData = new systemShare.SharedData({
    utd: utd.UniformDataType.HYPERLINK,
    content: 'https://sharekitdemo.drcn.agconnect.link/ZB3p',
    title: '碰一碰分享卡片标题',
    description: '碰一碰分享卡片描述'
  });
  sharableTarget.share(shareData);

  // 图片下载完成后更新预览图
  setTimeout(() => {
    let filePath = contextFaker.filesDir + '/exampleKnock1.jpg';
    sharableTarget.updateShareData({
      thumbnailUri: fileUri.getUriFromPath(filePath)
    });
  }, 5000);
});

这样用户不会因为预览图加载慢而等待，分享体验更流畅。

---

三、用户引导：让用户知道”这里可以碰”

碰一碰是一个相对新的交互方式，很多用户可能不知道当前页面支持这个功能。给出适当的引导可以有效提升分享意愿。

Share Kit 推荐两种引导方式：

• 文本提示：在页面上展示”可碰一碰分享至 HarmonyOS 5 及以上版本手机”的文案。
• 动图提示：用动画展示碰一碰的操作方式，更直观。

Share Kit 提供了统一的动图资源文件。下载后将 knock_share_guide 目录下的所有文件放到应用的 entry/src/main/resources/rawfile 目录即可使用。

---

四、核心开发流程：注册、发送、清理

4.1 注册与取消碰一碰事件

注册碰一碰事件有两种方式。简单场景下，直接传入回调函数即可：

private immersiveListening() {
  harmonyShare.on('knockShare', this.immersiveCallback);
}

private immersiveDisablingListening() {
  harmonyShare.off('knockShare', this.immersiveCallback);
}

如果需要更精细的控制（比如指定窗口、声明单向发送能力），可以传入 SendCapabilityRegistry 配置：

let capabilityRegistry: harmonyShare.SendCapabilityRegistry = {
  windowId: 999,  // 替换为实际的 windowId
};
harmonyShare.on('knockShare', capabilityRegistry, callback);

和隔空传送一样，生命周期管理是关键。进入可分享页面时注册，离开时（包括退后台）必须取消：

aboutToAppear(): void {
  this.immersiveListening();
  let context = this.getUIContext().getHostContext() as Context;
  context.eventHub.on('onBackGround', this.onBackGround);
}

aboutToDisappear(): void {
  this.immersiveDisablingListening();
  let context = this.getUIContext().getHostContext() as Context;
  context.eventHub.off('onBackGround', this.onBackGround);
}

onPageHide(): void {
  let context = this.getUIContext().getHostContext() as Context;
  context.eventHub.emit('onBackGround');
}

private onBackGround = () => {
  this.immersiveDisablingListening();
}

4.2 构造分享数据并发送

在碰一碰回调中构造分享数据。链接类分享的 utd 类型需要设置为 HYPERLINK：

private immersiveCallback = (sharableTarget: harmonyShare.SharableTarget) => {
  let filePath = contextFaker.filesDir + '/exampleKnock1.jpg';
  let shareData = new systemShare.SharedData({
    utd: utd.UniformDataType.HYPERLINK,
    content: 'https://sharekitdemo.drcn.agconnect.link/ZB3p',
    thumbnailUri: fileUri.getUriFromPath(filePath),
    title: '碰一碰分享卡片标题',
    description: '碰一碰分享卡片描述'
  });
  sharableTarget.share(shareData);
}

4.3 通过 App Linking 实现直达应用

分享链接时，强烈建议使用 App Linking 而不是普通 URL。App Linking 的好处在于：

• 应用已安装：直接拉起应用对应页面。
• 应用未安装：默认通过浏览器打开网页；配合 App Linking Kit 的直达应用市场能力，可以直接跳转到应用市场引导安装。再结合延迟链接能力，用户安装完成后首次打开应用时，仍能获取之前分享的链接内容——这对转化率的提升非常有价值。

另一种方案是 Deep Linking，但它只在本地已安装的应用中查找匹配项，未安装时会提示”暂无可用打开方式”。

4.4 异常场景的处理

碰一碰触发后，并不总是能顺利完成分享。Share Kit 提供了两种异常处理方式，帮助开发者优雅地终止分享，避免用户干等：

当前界面无可分享内容（6.0.2(22) 版本起支持）：

sharableTarget.clarifyNonShare({ 
  message: '请在支持碰一碰分享的界面再试' 
});

这会终止本次分享，并弹出提示引导用户去可分享的页面。

网络或业务原因导致分享失败（5.0.3(15) 版本起支持）：

sharableTarget.reject(harmonyShare.SharableErrorCode.DOWNLOAD_ERROR);

这会终止分享并提示用户具体原因。

---

五、邀请组队：碰一碰的另一种玩法

除了内容分享，碰一碰还有一个很有意思的应用场景——邀请组队。比如游戏中邀请旁边的朋友加入房间，碰一下手机就完成了。

这个场景有一个特殊问题：如果双方都在组队房间里互碰，会导致互相邀请加入对方房间的冲突。Share Kit 对此提供了单向仅发送能力，通过在注册时设置 sendOnly: true 来声明：

let capabilityRegistry: harmonyShare.SendCapabilityRegistry = {
  windowId: 999,
  sendOnly: true,  // 声明仅支持单向发送
};
harmonyShare.on('knockShare', capabilityRegistry, callback);

当碰一碰的双方都设置了 sendOnly，系统会终止本次分享并提示”请任意一方退出当前应用后再试”。只要有一方没设置 sendOnly，分享就能正常完成。

对端应用被拉起后，通过 onCreate 或 onNewWant 回调中的 want.uri 获取组队链接，解析其中的参数来处理组队逻辑：

onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
  console.log('收到组队链接: ', want.uri);
  // 解析链接参数，处理组队邀请
}

onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void {
  console.log('收到组队链接: ', want.uri);
  // 应用已在前台时的处理
}

---

六、手机与 PC/2in1 之间的碰一碰分享

碰一碰不只是手机之间的事。手机和 PC/2in1 设备之间也可以碰一碰分享，而且交互方式更有趣——手机直接往屏幕上一放，利用 PC/2in1 的屏幕感知能力识别碰触动作和位置，实现窗口级的精准交互。

6.1 谁发谁收的规则

从 6.0.0(20) Beta5 版本开始，手机与 PC/2in1 之间不支持双向分享，遵循明确的优先级：

1. 手机前台有可分享内容 → 手机发送，PC/2in1 接收。
2. 手机前台无可分享内容，PC/2in1 前台窗口有 → PC/2in1 发送，手机接收。
3. 双方前台都没有可分享内容 → 走无内容分享逻辑。

更早的版本（6.0.0(20) Beta3 及之前）支持双向同时分享，但后续版本取消了这个行为。

6.2 物理姿态要求

手机碰 PC/2in1 屏幕时，对放置姿态有具体要求：

• 俯视夹角 ≤ 5°（手机要基本平放在屏幕上）
• 侧视夹角 > 35°
• 正视夹角 ≤ 25°
• 手机不能超出屏幕边缘

此外，支持官方手机保护壳，但过厚的外壳可能影响感知。仅支持直板手机或折叠手机的直板形态。双端设备需要登录相同的华为账号。

6.3 沙箱接收：文件直达应用

从 6.0.0(20) 版本开始，PC/2in1 设备支持沙箱接收能力——手机碰一下屏幕，文件直接传入 PC/2in1 应用的沙箱目录，传完后通知应用处理，无需用户手动操作。

应用需要声明自己支持接收的文件类型和最大数量。如果类型不匹配，系统会回退到华为分享的默认接收逻辑；如果数量不匹配，会弹窗提示用户。

注册沙箱接收事件：

aboutToAppear(): void {
  let capabilityRegistry: harmonyShare.RecvCapabilityRegistry = {
    windowId: 999,
    capabilities: [{
      utd: utd.UniformDataType.IMAGE,
      maxSupportedCount: 1,
    }]
  };

  harmonyShare.on('dataReceive', capabilityRegistry, 
    (receivableTarget: harmonyShare.ReceivableTarget) => {
      let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
      receivableTarget.receive(context.filesDir, {
        onDataReceived: (sharedData: systemShare.SharedData) => {
          let records = sharedData.getRecords();
          records.forEach((record) => {
            // 处理接收到的文件
          });
        },
        onResult(resultCode: harmonyShare.ShareResultCode) {
          if (resultCode === harmonyShare.ShareResultCode.SHARE_SUCCESS) {
            // 接收成功
          }
        }
      });
    }
  );
}

离开页面时同样要解除注册。如果因为业务原因需要拒绝本次接收，可以调用 receivableTarget.reject()。

---

七、总结

碰一碰分享覆盖了两大场景：手机与手机之间的内容传输和组队邀请，以及手机与 PC/2in1 之间的文件传输。对开发者来说，接入时有几个核心关注点：

1. 生命周期管理是基本功。注册和取消事件必须与页面生命周期严格对应，退后台也要取消，否则会出现意料之外的行为。
2. 卡片设计影响转化。三种卡片模板由字段组合和图片比例自动决定，了解触发规则后有意识地选择合适的布局，预览图质量要控制在合理范围内。
3. 异常处理不能省。无内容可分享时用 clarifyNonShare 引导用户，网络异常时用 reject 终止等待。这些细节决定了用户在非理想状态下的体验。
4. App Linking 是最佳搭档。结合延迟链接和直达应用市场能力，即使对端没有安装应用，也能完成从分享到安装到打开内容的完整链路。
5. 手机碰 PC/2in1 的姿态要求值得在产品引导中告知用户，避免”碰了没反应”的困惑。沙箱接收能力则为 PC 端应用打开了一种高效的文件接收方式。