碰一碰功能简介

碰一碰是鸿蒙系统（HarmonyOS）提供的一种超近场分享能力。用户通过将两台设备顶部轻轻触碰（手机与手机）或将手机顶部轻触屏幕（手机与电脑/平板），即可快速建立连接并分享内容。该功能由 Share Kit（分享服务）提供支持，目前支持手机与手机、手机与 PC/2in1 设备之间的碰一碰分享；从 6.1.0(23) 版本开始，新增支持手机与 Tablet 设备之间的碰一碰分享。

适用场景：碰一碰分享适用于设备间的快速分享，支持分享的内容包括图片、视频、网络链接、联系人、链接等。

碰一碰分享界面设计

设备碰一碰成功建立连接后，会形成分享界面。分享界面由以下 4 大部分组成：

虫洞区：碰后设备间若成功建立连接，顶部出现虫洞，用于飞出或飞入卡片。不支持应用自定义。
卡片区：用于分享内容展示，提供 5 类模板，生态应用根据分享内容选择不同模板。
信息展示区：用于展示分享时对方的设备信息，包括华为账号头像以及设备名称。在 1 碰多的场景中会出现头像叠加。不支持应用自定义。
操作区：发送端和接收端分别为引导字符和按钮，展示交互方式和操作意图。不支持应用自定义。

说明：当前名片类模板仅对系统联系人应用开放。

卡片模板

根据不同的分享内容和业务诉求，Share Kit 提供 5 类卡片模板，应用可根据不同需求选择不同模板。

图片、视频类卡片模板

适用场景：分享内容为图片或视频。
应用接入：应用需传入预览图片或者视频。
卡片详情：根据原图片比例进行自适应显示，支持比例范围为 4:1 ～ 1:4 ，超出进行图片居中裁剪。

文件类卡片模板

适用场景：分享内容为文件、WIFI 或者个人热点。
应用接入：应用需传入主副文本。文件类主文本为文件名称及类型，辅助文本为文件大小。
卡片详情：卡片比例固定为 4:3 。

链接类卡片模板

适用场景：分享内容为链接，例如音乐链接、视频链接、商品链接等等。
应用接入：应用需传入主副文本、预览图以及应用图标。若分享类型为名片，则还需传入用户头像。
卡片详情：最佳预览图比例为 4:3、1:1、16:9，应用请尽量传入上述比例预览图。超出 4:3 ～ 16:9 的比例图片居中裁剪。

链接类模板可分为内容分享与名片分享两类，应用可根据分享内容进行匹配。应用传入的预览图尽量保持在 4:3、1:1、16:9 三种比例，以此可保障画面不被裁剪；同时尽量选取主体明确、比例合适、底部无重要信息露出的图片，以获得最佳显示效果。

其他卡片模板

适用场景：系统分享面板碰一碰 & 无预览图特殊场景。
应用接入：应用需传入主副文本，以及应用图标。
卡片详情：无预览图时，展示当前卡片样式。

手机与手机碰一碰分享开发适配

场景介绍与业务流程

场景介绍：宿主应用进入一个可以分享的界面，比如打开或者选中的一个文件、一条备忘录、一个联系人详情，或个人热点/Wi-Fi 等。宿主应用可以分享多个内容，如选中的多张图片等。

宿主应用注册碰一碰分享事件，并与亮屏且解锁的对端设备碰一碰。
宿主应用发现设备，调用碰一碰分享事件回调，在回调事件中构造分享数据并发送。
目标设备接收并处理分享数据。
宿主应用解除注册碰一碰分享事件。

使用约束与环境要求

手机应用发起碰一碰分享时，双端设备需要在亮屏、且解锁的状态下并且都已开启华为分享服务（系统默认开启），设备顶部轻碰即可触发。
如果用户已手动关闭华为分享服务开关，轻碰事件触发时，用户会接收到系统通知提示开启。
任意一端设备不支持碰一碰能力时，轻碰无任何响应。
宿主应用无法获得分享结果，Share Kit 会通过系统通知消息告知用户对端接收或拒绝。

