鸿蒙精准碰一碰实战：我用两台真机踩完了这些坑【鸿蒙心迹】

2501_91356259

11人浏览 · 2026-11-11 10:59:14

2501_91356259 · 2026-11-11 10:59:14 发布

一、前言

精准碰一碰是鸿蒙 Share Kit 提供的系统级近场交互能力，区别于传统 NFC 标签碰一碰，它依托鸿蒙分布式软总线，两台鸿蒙设备靠近触碰即可触发应用自定义交互，支持链接、文件、结构化数据的跨设备传递，在资料互传、协同办公、设备联动场景非常好用，也是官方扶持推荐方向。
很多新手在接入时会遇到：碰了没反应、3s 超时失败、接收端无法拉起应用、预览图模糊、冷启动参数丢失等问题。

二、能力原理

精准碰一碰(knockShare)整体流程：

发送端注册监听：当前页面向系统注册knockShare能力，绑定当前窗口ID，告诉系统：本应用支持碰一碰交换；
设备触发触碰：两台鸿蒙设备NFC开启，靠近触碰，系统触发回调；
回调内组装分享数据：在回调函数中构造沉浸式分享卡片、UTD数据，调用share()发起分享；
接收端接收数据：接收端通过want、onNewWant回调解析传递的数据，完成页面跳转/数据加载；
异常处理：支持reject()主动拒绝本次碰一碰，给用户友好提示；

对比普通NFC：精准碰一碰不需要实体标签，依靠鸿蒙分布式能力，支持沉浸式大卡片预览，体验更强，适配手机、平板、PC多形态设备协作协同。

三、开发前置准备

DevEco Studio 5.0+，SDK API21
两台支持 NFC 的鸿蒙设备（真机调试，模拟器无法测试碰一碰）
AGC 后台创建应用，配置 App Linking（如果需要跨应用拉起）
module.json5 配置权限、skills
依赖：@kit.ShareKit

3.1 module.json5配置

{
  "module": {
    "name": "entry",
    "type": "entry",
    "requestPermissions": [
      {
        "name": "ohos.permission.READ_USER_STORAGE",
        "reason": "读取相册文件用于碰一碰分享",
        "usedScene": {
          "abilities": ["EntryAbility"],
          "when": "inuse"
        }
      }
    ],
    "skills": [
      {
        "entities": ["entity.system.default"],
        "actions": ["ohos.want.action.sendData"],
        "uris": [
          {
            "scheme": "myapp",
            "host": "noteshare",
            "path": "*"
          }
        ]
      }
    ]
  }
}

module.json5配置讲解：

ohos.want.action.sendData 是碰一碰数据接收必须注册的 action；
uris 配置自定义协议，接收端可以通过该协议被拉起；
存储权限为动态危险权限，代码里还需要动态申请，仅静态声明无效分享图片功能实现解决方案。

四、发送端完整代码(核心ArkTS)

功能：注册碰一碰监听，触碰后分享笔记连接+预览卡片

import { harmonyShare } from '@kit.ShareKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { UIContext } from '@ohos/ui';
import { Want } from '@kit.AbilityKit';

const TAG = 'KnockShareDemo';

@Component
struct KnockSharePage {
  @State uiContext: UIContext | null = null;
  // 监听注册标识，页面销毁时取消监听，防止内存泄漏
  private knockShareOff: (() => void) | null = null;

  aboutToAppear() {
    this.uiContext = this.getUIContext();
    if (!this.uiContext) return;
    const windowId = this.uiContext.getWindowId();

    // 注册精准碰一碰能力
    const registry: harmonyShare.SendCapabilityRegistry = {
      windowId: windowId
    };

    this.knockShareOff = harmonyShare.on('knockShare', registry, async (sharableTarget: harmonyShare.SharableTarget) => {
      hilog.info(0x0000, TAG, '检测到碰一碰事件');
      try {
        // 【重点】提前组装数据，不要在回调里做耗时网络请求！避免3s超时
        const shareData: harmonyShare.ShareData = {
          title: "我的学习笔记",
          description: "鸿蒙精准碰一碰开发笔记",
          thumbnailUri: "file:///data/storage/el2/base/haps/entry/files/preview.jpg", // 沙箱内预览图
          utd: {
            type: "com.myapp.note",
            content: JSON.stringify({
              noteId: 10086,
              title: "精准碰一碰开发",
              link: "myapp://noteshare/detail?noteId=10086"
            })
          }
        };

        // 发起分享
        await sharableTarget.share(shareData);
        hilog.info(0x0000, TAG, '分享发起成功');
      } catch (err) {
        hilog.error(0x0000, TAG, '分享失败 %{public}s', JSON.stringify(err));
        // 主动拒绝本次碰一碰，给系统反馈
        sharableTarget.reject("数据准备失败");
      }
    })
  }

  // 页面销毁，取消监听，非常重要
  aboutToDisappear() {
    if (this.knockShareOff) {
      this.knockShareOff();
      this.knockShareOff = null;
    }
  }

  build() {
    Column() {
      Text("精准碰一碰发送端")
        .fontSize(22)
        .margin({ bottom: 10 })
      Text("打开本页面，两台鸿蒙手机触碰，即可分享笔记")
        .fontSize(14)
        .fontColor("#666")
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }
}

代码讲解：

harmonyShare.on('knockShare') 注册碰一碰回调，返回的函数用于注销监听，页面销毁必须调用，否则多次进入页面会重复注册；
thumbnailUri 优先使用沙箱文件 URI；不要直接传 PixelMap，旧参数 thumbnail 有 32KB 大小限制，图片会模糊，这是高频坑----(碰一碰视频链接分享开发实践解析)；
禁止在回调内部做网络请求、大文件读取这类耗时操作，很容易触发 3 秒超时，数据提前预加载；
sharableTarget.reject() 用于异常场景终止本次碰一碰交互，提升用户体验。

五、接收端代码：解析碰一碰传递的数据

接收端分两种场景：应用冷启动、应用已经在后台运行(onNewWant)

// EntryAbility.ets
import { UIAbility, Want } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

export default class EntryAbility extends UIAbility {
  onNewWant(want: Want) {
    // 应用后台运行，碰一碰拉起触发这里
    hilog.info(0x0000, 'Receiver', 'onNewWant, want: %{public}s', JSON.stringify(want));
    this.parseKnockWant(want);
  }

  onCreate() {
    hilog.info(0x0000, 'Receiver', 'Ability onCreate');
  }

  onWant(want: Want) {
    // 应用冷启动，碰一碰拉起
    this.parseKnockWant(want);
  }

  private parseKnockWant(want: Want) {
    const uri = want.uri;
    if (!uri) return;
    // 解析自定义协议 myapp://noteshare/detail?noteId=10086
    hilog.info(0x0000, 'Receiver', '收到碰一碰传递链接：%{public}s', uri);
    // 路由跳转笔记详情页
    this.context.router.pushUrl({ url: `pages/NoteDetail?uri=${uri}` })
  }
}