不用多设备模拟器跑通 ShareKit 碰一碰分享

爱吃大芒果

18人浏览 · 2026-07-10 19:30:38

爱吃大芒果 · 2026-07-10 19:30:38 发布

很多开发者想上手鸿蒙特色的碰一碰分享，但手头没有两台支持NFC的鸿蒙实体设备，甚至只有模拟器环境。先明确一个客观前提：

碰一碰的硬件触发环节（NFC近场检测、设备自动发现）依赖实体NFC与蓝牙硬件，纯模拟器无法1:1还原真实触碰的无感交互；
但碰一碰分享的核心数据封装、沙箱文件共享、跨端传输逻辑全部基于ShareKit统一套件，完全可以在单设备/模拟器上跑通验证。

本文的目标是：不用多台设备、不用实体NFC硬件，在模拟器中完成ShareKit分享核心逻辑的开发与调试。最终写出的代码100%兼容真实碰一碰场景，后续有实体设备时只需增加触发入口，无需重构任何核心业务代码。

一、先搞懂：ShareKit 与碰一碰分享的关系

1.1 什么是 ShareKit

@kit.ShareKit 是鸿蒙系统全域分享的统一官方套件，整合了系统分享面板、碰一碰分享、跨设备拖拽、近邻分享等多种分享形态，替代了旧版零散的分享接口。所有分享形态共用同一套数据参数规范，底层复用分布式软总线传输能力，开发者不用关心底层传输协议，一套代码适配所有分享场景。

从API 12开始正式纳入@kit体系，到鸿蒙7（API 26）已经完善了文本、文件、URI、富媒体等全类型分享能力，是鸿蒙分布式特色的核心入口之一。

1.2 碰一碰分享的两层结构

完整的碰一碰分享可以拆解为两个独立层级，这也是我们能在模拟器上调试的核心依据：

NFC触发层：设备通过NFC近场检测发现对端设备，匹配后拉起分享通道，属于硬件交互层
ShareKit传输层：封装分享数据（文本/文件/媒体），处理沙箱权限，通过软总线完成数据传输，属于业务逻辑层

模拟器缺失的只是「NFC触发层」的硬件检测能力，传输层的全部能力都可以正常调用。我们只需用按钮点击替代NFC触碰，直接调用ShareKit标准接口，就能验证90%以上的业务逻辑。

1.3 版本与环境要求

SDK版本：API 12及以上，推荐使用API 26（鸿蒙7）获得完整能力
开发工具：DevEco Studio 5.0 及以上版本
运行环境：鸿蒙系统模拟器 / 单台鸿蒙实体设备（无需两台）
注意：纯模拟器无法实现跨设备远端传输，但可完整验证分享参数封装、系统面板拉起、本地应用间分享、沙箱文件共享等核心逻辑

二、前置工程配置

2.1 编译环境校准

打开工程根目录 build-profile.json5，确保编译SDK版本满足要求：

{
  "app": {
    "compileSdkVersion": "26.0.0",
    "compatibleSdkVersion": "26.0.0",
    "targets": [
      {
        "name": "default",
        "runtimeOS": "HarmonyOS"
      }
    ]
  }
}

2.2 权限与能力配置

打开 entry/src/main/module.json5，在 requestPermissions 中添加必要权限。分享应用沙箱内的文件无需额外存储权限，但如果需要读取系统公共目录的文件，需配置对应权限：

"requestPermissions": [
  {
    "name": "ohos.permission.READ_IMAGEVIDEO",
    "reason": "$string:permission_read_media",
    "usedScene": {
      "abilities": ["EntryAbility"],
      "when": "inuse"
    }
  },
  {
    "name": "ohos.permission.READ_PASTEBOARD",
    "reason": "$string:permission_pasteboard"
  }
]

核心注意：分享应用自身沙箱目录内的文件，不需要申请系统存储权限，只需通过FileURI转换为系统可识别的分享地址即可，这是很多新手容易踩坑的地方。

三、实战：模拟器跑通 ShareKit 分享核心

我们实现一个完整可运行的Demo，包含文本分享和沙箱文件分享两个核心场景，点击按钮直接调用ShareKit标准接口，在模拟器中即可拉起系统分享面板，验证全部数据逻辑。