支持的手机系统：HarmonyOS NEXT Release 及以上版本，可使用 canIUse 判断系统能力是否支持：

if
(
canIUse
(
'SystemCapability.Collaboration.HarmonyShare'
)
)
{
}

集成开发环境：DevEco Studio NEXT Beta1 及以上版本。

注册碰一碰事件与发送分享数据

当用户进入支持碰一碰分享的界面或场景时，应通过 harmonyShare.on('knockShare', ...) 注册碰一碰分享事件。注册时需要传入 SendCapabilityRegistry ，其中包含 windowId 等信息。在回调中构造 SharedData 并调用 sharableTarget.share(shareData) 发送数据。

import
{
uniformTypeDescriptor
as
utd
}
from
'@kit.ArkData'
;
import
{
systemShare
,
harmonyShare
}
from
'@kit.ShareKit'
;
import
{
fileUri
}
from
'@kit.CoreFileKit'
;
@
Component
export
default
struct Index
{
aboutToAppear
(
)
:
void
{
let
capabilityRegistry
:
harmonyShare
.
SendCapabilityRegistry
=
{
windowId
:
999
,
}
harmonyShare
.
on
(
'knockShare'
,
capabilityRegistry
,
(
sharableTarget
:
harmonyShare
.
SharableTarget
)
=>
{
let
uiContext
:
UIContext
=
this
.
getUIContext
(
)
;
let
contextFaker
:
Context
=
uiContext
.
getHostContext
(
)
as
Context
;
let
filePath
=
contextFaker
.
filesDir
+
'/exampleKnock1.jpg'
;
let
shareData
:
systemShare
.
SharedData
=
new
systemShare
.
SharedData
(
{
utd
:
utd
.
UniformDataType
.
HYPERLINK
,
content
:
'https://sharekitdemo.drcn.agconnect.link/ZB3p'
,
thumbnailUri
:
fileUri
.
getUriFromPath
(
filePath
)
,
title
:
'碰一碰分享卡片标题'
,
description
:
'碰一碰分享卡片描述'
}
)
;
sharableTarget
.
share
(
shareData
)
;
}
)
;
}
aboutToDisappear
(
)
:
void
{
let
capabilityRegistry
:
harmonyShare
.
SendCapabilityRegistry
=
{
windowId
:
999
,
}
harmonyShare
.
off
(
'knockShare'
,
capabilityRegistry
)
;
}
build
(
)
{
}
}

设置分享预览

接入碰一碰分享时，需根据不同的分享数据类型，适配相应的卡片模板。Share Kit 支持三种卡片模板供手机发起碰一碰分享时选择：

纯图片布局

说明：只包括预览图。当分享数据为文件、图片等无需添加标题及描述的场景，推荐使用。
使用方法：构造分享数据时，仅传递预览图（ thumbnailUri ）字段。
布局要求：预览图支持最小宽高比 1:4，超出部分将被裁剪。

沉浸式大卡布局

说明：包括预览图、标题、描述、应用图标。当分享数据为链接类型，需要向用户传递链接内容时推荐使用。
使用方法：需同时满足两个条件：构造分享数据时，同时传入标题（ title ）、描述（ description ）和预览图（ thumbnailUri ）字段。预览图宽高比小于 1:1。
布局要求：预览图：支持最小宽高比 1:4，超出部分将被裁剪。标题：最大可显示 2 行，超过用省略号代替。建议应用自行控制字数约 20 个中文左右。描述：仅可显示 1 行，超过用省略号代替。应用图标：无需配置，系统默认获取应用图标显示在卡片底部。

白卡上下布局

说明：包括预览图、标题、描述、应用图标。当分享数据为链接类型，需要向用户传递链接内容时推荐使用。
使用方法：需同时满足两个条件：构造分享数据时，同时传入标题（ title ）、描述（ description ）和预览图（ thumbnailUri ）字段。预览图宽高比大于 1:1。
布局要求：预览图：仅显示在卡片上方，不会铺满整个卡片。标题：最大可显示 2 行，超过用省略号代替；建议控制约 20 个中文。描述：仅可显示 1 行，超过用省略号代替。应用图标：无需配置，系统默认获取应用图标显示在卡片底部。

