鸿蒙RN碰一碰分享落地实践：Share Kit桥接适配与真机踩坑

鸿蒙专家

碰一碰分享是HarmonyOS NEXT上很有代表性的近场交互能力：两台手机顶部轻碰，商品信息、文件或链接就能直接传过去。相比扫码和链接跳转，“碰”这个动作的成本极低，在电商、社交等强分享场景里尤其好用。这篇文章记录我们在HarmonyOS NEXT上把碰一碰分享接入React Native（RN）的开发经验，包括TurboModule桥接方案、核心接口使用、踩过的坑和分析思路。本文基于React Native 0.84 + RNOH 0.84.1编写，设备为HarmonyOS 6.0，不同版本间可能有差异，以实际测试为准。

一、整体方案：Share Kit + 自定义TurboModule

碰一碰分享底层依赖的是HarmonyOS Share Kit的近场发现能力。在原生鸿蒙应用里可以直接调用Share Kit接口，但在RN开发模式下，需要通过自定义TurboModule把原生能力暴露给JS侧。我们实现了一个名为TapShareModule的桥接模块，对上层提供三个核心方法：

2. import TapShareModule from '../native/NativeTapShareModule';
3. // 检查是否支持碰一碰
4. const available = await TapShareModule.isTapShareAvailable();
5. // 注册分享数据
6. const result = await TapShareModule.shareSku(payload);
7. // 停止分享
8. await TapShareModule.stopShare();

复制代码

shareSku接收的payload承载了分享的业务数据，其中targetRoute是接收方点击Deep Link拉起应用后要跳转的路由，sourceScene用于标识分享来源场景，方便后续做数据统计。

2. interface TapShareSkuPayload {
3.     skuId: string;
4.     spuId?: string;
5.     title: string;
6.     imageUrl?: string;
7.     price?: string;
8.     currency?: string;
9.     stockStatus?: 'normal' | 'low' | 'out_of_stock';
10.     targetRoute: string; // 接收方打开应用时跳转的路由
11.     sourceScene: string; // 来源场景
12. }
13. interface TapShareResult {
14.     code: number;
15.     message: string;
16.     shareId?: string;
17.     status: 'waiting' | 'success' | 'cancelled' | 'failed';
18.     targetRoute?: string;
19. }

复制代码

二、能力检测：必须真机，不能跳过

Share Kit依赖NFC等近场通信硬件，模拟器不支持，必须真机测试。因此开发中首先要做好能力检测，否则在不支持的设备上直接调用shareSku会抛异常，影响用户体验。

2. const checkSupport = async () => {
3.     if (!TapShareModule) {
4.         console.log('TapShareModule 未注册');
5.         return false;
6.     }
7.     try {
8.         const available = await TapShareModule.isTapShareAvailable();
9.         console.log('碰一碰分享能力:', available ? '可用' : '不可用');
10.         return available;
11.     } catch (error) {
12.         console.error('检测失败:', error);
13.         return false;
14.     }
15. };

复制代码

如果设备或系统版本不支持，isTapShareAvailable()会返回false。分享入口需要据此做降级处理，比如改用链接分享或二维码。

三、两个典型错误写法

错误一：不检查能力可用性直接调用shareSku

2. // 错误写法 直接调用 shareSku
3. const handleShare = async () => {
4.     const result = await TapShareModule.shareSku(payload);
5.     // 如果在不支持 Share Kit 的设备上，会抛异常
6. };

复制代码

正确做法是先判断模块是否存在、能力是否可用，再决定走碰一碰还是降级方案。

2. // 正确写法 先检查能力可用性
3. const handleShare = async () => {
4.     if (!TapShareModule) {
5.         Alert.alert('提示', 'TapShare 模块未注册');
6.         return;
7.     }
8.     const available = await TapShareModule.isTapShareAvailable();
9.     if (!available) {
10.         Alert.alert('提示', '当前设备不支持碰一碰分享');
11.         return;
12.     }
13.     const result = await TapShareModule.shareSku(payload);
14. };

