碰一碰传图完整 Demo，ShareKit 权限与软总线全配置-育师

很多开发者觉得碰一碰传图是个复杂功能：要写 NFC 设备发现、要调分布式软总线、要处理跨端权限，门槛很高。其实完全不用这么麻烦。

鸿蒙 ShareKit 已经把整套碰一碰能力封装成了标准统一接口——NFC 近场发现、软总线高速传输、临时权限授权、断点续传全部由系统底层处理，应用层只需要构造正确的分享参数，调用一行分享方法，就能实现和系统原生完全一致的碰一碰传图体验。

本文从零带你实现一个完整的碰一碰传图 Demo，从工程配置、权限申请、图片选择到分享调用全流程覆盖，基于鸿蒙 7（API 26）@kit 标准规范，代码可直接复制运行，同时讲清底层权限与软总线的工作原理，让你不仅会写，还懂为什么这么写。

一、先搞懂：碰一碰传图的三层架构

碰一碰不是一个独立的 API，而是「硬件触发 + 业务封装 + 底层传输」三层协同的系统能力，应用开发只需要对接中间的业务层，上下两层全部由系统接管。

架构层级	负责能力	开发方
NFC 触发层	近场设备检测、握手配对、通道建立	系统原生，应用无需开发
ShareKit 业务层	数据封装、权限处理、多形态分享适配	应用对接，仅需调用标准接口
分布式软总线	高速跨设备传输、流量调度、断点续传	系统自动调度，应用无感知

简单理解：你只需要告诉系统「我要分享这张图」，剩下的设备发现、连接建立、数据传输全部由系统自动完成。两台设备满足组网条件时，分享面板顶部会自动出现「碰一碰」近场设备入口，触碰后直接走软总线高速传输。

二、前置准备：环境、设备与全量配置

2.1 开发环境要求

SDK 版本：API 26（HarmonyOS 7.0）及以上
开发工具：DevEco Studio 5.0 及以上
工程模型：Stage 模型（FA 模型不支持新版 ShareKit）
运行环境：两台鸿蒙实体设备，模拟器无 NFC 硬件，仅能验证分享逻辑，无法体验碰一碰

2.2 设备端必备条件（碰一碰生效前提）

两台设备必须同时满足以下条件，系统才会识别近场设备并开启碰一碰通道：

登录同一个华为账号
连接同一个 Wi-Fi 局域网
开启蓝牙、NFC、华为分享开关
保持亮屏解锁状态
距离在 5cm 以内，背部 NFC 区域对齐

2.3 工程编译配置

打开工程根目录build-profile.json5，确认 SDK 版本与运行环境配置正确：

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

2.4 权限配置：只需要一个核心权限

很多新手以为碰一碰需要 NFC、存储、网络等一大堆权限，其实完全不用。

不需要 NFC 权限：碰一碰的硬件触发由系统分享面板接管，应用不直接操作 NFC 硬件
不需要存储权限：使用系统相册选择器选图，由用户主动授权，无需应用申请读写权限
仅需一个权限：分布式数据同步权限，用于跨设备软总线传输

打开entry/src/main/module.json5，在requestPermissions中添加：

"requestPermissions": [ { "name": "ohos.permission.DISTRIBUTED_DATASYNC", "reason": "$string:permission_distributed_share", "usedScene": { "abilities": ["EntryAbility"], "when": "inuse" } } ]

注意：该权限为危险权限，必须在分享前动态申请用户授权，仅在清单声明会导致分享失败。

三、核心原理：为什么几行代码就能实现

3.1 关键：分享的不是文件路径，是 File URI

这是新手最容易踩的核心坑：应用沙箱内的文件路径，其他设备/应用无权直接访问。
必须将本地文件路径转换为系统标准 File URI，系统会自动为接收方授予临时读取权限，分享完成后权限自动回收，符合鸿蒙沙箱安全规范。

系统相册选择器返回的图片 URI：本身就是合法的系统 URI，可直接用于分享
应用沙箱内的本地文件：必须通过fileUri.getUriFromFilePath()转换后才能分享