设置合适的预览图

预览图的质量直接影响碰一碰卡片的显示效果。建议按照以下推荐设置：

| 预览图来源 | 推荐比例 | 推荐分辨率（px） | 推荐大小（KB） |
| --- | --- | --- | --- |
| 应用创作的海报 | 3:4 | 最小 600 * 800，最大 3000 * 4000 | 512KB，若超过会被压缩 |
| 用户上传的图片 | 不限制 | 最小不限制，最大 3000 * 4000 | 512KB，若超过会被压缩 |

使用预览图更新能力

当应用使用云端存储的图片作为预览图时，碰一碰分享的回调触发时可能无法及时下载到本地而导致超时失败。Share Kit 提供预览图延迟更新能力：

在接到碰一碰事件回调时，可仅发送分享的核心数据内容，建立连接；Share Kit 会提供默认预览图用于卡片展示。
待云端图片下载完成后，调用 sharableTarget.updateShareData 接口更新预览图信息。

import
{
uniformTypeDescriptor
as
utd
}
from
'@kit.ArkData'
;
import
{
systemShare
,
harmonyShare
}
from
'@kit.ShareKit'
;
import
{
fileUri
}
from
'@kit.CoreFileKit'
;
@
Component
export
default
struct Index
{
aboutToAppear
(
)
:
void
{
let
capabilityRegistry
:
harmonyShare
.
SendCapabilityRegistry
=
{
windowId
:
999
}
harmonyShare
.
on
(
'knockShare'
,
capabilityRegistry
,
(
sharableTarget
:
harmonyShare
.
SharableTarget
)
=>
{
let
shareData
:
systemShare
.
SharedData
=
new
systemShare
.
SharedData
(
{
utd
:
utd
.
UniformDataType
.
HYPERLINK
,
content
:
'https://sharekitdemo.drcn.agconnect.link/ZB3p'
,
title
:
'碰一碰分享卡片标题'
,
description
:
'碰一碰分享卡片描述'
}
)
;
sharableTarget
.
share
(
shareData
)
;
setTimeout
(
(
)
=>
{
let
uiContext
:
UIContext
=
this
.
getUIContext
(
)
;
let
contextFaker
:
Context
=
uiContext
.
getHostContext
(
)
as
Context
;
let
filePath
=
contextFaker
.
filesDir
+
'/exampleKnock1.jpg'
;
sharableTarget
.
updateShareData
(
{
thumbnailUri
:
fileUri
.
getUriFromPath
(
filePath
)
}
)
;
}
,
5000
)
;
}
)
;
}
aboutToDisappear
(
)
:
void
{
let
capabilityRegistry
:
harmonyShare
.
SendCapabilityRegistry
=
{
windowId
:
999
}
harmonyShare
.
off
(
'knockShare'
,
capabilityRegistry
)
;
}
build
(
)
{
}
}

安全策略

在 HarmonyOS NEXT 5.0.0.123 SP16 及以上版本，碰一碰分享增加了对端华为账号或设备标识，帮助用户识别分享发送端/接收端的身份。具体规则如下：

| 设备 | 对端已登录华为账号 | 对端未登录华为账号 |
| --- | --- | --- |
| 碰一碰发送端 | 展示接收端华为账号昵称和头像。 | 展示接收端设备信息。 |
| 碰一碰接收端 | 展示发送端华为账号昵称和头像（若发送端为旧版本则不会展示）。 | 展示发送端设备信息（若发送端为旧版本则不会展示）。 |

发送分享数据方式

通过链接形式指定应用跳转，通常有两种方式： App Linking 和 Deep Linking 。指定应用跳转时， utd 类型需配置为 "general.hyperlink" ，确保 Share Kit 以正确的方式处理链接。

App Linking

