【鸿蒙开发实战篇】鸿蒙跨设备的碰一碰文件分享

大家好，我是 V 哥。今天我们来深入探讨如何在 HarmonyOS 6.0（API 21） 中使用 Share Kit 实现跨设备的"碰一碰"文件分享功能。这一能力是鸿蒙"一多"设计理念（一次开发，多端部署）的核心体现，可大幅提升手机与鸿蒙电脑、平板等设备间的交互效率。下面结合完整案例，详细拆解实现步骤。

联系V哥获取鸿蒙学习资料

一、功能概述与前置条件
1. 碰一碰分享的核心能力

场景支持：传输图片/视频、共享Wi-Fi密码、分享文档到指定应用窗口（如直接发送到电脑的美图秀秀）。
设备要求 ：
- 双端设备需为 HarmonyOS 5.0.0.102 SP6 及以上版本 （可用 canIUse 检测）。
- 设备需亮屏、解锁，且开启华为分享服务（系统默认开启）。
触发方式：设备顶部轻碰（手机碰手机、手机碰鸿蒙电脑）。

2. 开发环境配置

json 复制代码

// module.json5 依赖配置
"dependencies": {
  "@kit.ShareKit": "> 12.0.0",  // Share Kit 核心库
  "@kit.CoreFileKit": "> 12.0.0" // 文件路径处理
}

二、实现步骤与代码详解

步骤1：权限声明与能力检测

typescript 复制代码

// 在应用启动时检测碰一碰支持性
import { harmonyShare } from '@kit.ShareKit';

if (!harmonyShare.canIUse('SystemCapability.Collaboration.HarmonyShare')) {
  console.error("当前设备不支持碰一碰分享！");
}

注意：需在 module.json5 中声明权限：

json 复制代码

"requestPermissions": [
  { "name": "ohos.permission.COLLABORATION" }  // 跨设备协作权限
]

步骤2：注册碰一碰监听事件

在可分享页面（如图库预览页）注册监听：

typescript 复制代码

import { fileUri } from '@kit.CoreFileKit';

@Component
struct SharePage {
  // 定义回调函数处理分享目标
  private immersiveCallback(sharableTarget: harmonyShare.SharableTarget) {
    // 步骤3在此构造分享数据
  }

  onPageShow() {
    // 注册碰一碰监听
    harmonyShare.on('knockShare', this.immersiveCallback);
  }

  onPageHide() {
    // 取消监听避免冲突
    harmonyShare.off('knockShare', this.immersiveCallback);
  }
}

步骤3：构造分享数据并触发分享

以分享图片为例：

typescript 复制代码

private immersiveCallback(sharableTarget: harmonyShare.SharableTarget) {
  // 1. 获取图片路径（需转换为URI）
  const imagePath = '/data/storage/.../cache/image.png';
  const imageUri = fileUri.getUriFromPath(imagePath); // 关键！直接路径无效

  // 2. 构造分享数据（使用卡片模板）
  const shareData = {
    utd: utd.UniformDataType.IMAGE, // 文件类型
    thumbnailUri: imageUri,         // 缩略图URI
    title: '旅行照片',              // 卡片标题
    description: '西藏风景照'       // 卡片描述
  };

  // 3. 3秒内发起分享（超时失败）
  setTimeout(() => {
    sharableTarget.share(shareData); 
  }, 3000); 
}

卡片模板选择：

仅缩略图模式：宽高比需在 1:4 内。
图文卡片：适合宽高比 >1:1 的图片。

步骤4：处理Wi-Fi分享场景

typescript 复制代码

// 在WLAN设置页注册监听
private shareWifiCallback(sharableTarget: harmonyShare.SharableTarget) {
  const shareData = {
    utd: utd.UniformDataType.WIFI_CONFIG, // Wi-Fi数据类型
    title: '办公室Wi-Fi',
    description: '点击一键连接'
  };
  sharableTarget.share(shareData);
}

三、完整案例：图片分享应用

typescript 复制代码

@Entry
@Component
struct GalleryApp {
  @State selectedImage: string = '';

  // 碰一碰回调
  private knockCallback = (sharableTarget: harmonyShare.SharableTarget) => {
    if (!this.selectedImage) return;
    
    const uri = fileUri.getUriFromPath(this.selectedImage);
    sharableTarget.share({
      utd: utd.UniformDataType.IMAGE,
      thumbnailUri: uri,
      title: '即时分享',
      description: '来自图库'
    });
  };

  onPageShow() {
    harmonyShare.on('knockShare', this.knockCallback);
  }

  onPageHide() {
    harmonyShare.off('knockShare', this.knockCallback);
  }

  build() {
    Column() {
      // 图片选择列表
      Image($r('app.media.image1'))
        .onClick(() => { this.selectedImage = 'local_path/image1.jpg'; })
    }
  }
}

关键逻辑：

用户点击图片后存储路径到 selectedImage。
设备轻碰触发 knockCallback，转换路径为合法 URI。
通过 sharableTarget.share() 发送分享数据。

四、避坑指南

路径转换失败

必须使用 fileUri.getUriFromPath() 转换本地路径，直接使用 file:// 协议无效。
分享超时

从回调触发到调用 share() 需在 3秒内完成，否则系统自动取消。

图片大小限制

单文件建议不超过 32KB，过大文件需压缩：

typescript 复制代码

import { image } from '@kit.ImageKit';
const packer = image.createImagePacker();
const options = { quality: 70 }; // 压缩质量
const compressedUri = await packer.packing(imageUri, options);

设备状态校验

分享前检查设备状态：

typescript 复制代码

if (!device.isScreenOn || !device.isUnlocked) {
  prompt.showToast({ message: "请亮屏并解锁设备！" });
}

五、总结

在 HarmonyOS 6.0 中实现碰一碰分享，核心流程为 注册监听 → 构造数据 → 触发分享。开发者需重点关注：

使用 harmonyShare.on/off() 管理生命周期；
通过 fileUri.getUriFromPath() 解决路径问题；
选择符合场景的分享卡片模板；
遵守 3 秒超时限制。

"碰一碰"功能将鸿蒙的分布式能力转化为直观的物理交互，大幅简化了跨设备协作流程。未来可结合 AI 能力实现智能内容推荐（如自动识别照片场景并推荐分享对象），进一步提升用户体验。