本文介绍 HarmonyOS Share Kit 的碰一碰分享能力，涵盖手机间及手机与 PC/2in1 协同场景。内容包含环境要求、核心业务流程、事件注册、数据构造、预览图优化、App Linking 与 Deep Linking 选择、安全策略及异常处理。通过代码示例详解如何注册监听、发送共享数据、沙箱接收及组队邀请开发，帮助开发者实现跨设备一碰即传体验。
HarmonyOS 的 Share Kit 推出的'碰一碰分享'能力，通过'设备轻触'这一直观交互，将跨端分享简化为'一碰即传'，支持图片、文件、Wi-Fi、组队邀请等多场景。本文将结合官方开发文档，从手机间分享、手机与 PC/2in1 协同两大场景，详解开发流程、核心代码与避坑要点。
在开始开发前，需先明确功能依赖的环境要求与核心逻辑，避免因版本不兼容导致功能失效。
不同设备间的碰一碰分享，对系统版本和开发工具的要求不同，具体如下：
| 分享场景 | 设备系统要求 | 集成开发环境 |
|---|
| 手机与手机 | 双端均为 HarmonyOS NEXT Release 及以上（推荐 5.0+） | DevEco Studio NEXT Beta1+ |
| 手机与 PC/2in1 | 手机：同上方；PC/2in1：HarmonyOS 6.0.0 Beta1+ | DevEco Studio 6.0.0 Beta1+ |
关键检查：通过 canIUse 判断设备是否支持碰一碰能力，避免在不支持的设备上触发无效逻辑：
// 检查设备是否支持碰一碰分享
if(canIUse('SystemCapability.Collaboration.HarmonyShare')){
console.log("设备支持碰一碰分享，可初始化相关逻辑");
// 后续注册碰一碰事件...
} else {
console.log("设备不支持碰一碰分享，需隐藏相关引导");
}
无论哪种场景，碰一碰分享的核心流程都遵循'注册→触发→传输→解除'四步，以手机与手机为例：
手机间碰一碰是最基础的场景，需重点关注预览体验、数据传输方式、安全策略与异常兜底，以下分模块详解。
用户可能不清楚'何时可碰'，需在可分享界面添加引导（文本 + 动图），提升交互感知。
华为提供统一的碰一碰引导动图，需：
knock_share_guide 目录）；entry/src/main/resources/rawfile 目录；在页面 aboutToAppear 生命周期中注册碰一碰事件，aboutToDisappear 中解除，确保资源释放：
import { uniformTypeDescriptor as utd } from '@kit.ArkData';
import { systemShare, harmonyShare } from '@kit.ShareKit';
import { fileUri } from '@kit.CoreFileKit';
import { UIContext, Context } from '@kit.ArkUI';
@Component
export default struct ImageSharePage {
// 页面进入时注册碰一碰监听
aboutToAppear(): void {
this.registerKnockShare();
}
// 页面销毁时解除监听
aboutToDisappear(): void {
this.unregisterKnockShare();
}
// 注册碰一碰分享事件
private registerKnockShare() {
// 配置监听参数（windowId 需替换为实际页面的窗口 ID，不可用示例值）
const capabilityRegistry: harmonyShare.SendCapabilityRegistry = {
windowId: 1001, // 实际开发中通过 UIContext 获取真实 windowId
};
// 监听碰一碰事件，触发时构造并发送数据
harmonyShare.on('knockShare', capabilityRegistry, (sharableTarget: harmonyShare.SharableTarget) => {
this.buildShareData(sharableTarget);
});
}
// 解除碰一碰分享监听
private unregisterKnockShare() {
const capabilityRegistry: harmonyShare.SendCapabilityRegistry = {
windowId: 1001, // 与注册时的 windowId 一致
};
harmonyShare.off('knockShare', capabilityRegistry);
}
// 构造分享数据（核心逻辑）
private buildShareData(sharableTarget: harmonyShare.SharableTarget) {
// 1. 获取预览图 URI（示例：本地图片路径，实际需替换为业务图片路径）
const uiContext: UIContext = this.getUIContext();
const context: Context = uiContext.getHostContext() as Context;
const imagePath = context.filesDir + '/shared_image.jpg';
const thumbnailUri = fileUri.getUriFromPath(imagePath);
// 2. 构造分享数据（utd 类型根据内容调整，图片可设为 IMAGE，链接设为 HYPERLINK）
const shareData: systemShare.SharedData = new systemShare.SharedData({
utd: utd.UniformDataType.IMAGE, // 图片类型
content: thumbnailUri, // 图片 URI
title: '旅行照片', // 卡片标题（可选，根据模板决定）
description: '2025 年夏日旅行', // 卡片描述（可选）
thumbnailUri: thumbnailUri, // 预览图 URI
});
// 3. 发起分享（必须在 3 秒内调用，否则超时失败）
sharableTarget.share(shareData);
}
build() {
// 页面布局（省略，需包含图片预览 + 碰一碰引导动图）
}
}
分享卡片的预览效果直接影响用户接受度，Share Kit 提供 3 种卡片模板，需根据分享内容类型选择：
| 模板类型 | 适用场景 | 配置要求 | 布局约束 |
|---|---|---|---|
| 纯图片布局 | 文件、图片（无需文字说明） | 仅传递 thumbnailUri | 预览图宽高比≥1:4，超出部分裁剪 |
| 沉浸式大卡布局 | 链接（需展示文字） | 同时传递 title+description+thumbnailUri，且预览图宽高比＜1:1 | 标题最多 2 行（超出省略），描述 1 行，显应用图标 |
| 白卡上下布局 | 链接（需展示文字） | 同时传递 title+description+thumbnailUri，且预览图宽高比＞1:1 | 同上，预览图仅占卡片上方，不铺满 |
预览图分辨率影响加载速度与清晰度，推荐按以下标准设置（文档 2）：
| 预览图来源 | 推荐比例 | 推荐分辨率（px） |
|---|---|---|
| 应用海报 | 3:4 | 最小 600_800，最大 3000_4000 |
| 用户上传图片 | 无限制 | 最大 3000*4000（避免过大） |
若预览图存储在云端（如 OSS），碰一碰触发时可能未下载完成，导致卡片空白。可先发送核心数据，待图片下载后更新预览：
private buildShareData(sharableTarget: harmonyShare.SharableTarget) {
// 1. 先发送无预览图的核心数据（用系统默认图占位）
const shareData: systemShare.SharedData = new systemShare.SharedData({
utd: utd.UniformDataType.HYPERLINK,
content: 'https://example.com/travel', // 分享链接
title: '旅行攻略',
description: '超全景点指南',
});
sharableTarget.share(shareData);
// 2. 模拟云端图片下载（实际项目中替换为真实下载回调）
setTimeout(async () => {
const uiContext: UIContext = this.getUIContext();
const context: Context = uiContext.getHostContext() as Context;
// 假设下载完成，获取本地路径
const downloadedImagePath = context.filesDir + '/downloaded_poster.jpg';
const newThumbnailUri = fileUri.getUriFromPath(downloadedImagePath);
// 3. 更新预览图
sharableTarget.updateShareData({
thumbnailUri: newThumbnailUri,
});
}, 3000); // 实际不建议用固定延迟，应监听下载完成事件
}
若分享内容为'链接'（如商品页、文章页），需通过以下两种方式实现应用跳转，核心区别在于'未安装应用时的处理逻辑'。
优势：无论目标端是否安装应用，均能直达内容——
示例代码：
private buildShareData(sharableTarget: harmonyShare.SharableTarget) {
const shareData: systemShare.SharedData = new systemShare.SharedData({
utd: utd.UniformDataType.HYPERLINK, // 必须设为 HYPERLINK
content: 'https://sharekitdemo.drcn.agconnect.link/ZB3p', // App Linking 链接
title: '华为商城新品',
description: 'nova 14 系列限时优惠',
thumbnailUri: 'file:///data/storage/.../poster.jpg', // 预览图 URI
});
sharableTarget.share(shareData);
}
局限：仅在目标端已安装应用时生效，未安装则弹窗提示'暂无可用打开方式'。
示例代码：
// 与 App Linking 代码类似，仅 content 替换为 Deep Linking 链接
content: 'myapp://product/detail?id=123', // 自定义 Deep Linking 协议
为避免用户接收陌生设备的分享，Share Kit 会显示发送端/接收端的身份信息（需 HarmonyOS NEXT 5.0.0.123 SP16 及以上版本）：
| 角色 | 对端已登录华为账号 | 对端未登录华为账号 |
|---|---|---|
| 发送端 | 显示接收端账号昵称 + 头像 | 显示接收端设备名（如'Mate 70'） |
| 接收端 | 显示发送端账号昵称 + 头像 | 显示发送端设备名 |
注意：SP16 之前的版本不显示任何身份信息，开发时需考虑版本兼容。
当无法发起分享时，需主动提示用户，避免用户等待。
场景 1：当前界面无可分享内容
harmonyShare.on('knockShare', (sharableTarget: harmonyShare.SharableTarget) => {
// 调用 clarifyNonShare 终止分享，并提示用户
sharableTarget.clarifyNonShare({ message: '当前界面不支持碰一碰，请在图片预览或文件详情页尝试' });
});
效果：系统弹窗提示用户，引导至可分享界面。
场景 2：分享内容下载失败（如云端图片下载超时）
harmonyShare.on('knockShare', (sharableTarget: harmonyShare.SharableTarget) => {
// 模拟下载失败
const downloadFailed = true;
if (downloadFailed) {
// 调用 reject 终止分享，指定错误码
sharableTarget.reject(harmonyShare.SharableErrorCode.DOWNLOAD_ERROR);
}
});
效果：系统提示'分享内容下载失败，请稍后重试'。
手机与 PC/2in1 的碰一碰进一步拓展场景（如手机传图到 PC 编辑、PC 传文档到手机），需关注双向分享限制与沙箱接收特性。
从 HarmonyOS 6.0.0 Beta5 开始，手机与 PC/2in1 不支持'双向同时分享'，遵循以下优先级：
注意：Beta5 之前的版本支持双向分享（双方同时发送接收），开发时需根据版本适配逻辑。
PC/2in1 支持'沙箱接收'，即手机碰 PC 后，文件直接传入 PC 应用的沙箱目录，无需用户选择保存路径，实现'直达编辑'（如手机传图到 PC 版 PS，直接打开编辑）。
import { uniformTypeDescriptor as utd } from '@kit.ArkData';
import { systemShare, harmonyShare } from '@kit.ShareKit';
import { common } from '@kit.AbilityKit';
@Component
export default struct PCImageEditorPage {
aboutToAppear(): void {
this.registerSandboxReceive();
}
aboutToDisappear(): void {
this.unregisterSandboxReceive();
}
// 注册沙箱接收事件（仅支持文件类型）
private registerSandboxReceive() {
const capabilityRegistry: harmonyShare.RecvCapabilityRegistry = {
windowId: 2001, // PC 应用窗口 ID
capabilities: [
{
utd: utd.UniformDataType.IMAGE, // 仅接收图片类型
maxSupportedCount: 5, // 最多接收 5 张图片
},
],
};
// 监听数据接收事件
harmonyShare.on('dataReceive', capabilityRegistry, (receivableTarget: harmonyShare.ReceivableTarget) => {
const uiContext = this.getUIContext();
const context = uiContext.getHostContext() as common.UIAbilityContext;
// 指定文件保存路径（应用沙箱目录）
const savePath = context.filesDir + '/received_images/';
// 接收文件
receivableTarget.receive(savePath, {
// 每接收一个文件触发 onDataReceived
onDataReceived: (sharedData: systemShare.SharedData) => {
const records = sharedData.getRecords();
records.forEach((record) => {
console.log(`接收文件：${record.uri}`);
// 触发应用编辑逻辑（如打开图片编辑界面）
this.openImageEditor(record.uri);
});
},
// 接收完成/失败触发 onResult
onResult: (resultCode: harmonyShare.ShareResultCode) => {
if (resultCode === harmonyShare.ShareResultCode.SHARE_SUCCESS) {
console.log("所有文件接收完成");
} else {
console.log(`接收失败，错误码：${resultCode}`);
}
},
});
});
}
// 解除沙箱接收监听
private unregisterSandboxReceive() {
const capabilityRegistry: harmonyShare.RecvCapabilityRegistry = {
windowId: 2001,
capabilities: [
{
utd: utd.UniformDataType.IMAGE,
maxSupportedCount: 5,
},
],
};
harmonyShare.off('dataReceive', capabilityRegistry);
}
// 打开图片编辑界面
private openImageEditor(imageUri: string) {
// 业务逻辑：跳转编辑页并加载图片
}
build() {
// PC 应用界面（省略）
}
}
若应用当前无法接收（如编辑中），可调用 reject 拒绝：
harmonyShare.on('dataReceive', (receivableTarget: harmonyShare.ReceivableTarget) => {
// 业务判断：当前正在编辑，拒绝接收
if (this.isEditing) {
receivableTarget.reject(harmonyShare.ReceivableErrorCode.NO_RECEIVABLE_ERROR);
}
});
在游戏、运动类应用中，可通过碰一碰发起'组队邀请'，需避免'双方同时邀请'导致的冲突，此时需使用单向分享能力。
aboutToAppear(): void {
const capabilityRegistry: harmonyShare.SendCapabilityRegistry = {
windowId: 3001,
sendOnly: true, // 申明'仅发送邀请，不接收邀请'
};
harmonyShare.on('knockShare', capabilityRegistry, (sharableTarget) => {
// 构造组队链接（含房间 ID、邀请者信息）
const teamLink = `mygame://team/join?id=12345&inviter=user1`;
const shareData = new systemShare.SharedData({
utd: utd.UniformDataType.HYPERLINK,
content: teamLink,
title: '邀请加入游戏战队',
description: '点击立即组队开黑',
thumbnailUri: 'file:///.../team_poster.jpg',
});
sharableTarget.share(shareData);
});
}
sendOnly: true：系统终止分享，提示'请任意一方退出当前应用后再试'；onNewWant 获取组队链接。获取组队链接：
import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
export default class GameAbility extends UIAbility {
// 应用首次启动时获取链接
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
if (want.uri) {
console.log(`收到组队邀请：${want.uri}`);
this.joinTeam(want.uri); // 解析链接并加入队伍
}
}
// 应用已启动时获取链接
onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void {
if (want.uri) {
this.joinTeam(want.uri);
}
}
private joinTeam(teamUri: string) {
// 解析 URI 中的房间 ID、邀请者信息，发起加入请求
}
}
canIUse 判断设备能力，避免无效逻辑；aboutToDisappear 中解除碰一碰监听，防止内存泄漏；希望开发者可以通过以上开发指南，快速实现 HarmonyOS 碰一碰分享功能，为用户提供'一碰即传'的跨端体验。随着鸿蒙生态的扩展，未来碰一碰还将支持更多设备（如平板、智慧屏），进一步丰富全场景交互。
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online
将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。 在线工具，HTML转Markdown在线工具，online
通过删除不必要的空白来缩小和压缩JSON。 在线工具，JSON 压缩在线工具，online
将JSON字符串修饰为友好的可读格式。 在线工具，JSON美化和格式化在线工具，online