使用 App Linking 进行跳转时，无论应用是否已安装，用户都可以访问到链接对应的内容。
结合 App Linking Kit（应用链接服务）能力，在指定应用未安装时，可实现直达应用市场等能力。
当应用已安装时，App Linking 可直接拉起应用；当应用未安装时，默认通过系统浏览器打开链接对应网页，也可通过直达应用市场能力跳转应用市场。
配合延迟链接能力，即便触发碰一碰分享时应用未安装，待下载启动后仍能获取之前分享的链接，提升链接转换率。

示例代码（App Linking 方式）：

import
{
uniformTypeDescriptor
as
utd
}
from
'@kit.ArkData'
;
import
{
harmonyShare
,
systemShare
}
from
'@kit.ShareKit'
;
import
{
fileUri
}
from
'@kit.CoreFileKit'
;
@
Component
export
struct HarmonyShareScenes
{
onPageHide
(
)
:
void
{
let
uiContext
:
UIContext
=
this
.
getUIContext
(
)
;
let
context
:
Context
=
uiContext
.
getHostContext
(
)
as
Context
;
context
.
eventHub
.
emit
(
'onBackGround'
)
;
}
aboutToAppear
(
)
:
void
{
this
.
immersiveListening
(
)
;
let
uiContext
:
UIContext
=
this
.
getUIContext
(
)
;
let
context
:
Context
=
uiContext
.
getHostContext
(
)
as
Context
;
context
.
eventHub
.
on
(
'onBackGround'
,
this
.
onBackGround
)
;
}
aboutToDisappear
(
)
:
void
{
this
.
immersiveDisablingListening
(
)
;
let
uiContext
:
UIContext
=
this
.
getUIContext
(
)
;
let
context
:
Context
=
uiContext
.
getHostContext
(
)
as
Context
;
context
.
eventHub
.
off
(
'onBackGround'
,
this
.
onBackGround
)
;
}
build
(
)
{
}
private
onBackGround
=
(
)
=>
{
this
.
immersiveDisablingListening
(
)
;
}
private
immersiveCallback
=
(
sharableTarget
:
harmonyShare
.
SharableTarget
)
=>
{
let
uiContext
:
UIContext
=
this
.
getUIContext
(
)
;
let
contextFaker
:
Context
=
uiContext
.
getHostContext
(
)
as
Context
;
let
filePath
=
contextFaker
.
filesDir
+
'/exampleKnock1.jpg'
;
let
shareData
:
systemShare
.
SharedData
=
new
systemShare
.
SharedData
(
{
utd
:
utd
.
UniformDataType
.
HYPERLINK
,
content
:
'https://sharekitdemo.drcn.agconnect.link/ZB3p'
,
thumbnailUri
:
fileUri
.
getUriFromPath
(
filePath
)
,
title
:
'碰一碰分享卡片标题'
,
description
:
'碰一碰分享卡片描述'
}
)
;
sharableTarget
.
share
(
shareData
)
;
}
private
immersiveListening
(
)
{
harmonyShare
.
on
(
'knockShare'
,
this
.
immersiveCallback
)
;
}
private
immersiveDisablingListening
(
)
{
harmonyShare
.
off
(
'knockShare'
,
this
.
immersiveCallback
)
;
}
}

Deep Linking

使用 Deep Linking 进行跳转时，系统仅会在本地已安装的应用中寻找到符合条件的应用。未找到时将弹出提示暂无可用打开方式。

异常场景终止分享

在碰一碰事件回调触发时，可能由于某些原因无法发起分享，此时需及时终止分享，避免用户长时间等待。根据实际场景，有以下处理方式：

当前界面无可分享内容

从 6.0.2(22) 版本开始，当前界面的内容不支持碰一碰分享时，开发者可通过 sharableTarget.clarifyNonShare() 终止本次分享，并引导用户前往可分享界面再次尝试。