复制代码

错误二：分享成功后不清理状态

shareSku的返回值是异步的，上次分享的结果如果不清理，下次进入页面时可能会影响UI判断。

2. // 错误写法 分享后不处理
3. const handleShare = () => {
4.     TapShareModule.shareSku(payload);
5.     // 没有清理状态，下次分享时上次的结果还在
6. };
8. // 正确写法 分享前后管理状态
9. const [result, setResult] = useState<TapShareResult | null>(null);
10. const handleShare = async () => {
11.     setResult(null); // 清空上次结果
12.     const res = await TapShareModule.shareSku(payload);
13.     setResult(res);
14. };

复制代码

四、完整实战：SKU分享组件

以电商商品详情页为例，分享按钮的完整实现包含状态管理、payload构建和结果展示：

2. const SkuShareButton = ({ sku }) => {
3.     const [sharing, setSharing] = useState(false);
4.     const [result, setResult] = useState(null);
5.     const buildPayload = (sku) => ({
6.         skuId: sku.id,
7.         spuId: sku.spuId,
8.         title: sku.title,
9.         imageUrl: sku.image,
10.         price: sku.price,
11.         currency: 'USD',
12.         stockStatus: sku.stock > 10 ? 'normal' : 'low',
13.         targetRoute: `/sku/detail?skuId=${sku.id}`,
14.         sourceScene: 'sku_detail',
15.     });
16.     const handleShare = async () => {
17.         setSharing(true);
18.         try {
19.             if (!TapShareModule) {
20.                 throw new Error('模块未注册');
21.             }
22.             const payload = buildPayload(sku);
23.             const res = await TapShareModule.shareSku(payload);
24.             setResult(res);
25.         } catch (error) {
26.             Alert.alert('分享失败', String(error));
27.         } finally {
28.             setSharing(false);
29.         }
30.     };
31.     return (
32.         <View>
33.             <Pressable onPress={handleShare} disabled={sharing}>
34.                 <Text>{sharing ? '准备中...' : '碰一碰分享'}</Text>
35.             </Pressable>
36.             {result?.status === 'waiting' && (
37.                 <View>
38.                     <Text>已注册，请碰一碰手机</Text>
39.                     <Pressable onPress={() => TapShareModule.stopShare()}>
40.                         <Text>取消</Text>
41.                     </Pressable>
42.                 </View>
43.             )}
44.         </View>
45.     );
46. };

复制代码

调用shareSku成功后，系统会注册一份待分享内容，两台支持碰一碰的设备亮屏解锁后顶部轻碰，数据即开始传输。用户点击取消时调用stopShare解除注册；如果已经分享完成，stopShare不影响已完成的传输。

接收端通过Deep Link拉起应用，在App.tsx用Linking监听URL并解析参数：

2. const handleDeepLink = (url: string) => {
3.     const parsed = parseTapShareUrl(url);
4.     if (parsed) {
5.         // 跳转到 SKU 详情页
6.         navigation.navigate('SkuDetail', { skuId: parsed.skuId });
7.     }
8. };
9. const parseTapShareUrl = (url: string): TapShareSkuPayload | null => {
10.     try {
11.         // 示例 URL: skuassistant://sku/detail?skuId=SKU-HM-001&title=...
12.         const match = url.match(/skuassistant:\/\/sku\/detail\?(.+)/);
13.         if (!match) return null;
14.         const params = new URLSearchParams(match[1]);
15.         return {
16.             skuId: params.get('skuId') || '',
17.             title: params.get('title') || '',
18.             targetRoute: url,
19.             sourceScene: 'sku_detail',
20.         };
21.     } catch {
22.         return null;
23.     }
24. };

复制代码

五、原生桥接实现三层结构

TapShareModule的桥接实现分三层。第一层是JS侧接口定义：

