鸿蒙 Share Kit 隔空传送功能通过手势交互实现跨端数据传输，无需物理接触。核心流程包括伸掌抓取、移动传输及放手完成，需满足 HarmonyOS 5.0+ 及设备姿态传感器要求。开发涉及注册监听 gestureshare 事件、3 秒内构造并发送数据、管理生命周期避免超时。特殊场景涵盖与隔空截屏联动逻辑及双端账号信任机制。支持 App Linking 直达应用，并提供异常处理方案如回调超时或下载失败。开发者需优化手势引导与状态反馈以提升用户体验。
注：隔空传送开关开启路径为'设置 > 系统 > 快捷启动和手势 > 隔空传送'。
继碰一碰分享后，HarmonyOS Share Kit 再推创新功能——隔空传送。无需设备物理接触，只需通过'伸掌、抓取、移动、放手'的自然手势，即可完成跨端数据传输，让文件分享从'碰一碰'升级为'隔空传'。这种直观的交互方式，彻底解放了设备接触的限制，尤其适合多设备摆放较近但不便触碰的场景（如桌面多设备协同、会议中文件快速分发）。本文基于官方开发文档，详解隔空传送的核心逻辑、开发步骤、特殊场景适配及最佳实践，助力开发者快速集成这一便捷功能。
隔空传送的核心优势在于'手势驱动 + 精准反馈'，开发者需先明确其交互流程、设备要求与权限说明，确保功能落地时符合用户预期。
隔空传送的手势交互分为'发送端'和'接收端'两大环节，每个环节对应明确的状态反馈，让用户清晰感知操作进度：
| 操作阶段 | 发送端状态 | 接收端状态 | 手势动作与反馈 |
|---|---|---|---|
| 准备阶段 | 发送起始准备（状态 1） | 接收起始准备/接收选中（状态 5） | 双端开启隔空传送开关，发送端在距屏幕 20~40 厘米处伸掌停留，屏幕出现掌型图标（提示'可抓取'） |
| 选中阶段 | 发送选中（状态 2） | - | 发送端看到掌型图标后，握拳完成'抓取'动作，图标变为拳型（提示'已选中内容'） |
| 传输阶段 | 待发送（状态 3）→ 发送中（状态 4） | 待接收（状态 6）→ 接收中（状态 7） | 发送端握拳状态下，将手移动至接收端设备上方，接收端屏幕出现拳型图标（提示'可接收'） |
| 完成阶段 | 发送完成 | 接收完成 | 接收端出现拳型图标后，发送端松开手掌，文件开始传输，传输完成后双端显示'传输成功'提示 |
关键感知要求：手势动作需在屏幕正前方 20~40 厘米范围内完成，动作幅度适中且连贯，设备通过传感器精准识别手势轨迹，避免误触发。
canIUse 判断设备是否支持（参考碰一碰分享的能力检测逻辑）。使用隔空传送前，用户需手动开启功能开关，开启后将联动触发相关系统服务与权限：
隔空传送的开发流程与碰一碰分享类似，核心围绕'注册监听→感知手势→构造数据→发起传输→取消监听'展开，但需重点关注手势事件的时效性与状态反馈，具体步骤如下：
需在'可分享界面'（如图片预览页、文件列表页）进入时注册监听，离开时（包括应用退至后台）立即取消，避免无效监听占用系统资源或误触发。
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);
}
}
}
gesturesShare 回调后，必须在 3 秒内调用 sharableTarget.share()，否则系统会判定为'用户操作超时'，分享失败。建议提前预加载分享数据（如预览图、文件 URI），避免回调中耗时操作；onPageHide）时，需主动取消监听，返回前台后重新注册，确保监听状态与页面可见性一致。隔空传送并非独立功能，其与隔空截屏存在联动逻辑，且设备信任机制直接影响传输体验，开发者需重点适配这两大场景。
开启隔空传送开关时，系统会自动联动开启'隔空截屏'功能（后续用户可手动关闭），两者共用'伸掌 - 握拳'手势，触发逻辑需按开关状态区分，避免功能冲突。具体联动规则如下：
| 隔空传送开关状态 | 隔空截屏开关状态 | 功能触发效果 |
|---|---|---|
| 开启 | 开启 | 1. 图库场景：传输原图 + 可选保存截屏至本机； 2. 其他场景：传输截屏 + 可选保存截屏至本机； 3. 首次操作默认不保存截屏，系统记录用户选择作为下次默认值 |
| 开启 | 关闭 | 1. 图库场景：仅传输原图，无截屏； 2. 其他场景：无截屏，不传输 |
| 关闭 | 开启 | 仅触发隔空截屏，保存至本机，不进行跨端传输 |
| 关闭 | 关闭 | 无截屏，不传输 |
为提升传输效率，隔空传送引入'设备信任'机制，根据双端华为账号状态决定是否需要用户确认：
| 双端账号状态 | 信任机制 | 传输体验 |
|---|---|---|
| 已登录相同华为账号 | 默认可信 | 无需用户确认，手势完成后直接开始传输 |
| 未登录相同华为账号 | 需手动信任 | 1. 首次传输：双端弹出'是否信任该设备'弹窗，均确认后建立信任； 2. 信任有效期：1 小时内再次传输，无需重复确认； 3. 超时后：需重新确认信任 |
与碰一碰分享类似，隔空传送支持通过 App Linking 实现'分享链接→直达应用'的闭环体验，无论接收端是否安装应用，都能快速访问分享内容，提升用户转化率。
content 字段设为 App Linking 链接；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') || ''
};
}
}
| 异常场景 | 处理方式 | 代码示例 |
|---|---|---|
| 回调超时（超过 3 秒未调用 share()） | 系统自动终止分享，弹窗提示'操作超时' | 提前预加载分享数据，避免回调中耗时操作 |
| 当前界面无可分享内容 | 调用 clarifyNonShare() 终止分享，提示用户 | sharableTarget.clarifyNonShare({ message: '当前页面无可用分享内容，请选择文件后重试' }) |
| 分享数据下载失败（如云端图片） | 调用 reject() 终止分享，指定错误码 | sharableTarget.reject(harmonyShare.SharableErrorCode.DOWNLOAD_ERROR) |
| 接收端拒绝信任/拒绝接收 | 系统通过通知提示发送端，无需开发者额外处理 | - |
rawfile 目录）；隔空传送作为 HarmonyOS 全场景交互的重要组成部分，以自然手势打破了设备接触的限制，为用户带来更便捷、更具科技感的分享体验。开发者通过本文的指南，可快速完成功能集成，并结合实际业务场景优化交互细节，让应用在多设备协同生态中更具竞争力。随着鸿蒙生态的持续扩展，隔空传送未来还将支持更多设备类型（如智慧屏、手表）和数据格式，进一步丰富全场景分享能力。
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online
将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。 在线工具，HTML转Markdown在线工具，online
通过删除不必要的空白来缩小和压缩JSON。 在线工具，JSON 压缩在线工具，online
将JSON字符串修饰为友好的可读格式。 在线工具，JSON美化和格式化在线工具，online