import
{
harmonyShare
}
from
'@kit.ShareKit'
;
aboutToAppear
(
)
:
void
{
harmonyShare
.
on
(
'knockShare'
,
(
sharableTarget
:
harmonyShare
.
SharableTarget
)
=>
{
sharableTarget
.
clarifyNonShare
(
{
message
:
'请在支持碰一碰分享的界面再试'
}
)
;
}
)
;
}

分享内容下载失败等其他异常场景

从 5.0.3(15) 版本开始，由于网络或者业务原因无法发起分享时，开发者可通过 sharableTarget.reject() 终止本次分享，并提示用户终止的原因。

import
{
harmonyShare
}
from
'@kit.ShareKit'
;
aboutToAppear
(
)
:
void
{
harmonyShare
.
on
(
'knockShare'
,
(
sharableTarget
:
harmonyShare
.
SharableTarget
)
=>
{
sharableTarget
.
reject
(
harmonyShare
.
SharableErrorCode
.
DOWNLOAD_ERROR
)
;
}
)
;
}

邀请组队场景

在组队房间邀请界面，可以通过碰一碰分享邀请好友加入组队房间。

注册单向分享能力

若双方都同时在组队房间内互相邀请，无法相互加入对方的组队房间。针对此场景，Share Kit 提供单向仅发送能力（ sendOnly 属性）。若碰一碰的双方都设置单向仅发送，则终止本次分享并提示用户“请任意一方退出当前应用后再试”；反之，均可分享成功。

import
{
uniformTypeDescriptor
as
utd
}
from
'@kit.ArkData'
;
import
{
systemShare
,
harmonyShare
}
from
'@kit.ShareKit'
;
import
{
fileUri
}
from
'@kit.CoreFileKit'
;
@
Component
export
default
struct Index
{
aboutToAppear
(
)
:
void
{
let
capabilityRegistry
:
harmonyShare
.
SendCapabilityRegistry
=
{
windowId
:
999
,
sendOnly
:
true
}
harmonyShare
.
on
(
'knockShare'
,
capabilityRegistry
,
(
sharableTarget
:
harmonyShare
.
SharableTarget
)
=>
{
let
uiContext
:
UIContext
=
this
.
getUIContext
(
)
;
let
contextFaker
:
Context
=
uiContext
.
getHostContext
(
)
as
Context
;
let
filePath
=
contextFaker
.
filesDir
+
'/exampleKnock1.jpg'
;
let
shareData
:
systemShare
.
SharedData
=
new
systemShare
.
SharedData
(
{
utd
:
utd
.
UniformDataType
.
HYPERLINK
,
content
:
'https://sharekitdemo.drcn.agconnect.link/ZB3p'
,
thumbnailUri
:
fileUri
.
getUriFromPath
(
filePath
)
,
title
:
'碰一碰分享卡片标题'
,
description
:
'碰一碰分享卡片描述'
}
)
;
sharableTarget
.
share
(
shareData
)
;
}
)
;
}
aboutToDisappear
(
)
:
void
{
let
capabilityRegistry
:
harmonyShare
.
SendCapabilityRegistry
=
{
windowId
:
999
}
harmonyShare
.
off
(
'knockShare'
,
capabilityRegistry
)
;
}
build
(
)
{
}
}

设置组队邀请预览

处理组队链接

当目标应用被分享拉起时，可以通过 onCreate 或 onNewWant 回调中获取传入的 want 参数。其中 want.uri 字段为邀请组队的链接，通过链接上携带的参数信息，处理组队邀请的业务逻辑。

import
{
AbilityConstant
,
UIAbility
,
Want
}
from
'@kit.AbilityKit'
;
import
{
window
}
from
'@kit.ArkUI'
;
export
default
class
EntryAbility
extends
UIAbility
{
async
onWindowStageCreate
(
windowStage
:
window
.
WindowStage
)
:
Promise
<
void
>
{
try
{
windowStage
.
loadContent
(
'pages/Index'
)
;
}
catch
(
error
)
{
console
.
error
(
`
onWindowStageCreate error. Code:
${
error
?.
code
}
, message:
${
error
?.
message
}
`
)
;
}
}
onCreate
(
want
:
Want
,
launchParam
:
AbilityConstant
.
LaunchParam
)
:
void
{
console
.
info
(
'EntryAbility onCreate invoked. uri: '
,
want
.
uri
)
;
}
onNewWant
(
want
:
Want
,
launchParam
:
AbilityConstant
.
LaunchParam
)
:
void
{
console
.
info
(
'EntryAbility onNewWant invoked. uri: '
,
want
.
uri
)
;
}
}