2. import type { TurboModule } from 'react-native';
3. import { TurboModuleRegistry } from 'react-native';
5. export interface TapShareSkuPayload {
6.     skuId: string;
7.     spuId?: string;
8.     title: string;
9.     imageUrl?: string;
10.     price?: string;
11.     currency?: string;
12.     stockStatus?: string;
13.     targetRoute: string;
14.     sourceScene: string;
15. }
16. export interface TapShareResult {
17.     code: number;
18.     message: string;
19.     shareId?: string;
20.     status: string;
21.     targetRoute?: string;
22. }
23. export interface Spec extends TurboModule {
24.     shareSku(payload: TapShareSkuPayload): Promise<TapShareResult>;
25.     stopShare(): Promise<boolean>;
26.     isTapShareAvailable(): Promise<boolean>;
27. }
28. export default TurboModuleRegistry.getEnforcing<Spec>('TapShareModule');

复制代码

第二层是C++方法映射，把JS调用映射到ArkTS实现：

2. TapShareModule::TapShareModule(const ArkTSTurboModule::Context ctx, const std::string name)
3.     : ArkTSTurboModule(ctx, name) {
4.     methodMap_ = {
5.         ARK_ASYNC_METHOD_METADATA(shareSku, 1),
6.         ARK_ASYNC_METHOD_METADATA(stopShare, 0),
7.         ARK_ASYNC_METHOD_METADATA(isTapShareAvailable, 0),
8.     };
9. }

复制代码

第三层是ArkTS原生实现。能力检测用HarmonyOS的canIUse API判断当前系统是否支持Share Kit：

2. import { harmonyShare } from '@kit.ShareKit';
3. async isTapShareAvailable(): Promise<boolean> {
4.     return canIUse('SystemCapability.Collaboration.HarmonyShare');
5. }

复制代码

注册碰一碰分享则通过harmonyShare的事件监听实现：

2. // 注册碰一碰事件监听
3. harmonyShare.on('knockShare', (sharableTarget) => {
4.     // 碰一碰触发后的回调
5.     this.handleKnockShare(sharableTarget);
6. });
7. // 取消注册
8. harmonyShare.off('knockShare');

复制代码

原生侧根据传递的payload参数构造JSON数据，通过Share Kit的sharableTarget分发到接收端，接收端再通过Deep Link拉起应用并传递参数。

六、错误码速查与状态处理

实际开发中，建议为TapShare维护一份错误码表，方便定位问题和展示给用户：

2. const TapShareErrorCodes = {
3.     1001: { level: 'info', message: '已注册，等待碰一碰' },
4.     1002: { level: 'info', message: '已更新待分享内容' },
5.     2001: { level: 'info', message: '已解除注册' },
6.     3001: { level: 'warn', message: '系统不支持 Share Kit' },
7.     3002: { level: 'error', message: '模块未注册' },
8.     5001: { level: 'error', message: '调用失败' },
9.     5002: { level: 'error', message: '解除注册失败' },
10. };
11. const handleTapShareResult = (result: TapShareResult) => {
12.     const codeInfo = TapShareErrorCodes[result.code];
13.     if (codeInfo.level === 'error') {
14.         console.error(`[TapShare] ${codeInfo.message}: ${result.message}`);
15.     } else if (codeInfo.level === 'warn') {
16.         console.warn(`[TapShare] ${codeInfo.message}`);
17.     } else {
18.         console.log(`[TapShare] ${codeInfo.message}`);
19.     }
20. };

复制代码

接收端拿到Deep Link后，页面需要根据解析出的skuId等标识从API拉取完整的商品数据渲染。不要在payload里塞全量数据。

七、鸿蒙上的坑：五个关键注意点

坑1：必须真机测试。Share Kit依赖NFC和近场通信硬件，模拟器上不可用。开发调试时一定用真机，并且要准备至少两台HarmonyOS NEXT设备。

坑2：不能实时获知传输结果。发送端无法直接获取接收端是否成功接收。真正的结果由HarmonyOS系统通过通知告知用户。所以分享后的UI提示要明确说明“等待碰一碰触发”，而不是“传输成功”。

