【HarmonyOS 5】鸿蒙碰一碰分享功能开发指南

【HarmonyOS 5】鸿蒙碰一碰分享功能开发指南

一、前言

碰一碰分享的定义
在 HarmonyOS NEXT 系统中，华为分享推出的碰一碰分享功能，为用户带来了便捷高效的跨端分享体验。开发者通过简单的代码实现，就能调用系统 API 拉起分享卡片模板，实现设备间的快速分享。

本文将结合 HarmonyOS 官网信息，详细介绍碰一碰分享功能的实现与应用。

碰一碰分享功能的应用场景​
文件快速传输：
在工作场景中，用户可通过碰一碰快速分享文档、表格等文件，无需繁琐的网络传输或蓝牙配对，提高工作效率。​
照片分享：
在聚会、旅行等场景下，用户能将拍摄的照片迅速分享给朋友，让美好瞬间及时传递。​
Wi-Fi 共享：
当处于陌生网络环境时，用户可通过碰一碰共享他人设备上的 Wi-Fi 连接信息，快速接入网络，避免手动输入密码的麻烦。​
文章分享：
在阅读资讯类应用时，用户可通过碰一碰将感兴趣的文章分享给他人，简化分享流程。

二、碰一碰分享功能概述

碰一碰分享功能支持用户通过设备轻触发起跨端分享，可实现图片传输、Wi-Fi 共享等功能。目前该功能仅支持手机与手机之间的操作，且双端设备需为 HarmonyOS NEXT 5.0.0.102 SP6 及以上版本，可使用canIUse进行判断。

手机应用发起碰一碰分享时，双端设备需处于亮屏、解锁状态，且均已开启华为分享服务（系统默认开启），设备顶部轻碰即可触发。若用户手动关闭华为分享服务开关，轻碰时会收到系统通知提示开启。

三、业务流程

注册靠近分享：
源端设备的宿主应用进入可分享界面后，需注册靠近分享功能，以便能响应碰一碰操作。

设备触碰与条件判断：
源端与目标设备碰一碰，此时系统会判断是否满足分享条件，如设备版本、分享服务是否开启等。

构造分享数据：
满足条件后，宿主应用构造分享数据，包括分享内容的类型、标题、描述、缩略图等信息。
发起华为分享：通过调用相关 API，发起华为分享，将分享数据传输至目标设备。

拉起目标应用：
目标设备接收分享数据后，拉起对应的目标应用。

解除注册：
分享完成后，源端设备的宿主应用解除注册靠近分享，避免后续冲突。

四、宿主设备开发步骤

导入相关模块：
在开发过程中，需要引入 arkdata、sharekit、corefilekit 等模块。例如：

import { uniformTypeDescriptor as utd } from '@kit.ArkData'; 
import { systemShare, harmonyShare } from '@kit.ShareKit'; 
import { fileUri } from '@kit.CoreFileKit';

定义方法
监听方法：定义碰一碰分享事件监听方法，通过harmonyShare.on()来实现，并传入回调函数处理分享事件。例如：

private immersiveCallback(sharableTarget: harmonyShare.SharableTarget) { // 处理分享逻辑
} 
private immersiveListening() { harmonyShare.on('knockShare', this.immersiveCallback); 
}

取消监听方法：
当宿主设备离开可分享页面（如应用退至后台等场景）时，需取消碰一碰分享监听事件，通过harmonyShare.off()实现。例如：

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

注意：收到回调后，需在 3 秒内调用
sharableTarget.share()方法发起分享，否则可能导致分享失败。

处理事件：
在页面的不同生命周期，处理注册和取消监听事件。例如：

onPageHide(): void { // 页面隐藏时取消监听this.immersiveDisablingListening(); 
} 
aboutToAppear(): void { // 页面即将显示时注册监听this.immersiveListening(); 
} 
aboutToDisappear(): void { // 页面即将消失时取消监听this.immersiveDisablingListening(); 
} 
private onBackGround() { // 应用退至后台时取消监听this.immersiveDisablingListening(); 
}

五、分享卡片模板

Share Kit 提供了三种分享卡片模板，开发者可根据分享数据类型和预览图宽高比进行选择。