手机与 PC/2in1（及 Tablet）碰一碰分享开发适配

场景介绍与业务流程

Share Kit 支持 Phone 和 PC/2in1 之间的碰一碰分享。利用 PC/2in1 设备的屏幕感知能力，识别 Phone 轻碰屏幕的动作及位置，实现 PC/2in1 窗口级的交互。从 6.1.0(23) 版本开始，支持 Phone 与 Tablet 设备之间的碰一碰分享。

PC/2in1 设备作为数据接收端：手机轻碰 PC/2in1 屏幕，PC/2in1 接收数据。
PC/2in1 设备作为数据发送端：PC/2in1 窗口内容通过碰一碰发送至手机。

双向分享限制

从 6.0.0(20) Beta5 版本开始，手机与 PC/2in1 设备之间不支持双向分享。遵循以下机制：

当手机前台有可分享内容时，无论 PC/2in1 设备前台窗口是否有可分享内容，优先将手机作为发送端，PC/2in1 设备作为接收端。
当手机前台无可分享内容且 PC/2in1 设备前台窗口有可分享内容时，PC/2in1 设备作为发送端，手机作为接收端。
当手机前台和 PC/2in1 设备前台窗口均无可分享内容时，遵循无内容分享逻辑。

对于 6.0.0(20) Beta3 及之前的版本，当手机前台和 PC/2in1 设备前台窗口均有可分享内容时，支持双向分享（发送分享内容的同时也可接收到分享内容）。

使用约束

手机与 PC/2in1 设备间碰一碰分享需登录相同的华为账号。
仅支持直板手机或折叠手机直板态与 PC/2in1 屏幕碰一碰分享。
轻碰屏幕交互约束：手机与 PC/2in1 屏幕俯视夹角应 ≤5°。手机与 PC/2in1 屏幕侧视夹角应 >35°。手机与 PC/2in1 屏幕正视夹角应 ≤25°。手机不能超出 PC/2in1 设备屏幕。支持官方手机保护壳，不支持过厚的手机外壳。

环境要求

支持的 PC/2in1 系统：HarmonyOS 6.0.0 Beta1 及以上版本。
集成开发环境：DevEco Studio 6.0.0 Beta1 及以上版本。

分享内容直达应用界面（沙箱接收）

从 6.0.0(20) 版本开始，沙箱接收能力支持 PC/2in1 设备；从 6.1.0(23) 版本开始，新增支持 Tablet 设备。支持手机轻贴屏幕即可将单/多文件快速传输至 PC/2in1 或 Tablet 设备应用沙箱，传输完成后通知目标应用接收文件列表，实现无缝预览与编辑。

约束：沙箱接收仅支持文件类型的数据，应用需指定支持接收的文件类型和最大数量。若类型不匹配，则跳过已注册的沙箱接口能力，采用华为分享默认逻辑接收文件数据；若数量不匹配，则通过系统弹窗提示用户异常。

开发步骤

导入相关模块：

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

注册沙箱接收事件（在可接收数据的窗口出现时）：

