当前位置：首页 > news >正文

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

news 2026/7/13 18:28:56

很多开发者觉得碰一碰传图是个复杂功能：要写 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]};