3.1 完整可运行代码

在这里插入图片描述

打开 entry/src/main/ets/pages/Index.ets，替换为以下代码，直接复制即可运行：

// 导入所需Kit，全部为鸿蒙7标准@kit体系
import { share, ShareParams, ShareType } from '@kit.ShareKit';
import { fs, fileUri } from '@kit.CoreFileKit';
import { promptAction } from '@kit.ArkUI';
import { hilog } from '@kit.PerformanceAnalysisKit';

const TAG = 'ShareKitDemo';

@Entry
@Component
struct ShareDemoPage {
  @State inputText: string = '这是来自ShareKit的测试文本，单设备模拟器也能跑通！';

  /**
   * 文本分享：最基础的分享能力，碰一碰与系统面板共用同一逻辑
   */
  async handleTextShare() {
    if (!this.inputText.trim()) {
      promptAction.showToast({ message: '请输入分享内容' });
      return;
    }

    try {
      // 构造标准分享参数，所有分享场景通用
      const shareParams: ShareParams = {
        shareType: ShareType.TEXT,
        title: '文本分享测试',
        text: this.inputText,
        // 可选：配置分享摘要、缩略图等扩展信息
        summary: '来自鸿蒙应用的碰一碰分享测试'
      };

      // 调用统一分享入口：实体设备碰一碰时自动优先展示近场设备
      await share.share(shareParams);
      hilog.info(0x0000, TAG, '分享面板拉起成功');
    } catch (err) {
      hilog.error(0x0000, TAG, `文本分享失败: ${JSON.stringify(err)}`);
      promptAction.showToast({ message: '分享调用失败' });
    }
  }

  /**
   * 文件分享：沙箱文件转系统可分享URI，碰一碰跨设备传输核心逻辑
   */
  async handleFileShare() {
    try {
      const context = getContext(this);
      const testFilePath = `${context.filesDir}/share_test.txt`;

      // 1. 先在应用沙箱内创建一个测试文件
      const testContent = `鸿蒙ShareKit碰一碰分享测试文件\n生成时间: ${new Date().toLocaleString()}\n支持沙箱文件跨设备安全共享`;
      fs.writeText(testFilePath, testContent);
      hilog.info(0x0000, TAG, `测试文件已创建: ${testFilePath}`);

      // 2. 核心步骤：将沙箱本地路径转换为系统可识别的File URI
      // 注意：直接传文件路径会导致分享失败，必须经过URI转换
      const shareFileUri = fileUri.getUriFromFilePath(testFilePath);
      hilog.info(0x0000, TAG, `分享URI: ${shareFileUri}`);

      // 3. 构造文件分享参数
      const shareParams: ShareParams = {
        shareType: ShareType.FILE,
        title: '碰一碰文件分享',
        fileUris: [shareFileUri],
        // 可选：指定文件分享的有效期、访问权限
        fileShareOptions: {
          writePermission: false,
          validityDuration: 3600
        }
      };

      await share.share(shareParams);
      promptAction.showToast({ message: '文件分享面板已拉起' });
    } catch (err) {
      hilog.error(0x0000, TAG, `文件分享失败: ${JSON.stringify(err)}`);
      promptAction.showToast({ message: '文件分享失败' });
    }
  }