纯图片布局：
适用于分享文件、图片等无需标题和描述的场景。构造分享数据时，仅传递预览图（thumbnailUri）字段。预览图支持最小宽高比 1:4，超出部分将被裁剪。

沉浸式大卡布局：
用于分享链接且预览图宽高比小于 1:1 的情况。构造分享数据时，需同时传入标题、描述、预览图字段。预览图最小宽高比 1:4，标题最大显示 2 行，描述仅显示 1 行，系统默认获取应用图标。

白卡上下布局：
当分享链接且预览图宽高比大于 1:1 时使用。构造分享数据时，同样需传入标题、描述、预览图字段。预览图显示在卡片上方，标题最大显示 2 行，描述仅显示 1 行，系统默认获取应用图标。

六、源码示例分享

// 导入必要的模块：统一类型描述符、分享工具包和文件URI处理工具
import { uniformTypeDescriptor as utd } from '@kit.ArkData';
import { systemShare, harmonyShare } from '@kit.ShareKit';
import { fileUri } from '@kit.CoreFileKit';/*** 组件即将显示时的生命周期回调* 页面加载完成，即将显示在屏幕上时触发*/
aboutToAppear(): void {// 注册碰一碰分享监听，准备接收碰一碰事件this.immersiveListening();// 获取当前上下文的事件中心let context = getContext(this);// 监听应用进入后台事件，当应用进入后台时执行相应处理context.eventHub.on('onBackGround', this.onBackGround);
}/*** 组件即将销毁时的生命周期回调* 页面即将被销毁时触发*/
aboutToDisappear(): void {// 取消碰一碰分享监听，避免资源浪费和误触发this.immersiveDisablingListening();// 获取当前上下文的事件中心let context = getContext(this);// 继续监听应用进入后台事件，确保在组件销毁过程中也能响应context.eventHub.on('onBackGround', this.onBackGround);
}/*** 应用进入后台时的处理函数* 当应用被切换到后台运行时调用*/
private onBackGround() {// 确保应用在后台时取消碰一碰分享监听// 避免与其他应用产生碰一碰数据传输冲突this.immersiveDisablingListening();
}/*** 碰一碰触发回调函数* @param sharableTarget - 碰一碰分享目标对象，用于发起实际分享操作*/
private immersiveCallback(sharableTarget: harmonyShare.SharableTarget) {// 获取当前上下文，用于访问文件系统const contextFaker: Context = getContext(this);// 构建分享文件的路径，exampleKnock1.jpg需提前准备在应用文件目录中let filePath = contextFaker.filesDir + '/exampleKnock1.jpg';// 创建分享数据对象，配置分享内容和展示样式let shareData: systemShare.SharedData = new systemShare.SharedData({// 设置分享内容类型为超链接utd: utd.UniformDataType.HYPERLINK,// 分享的链接地址content: 'https://sharekitdemo.drcn.agconnect.link/ZB3p',// 配置分享卡片的预览图（需确保文件存在）thumbnailUri: fileUri.getUriFromPath(filePath),// 分享卡片的标题（显示在卡片上方）title: '碰一碰分享卡片标题',// 分享卡片的描述信息（显示在标题下方）description: '碰一碰分享卡片描述'});// 调用分享目标对象的share方法发起碰一碰分享// 注意：必须在3秒内调用此方法，否则可能导致分享失败sharableTarget.share(shareData);
}/*** 注册碰一碰分享监听事件* 当两个设备碰一碰时，系统会触发knockShare事件*/
private immersiveListening() {// 注册碰一碰分享事件监听器，指定回调函数处理分享逻辑harmonyShare.on('knockShare', this.immersiveCallback);
}/*** 取消碰一碰分享监听事件* 防止在不需要分享的场景下误触发*/
private immersiveDisablingListening() {// 移除碰一碰分享事件监听器，停止接收碰一碰事件harmonyShare.off('knockShare', this.immersiveCallback);
}/*** 页面隐藏时的生命周期回调* 当页面被其他页面覆盖时触发*/
onPageHide(): void {// 获取当前上下文的事件中心let context = getContext(this);// 发送应用进入后台的事件通知context.eventHub.emit('onBackGround');
}