aboutToAppear
(
)
:
void
{
let
capabilityRegistry
:
harmonyShare
.
RecvCapabilityRegistry
=
{
windowId
:
999
,
capabilities
:
[
{
utd
:
utd
.
UniformDataType
.
IMAGE
,
maxSupportedCount
:
1
}
]
}
harmonyShare
.
on
(
'dataReceive'
,
capabilityRegistry
,
(
receivableTarget
:
harmonyShare
.
ReceivableTarget
)
=>
{
let
uiContext
:
UIContext
=
this
.
getUIContext
(
)
;
let
context
=
uiContext
.
getHostContext
(
)
as
common
.
UIAbilityContext
;
receivableTarget
.
receive
(
context
.
filesDir
,
{
onDataReceived
:
(
sharedData
:
systemShare
.
SharedData
)
=>
{
let
sharedRecords
=
sharedData
.
getRecords
(
)
;
sharedRecords
.
forEach
(
(
record
:
systemShare
.
SharedRecord
)
=>
{
}
)
;
}
,
onResult
(
resultCode
:
harmonyShare
.
ShareResultCode
)
{
if
(
resultCode
===
harmonyShare
.
ShareResultCode
.
SHARE_SUCCESS
)
{
}
}
}
)
;
}
)
;
}

取消沙箱接收事件（在窗口关闭时）：

aboutToDisappear
(
)
:
void
{
let
capabilityRegistry
:
harmonyShare
.
RecvCapabilityRegistry
=
{
windowId
:
999
,
capabilities
:
[
{
utd
:
utd
.
UniformDataType
.
IMAGE
,
maxSupportedCount
:
1
}
]
}
harmonyShare
.
off
(
'dataReceive'
,
capabilityRegistry
)
;
}

拒绝本次沙箱接收

当本次沙箱接收回调触发时，如果应用因为业务实现需要拒绝本次接收，可使用 ReceivableTarget.reject() 方法。

import
{
uniformTypeDescriptor
as
utd
}
from
'@kit.ArkData'
;
import
{
harmonyShare
}
from
'@kit.ShareKit'
;
@
Component
export
default
struct Index
{
aboutToAppear
(
)
:
void
{
let
capabilityRegistry
:
harmonyShare
.
RecvCapabilityRegistry
=
{
windowId
:
999
,
capabilities
:
[
{
utd
:
utd
.
UniformDataType
.
IMAGE
,
maxSupportedCount
:
1
}
]
}
harmonyShare
.
on
(
'dataReceive'
,
capabilityRegistry
,
(
receivableTarget
:
harmonyShare
.
ReceivableTarget
)
=>
{
receivableTarget
.
reject
(
harmonyShare
.
ReceivableErrorCode
.
NO_RECEIVABLE_ERROR
)
;
}
)
;
}
aboutToDisappear
(
)
:
void
{
let
capabilityRegistry
:
harmonyShare
.
RecvCapabilityRegistry
=
{
windowId
:
999
,
capabilities
:
[
{
utd
:
utd
.
UniformDataType
.
IMAGE
,
maxSupportedCount
:
1
}
]
}
harmonyShare
.
off
(
'dataReceive'
,
capabilityRegistry
)
;
}
build
(
)
{
}
}

获取轻碰坐标

从 26.0.0 版本开始，手机与 PC/2in1、手机与 Tablet 设备触发轻碰事件时，在 PC/2in1 或 Tablet 设备侧可从回调事件中获取轻碰的位置（基于屏幕左上角为初始点的坐标信息）。通过轻碰的位置不同，可实现不同的业务逻辑，例如向文档指定位置插入图片，或者获取窗口中指定的图片等。

示例代码（包含发送端和接收端获取坐标）：

