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

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

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

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

1.1基本流程

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

注册：应用在可分享的页面注册碰一碰事件（knockShare）。

触发：用户将手机与对端设备轻碰，系统发现设备后触发回调。

发送：应用在回调中构造分享数据并发送。

清理：离开可分享页面时，解除事件注册。

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

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

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

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

1.2设备间的信任与安全

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

如果对端已登录华为账号，会展示对方的账号昵称和头像。

如果对端未登录华为账号，则展示设备信息。

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

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

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

2.1三种卡片模板

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

纯图片布局——只有预览图，没有标题和描述。适合分享文件、图片等不需要文字说明的场景。构造分享数据时只传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预览图来不及下载怎么办

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

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

harmonyShare.on('knockShare',capabilityRegistry,(sharableTarget)=>{//先发送核心数据，不带预览图letshareData=newsystemShare.SharedData({utd:utd.UniformDataType.HYPERLINK,content:'https://sharekitdemo.drcn.agconnect.link/ZB3p',title:'碰一碰分享卡片标题',description:'碰一碰分享卡片描述'});sharableTarget.share(shareData);//图片下载完成后更新预览图setTimeout(=>{letfilePath=contextFaker.filesDir+'/exampleKnock1.jpg';sharableTarget.updateShareData({thumbnailUri:fileUri.getUriFromPath(filePath)});},5000);});

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

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

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

ShareKit推荐两种引导方式：

文本提示：在页面上展示”可碰一碰分享至HarmonyOS5及以上版本手机”的文案。

动图提示：用动画展示碰一碰的操作方式，更直观。

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

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

4.1注册与取消碰一碰事件

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

privateimmersiveListening{harmonyShare.on('knockShare',this.immersiveCallback);}privateimmersiveDisablingListening{harmonyShare.off('knockShare',this.immersiveCallback);}

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

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

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

aboutToAppear:void{this.immersiveListening;letcontext=this.getUIContext.getHostContextasContext;context.eventHub.on('onBackGround',this.onBackGround);}aboutToDisappear:void{this.immersiveDisablingListening;letcontext=this.getUIContext.getHostContextasContext;context.eventHub.off('onBackGround',this.onBackGround);}onPageHide:void{letcontext=this.getUIContext.getHostContextasContext;context.eventHub.emit('onBackGround');}privateonBackGround==>{this.immersiveDisablingListening;}

4.2构造分享数据并发送

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

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

4.3通过AppLinking实现直达应用

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

应用已安装：直接拉起应用对应页面。

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

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

4.4异常场景的处理

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

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

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

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

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

sharableTarget.reject(harmonyShare.SharableErrorCode.DOWNLOAD_ERROR);

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

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

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

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

letcapabilityRegistry: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之间不支持双向分享，遵循明确的优先级：

手机前台有可分享内容→手机发送，PC/2in1接收。

手机前台无可分享内容，PC/2in1前台窗口有→PC/2in1发送，手机接收。

双方前台都没有可分享内容→走无内容分享逻辑。

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

6.2物理姿态要求

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

俯视夹角≤5°（手机要基本平放在屏幕上）

侧视夹角>35°

正视夹角≤25°

手机不能超出屏幕边缘

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

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

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

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

注册沙箱接收事件：

aboutToAppear:void{letcapabilityRegistry:harmonyShare.RecvCapabilityRegistry={windowId:999,capabilities:[{utd:utd.UniformDataType.IMAGE,maxSupportedCount:1,}]};harmonyShare.on('dataReceive',capabilityRegistry,(receivableTarget:harmonyShare.ReceivableTarget)=>{letcontext=this.getUIContext.getHostContextascommon.UIAbilityContext;receivableTarget.receive(context.filesDir,{onDataReceived:(sharedData:systemShare.SharedData)=>{letrecords=sharedData.getRecords;records.forEach((record)=>{//处理接收到的文件});},onResult(resultCode:harmonyShare.ShareResultCode){if(resultCode===harmonyShare.ShareResultCode.SHARE_SUCCESS){//接收成功}}});});}

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

七、总结

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

生命周期管理是基本功。注册和取消事件必须与页面生命周期严格对应，退后台也要取消，否则会出现意料之外的行为。

卡片设计影响转化。三种卡片模板由字段组合和图片比例自动决定，了解触发规则后有意识地选择合适的布局，预览图质量要控制在合理范围内。

异常处理不能省。无内容可分享时用clarifyNonShare引导用户，网络异常时用reject终止等待。这些细节决定了用户在非理想状态下的体验。

AppLinking是最佳搭档。结合延迟链接和直达应用市场能力，即使对端没有安装应用，也能完成从分享到安装到打开内容的完整链路。

手机碰PC/2in1的姿态要求值得在产品引导中告知用户，避免”碰了没反应”的困惑。沙箱接收能力则为PC端应用打开了一种高效的文件接收方式。