鸿蒙 Share Kit 隔空传送功能开发详解

2.1.1 核心代码：监听注册与取消

import { uniformTypeDescriptor as utd } from '@kit.ArkData';
import { systemShare, harmonyShare } from '@kit.ShareKit';
import { fileUri } from '@kit.CoreFileKit';
import { UIContext, Context } from '@kit.ArkUI';

@Component
export default struct AirSharePage {
    // 标记是否已注册监听，避免重复注册
    private isListening = false;

    // 页面进入可分享状态时，注册隔空传送监听
    aboutToAppear(): void {
        this.registerAirShareListener();
    }

    // 页面消失（关闭/退后台）时，取消监听
    aboutToDisappear(): void {
        this.unregisterAirShareListener();
    }

    // 应用退至后台时，取消监听（补充 aboutToDisappear 未覆盖的场景）
    onPageHide(): void {
        this.unregisterAirShareListener();
    }

    // 注册隔空传送监听事件
    private registerAirShareListener() {
        if (this.isListening) return;
        // 检查设备是否支持隔空传送能力（推荐添加，避免无效逻辑）
        if (!canIUse('SystemCapability.Collaboration.HarmonyShare.Gestures')) {
            console.log("设备不支持隔空传送，隐藏相关引导");
            return;
        }
        // 注册手势分享监听，回调函数需在 3 秒内发起分享，否则超时失败
        harmonyShare.on('gesturesShare', this.airShareCallback);
        this.isListening = true;
        console.log("隔空传送监听注册成功");
    }

    // 取消隔空传送监听事件
    private unregisterAirShareListener() {
        if (!this.isListening) return;
        harmonyShare.off('gesturesShare', this.airShareCallback);
        this.isListening = false;
        console.log("隔空传送监听已取消");
    }

    // 隔空传送回调：构造并发送分享数据
    private airShareCallback = (sharableTarget: harmonyShare.SharableTarget) => {
        try {
            // 3 秒内必须调用 share()，否则系统判定超时，分享失败
            this.buildShareData(sharableTarget);
        } catch (error) {
            console.error("构造分享数据失败：", error);
            // 异常场景：终止分享并提示用户
            sharableTarget.reject(harmonyShare.SharableErrorCode.UNKNOWN_ERROR);
        }
    };

    // 构造分享数据（核心业务逻辑）
    private buildShareData(sharableTarget: harmonyShare.SharableTarget) {
        const uiContext: UIContext = this.getUIContext();
        const context: Context = uiContext.getHostContext() as Context;
        // 1. 示例：分享本地图片（根据实际业务替换为文件、链接等内容）
        const imagePath = context.filesDir + '/air_share_example.jpg';
        const thumbnailUri = fileUri.getUriFromPath(imagePath);
        // 2. 构造分享数据（支持 IMAGE、HYPERLINK 等多种 utd 类型）
        const shareData: systemShare.SharedData = new systemShare.SharedData({
            utd: utd.UniformDataType.IMAGE,
            content: thumbnailUri,
            title: '隔空传送图片',
            description: '通过 HarmonyOS 隔空传送发送',
            thumbnailUri: thumbnailUri
        });
        // 3. 发起隔空传送
        sharableTarget.share(shareData);
        console.log("隔空传送已发起，等待接收端确认");
    }

    build() {
        // 页面布局：需包含手势引导提示（如'伸掌停留 20-40 厘米处可抓取'）
        Column() {
            Text("隔空传送引导").fontSize(16).margin(16);
            Text("1. 伸掌停留屏幕前 20-40cm，出现掌型图标后握拳抓取").fontSize(14).marginLeft(16);
            Text("2. 握拳移动至接收设备上方，待出现拳型图标后放手").fontSize(14).marginLeft(16).marginTop(8);
        }
    }
}

2.2 关键注意点：超时与生命周期管理

• 3 秒超时限制：收到 gesturesShare 回调后，必须在 3 秒内调用 sharableTarget.share()，否则系统会判定为'用户操作超时'，分享失败。建议提前预加载分享数据（如预览图、文件 URI），避免回调中耗时操作；
• 监听注册时机：仅在'可分享界面'（如选中文件、打开图片预览页）注册监听，非分享界面需及时取消，避免无关场景误触发手势；
• 后台取消监听：应用退至后台（onPageHide）时，需主动取消监听，返回前台后重新注册，确保监听状态与页面可见性一致。

三、特殊场景适配：隔空截屏联动与可信任设备

隔空传送并非独立功能，其与隔空截屏存在联动逻辑，且设备信任机制直接影响传输体验，开发者需重点适配这两大场景。

3.1 隔空传送与隔空截屏的联动逻辑

开启隔空传送开关时，系统会自动联动开启'隔空截屏'功能（后续用户可手动关闭），两者共用'伸掌 - 握拳'手势，触发逻辑需按开关状态区分，避免功能冲突。具体联动规则如下：

开发适配建议

• 在分享卡片下方添加'保存截屏至本机'提示（系统自动触发，无需额外开发）；
• 针对非图库场景（如文档、链接分享），需提前告知用户'开启隔空截屏后会传输截屏而非原文件'，避免认知偏差；
• 若应用需禁用截屏联动，可引导用户手动关闭隔空截屏开关（跳转路径：设置 > 系统 > 快捷启动和手势 > 隔空截屏）。