3.2 ShareKit 一套接口适配所有分享形态

share.share()是 ShareKit 的唯一标准入口，自动适配所有分享场景：

近场碰一碰传输
系统应用内分享（备忘录、文件管理等）
第三方应用分享
近邻设备发现分享

检测到碰一碰近场设备时，系统会自动将其置顶到分享面板最顶部，优先走分布式软总线高速通道，传输速度远快于蓝牙。

四、完整实战：碰一碰传图 Demo

4.1 功能说明

我们实现一个最通用的碰一碰传图流程：

调用系统相册选择器选择图片
预览选中的图片
动态申请分布式权限
调用 ShareKit 拉起分享面板
两台设备碰一碰完成高速传输

全程使用系统原生组件，无第三方依赖，符合隐私安全规范。

4.2 完整可运行代码

打开entry/src/main/ets/pages/Index.ets，替换为以下完整代码：

import{share,ShareParams,ShareType}from'@kit.ShareKit';import{PhotoViewPicker,photoAccessHelper,promptAction}from'@kit.ArkUI';import{hilog}from'@kit.PerformanceAnalysisKit';constTAG='ShareImageDemo';constDISTRIBUTED_PERMISSION='ohos.permission.DISTRIBUTED_DATASYNC';@Entry@Componentstruct ShareImagePage{// 选中的图片URI@StateimageUri:string='';// 相册选择器实例privatephotoPicker:PhotoViewPicker=newPhotoViewPicker();/** * 打开系统相册选择图片 */asyncpickImage(){try{constselectResult=awaitthis.photoPicker.select({MIMEType:photoAccessHelper.MimeType.IMAGE,maxSelectNumber:1});if(selectResult.photoUris&&selectResult.photoUris.length>0){this.imageUri=selectResult.photoUris[0];hilog.info(0x0000,TAG,`选中图片:${this.imageUri}`);}}catch(err){hilog.error(0x0000,TAG,`选图失败:${JSON.stringify(err)}`);promptAction.showToast({message:'选择图片失败'});}}/** * 检查并申请分布式权限 */privateasynccheckPermission():Promise<boolean>{constcontext=getContext(this);try{// 先检查是否已授权constresult=awaitcontext.checkAccessToken(DISTRIBUTED_PERMISSION);if(result===0){returntrue;}// 未授权则申请constauthRes=awaitcontext.requestPermissionsFromUser([DISTRIBUTED_PERMISSION]);returnauthRes.authResults[0]===0;}catch(err){hilog.error(0x0000,TAG,`权限检查失败:${JSON.stringify(err)}`);returnfalse;}}/** * 发起分享，支持碰一碰传输 */asyncstartShare(){if(!this.imageUri){promptAction.showToast({message:'请先选择图片'});return;}// 1. 校验分布式权限consthasPermission=awaitthis.checkPermission();if(!hasPermission){promptAction.showToast({message:'请授予分布式权限以使用碰一碰分享'});return;}try{// 2. 构造分享参数constshareParams:ShareParams={shareType:ShareType.FILE,title:'分享图片',fileUris:[this.imageUri],// 可选：配置文件分享权限与有效期fileShareOptions:{writePermission:false,validityDuration:7200}};// 3. 拉起系统分享面板，自动支持碰一碰awaitshare.share(shareParams);hilog.info(0x0000,TAG,'分享面板已拉起');}catch(err){hilog.error(0x0000,TAG,`分享失败:${JSON.stringify(err)}`);promptAction.showToast({message:'分享调用失败'});}}build(){Column({space:24}){Text('碰一碰传图').fontSize(28).fontWeight(FontWeight.Bold).width('90%').margin({top:40});// 图片预览区Stack({alignContent:Alignment.Center}){if(this.imageUri){Image(this.imageUri).width('100%').aspectRatio(1).objectFit(ImageFit.Contain).borderRadius(12).backgroundColor('#F5F5F5');}else{Column({space:12}){Text('🖼️').fontSize(48);Text('点击下方按钮选择图片').fontSize(14).fontColor('#999999');}}}.width('90%').aspectRatio(1).backgroundColor('#FFFFFF').borderRadius(16).shadow({radius:6,color:'#1A000000'});// 操作按钮区Column({space:16}){Button('选择图片').width('100%').height(52).borderRadius(26).backgroundColor('#0A59F7').fontSize(16).onClick(()=>{this.pickImage();});Button('碰一碰分享').width('100%').height(52).borderRadius(26).backgroundColor('#00B578').fontSize(16).enabled(!!this.imageUri).onClick(()=>{this.startShare();});}.width('90%');Blank();// 说明卡片Column({space:8}){Text('使用说明').fontSize(16).fontWeight(FontWeight.Medium).width('100%');Text('1. 两台设备登录同一华为账号，开启NFC、蓝牙、华为分享\n2. 点击分享后将设备背部对齐触碰\n3. 接收端确认后自动通过软总线高速传输').fontSize(13).fontColor('#666666').width('100%').lineHeight(20);}.width('90%').padding(16).backgroundColor('#FFF7E6').borderRadius(12).margin({bottom:30});}.width('100%').height('100%').backgroundColor('#F8F9FA');}}

4.3 运行验证步骤

将应用分别安装到两台鸿蒙实体设备上
确认两台设备满足前文提到的组网条件
在发送端选择一张图片，点击「碰一碰分享」
系统弹出分享面板，顶部会出现近场设备的碰一碰入口
将两台设备背部 NFC 区域对齐触碰，接收端确认后自动开始传输
传输完成后，图片会自动保存到接收端系统相册

五、进阶：分享应用沙箱内的图片

如果需要分享应用沙箱内的图片（比如截图、生成的海报），不能直接传文件路径，必须转换为系统 File URI。

核心转换代码如下：

import{fileUri}from'@kit.CoreFileKit';// 沙箱文件路径constsandboxPath=`${getContext(this).filesDir}/poster.png`;// 转换为系统可分享的URIconstshareUri=fileUri.getUriFromFilePath(sandboxPath);// 构造分享参数，后续逻辑和相册图片完全一致constshareParams:ShareParams={shareType:ShareType.FILE,fileUris:[shareUri]};

核心规则：只要是跨应用/跨设备分享文件，一律传 URI，不要传本地路径。这是鸿蒙沙箱安全机制的硬性要求。

六、高频踩坑与解决方案

1. 分享面板里没有碰一碰选项

排查优先级：
1. 确认两台设备登录同一个华为账号（最常见原因）
2. 确认都开启了 NFC、蓝牙、华为分享开关
3. 确认连接同一 Wi-Fi，亮屏解锁
4. 确认应用已授予分布式数据同步权限
5. 确认设备距离足够近，背部 NFC 区域对齐

2. 提示「文件不存在」或「权限不足」

原因：直接传入了应用沙箱本地路径，接收方无权访问
解决：使用fileUri.getUriFromFilePath()转换为标准 File URI 后再分享；系统相册返回的 URI 可直接使用

3. 大文件传输中断

原因：网络波动或距离过远导致连接断开
优化：ShareKit 底层已内置断点续传，重新连接后会自动续传；建议 500MB 以上文件尽量保持设备稳定连接

4. 模拟器无法体验碰一碰

说明：模拟器无 NFC 硬件，无法模拟近场触发
替代方案：模拟器可验证分享面板拉起、参数构造、应用内分享等逻辑；碰一碰真机验证即可，核心代码完全通用

5. 多张图片分享失败

解决：fileUris支持数组，最多可同时分享 50 个文件；注意所有文件都必须是合法的 File URI

七、总结

碰一碰传图看似有科技感，底层逻辑其实非常简单：应用层只需要做好「构造合法分享参数」这一件事，剩下的设备发现、连接建立、高速传输、权限管理全部交给系统。

ShareKit 的设计精髓也正在于此：一套接口，全形态适配。你不用为碰一碰单独写一套代码，也不用为应用内分享写另一套，统一的参数规范自动适配所有分享场景，既降低了开发成本，也保证了用户体验的一致性。

碰一碰传图完整 Demo，ShareKit 权限与软总线全配置