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

一、前言

碰一碰分享的定义

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

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

碰一碰分享功能的应用场景
文件快速传输：

在工作场景中，用户可通过碰一碰快速分享文档、表格等文件，无需繁琐的网络传输或蓝牙配对，提高工作效率。
照片分享：

在聚会、旅行等场景下，用户能将拍摄的照片迅速分享给朋友，让美好瞬间及时传递。
Wi-Fi 共享：

当处于陌生网络环境时，用户可通过碰一碰共享他人设备上的 Wi-Fi 连接信息，快速接入网络，避免手动输入密码的麻烦。
文章分享：

在阅读资讯类应用时，用户可通过碰一碰将感兴趣的文章分享给他人，简化分享流程。

二、碰一碰分享功能概述

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

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

三、业务流程

注册靠近分享：

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

设备触碰与条件判断：

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

构造分享数据：

满足条件后，宿主应用构造分享数据，包括分享内容的类型、标题、描述、缩略图等信息。

发起华为分享：通过调用相关 API，发起华为分享，将分享数据传输至目标设备。

拉起目标应用：

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

解除注册：

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

四、宿主设备开发步骤

导入相关模块：

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

dart 复制代码

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

定义方法

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

dart 复制代码

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

取消监听方法：

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

dart 复制代码

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

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

处理事件：

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

dart 复制代码

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 行，系统默认获取应用图标。

六、源码示例分享

dart 复制代码

// 导入必要的模块：统一类型描述符、分享工具包和文件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');
}