3.2 可信任设备：免确认传输机制

为提升传输效率，隔空传送引入'设备信任'机制，根据双端华为账号状态决定是否需要用户确认：

开发适配要点

• 异账号场景下，需在分享卡片中显示对端设备信息（如设备名称、账号昵称，需 HarmonyOS 5.0+ 支持），帮助用户判断是否信任；
• 传输前需检查网络状态（蓝牙/WLAN 需开启），若未开启，通过系统弹窗提示用户开启，避免因网络问题导致信任确认后传输失败；
• 信任状态变更无需开发者额外处理，由 Share Kit 底层维护，开发者仅需关注传输结果回调（如成功、失败、被拒绝）。

四、进阶功能：App Linking 直达应用

与碰一碰分享类似，隔空传送支持通过 App Linking 实现'分享链接→直达应用'的闭环体验，无论接收端是否安装应用，都能快速访问分享内容，提升用户转化率。

4.1 核心实现逻辑

1. 应用接入 App Linking Kit（参考华为应用链接服务开发文档）；
2. 构造分享数据时，将 content 字段设为 App Linking 链接；
3. 接收端收到分享后，若已安装应用，直接拉起应用并跳转至对应页面；若未安装，跳转应用市场下载（需配置 App Linking 直达应用市场能力）。

4.2 代码示例

private buildShareData(sharableTarget: harmonyShare.SharableTarget) {
    // 构造 App Linking 分享数据（链接需提前通过 App Linking Kit 生成）
    const shareData: systemShare.SharedData = new systemShare.SharedData({
        utd: utd.UniformDataType.HYPERLINK,
        content: 'https://sharekitdemo.drcn.agconnect.link/ZB3p',
        title: 'HarmonyOS 开发者大会直播回放',
        description: '点击直达应用观看完整视频',
        thumbnailUri: 'file:///data/storage/.../live_cover.jpg'
    });
    sharableTarget.share(shareData);
}

// 接收端应用获取链接并跳转（在 Ability 的 onCreate/onNewWant 中处理）
import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';

export default class EntryAbility extends UIAbility {
    onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
        if (want.uri) {
            console.log("收到隔空传送的 App Linking 链接：", want.uri);
            // 解析链接参数，跳转至对应页面（如直播回放页）
            this.navigateToTargetPage(want.uri);
        }
    }

    onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void {
        // 应用已启动时，接收新的分享链接
        this.onCreate(want, launchParam);
    }

    private navigateToTargetPage(uri: string) {
        // 解析 uri 中的参数（如视频 ID、页面路径）
        const params = this.parseAppLinkingParams(uri);
        // 跳转至目标页面（根据参数动态跳转）
        router.pushUrl({ url: `/pages/livePlayback?videoId=${params.videoId}` });
    }

    private parseAppLinkingParams(uri: string): { videoId: string } {
        // 实际开发中需按 App Linking 生成规则解析参数
        const urlObj = new URL(uri);
        return {
            videoId: urlObj.searchParams.get('videoId') || ''
        };
    }
}

五、异常场景处理与用户体验优化

5.1 常见异常场景及处理方案

5.2 用户体验优化建议

• 手势引导可视化：在可分享界面添加动态引导图（如手势步骤动画），提示用户'伸掌停留→握拳抓取→移动→放手'的操作流程，降低学习成本（可下载官方手势引导资源，放置于 rawfile 目录）；
• 状态反馈及时化：传输过程中显示进度条（如'传输中 30%'），传输成功/失败后给出明确提示（如弹窗、Toast），让用户实时掌握状态；
• 权限说明透明化：首次开启功能时，通过应用内引导页说明'开启隔空传送将联动开启蓝牙、WLAN，读取设备信息'，避免用户因权限弹窗产生抵触；
• 设备发现提示：若未检测到可接收设备，提示用户'确保接收端已开启隔空传送且在附近'，帮助用户快速定位问题。

六、开发最佳实践总结

1. 监听注册与取消时机：严格遵循'进入可分享界面注册，离开/退后台取消'，避免内存泄漏和误触发；
2. 超时处理优先级：回调中优先发起分享，耗时操作（如图片下载）可通过'先发送核心数据，后更新预览图'的方式（参考碰一碰分享的延迟更新逻辑）；
3. 版本适配：针对 HarmonyOS 5.0 以下版本，隐藏隔空传送功能入口，避免不支持的设备出现异常；
4. 安全合规：不存储用户的设备标识符、账号信息等敏感数据，仅通过 Share Kit 提供的合法接口获取必要信息；
5. 测试重点：重点测试手势识别成功率（不同距离、光线条件下）、双端账号信任逻辑、与隔空截屏的联动效果，确保功能稳定性。

七、总结

隔空传送作为 HarmonyOS 全场景交互的重要组成部分，以自然手势打破了设备接触的限制，为用户带来更便捷、更具科技感的分享体验。开发者通过本文的指南，可快速完成功能集成，并结合实际业务场景优化交互细节，让应用在多设备协同生态中更具竞争力。随着鸿蒙生态的持续扩展，隔空传送未来还将支持更多设备类型（如智慧屏、手表）和数据格式，进一步丰富全场景分享能力。