精准碰一碰近场分享与拖拽投送实战：把文件“碰“进另一台设备【鸿蒙心迹】

最新推荐文章于 2026-10-28 16:35:10 发布

原创最新推荐文章于 2026-10-28 16:35:10 发布 · 193 阅读

3 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

话题

#【多重好礼】鸿蒙心迹 · 开发录原创征稿活动

本文详解HarmonyOS精准碰一碰（NearLink）近场分享能力的接入实践，涵盖设备能力探测、分享URI转换、MIME类型规范、大文件进度与续传、接收端声明及权限配置等关键环节。强调沙箱路径需转为content://URI、双方需亮屏靠近、传输依赖硬件支持等核心约束，适用于图片、短视频等小文件无感投送场景。

一、背景与痛点

传文件最烦的是"先开 App、再选设备、再等配对"。HarmonyOS 的精准碰一碰（NearLink / 碰一碰分享）把这一步压缩成"两台设备靠近一碰，文件就过去了"，配合拖拽投送还能把图直接拖进对方窗口。但真做接入，我遇到：设备不支持、距离太远拉不起、权限没配导致静默失败、大文件传输中断。

碰一碰底层是近场发现 + 近场传输，开发侧主要和分享意图（Want）+ 近场能力打交道。本文讲清接入链路与避坑。

二、能力与规格

维度	说明
能力	近场发现、近场分享、拖拽投送
依赖	设备需支持 NearLink / 碰一碰硬件与系统版本
入口	系统分享面板（Want `sendData`）+ 近场投送通道
约束	距离近（厘米级）、需双方亮屏解锁、权限与可见性
典型场景	图片/视频碰传、会议纪要投送、跨设备接力

三、核心代码（发起近场分享）

import { wantConstant } from '@kit.AbilityKit';
import { fileUri } from '@kit.CoreFileKit';
import { nearbyShare } from '@kit.NearLinkKit'; // 近场能力查询/传输

// 1. 把沙箱文件转成可分享 URI
function toShareUri(sandboxPath: string): string {
  return fileUri.getUriFromPath(sandboxPath); // 如 file://...
}

// 2. 能力探测：先确认设备支持碰一碰，避免按钮点了没反应
function isNearbySupported(): boolean {
  return nearbyShare.isSupported(); // 低端机/旧版本返回 false
}

// 3. 构造分享 Want，交给系统分享面板（碰一碰会在面板里出现）
function shareNearby(ctx: Context, filePath: string): void {
  if (!isNearbySupported()) {
    // 降级：走普通二维码/蓝牙分享
    fallbackShare(ctx, filePath);
    return;
  }
  const want: Want = {
    action: wantConstant.Action.sendData,
    type: 'image/jpeg',                 // MIME，决定接收方可识别
    uri: toShareUri(filePath),
    parameters: { 'ohos.extra.param.key_share_target': 'nearby' },
  };
  // 拉起系统分享，用户选"碰一碰/近场"即可近场发送
  (ctx as common.UIAbilityContext).startAbility(want)
    .catch(err => console.error('share failed', err));
}

// 4. 降级方案：二维码/蓝牙分享
function fallbackShare(ctx: Context, filePath: string): void {
  // 生成二维码或走蓝牙通道，保证功能可用
  console.info('device not support nearby, fallback to qrcode/bluetooth');
}

// 5. 大文件进度回调：监听传输进度，UI 上提示"保持设备靠近"
function watchProgress(taskId: string): void {
  nearbyShare.on('progress', (info: ProgressInfo) => {
    const percent = Math.round(info.transferred / info.total * 100);
    console.info(`transfer progress: ${percent}%`);
    // 更新 UI 进度条，并提示用户保持设备靠近
  });
  nearbyShare.on('interrupt', () => {
    console.warn('transfer interrupted, retry...');
    // 触发续传/重试逻辑
  });
}

四、实战要点

要点 1：先确认设备能力，别假设都支持。
碰一碰依赖硬件与系统版本，低端机/旧版本可能没有。发起前用能力查询判断，不支持就降级成普通二维码/蓝牙分享，别让按钮点了没反应。

要点 2：URI 必须用 getUriFromPath 转换。
直接塞沙箱绝对路径，接收方拿不到（跨应用沙箱隔离）。一定要转成 file:// 形式的分享 URI。

要点 3：MIME type 写准，否则接收端不认。
type 决定对方用什么打开。图片用 image/jpeg、视频 video/mp4，乱写会导致接收方无应用可处理，传输白做。

要点 4：大文件做好中断与进度。
近场传输受距离、干扰影响可能中断。大文件务必带进度回调与续传/重试，并在 UI 上明示"保持设备靠近"，别让用户以为卡死了。

五、进阶：接收端与权限配置

碰一碰是双向的，发送端只是链路的一半。接收端要能"接住"文件，还需要做好三件事：

1. 声明接收能力（module.json5）

接收方要在 module.json5 里声明 sendData 的 want 过滤，否则系统分享面板不会把文件投给它：

{
  "abilities": [
    {
      "name": "ReceiveAbility",
      "skills": [
        {
          "actions": ["ohos.want.action.sendData"],
          "uris": [
            { "scheme": "file", "type": "image/*" },
            { "scheme": "file", "type": "video/*" }
          ]
        }
      ]
    }
  ]
}

2. 在 onNewWant 里接收文件

import { fileUri } from '@kit.CoreFileKit';

export default class ReceiveAbility extends UIAbility {
  onNewWant(want: Want): void {
    const uri = want.uri; // file:// 形式的分享 URI
    if (!uri) return;
    // 转回沙箱路径并落盘
    const sandboxPath = fileUri.getPathFromUri(uri);
    console.info(`received file at: ${sandboxPath}`);
    // 通知 UI 展示接收结果
  }
}