👋 你好,欢迎来到我的博客!我是【菜鸟学鸿蒙】
   我是一名在路上的移动端开发者,正从传统“小码农”转向鸿蒙原生开发的进阶之旅。为了把学习过的知识沉淀下来,也为了和更多同路人互相启发,我决定把探索 HarmonyOS 的过程都记录在这里。
  
  🛠️ 主要方向:ArkTS 语言基础、HarmonyOS 原生应用(Stage 模型、UIAbility/ServiceAbility)、分布式能力与软总线、元服务/卡片、应用签名与上架、性能与内存优化、项目实战,以及 Android → 鸿蒙的迁移踩坑与复盘。
  🧭 内容节奏:从基础到实战——小示例拆解框架认知、专项优化手记、实战项目拆包、面试题思考与复盘,让每篇都有可落地的代码与方法论。
  💡 我相信:写作是把知识内化的过程,分享是让生态更繁荣的方式。
  
   如果你也想拥抱鸿蒙、热爱成长,欢迎关注我,一起交流进步!🚀

前言

两台 HarmonyOS 设备靠在一起,屏幕上什么都没发生。这是碰一碰分享开发过程中最常见、也最让人摸不着头脑的现象。问题来源可能分布在硬件、系统开关、代码配置、分享内容格式、接收端处理逻辑这五个不同的层面,任意一环出问题都会导致"无反应"的结果。

这篇文章围绕 Share Kit 碰一碰分享,从最小 Demo 出发,逐层拆解各个可能的失效原因,并在最后整理出一套可以复用的排查流程。涉及的场景包括手机端发送、手机到 PC、手机到 2in1 三种组合,官方均有对应指导文档。

一、碰一碰分享到底做了什么

在介绍怎么排查之前,先把机制说清楚。

碰一碰分享利用 NFC 近场通信技术,在两台设备贴近时触发数据交换。发送端应用通过 Share Kit 的 setShareParams 接口,把要共享的内容(文字、链接、文件等)预先注册到系统;当 NFC 碰触发生时,系统读取这段数据,并在接收端找到能处理它的应用,通过 Want 拉起对应的 Ability。

整个链路涉及:

  • 发送端:应用前台运行 → 调用 setShareParams → NFC 硬件感应 → 系统发送数据
  • 接收端:NFC 接收数据 → 系统解析 Want → 匹配 skills 配置 → 拉起 Ability → onNewWant 取出数据

任何一个环节断了,两边都没有反应。

二、先把前置条件理清楚

2.1 设备硬件要求

碰一碰分享依赖 NFC 硬件。根据官方 Share Kit 开发指南,发送端和接收端都必须是支持 NFC 的设备。并非所有 HarmonyOS 设备都带 NFC 模块,部分定位偏低端的手机或旧款平板不具备这一能力。

排查第一步:确认两台设备的规格页均标注支持 NFC。

2.2 设备类型组合

官方文档明确给出了支持的设备组合:

方向文档
手机 → 手机碰一碰分享(手机端)
手机 → PC碰一碰分享(手机到 PC)
手机 → 2in1碰一碰分享(手机到 2in1)
PC → 手机碰一碰分享(PC 端)

不同设备组合的开发实现和配置要求略有差异,使用了手机到 PC 的文档逻辑去开发手机到手机的场景,可能导致配置不完整。

2.3 API Level 要求

Share Kit 的碰一碰分享能力从 API 12 开始提供(对应 HarmonyOS 5.0.0),开发前需确认工程的 compileSdkVersion 和设备系统版本均满足这一要求。

在 build-profile.json5 中,compileSdkVersion 不能低于 12:

// build-profile.json5(app 级别)
"app": {
  "compileSdkVersion": "5.0.0(12)",
  "compatibleSdkVersion": "5.0.0(12)"
}

如果低于这个版本,@kit.ShareKit 的相关接口在编译阶段可能不会报错(类型声明层面),但运行时行为不可预期。

三、从最小 Demo 开始验证

在上任何业务逻辑之前,先用最精简的代码验证链路是否通:

发送端(手机)核心代码:

// 需要 import 对应的 Kit
import { ShareKit } from '@kit.ShareKit';
import { UIAbility, Want } from '@kit.AbilityKit';

export default class MainAbility extends UIAbility {
  onForeground(): void {
    // 在应用进入前台时注册分享内容
    let shareData: ShareKit.ShareData = {
      // 分享类型:文本
      shareType: ShareKit.ShareType.SHARE_TYPE_TEXT,
      shareText: '这是一段用于碰一碰测试的文字'
    };
    try {
      ShareKit.setShareParams(shareData);
    } catch (err) {
      console.error('setShareParams failed: ' + JSON.stringify(err));
    }
  }
}