import
{
uniformTypeDescriptor
as
utd
}
from
'@kit.ArkData'
;
import
{
harmonyShare
,
systemShare
}
from
'@kit.ShareKit'
;
import
{
fileUri
}
from
'@kit.CoreFileKit'
;
import
{
common
}
from
'@kit.AbilityKit'
;
@
Component
export
default
struct KnockShareScreen
{
@
State
knockShareScreenX
:
number
|
undefined
=
undefined
;
@
State
knockShareScreenY
:
number
|
undefined
=
undefined
;
@
State
dataReceiveScreenX
:
number
|
undefined
=
undefined
;
@
State
dataReceiveScreenY
:
number
|
undefined
=
undefined
;
aboutToAppear
(
)
:
void
{
this
.
knockShareListening
(
)
;
}
private
knockShareListening
(
)
{
harmonyShare
.
on
(
'knockShare'
,
this
.
knockShareCallback
)
;
let
capabilityRegistry
:
harmonyShare
.
RecvCapabilityRegistry
=
{
windowId
:
999
,
capabilities
:
[
{
utd
:
utd
.
UniformDataType
.
IMAGE
,
maxSupportedCount
:
1
}
]
}
harmonyShare
.
on
(
'dataReceive'
,
capabilityRegistry
,
this
.
dataReceiveCallback
)
;
}
private
knockShareCallback
=
(
sharableTarget
:
harmonyShare
.
SharableTarget
)
=>
{
let
uiContext
:
UIContext
=
this
.
getUIContext
(
)
;
let
contextFaker
:
Context
=
uiContext
.
getHostContext
(
)
as
Context
;
let
filePath
=
contextFaker
.
filesDir
+
'/exampleKnock1.jpg'
;
let
shareData
:
systemShare
.
SharedData
=
new
systemShare
.
SharedData
(
{
utd
:
utd
.
UniformDataType
.
JPEG
,
uri
:
fileUri
.
getUriFromPath
(
filePath
)
,
thumbnailUri
:
fileUri
.
getUriFromPath
(
filePath
)
}
)
;
let
sharableTargetInfo
=
sharableTarget
.
getInfo
(
)
;
this
.
knockShareScreenX
=
sharableTargetInfo
.
coordinate
?.
screenX
;
this
.
knockShareScreenY
=
sharableTargetInfo
.
coordinate
?.
screenY
;
sharableTarget
.
share
(
shareData
)
;
}
private
dataReceiveCallback
=
(
receivableTarget
:
harmonyShare
.
ReceivableTarget
)
=>
{
let
uiContext
:
UIContext
=
this
.
getUIContext
(
)
;
let
context
=
uiContext
.
getHostContext
(
)
as
common
.
UIAbilityContext
;
let
sandboxUri
=
fileUri
.
getUriFromPath
(
context
.
filesDir
)
;
let
receivableTargetInfo
=
receivableTarget
.
getInfo
(
)
;
this
.
dataReceiveScreenX
=
receivableTargetInfo
.
coordinate
?.
screenX
;
this
.
dataReceiveScreenY
=
receivableTargetInfo
.
coordinate
?.
screenY
;
receivableTarget
.
receive
(
sandboxUri
,
{
onDataReceived
:
(
sharedData
:
systemShare
.
SharedData
)
=>
{
}
,
onResult
:
(
resultCode
:
harmonyShare
.
ShareResultCode
)
=>
{
if
(
resultCode
===
harmonyShare
.
ShareResultCode
.
SHARE_SUCCESS
)
{
}
}
}
)
;
}
build
(
)
{
}
}

手机与 PC/2in1、手机与 Tablet 间相互分享

Phone 与 PC/2in1 设备间相互分享，以及从 6.1.0(23) 版本开始的 Phone 与 Tablet 设备间相互分享，可参考“手机间内容分享”部分的开发方式。

总结

鸿蒙系统的碰一碰功能通过 Share Kit 提供了便捷的超近场分享能力，覆盖手机与手机、手机与 PC/2in1、手机与 Tablet 等多种设备组合。开发者在适配时需要关注：

界面设计：根据分享内容选择合适的卡片模板，并设置符合要求的预览图。
事件注册：使用 harmonyShare.on('knockShare') 注册发送事件，使用 harmonyShare.on('dataReceive') 注册接收事件。
参数配置：正确设置 SendCapabilityRegistry 、 RecvCapabilityRegistry 中的 windowId 、 capabilities 等参数。
异常处理：在无法分享或接收时，调用 clarifyNonShare() 或 reject() 方法及时终止。
高级能力：支持预览图延迟更新、单向分享、沙箱接收、获取轻碰坐标等，满足不同业务场景需求。

通过合理利用以上能力，开发者可以为用户提供流畅、直观的碰一碰分享体验。