鸿蒙碰一碰分享实战：从触发到沙箱接收的全流程记录

预览卡片：别让裁剪毁了第一印象

预览卡片有三种布局：纯图片、沉浸式大卡、白卡上下布局。选错了布局，预览图可能被裁得很难看。规则不复杂：

分辨率推荐：海报图用 3:4 比例，最小 600×800，最大 3000×4000；用户上传的图片不超过 3000×4000 就行。

图片在云端时，碰一下还没下载下来，卡片就会空白。可以先发不带图的数据，下载完再补上。

private buildShareData(sharableTarget: harmonyShare.SharableTarget) {
    const shareData: systemShare.SharedData = new systemShare.SharedData({
        utd: utd.UniformDataType.HYPERLINK,
        content: 'https://example.com/travel',
        title: '旅行攻略',
        description: '超全景点指南',
    });
    sharableTarget.share(shareData);

    // 模拟下载完成，实际监听下载回调
    setTimeout(async () => {
        const uiContext: UIContext = this.getUIContext();
        const context: Context = uiContext.getHostContext() as Context;
        const downloadedImagePath = context.filesDir + '/downloaded_poster.jpg';
        const newThumbnailUri = fileUri.getUriFromPath(downloadedImagePath);
        sharableTarget.updateShareData({
            thumbnailUri: newThumbnailUri,
        });
    }, 3000); // 不要学我用固定延迟，监听下载事件
}

数据传输选 App Linking 还是 Deep Linking

分享链接时，选 App Linking 省心：已安装应用直接拉起，没装就弹应用市场。Deep Linking 只在已安装时有效，未安装会提示'暂无可用打开方式'。代码上只是 content 字段不一样。

App Linking 示例：

content: 'https://sharekitdemo.drcn.agconnect.link/ZB3p', // App Linking 链接

Deep Linking 示例：

content: 'myapp://product/detail?id=123', // Deep Linking scheme

安全和异常，别让用户蒙在鼓里

Share Kit 会显示对方身份信息（登录了账号就是昵称+头像，没登录是设备名），但注意这功能 HarmonyOS NEXT 5.0.0.123 SP16 才开始支持，老版本是空白的。

异常情况要主动告诉用户发生了什么：

• 当前界面没得分享：调 clarifyNonShare，系统会提示。
• 下载失败了：调 reject(DOWNLOAD_ERROR)，系统提示'下载失败，稍后重试'。

// 无内容
sharableTarget.clarifyNonShare({ message: '当前界面不支持碰一碰，请在图片预览或文件详情页尝试' });

// 下载错误
sharableTarget.reject(harmonyShare.SharableErrorCode.DOWNLOAD_ERROR);

手机 ↔ PC/2in1 的碰一碰——角度是硬门槛

这部分有几个硬性约束：

• 同一个华为账号
• 手机必须是直板态
• 角度要求：俯视夹角≤5°（基本平行），侧视夹角>35°，正视夹角≤25°
• 官方轻薄保护壳，厚的会影响

从 Beta5 版本开始，不支持双向同时分享。规则简单：谁前台有可分享内容谁就发送，如果双方都有或都没有，按优先级来。老版本（<Beta5）还是双向的，适配时得分情况。

沙箱接收：直达应用的体验

手机碰 PC，文件能直接存进 PC 应用的沙箱目录，不用用户选路径。开发时用 dataReceive 事件，配置接收的文件类型和数量上限。接收完后在 onDataReceived 回调里处理文件。

import { uniformTypeDescriptor as utd } from '@kit.ArkData';
import { systemShare, harmonyShare } from '@kit.ShareKit';
import { common } from '@kit.AbilityKit';

@Component
export default struct PCImageEditorPage {
    aboutToAppear(): void {
        this.registerSandboxReceive();
    }

    aboutToDisappear(): void {
        this.unregisterSandboxReceive();
    }

    private registerSandboxReceive() {
        const capabilityRegistry: harmonyShare.RecvCapabilityRegistry = {
            windowId: 2001,
            capabilities: [
                {
                    utd: utd.UniformDataType.IMAGE,
                    maxSupportedCount: 5,
                },
            ],
        };

        harmonyShare.on('dataReceive', capabilityRegistry, (receivableTarget: harmonyShare.ReceivableTarget) => {
            const uiContext = this.getUIContext();
            const context = uiContext.getHostContext() as common.UIAbilityContext;
            const savePath = context.filesDir + '/received_images/';

            receivableTarget.receive(savePath, {
                onDataReceived: (sharedData: systemShare.SharedData) => {
                    const records = sharedData.getRecords();
                    records.forEach((record) => {
                        console.log(`接收文件：${record.uri}`);
                        this.openImageEditor(record.uri);
                    });
                },
                onResult: (resultCode: harmonyShare.ShareResultCode) => {
                    if (resultCode === harmonyShare.ShareResultCode.SHARE_SUCCESS) {
                        console.log("所有文件接收完成");
                    } else {
                        console.log(`接收失败，错误码：${resultCode}`);
                    }
                },
            });
        });
    }

    private unregisterSandboxReceive() {
        const capabilityRegistry: harmonyShare.RecvCapabilityRegistry = {
            windowId: 2001,
            capabilities: [
                {
                    utd: utd.UniformDataType.IMAGE,
                    maxSupportedCount: 5,
                },
            ],
        };
        harmonyShare.off('dataReceive', capabilityRegistry);
    }

    private openImageEditor(imageUri: string) {
        // 跳转编辑页
    }

    build() {
        // UI
    }
}

如果 PC 应用正在编辑不想接收，调 reject 就行：

receivableTarget.reject(harmonyShare.ReceivableErrorCode.NO_RECEIVABLE_ERROR);

组队邀请——别让双方同时邀请

游戏组队邀请容易撞车，双方都发邀请会失败。解决办法：一方在注册时设 sendOnly: true，表示只发送不接收。这样碰一碰时只有发送端构造数据。

const capabilityRegistry: harmonyShare.SendCapabilityRegistry = {
    windowId: 3001,
    sendOnly: true,
};
harmonyShare.on('knockShare', capabilityRegistry, (sharableTarget) => {
    const teamLink = `mygame://team/join?id=12345&inviter=user1`;
    const shareData = new systemShare.SharedData({
        utd: utd.UniformDataType.HYPERLINK,
        content: teamLink,
        title: '邀请加入游戏战队',
        description: '点击立即组队开黑',
        thumbnailUri: 'file:///.../team_poster.jpg',
    });
    sharableTarget.share(shareData);
});

接收端通过 onNewWant 获取链接并解析房间信息：

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

export default class GameAbility extends UIAbility {
    onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
        if (want.uri) {
            this.joinTeam(want.uri);
        }
    }

    onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void {
        if (want.uri) {
            this.joinTeam(want.uri);
        }
    }

    private joinTeam(teamUri: string) {
        // 解析 URI 并加入
    }
}

最后再啰嗦几点

开发时容易忘的东西，列在这里：

• canIUse 检查，不支持就别显示入口。
• 注册事件后一定要在合适的时机注销。
• 预览图不要过大，云端图片必须处理延迟更新。
• 异常提示做全，别让用户干等。
• 手机和 PC 版本要求不同，双向分享逻辑按版本区分。
• 引导动图和文字必不可少，否则用户不知道能碰。

希望这些记录能让你的碰一碰分享开发少踩坑，一碰即传体验顺滑。