坑3：设备要求严格。两台设备都必须是HarmonyOS NEXT，都亮屏解锁，顶部区域相互接触。任何条件不满足都可能触发失败。

坑4：分享数据大小限制。当前版本中payload的总数据量不宜过大，建议只传必要的业务标识（skuId、targetRoute），详细数据由接收端通过API自行拉取。这样payload小了，传输更快，数据也更安全。

坑5：业务标识vs完整数据。不要把商品描述、价格、图片全塞进payload，接收端拿到Deep Link后按需请求接口即可。

八、适配步骤与降级建议

发送端适配四步走：先检测能力，不可用则降级到URL分享；构建最小payload；注册分享；UI提示用户碰一碰。

2. // 1. 检测能力
3. const available = await TapShareModule.isTapShareAvailable();
4. if (!available) {
5.     // 降级到 URL 分享
6.     return shareByUrl(payload);
7. }
8. // 2. 构建 payload
9. const payload = buildMinimalPayload(sku);
10. // 3. 注册分享
11. const result = await TapShareModule.shareSku(payload);
12. // 4. UI 提示
13. showKnockGuide(result);

复制代码

接收端则配置Deep Link scheme，在App.tsx中监听Linking，解析URL参数，跳转对应页面并拉取完整数据。

还有一个容易被忽略的点：组件卸载时要清理状态。用useEffect的清理函数调用stopShare，避免页面已销毁但分享注册还挂着的情况。

九、结语

碰一碰分享是HarmonyOS的独特能力，其最大价值在于“碰”这个交互成本极低——不需要扫码、不需要点链接、不需要输验证码。在电商场景里，这种交互对于商品分享、邀请拼单等业务有天然的适配空间。但在不支持碰一碰的设备上一定要有降级方案，不能把碰一碰作为唯一分享方式。建议分享场景接上埋点追踪，记录从哪个页面发起的分享、分享状态如何，方便后续优化。

文中代码示例基于HarmonyOS 6.0和RNOH 0.84.1实测通过，可直接复用。版本升级后需重新回归验证。

热心网友7

楼主的分享很实在，尤其是“必须真机、模拟器不支持”和“分享成功后清理状态”这两个点，都是实际开发中容易踩的坑。我们也在做类似功能，不过目前还在评估阶段，有几个问题想请教一下： 1. 碰一碰分享在真机上，两台设备的系统版本有限制吗？比如都必须鸿蒙6.0以上？ 2. `shareSku` 里那个 `targetRoute`，接收方点击拉起应用后，是直接能跳转到对应页面，还是需要先在应用里处理一次路由分发？ 3. 分享过程中如果用户手机离开太近或者中途取消了，`status` 回调里能明确区分“取消”和“失败”吗？我们想针对取消做不打扰的提示。 另外，楼主提到的“降级方案”是直接用系统分享链接还是走的其他方式？如果方便的话希望展开说说。

热心网友6

楼主的分享很详实，尤其是“必须先做能力检测”和“分享后清理状态”这两个点，实际开发中太容易踩了。我们当初接的时候就是因为没处理好状态残留，导致页面复用时一直弹上次的分享结果，排查了好久。 想追问一下：接收方被拉起后，Deep Link的targetRoute传参在RN侧是怎么处理的？是走的系统路由拦截还是自己维护了一套页面映射？另外，真机上两台设备“碰”的时候，对机型或者握持姿势有没有什么特殊要求，比如NFC天线位置会不会影响成功率？

热心网友3

感谢分享，这篇实战记录写得非常实在。特别是“必须真机、模拟器不支持”和“分享后清理状态”这两点，确实是很多人容易踩的坑。想追问一下楼主：碰一碰在真机上对距离和角度的敏感度如何？我们之前做NFC相关功能时，发现不同机型的线圈位置差异挺大的，有时候用户“碰”一下没反应，体验就容易打折扣。你们在电商场景里有没有做引导动画或者失败后的降级提示？另外，RN桥接这块性能损耗明显吗？期待楼主再多分享一些细节。