真正需要关注的是这几个地方:

  1. setShareParams 必须在应用位于前台时调用。如果在 onCreate 里调用但应用还未进入前台,系统不会接受这次注册。
  2. shareType 必须与实际内容匹配,类型和数据不一致会导致接收端无法解析。
  3. 接口调用需要做错误捕获,通过日志确认是否有异常抛出。

四、系统开关与运行状态

代码写对了,碰了还是没反应,下一个检查点是系统开关。

NFC 开关: 进入设备"设置 → 更多连接 → NFC",确认 NFC 已开启。这个开关被关掉是最常见的环境问题,也是最容易忽略的一个。

互联互通设置: 手机到 PC 或 2in1 的场景下,官方文档指出还需要确认相关跨设备互联的系统开关处于开启状态(通常在"设置 → 超级终端"或"设置 → 设备互联"中)。具体路径因系统版本略有差异。

设备登录状态: 手机到 PC/2in1 场景依赖华为账号。两台设备需要登录同一华为账号,或在同一局域网内完成互信配对(具体要求以官方各场景指导文档为准)。

五、分享内容准备是否正确

setShareParams 接收一个 ShareData 对象,这个对象的字段组合有几个地方容易出问题。

问题一:shareType 与字段不匹配

// 错误示例:声明了文本类型,但实际设置的是 URL 字段
let shareData: ShareKit.ShareData = {
  shareType: ShareKit.ShareType.SHARE_TYPE_TEXT,
  shareUrl: 'https://example.com'  // 字段与类型不符
};

// 正确:分享链接时使用对应类型和字段
let shareData: ShareKit.ShareData = {
  shareType: ShareKit.ShareType.SHARE_TYPE_URL,
  shareUrl: 'https://example.com'
};

问题二:分享文件时路径不合法

分享文件时,文件路径必须是接收端可访问的有效路径。沙箱内部路径直接传过去,对方应用无法读取。官方文档建议通过应用沙箱路径或统一资源标识符(URI)的方式处理。

问题三:在错误的生命周期调用

setShareParams 需要在应用前台期间调用(onForeground 之后),且每次进入前台都应当重新调用一次,因为分享数据不会自动持久化到下次前台。如果只在 onCreate 调用一次,退后台再进来后,注册的数据可能已经失效。

六、接收端 module.json5 的 skills 配置

这里是最容易出问题、也最难从表象上察觉的环节。

系统根据 NFC 碰触数据中的 Want 信息,在接收端查找能处理它的 Ability。这个匹配依赖 module.json5 中 Ability 的 skills 配置。如果配置缺失或字段写错,系统会找不到对应的 Ability,碰了也没反应。

按照官方碰一碰分享(手机端)指导,接收端 Ability 的 skills 需要包含正确的 actions、entities 和 uris 配置:

// module.json5 中 abilities 数组内的某个 ability 配置(接收端)
{
  "name": "EntryAbility",
  "srcEntry": "./ets/entryability/EntryAbility.ets",
  "launchType": "singleton",
  "skills": [
    {
      "actions": [
        "ohos.want.action.viewData"
      ],
      "entities": [
        "entity.system.default"
      ],
      "uris": [
        {
          "scheme": "https"
        }
      ]
    }
  ]
}

关键点:

  • actions 中的字符串需要与发送端 Want 携带的 action 严格匹配,大小写敏感;
  • uris 中的 scheme 要与分享内容的 URI scheme 对应,例如分享 https:// 链接就填 https,分享文件可能是 file;
  • 如果 uris 配置了但 scheme 不匹配,系统不会报错,只是静默地找不到接收者。

七、接收端 onNewWant 里取数据

Ability 被碰一碰拉起时,如果它已经在运行(launchType 为 singleton),系统会走 onNewWant 回调而不是 onCreate。很多开发者只在 onCreate 里写了取数据的逻辑,导致第二次碰触后数据没有被正确处理。

import { UIAbility, Want, AbilityConstant } from '@kit.AbilityKit';

export default class EntryAbility extends UIAbility {

  // 首次冷启动时走这里
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    this.handleShareWant(want);
  }

  // 已存在实例时走这里(碰一碰场景更常见走这里)
  onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    this.handleShareWant(want);
  }

  private handleShareWant(want: Want): void {
    if (want.parameters) {
      // 从 want.parameters 中取出分享数据
      let sharedText = want.parameters['ohos.extra.STREAM'] as string;
      console.info('received share text: ' + sharedText);
    }
  }
}

want.parameters 里的键名需要与发送端实际写入的参数键名对应。建议先把整个 want.parameters 打印出来,确认接收到的字段结构,再做取值。

八、前后台状态的影响

