本模块提供华为分享的事件注册。
模型约束: 此模块的接口仅可在Stage模型下使用。
起始版本: 5.0.0(12)
拒绝分享回调时,提供拒绝原因,用户可收到系统通知消息。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.Collaboration.HarmonyShare
起始版本: 5.0.3(15)
| 名称 | 值 | 说明 |
|---|---|---|
| NO_CONTENT_ERROR | 1 | 用于无内容分享场景。 |
| NO_INTERNET_ERROR | 2 | 用于无网络场景。 |
| DOWNLOAD_ERROR | 3 | 用于下载失败场景。 |
拒绝沙箱接收回调时,提供拒绝原因,用户可收到系统通知消息。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.Collaboration.HarmonyShare
起始版本: 6.0.0(20)
| 名称 | 值 | 说明 |
|---|---|---|
| NO_RECEIVABLE_ERROR | 1 | 用于当前无法接收数据的场景。 |
华为分享事件触发后回调参数,可通过此参数跨端分享。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.Collaboration.HarmonyShare
起始版本: 5.0.0(12)
reject(error: SharableErrorCode): Promise<void>
当开发者收到回调时,由于某些原因无法继续分享时,可选择拒绝本次分享,使用Promise异步回调。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.Collaboration.HarmonyShare
起始版本: 5.0.3(15)
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| error | SharableErrorCode | 是 | 拒绝本次分享的原因。通过系统弹窗提示用户。 |
返回值:
| 类型 | 说明 |
|---|---|
| Promise<void> | Promise对象。无返回结果的Promise对象。 |
错误码:
以下错误码的详细介绍请参见通用错误码。
| 错误码ID | 错误信息 |
|---|---|
| 401 | Parameter error. |
示例:
import { harmonyShare } from '@kit.ShareKit';
// 注册设备轻贴'knockShare'监听事件
harmonyShare.on('knockShare', (sharableTarget: harmonyShare.SharableTarget) => {
// 拒绝本次分享
sharableTarget.reject(harmonyShare.SharableErrorCode.NO_CONTENT_ERROR);
}); getInfo(): SharableTargetInfo
获取PC/2in1或Tablet设备作为发送端触发碰一碰事件时的相关信息。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.Collaboration.HarmonyShare
起始版本: 26.0.0
返回值:
| 类型 | 说明 |
|---|---|
| SharableTargetInfo | PC/2in1或Tablet设备作为发送端触发碰一碰事件时的相关信息,如轻碰屏幕位置的坐标信息等。 |
示例:
import { harmonyShare } from '@kit.ShareKit';
// 注册设备轻贴'knockShare'监听事件
harmonyShare.on('knockShare', (sharableTarget: harmonyShare.SharableTarget) => {
// 获取轻碰时的坐标信息
let sharableTargetInfo = sharableTarget.getInfo();
console.info('screenX is:', sharableTargetInfo.coordinate?.screenX);
console.info('screenY is:', sharableTargetInfo.coordinate?.screenY);
}); 沙箱接收事件触发后回调参数,可通过此参数进行沙箱接收。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.Collaboration.HarmonyShare
起始版本: 6.0.0(20)
receive(receiveUri: string, callback: ReceiveCallback): Promise<void>
提供沙箱接收目录uri,接收的文件将保存至此目录下,使用Promise异步回调。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.Collaboration.HarmonyShare
起始版本: 6.0.0(20)
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| receiveUri | string | 是 | 沙箱接收时,存放数据的目录(必须真实存在)。 说明: Share Kit会在传输开始前获取此目录的授权,在数据传输完成后自动撤销授权,建议使用已存在的空文件夹,保护信息安全。 |
| callback | ReceiveCallback | 是 | 沙箱接收的回调。 |
返回值:
| 类型 | 说明 |
|---|---|
| Promise<void> | Promise对象。无返回结果的Promise对象。 |
示例:
import { uniformTypeDescriptor as utd } from '@kit.ArkData';
import { systemShare, harmonyShare } from '@kit.ShareKit';
import { common } from '@kit.AbilityKit';
let capabilityRegistry: harmonyShare.RecvCapabilityRegistry = {
windowId: 999, // 此值仅为示例 实际使用时请替换正确的windowId
capabilities: [{
utd: utd.UniformDataType.IMAGE,
maxSupportedCount: 1
}]
}
// 注册沙箱接收'dataReceive'监听事件
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) {
// To do things.
}
}
});
}); reject(error: ReceivableErrorCode): Promise<void>
当开发者收到回调时,由于某些原因无法继续接收分享内容时,可选择拒绝本次接收,使用Promise异步回调。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.Collaboration.HarmonyShare
起始版本: 6.0.0(20)
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| error | ReceivableErrorCode | 是 | 拒绝本次沙箱接收的原因。通过系统弹窗提示用户。 |
返回值:
| 类型 | 说明 |
|---|---|
| Promise<void> | Promise对象。无返回结果的Promise对象。 |
示例:
import { uniformTypeDescriptor as utd } from '@kit.ArkData';
import { harmonyShare } from '@kit.ShareKit';
let capabilityRegistry: harmonyShare.RecvCapabilityRegistry = {
windowId: 999, // 此值仅为示例 实际使用时请替换正确的windowId
capabilities: [{
utd: utd.UniformDataType.IMAGE,
maxSupportedCount: 1
}]
}
// 注册沙箱接收'dataReceive'监听事件
harmonyShare.on('dataReceive', capabilityRegistry, (receivableTarget: harmonyShare.ReceivableTarget) => {
receivableTarget.reject(harmonyShare.ReceivableErrorCode.NO_RECEIVABLE_ERROR);
}); getInfo(): ReceivableTargetInfo
获取PC/2in1或Tablet设备作为接收端触发碰一碰事件时的相关信息。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.Collaboration.HarmonyShare
起始版本: 26.0.0
返回值:
| 类型 | 说明 |
|---|---|
| ReceivableTargetInfo | PC/2in1或Tablet设备作为接收端触发碰一碰事件时的相关信息,如轻碰屏幕位置的坐标信息等。 |
示例:
import { uniformTypeDescriptor as utd } from '@kit.ArkData';
import { systemShare, harmonyShare } from '@kit.ShareKit';
import { common } from '@kit.AbilityKit';
import { fileUri } from '@kit.CoreFileKit';
let capabilityRegistry: harmonyShare.RecvCapabilityRegistry = {
windowId: 999, // 此值仅为示例 实际使用时请替换正确的windowId
capabilities: [{
utd: utd.UniformDataType.IMAGE,
maxSupportedCount: 1
}]
}
// 注册沙箱接收'dataReceive'监听事件
harmonyShare.on('dataReceive', capabilityRegistry, (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();
console.info('screenX is:', receivableTargetInfo.coordinate?.screenX);
console.info('screenY is:', receivableTargetInfo.coordinate?.screenY);
receivableTarget.receive(sandboxUri, {
onDataReceived: (sharedData: systemShare.SharedData) => {
let sharedRecords = sharedData.getRecords();
sharedRecords.forEach((record: systemShare.SharedRecord) => {
// 处理分享数据
});
},
onResult(resultCode: harmonyShare.ShareResultCode) {
if (resultCode === harmonyShare.ShareResultCode.SHARE_SUCCESS) {
// To do things.
}
}
});
}); 华为分享事件发送的数据信息。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.Collaboration.HarmonyShare
起始版本: 6.0.0(20)
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| thumbnailUri | string | 否 | 是 | 预览图的uri。 |
华为分享事件注册基础配置。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.Collaboration.HarmonyShare
起始版本: 6.0.0(20)
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| windowId | number | 否 | 否 | 窗口id。 |
华为分享事件窗口注册配置项。继承BaseCapabilityRegistry。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.Collaboration.HarmonyShare
起始版本: 6.0.0(20)
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| sendOnly | boolean | 否 | 是 | 设置是否仅支持发送数据。默认值:false,表示可同时接收分享数据。当双端设备均设置为true时,双向分享会被拦截。 说明:仅支持碰一碰分享功能。 |
设置沙箱接收支持的能力范围(可接收的文件类型及最大数量限制)。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.Collaboration.HarmonyShare
起始版本: 6.0.0(20)
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| utd | string | 否 | 否 | 统一数据类型,参考@ohos.data.uniformTypeDescriptor (标准化数据定义与描述)。 |
| maxSupportedCount | number | 否 | 否 | 可接收文件的最大数量限制,仅允许设置大于0的整数。 |
沙箱接收事件窗口注册配置项。继承BaseCapabilityRegistry。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.Collaboration.HarmonyShare
起始版本: 6.0.0(20)
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| capabilities | RecvCapability[] | 否 | 否 | 沙箱接收能力设置,用于设置可接收的数据类型和数量。 |
沙箱接收时,文件数据传输完成的回调函数。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.Collaboration.HarmonyShare
起始版本: 6.0.0(20)
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| onResult | Callback<ShareResultCode> | 否 | 是 | 传输完成的回调函数。用于通知传输结果。 |
沙箱接收传输完成后回调函数。可用此方法监听完成事件,并处理接收后的数据。继承TransferBaseResults。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.Collaboration.HarmonyShare
起始版本: 6.0.0(20)
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| onDataReceived | Callback<systemShare.SharedData> | 否 | 否 | 沙箱接收传输完成后回调函数。用于接收已保存至沙箱路径下的文件列表。 |
提示信息,用于告知用户无法分享的原因。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.Collaboration.HarmonyShare
起始版本: 6.0.2(22)
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| message | string | 否 | 是 | 提示文案。 |
手机与PC/2in1或Tablet设备碰一碰触发时,轻碰屏幕位置的坐标信息。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.Collaboration.HarmonyShare
起始版本: 26.0.0
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| screenX | number | 否 | 否 | 碰一碰事件触发时,以屏幕左上角为原点的相对坐标系的X坐标。当前仅支持整数。单位:px。 |
| screenY | number | 否 | 否 | 碰一碰事件触发时,以屏幕左上角为原点的相对坐标系的Y坐标。当前仅支持整数。单位:px。 |
PC/2in1或Tablet设备作为发送端,触发碰一碰时的相关信息。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.Collaboration.HarmonyShare
起始版本: 26.0.0
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| coordinate | CoordinateInfo | 否 | 是 | 碰一碰事件触发时,轻碰屏幕位置的坐标信息。 |
PC/2in1或Tablet设备作为接收端,触发碰一碰时的相关信息。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.Collaboration.HarmonyShare
起始版本: 26.0.0
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| coordinate | CoordinateInfo | 否 | 是 | 碰一碰事件触发时,轻碰屏幕位置的坐标信息。 |
on(event: 'dataReceive', capability: RecvCapabilityRegistry, callback: Callback<ReceivableTarget>): void
注册沙箱接收事件监听。仅支持文件类型数据。文本(包含链接)类型的数据保持原有接收逻辑。使用callback异步回调。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.Collaboration.HarmonyShare
设备行为差异: 对于6.0.2(22)及之前的版本,该接口在PC/2in1中可正常调用,在其他设备类型中返回801错误码。从6.1.0(23)开始,该接口在PC/2in1、Tablet中均可正常使用,在其他设备类型中无响应。
起始版本: 6.0.0(20)
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| event | string | 是 | 事件回调类型,取值为'dataReceive',当手机设备轻贴PC/2in1、Tablet设备屏幕时,触发该事件。 |
| capability | RecvCapabilityRegistry | 是 | 事件属性。 |
| callback | Callback<ReceivableTarget> | 是 | 回调函数。返回分享接收对象,用于完成分享内容接收。 |
示例:
private dataReceiveCallback = (receivableTarget: harmonyShare.ReceivableTarget) => {
let uiContext: UIContext = this.getUIContext();
let context = uiContext.getHostContext() as common.UIAbilityContext;
let sandboxUri = fileUri.getUriFromPath(context.filesDir);
receivableTarget.receive(sandboxUri, {
onDataReceived: (sharedData: systemShare.SharedData) => {
let sharedRecords = sharedData.getRecords();
sharedRecords.forEach((record: systemShare.SharedRecord) => {
this.dataReceiveUri = record.uri;
});
},
onResult: (resultCode: harmonyShare.ShareResultCode) => {
if (resultCode === harmonyShare.ShareResultCode.SHARE_SUCCESS) {
try {
const uiContext: UIContext = this.getUIContext();
uiContext.getPromptAction().showToast({ message: $r('app.string.success_supported') });
} catch (error) {
hilog.error(DOMAIN, 'testTag', `showToast error. Code: ${error?.code}, message: ${error?.message}`);
}
}
}
});
}
private isNoListening() {
return !this.dataReceiveStatus;
}
private dataReceiveListening() {
if (this.isNoListening()) {
if (this.windowId) {
let capabilityRegistry: harmonyShare.RecvCapabilityRegistry = {
windowId: this.windowId,
capabilities: [{
utd: utd.UniformDataType.IMAGE,
maxSupportedCount: 1,
}]
}
harmonyShare.on('dataReceive', capabilityRegistry, this.dataReceiveCallback);
this.dataReceiveStatus = true;
}
} else {
try {
const uiContext: UIContext = this.getUIContext();
uiContext.getPromptAction().showToast({ message: $r('app.string.knock_close_other') });
} catch (error) {
hilog.error(DOMAIN, 'testTag', `showToast error. Code: ${error?.code}, message: ${error?.message}`);
}
}
} off(event: 'dataReceive', capability: RecvCapabilityRegistry, callback?: Callback<ReceivableTarget>): void
取消沙箱接收的事件监听。使用callback异步回调。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.Collaboration.HarmonyShare
设备行为差异: 对于6.0.2(22)及之前的版本,该接口在PC/2in1中可正常调用,在其他设备类型中返回801错误码。从6.1.0(23)开始,该接口在PC/2in1、Tablet中均可正常使用,在其他设备类型中无响应。
起始版本: 6.0.0(20)
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| event | string | 是 | 事件回调类型,取值为'dataReceive',取消沙箱接收的事件监听。 |
| capability | RecvCapabilityRegistry | 是 | 事件属性。 |
| callback | Callback<ReceivableTarget> | 否 | 回调函数。可以指定传入on中的callback取消对应的监听,也可以不指定callback清空所有监听。 |
示例:
private dataReceiveDisablingListening() {
try {
if (this.windowId) {
let capabilityRegistry: harmonyShare.RecvCapabilityRegistry = {
windowId: this.windowId,
capabilities: [{
utd: utd.UniformDataType.IMAGE,
maxSupportedCount: 1,
}]
}
harmonyShare.off('dataReceive', capabilityRegistry, this.dataReceiveCallback);
this.dataReceiveStatus = false;
}
} catch (error) {
hilog.error(DOMAIN, 'testTag', 'error message: %s', error?.message ?? 'unknown error');
}
}