  build() {
    Column({ space: 24 }) {
      Text('ShareKit 碰一碰分享调试')
        .fontSize(26)
        .fontWeight(FontWeight.Bold)
        .margin({ top: 40 });

      Text('无需多设备，模拟器即可验证核心分享逻辑')
        .fontSize(14)
        .fontColor('#888888');

      // 文本输入区域
      Column({ space: 8 }) {
        Text('分享文本内容')
          .fontSize(16)
          .width('100%');

        TextArea({ text: this.inputText })
          .width('100%')
          .height(120)
          .borderRadius(10)
          .padding(12)
          .backgroundColor('#F5F5F5')
          .onChange((value) => {
            this.inputText = value;
          });
      }
      .width('90%')
      .alignItems(HorizontalAlign.Start);

      // 操作按钮区
      Column({ space: 16 }) {
        Button('分享文本')
          .width('100%')
          .height(52)
          .borderRadius(26)
          .backgroundColor('#0A59F7')
          .fontSize(16)
          .onClick(() => {
            this.handleTextShare();
          });

        Button('分享沙箱文件')
          .width('100%')
          .height(52)
          .borderRadius(26)
          .backgroundColor('#00B578')
          .fontSize(16)
          .onClick(() => {
            this.handleFileShare();
          });
      }
      .width('90%');

      // 说明卡片
      Column({ space: 8 }) {
        Text('调试说明')
          .fontSize(16)
          .fontWeight(FontWeight.Medium)
          .width('100%');

        Text('1. 点击按钮会拉起系统分享面板，选择备忘录/文件管理即可验证数据\n2. 实体设备开启NFC后，面板自动出现碰一碰设备选项\n3. 核心分享代码无需修改，兼容所有分享形态')
          .fontSize(14)
          .fontColor('#666666')
          .width('100%')
          .lineHeight(22);
      }
      .width('90%')
      .padding(16)
      .backgroundColor('#F0F7FF')
      .borderRadius(12)
      .margin({ top: 20 });

      Blank();
    }
    .width('100%')
    .height('100%')
    .backgroundColor('#F8F9FA');
  }
}

3.2 代码核心逻辑解析

在这里插入图片描述

这段代码的核心价值在于：一套代码同时适配模拟器调试与真实碰一碰，没有任何模拟、伪造逻辑，完全基于官方标准API。

统一分享入口：share.share() 是ShareKit的唯一标准入口。在模拟器/单设备上，它拉起系统应用分享面板；在两台靠近的鸿蒙实体设备上，系统会自动在面板顶部优先展示「碰一碰」设备选项，用户触碰即可完成跨设备传输。
沙箱文件安全共享：通过 fileUri.getUriFromFilePath() 将应用私有沙箱路径转换为系统级可访问URI，分享时对方只能读取该文件，无法访问应用其他数据，符合鸿蒙隐私沙箱规范。
参数标准化：ShareParams 是通用参数结构，文本、文件、图片、视频等所有分享类型都复用同一套调用方式，扩展成本极低。

3.3 模拟器验证方法

运行到鸿蒙模拟器后，按以下步骤验证逻辑正确性：

文本分享验证：点击「分享文本」按钮，在弹出的分享面板中选择「备忘录」，跳转后能看到文本内容正确带入，即代表参数封装与分享链路正常。
文件分享验证：点击「分享沙箱文件」按钮，选择「保存到文件」，可以将应用沙箱内的测试文件保存到系统公共下载目录，验证沙箱文件共享能力正常。
日志验证：通过HiLog查看输出的URI与状态码，确认没有权限错误与参数异常。

四、无缝升级：实体设备碰一碰对接方案

当你有两台支持NFC的鸿蒙实体设备后，不需要修改上面的任何核心分享代码，只需根据业务需求选择触发方式即可。

方式一：系统默认碰一碰（零额外代码）

这是最推荐的方式，无需额外开发NFC逻辑，系统自动完成设备发现：

两台设备都开启NFC、蓝牙、Wi-Fi，亮屏解锁，登录同一华为账号
点击分享按钮拉起ShareKit面板，面板顶部会自动出现「碰一碰分享」的设备入口
两台设备背部触碰，即可自动开始传输，全程由系统托管，应用无需处理设备连接逻辑

优势：开发成本为零，系统统一交互，用户认知一致，稳定性最高。

方式二：自定义NFC主动触发

如果需要实现「触碰即分享，不弹面板」的无感交互，可以配合NFC检测能力，检测到对端设备后自动调用分享接口。核心逻辑如下：

import { nfcController } from '@kit.BasicServicesKit';

// 监听NFC近场发现，检测到设备后自动触发分享
function initNfcShare() {
  const nfc = nfcController.getNfcController();
  // 注册NFC状态监听，检测到碰一碰标签时触发分享
  nfc.on('nfcFieldOn', () => {
    // 检测到近场，直接调用ShareKit分享
    // 此时系统会优先走碰一碰近场传输通道
    share.share(shareParams);
  });
}