碰一碰分享有一个明确的前提:发送端应用必须处于前台。后台应用调用的 setShareParams 不会生效。

这个要求影响了几个常见的开发误区:

  • 在 onBackground 里调用 setShareParams:注册不会成功;
  • 应用被系统回收后重新进入,但没有在 onForeground 重新注册:数据已清空;
  • 页面通过路由切换到另一个页面后,如果新页面需要分享不同内容,必须重新调用 setShareParams 更新;

另外,屏幕锁定状态下 NFC 的行为由系统策略控制,开发层面无法干预。碰触时如果屏幕是锁定的,分享可能不会触发应用侧逻辑。

九、用日志定位到底哪一步断了

碰了没反应,最直接的定位手段是日志。

发送端排查:

在 setShareParams 调用处加日志,确认函数确实在前台时被执行、且没有抛出异常。

onForeground(): void {
  console.info('[ShareDebug] onForeground called, registering share params');
  let shareData: ShareKit.ShareData = {
    shareType: ShareKit.ShareType.SHARE_TYPE_TEXT,
    shareText: 'test'
  };
  try {
    ShareKit.setShareParams(shareData);
    console.info('[ShareDebug] setShareParams success');
  } catch (err) {
    console.error('[ShareDebug] setShareParams failed, code: ' + (err as BusinessError).code
      + ', message: ' + (err as BusinessError).message);
  }
}

在 DevEco Studio 的 Log 视图中过滤 [ShareDebug] 标签,可以快速确认注册环节是否正常。

接收端排查:

在 onNewWant 和 onCreate 都加上日志,确认回调是否被触发。如果回调完全没走到,说明系统根本没有匹配到接收端的 Ability,问题就在 module.json5 的 skills 配置上。

onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void {
  console.info('[ShareDebug] onNewWant triggered');
  console.info('[ShareDebug] want action: ' + want.action);
  console.info('[ShareDebug] want parameters: ' + JSON.stringify(want.parameters));
}

十、一套可复用的排查流程

把上面每个检查点整理成顺序清单,遇到"碰了没反应"可以按顺序走:

第一层:硬件与系统

  1. 确认两台设备均支持 NFC(查设备规格)
  2. 确认双方 NFC 开关已开启(设置 → 更多连接 → NFC)
  3. 手机到 PC/2in1 场景:确认账号已登录、互联互通开关已开启
  4. 确认两台设备系统版本均 ≥ HarmonyOS 5.0.0(API 12)

第二层:工程配置

  1. 确认 build-profile.json5 中 compileSdkVersion ≥ 12
  2. 确认接收端 module.json5 中目标 Ability 有正确的 skills 配置
  3. 确认 skills 的 actions、entities、uris.scheme 与发送数据匹配

第三层:代码逻辑

  1. 确认 setShareParams 在 onForeground 后调用(不在 onBackground、不在应用未进前台时调用)
  2. 确认 ShareData 的 shareType 与实际填充字段一致
  3. 确认接收端同时实现了 onCreate 和 onNewWant,两处都有取数据逻辑

第四层:日志确认

  1. 发送端:确认 setShareParams 无异常,日志显示注册成功
  2. 接收端:确认碰触后 onNewWant 被触发;若未触发,回头检查 skills 配置

开发经验总结

碰一碰功能的失效原因分布很散,从硬件到系统开关,再到代码配置,每一层都有独立的失效点,而这些失效点在表象上都是同一个现象——“没反应”。

几个真正值得重点关注的地方:

  • setShareParams 的调用时机要严格在前台,并且每次进入前台都应当重新注册;
  • 接收端的 module.json5 skills 配置是最容易被忽略、也最难从运行现象倒推出问题的地方,建议先检查这里;
  • onNewWant 必须和 onCreate 一起处理 Want 数据,仅写一处容易在应用已存活时丢失数据;
  • 分享文件场景的 URI 合法性和跨应用访问权限,复杂度高于文本和链接,建议先用文本场景验证链路通畅后再扩展。

如果你正在排查"碰一碰接收端拉起了应用但数据是空的"这种情况,重点看 onNewWant 是否有被调用,以及 want.parameters 的完整内容打出来是否与预期一致——这两个信息通常能直接定位到问题。

📝 写在最后

如果你觉得这篇文章对你有帮助,或者有任何想法、建议,欢迎在评论区留言交流!你的每一个点赞 👍、收藏 ⭐、关注 ❤️,都是我持续更新的最大动力!

我是一个在代码世界里不断摸索的小码农,愿我们都能在成长的路上越走越远,越学越强!

感谢你的阅读,我们下篇文章再见~👋

✍️ 作者:菜鸟不学编程
🧵 本文原创,转载请注明出处。

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