文档管理中心

systemShare(分享)

Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+TV5.1.1(19)+

本模块提供分享数据创建及分享面板拉起的功能,提供多种系统标准分享服务,例如分享数据给其他应用、复制、打印等。

  • 分享接入应用需要配置、呈现和关闭分享面板。

  • 分享面板的配置包括数据对象、呈现视图的方式、预览模式等。

模型约束: 此模块的接口仅可在Stage模型下使用。

起始版本: 4.1.0(11)

导入模块

收起
自动换行
深色代码主题
复制
  1. import { systemShare } from '@kit.ShareKit';

SharedRecord

Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+TV5.1.1(19)+

用于构造一条分享数据记录。包含数据类型、数据内容及描述等信息。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.Collaboration.SystemShare

起始版本: 4.1.0(11)

展开
名称 类型 只读 可选 说明
utd string 否 否

统一数据类型,参考@ohos.data.uniformTypeDescriptor (标准化数据定义与描述)

建议开发者传入精准的数据类型,有助于匹配到精确的目标应用,参见:Share Kit体验规范 。

title string 否 是 如果是文本、链接等内容,建议填入title标识其标题。缺省时,若分享内容为文本类型,则文本内容作为title字段;若分享内容为文件类型,则文件名作为title字段。
label string 否 是 标识当前数据记录类型的标签,在单选模式时生效。缺省为UniformDataType类型相应的标签。具体如下:HYPERLINK显示为链接;HTML显示为网页;TEXT显示为文本;VIDEO显示为视频;AUDIO显示为音乐;IMAGE显示为图片;FILE显示为文件。
description string 否 是 数据记录的描述。缺省为空字符串。
thumbnail Uint8Array 否 是

数据记录缩略图。缺省时使用与分享内容类型匹配的图标作为缩略图。

建议开发者传入符合数据记录的缩略图,如无,可传入应用图标。

说明: 限制图片大小:32KB以下。过大的图片可能导致want数据超限无法拉起分享,可使用ImagePacker.packToData压缩图片质量。

thumbnailUri string 否 是

数据记录缩略图的uri。缺省时使用与分享内容类型匹配的图标作为缩略图。支持的uri类型:

应用文件URI,参见:应用文件分享

用户文件URI,参见:用户文件URI介绍

起始版本: 5.0.0(12)。

说明: 与thumbnail字段同时存在时,优先使用thumbnail字段。

uri string 否 是

数据记录的uri。支持的uri类型:

应用文件URI,参见:应用文件分享

用户文件URI,参见:用户文件URI介绍

说明: 沙箱路径可通过fileUri.getUriFromPath方法获取文件URI。content和uri二者至少有一个不为空,否则会导致分享失败。

content string 否 是

数据记录内容。链接(包含App Linking)、文本类型的内容通过该字段传递。

说明: content和uri二者至少有一个不为空,否则会导致分享失败。

extraData Record<string, string | number | boolean | Array<string | number | boolean>> 否 是 扩展数据,用于向目标应用/设备分享自定义的扩展内容。
revisitShareRecordData RevisitShareRecordData 否 是

通过该字段生成二维码复访分享图。支持类型见RevisitShareRecordType。

起始版本: 6.1.0(23)。

ShareControllerOptions

Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+TV5.1.1(19)+

分享控制器配置项。用于配置分享预览模式,选择模式等,决定了分享面板的显示样式。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.Collaboration.SystemShare

需要权限: 如需使用appLaunchTrustInfo字段时,需申请权限ohos.permission.SET_SYSTEMSHARE_APPLAUNCHTRUSTLIST,该能力受限开放,仅支持企业应用限制内部数据分享到企业集团信任的应用。权限申请方式请参考申请使用受限权限。

起始版本: 4.1.0(11)

展开
名称 类型 只读 可选 说明
anchor ShareControllerAnchor | string 否 是

类型为string时,表示分享面板关联的控件ID(ArkUI组件常规属性的id值)。

类型为ShareControllerAnchor时,表示锚点位置。

不传此参数时,面板会显示在默认位置(居中)。

previewMode SharePreviewMode 否 是 预览的模式,缺省为卡片模式。
selectionMode SelectionMode 否 是 选择的模式,缺省为单选模式。
excludedAbilities Array<ShareAbilityType> 否 是

操作区不需要显示的能力列表。

起始版本: 5.0.0(12)。

appLaunchTrustInfo Array<string> 否 是

通过配置应用唯一标识符(appIdentifier字段)列表,指定可分享的目标应用名单,系统仅读取前50个配置项,超出部分将不生效。调用此功能需申请ohos.permission.SET_SYSTEMSHARE_APPLAUNCHTRUSTLIST权限。该能力属于受限开放范围,仅限企业应用用于限制内部数据分享至集团信任的应用列表。

起始版本: 6.0.1(21)。

ShareControllerAnchor

Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+TV5.1.1(19)+

分享悬浮窗视图依附锚点,分享面板会根据屏幕大小选择是否在指定的位置显示悬浮窗。

说明

设备屏幕宽度较小时,不会以悬浮形态展示,而是以模态形式/弹窗形式显示。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.Collaboration.SystemShare

起始版本: 4.1.0(11)

展开
名称 类型 只读 可选 说明
windowOffset Offset 否 否 表示共享控制器的窗口偏移量,推荐设置组件左上角顶点的坐标。
size Size 否 是 锚点矩形的尺寸,缺省时,锚点是一个点,即宽高都为0。

Offset

Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+TV5.1.1(19)+

可以设置的相对锚点的窗口偏移值。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.Collaboration.SystemShare

起始版本: 4.1.0(11)

展开
名称 类型 只读 可选 说明
x number 否 否 x点的坐标。单位:像素。
y number 否 否 y点的坐标。单位:像素。

Size

Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+TV5.1.1(19)+

锚点矩形的尺寸,缺省时,锚点是一个点,即宽高都为0。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.Collaboration.SystemShare

起始版本: 4.1.0(11)

展开
名称 类型 只读 可选 说明
width number 否 否 组件宽度,单位:像素。负数按0处理。
height number 否 否 组件高度,单位:像素。负数按0处理。

ShareOperationResult

Phone5.1.0(18)+PC/2in15.1.0(18)+Tablet5.1.0(18)+TV5.1.1(19)+

shareCompleted事件的返回值,用于获知用户分享渠道信息。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.Collaboration.SystemShare

起始版本: 5.1.0(18)

展开
名称 类型 只读 可选 说明
targetAbilityInfo ShareAbilityInfo 否 否 用户分享渠道的信息。

ShareAbilityInfo

Phone5.1.0(18)+PC/2in15.1.0(18)+Tablet5.1.0(18)+TV5.1.1(19)+

用户分享渠道的信息。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.Collaboration.SystemShare

起始版本: 5.1.0(18)

展开
名称 类型 只读 可选 说明
name string 否 否

分享渠道的名称。

- 系统操作有固定名称。请参见:ShareAbilityName枚举值。

- 非系统操作采用'[bundleName]#[moduleName]#[abilityName]'格式拼接。

ContactInfo

Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+TV5.1.1(19)+

意图框架推荐联系人的信息。当分享到推荐联系人时,携带此参数用于区分。

数据捐献参考:共享联系人信息到分享推荐区。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.Collaboration.SystemShare

起始版本: 4.1.0(11)

展开
名称 类型 只读 可选 说明
contactType string 否 否 联系人类型:取值来源应用向意图捐赠数据中的entityName字段,例如"Contact"、"ChatGroup"。
contactId string 否 否 联系人ID:取值来源应用向意图捐赠数据中的entityId字段。

RevisitShareRecordData

Phone6.1.0(23)+PC/2in16.1.0(23)+Tablet6.1.0(23)+TV6.1.0(23)+

复访分享数据。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.Collaboration.SystemShare

起始版本: 6.1.0(23)

参数:

展开
名称 类型 只读 可选 说明
revisitShareRecordType RevisitShareRecordType 否 否 复访分享数据类型。
generatedImageUri string 否 否

生成的分享图uri路径 (应用文件URI),用于写入绘图结果或预览。开发者需要在该路径下创建一个空的图片文件,支持的图片文件类型包括PNG、JPG。

应用文件URI,参见:应用文件分享

说明: 沙箱路径可通过fileUri.getUriFromPath方法获取文件URI。

ReadingExtendedShareRecordData

Phone6.1.0(23)+PC/2in16.1.0(23)+Tablet6.1.0(23)+TV6.1.0(23)+

阅读分享拓展数据记录,ReadingExtendedShareRecordData继承自RevisitShareRecordData。

当utd为utd.UniformDataType.TEXT, 且revisitShareRecordType为RevisitShareRecordType.READING_SHARE条件下生效。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.Collaboration.SystemShare

起始版本: 6.1.0(23)

参数:

展开
名称 类型 只读 可选 说明
sourceTitle string 否 否

来源标题(原文章/书名),用于生成共享镜像的标题。

长度限制:

当readingShareStyle为STYLE_HIGHLIGHT_CONTENT时,最大显示行数为2行。默认字号为16vp,超出部分显示省略号(...)

当readingShareStyle为STYLE_HIGHLIGHT_TITLE时,最大显示行数为2行。默认字号为24vp,若空间不足,则按阶梯逐级缩小至18vp。若在18vp字号下仍无法完全显示,则对末尾超出部分进行省略号(...)。

appLink string 否 否

文章appLink(https链接格式)。

当ReadingExtendedData不为空时,此值必填。

长度限制:appLink与appLinkExtraInfo拼接后的总长度不得超过512个字符。

readingShareStyle ReadingShareRecordStyle 否 是 阅读分享模版数据类型, 默认STYLE_HIGHLIGHT_CONTENT。
subtitle string 否 是

副标题(如:书籍章节信息、段落信息)。readingShareStyle为STYLE_HIGHLIGHT_TITLE生效。

长度限制:单行显示,超出部分显示省略号(...)。

appLinkExtraInfo string 否 是

appLink补充信息,拼接到appLink后参与二维码生成。

web文本选中分享场景,建议携带textFragement信息(#:~:text=[prefix-,]textStart[,textEnd][,-suffix]),以便支持高亮突出显示;

其他场景,应用可携带自定义参数,用于应用直达后的内部逻辑处理。

coverImageUri string 否 是

封面图uri路径(应用文件URI)(如:书籍封面图路径)。readingShareStyle为STYLE_HIGHLIGHT_TITLE生效。

应用文件URI,参见:应用文件分享。

prefixText string 否 是

所选文本的前缀文本。

长度限制:最大显示行数为1行,超出时使用前置省略。

suffixText string 否 是

所选文本的后缀文本。

长度限制:最大显示行数为2行,超出时使用后置省略。

author string 否 是

文章作者的姓名,用于生成作者分享的图片中显示的信息。

长度限制:最大显示行数为1行,超出部分显示省略号(...)。

publishDate Date 否 是 文章发表日期。readingShareStyle为STYLE_HIGHLIGHT_CONTENT生效。
sharerName string 否 是

分享者名字。

长度限制:最大显示行数为1行,超出部分显示省略号(...)。

appSlogan string 否 是

应用的口号。

长度限制:最大显示行数为1行。超出部分显示省略号(...)。

SharePreviewMode

Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+TV5.1.1(19)+

分享预览模式。图片、视频等格式推荐使用详细预览图模式。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.Collaboration.SystemShare

起始版本: 4.1.0(11)

展开
名称 值 说明
DEFAULT 0 默认模式(缩略图卡片)。推荐文本、链接等数据使用此模式。
DETAIL 1 详细预览图模式。推荐图片、视频等数据使用此模式。

SelectionMode

Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+TV5.1.1(19)+

分享面板选择模式。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.Collaboration.SystemShare

起始版本: 4.1.0(11)

展开
名称 值 说明
SINGLE 0 单选模式,当传入多条分享数据记录(SharedRecord)时,需要用户多选一进行分享。
BATCH 1 批量模式,分享全部数据记录。

ShareAbilityType

Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+TV5.1.1(19)+

系统能力类型定义。用于排除操作区的系统能力。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.Collaboration.SystemShare

起始版本: 5.0.0(12)

展开
名称 值 说明
COPY_TO_PASTEBOARD 0 复制
SAVE_TO_MEDIA_ASSET 1 保存至图库
SAVE_AS_FILE 2 另存为
PRINT 3 打印
SAVE_TO_SUPERHUB 4 添加至中转站

ShareAbilityResultCode

Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+TV5.1.1(19)+

从UIExtensionAbility返回的Code值。可控制分享面板的行为。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.Collaboration.SystemShare

起始版本: 5.0.0(12)

展开
名称 值 说明
ERROR -1 发生错误。如果同时传递message参数,将弹出toast提示。
BACK 0 用户点击返回按钮。返回分享面板。
CLOSE 1 用户点击关闭按钮。关闭分享面板。

ShareAbilityName

Phone5.1.0(18)+PC/2in15.1.0(18)+Tablet5.1.0(18)+TV5.1.1(19)+

系统操作的名称,用于返回分享结果数据。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.Collaboration.SystemShare

起始版本: 5.1.0(18)

展开
名称 值 说明
COPY_TO_PASTEBOARD 'SystemShare_CopyToPasteboard' 复制
SAVE_TO_MEDIA_ASSET 'SystemShare_SaveToMediaAsset' 保存至图库
SAVE_AS_FILE 'SystemShare_SaveAsFile' 另存为
PRINT 'SystemShare_Print' 打印
SAVE_TO_SUPERHUB 'SystemShare_Superhub' 添加至中转站
COLLECTION 'SystemShare_Collection' 小艺知识空间
HARMONYSHARE 'SystemShare_HarmonyShare' 华为分享
ENCRYPT 'SystemShare_Encrypt' 加密分享

RevisitShareRecordType

Phone6.1.0(23)+PC/2in16.1.0(23)+Tablet6.1.0(23)+TV6.1.0(23)+

定义复访分享的类型。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.Collaboration.SystemShare

起始版本: 6.1.0(23)

展开
名称 值 说明
READING_SHARE 1 阅读分享数据类型。

ReadingShareRecordStyle

Phone6.1.0(23)+PC/2in16.1.0(23)+Tablet6.1.0(23)+TV6.1.0(23)+

阅读分享场景显示模版类型。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.Collaboration.SystemShare

起始版本: 6.1.0(23)

展开
名称 值 说明
STYLE_HIGHLIGHT_CONTENT 0 选定文本高亮显示,默认。
STYLE_HIGHLIGHT_TITLE 1 标题突出显示。

SharedData

Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+TV5.1.1(19)+

表示分享数据对象,提供封装一组数据记录的方法。

一个分享数据对象至少存在一条记录,开发者需要在SharedData实例化过程中,通过构造器第一个参数传入;当分享数据包含多条数据记录时,则需要使用addRecord(record: SharedRecord)方法追加记录。

说明

数据记录当前最大可支持500条,且需同时满足数据总大小不超过IPC传输上限200KB。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.Collaboration.SystemShare

起始版本: 4.1.0(11)

constructor

Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+TV5.1.1(19)+

constructor(record: SharedRecord)

用于构造分享数据对象。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.Collaboration.SystemShare

起始版本: 4.1.0(11)

参数:

展开
参数名 类型 必填 说明
record SharedRecord 是 分享数据记录对象。

错误码:

以下错误码的详细介绍请参见通用错误码。

展开
错误码ID 错误信息
401 Parameter error.

示例:

收起
自动换行
深色代码主题
复制
  1. let data: systemShare.SharedData = new systemShare.SharedData({
  2. utd: utd.UniformDataType.PLAIN_TEXT,
  3. content: 'Hello HarmonyOS'
  4. });

addRecord

Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+TV5.1.1(19)+

addRecord(record: SharedRecord): void

在当前分享数据中添加一条分享数据记录。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.Collaboration.SystemShare

起始版本: 4.1.0(11)

参数:

展开
参数名 类型 必填 说明
record SharedRecord 是 要添加到分享数据对象中的数据记录,该记录为SharedRecord对象。

错误码:

以下错误码的详细介绍请参见通用错误码和分享服务错误码。

展开
错误码ID 错误信息
401 Parameter error.
1003700001 The number of records exceeds the maximum.

示例:

收起
自动换行
深色代码主题
复制
  1. let shareData: systemShare.SharedData = new systemShare.SharedData({
  2. utd: utd.UniformDataType.IMAGE,
  3. // ...
  4. title: 'Picture Title',
  5. description: 'Picture Description',
  6. label: 'Poster'
  7. });
  8. try {
  9. shareData.addRecord({
  10. utd: utd.UniformDataType.HYPERLINK,
  11. content: 'https://www.vmall.com/index.html?cid=128688',
  12. title: 'Huawei Vmall',
  13. description: 'Phone',
  14. label: 'Huawei Vmall',
  15. // ...
  16. });
  17. } catch (error) {
  18. hilog.error(DOMAIN, 'testTag', `addRecord error. Code: ${error?.code}, message: ${error?.message}`);
  19. }

getRecords

Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+TV5.1.1(19)+

getRecords(): Array<SharedRecord>

获取当前分享数据中的所有数据记录。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.Collaboration.SystemShare

起始版本: 4.1.0(11)

返回值:

展开
类型 说明
Array<SharedRecord> 当前分享数据对象内所包含的记录。

示例:

收起
自动换行
深色代码主题
复制
  1. aboutToAppear(): void {
  2. systemShare.getSharedData(this.want).then((data: systemShare.SharedData) => {
  3. let records: systemShare.SharedRecord[] = data.getRecords();
  4. records.forEach(async (record: systemShare.SharedRecord) => {
  5. // ...
  6. });
  7. }).catch((error: BusinessError) => {
  8. hilog.error(DOMAIN, 'testTag', `getSharedData error. Code: ${error?.code}, message: ${error?.message}`);
  9. });
  10. }

ShareController

Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+TV5.1.1(19)+

分享面板在不同设备下有不同的展示形式,根据屏幕规格&参数为应用提供不同的预览形式以及分享方式。

  • 例如手机和TV设备中,分享以模态显示;横屏/折叠屏展开状态时,分享面板以对话框形式显示;

  • 而PC/2in1设备及Tablet,需要传入锚点信息并且以悬浮窗(Popup)形式显示。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.Collaboration.SystemShare

起始版本: 4.1.0(11)

constructor

Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+TV5.1.1(19)+

constructor(data: SharedData)

用于创建分享面板的控制器。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.Collaboration.SystemShare

起始版本: 4.1.0(11)

参数:

展开
参数名 类型 必填 说明
data SharedData 是 分享数据。

错误码:

以下错误码的详细介绍请参见通用错误码。

展开
错误码ID 错误信息
401 Parameter error.

示例:

收起
自动换行
深色代码主题
复制
  1. let shareData: systemShare.SharedData = new systemShare.SharedData({
  2. utd: utd.UniformDataType.HYPERLINK,
  3. content: 'https://www.vmall.com/index.html?cid=128688',
  4. title: 'Huawei Vmall',
  5. description: 'Phone',
  6. });
  7. let controller: systemShare.ShareController = new systemShare.ShareController(shareData);

show

Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+TV5.1.1(19)+

show(context: common.UIAbilityContext, options: ShareControllerOptions): Promise<void>

显示分享面板,使用Promise异步回调。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.Collaboration.SystemShare

起始版本: 4.1.0(11)

参数:

展开
参数名 类型 必填 说明
context

common.UIAbilityContext

是 拉起分享面板的上下文对象。
options ShareControllerOptions 是 分享控制器配置项。

返回值:

展开
类型 说明
Promise<void> Promise对象。无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见通用错误码和分享服务错误码。

展开
错误码ID 错误信息
401 Parameter error.
1003702001 Record types are not support. (The batch and multiple selection modes support { @link UDMF.File } type records only.)
1003702002 IPC data is oversized.

示例:

收起
自动换行
深色代码主题
复制
  1. @Component
  2. export default struct LinkScenario {
  3. private async share() {
  4. let shareData: systemShare.SharedData = new systemShare.SharedData({
  5. utd: utd.UniformDataType.HYPERLINK,
  6. content: 'https://www.vmall.com/index.html?cid=128688',
  7. title: 'Huawei Vmall',
  8. description: 'Phone',
  9. });
  10. let controller: systemShare.ShareController = new systemShare.ShareController(shareData);
  11. const uiContext: UIContext = this.getUIContext();
  12. const context: common.UIAbilityContext = uiContext.getHostContext() as common.UIAbilityContext;
  13. controller.show(context, {
  14. selectionMode: systemShare.SelectionMode.SINGLE,
  15. previewMode: systemShare.SharePreviewMode.DEFAULT,
  16. }).then(() => {
  17. hilog.info(DOMAIN, 'testTag', 'ShareController show success.');
  18. }).catch((error: BusinessError) => {
  19. hilog.error(DOMAIN, 'testTag', `ShareController show error. code: ${error?.code}, message: ${error?.message}`);
  20. });
  21. }
  22. // ...
  23. }

on('dismiss')

Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+TV5.1.1(19)+

on(event: 'dismiss', callback: () => void): void

注册分享面板关闭事件监听。使用callback异步回调。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.Collaboration.SystemShare

起始版本: 4.1.0(11)

参数:

展开
参数名 类型 必填 说明
event string 是 事件回调类型,支持的事件为'dismiss',当分享面板关闭时,触发该事件。
callback () => void 是 事件回调。

错误码:

以下错误码的详细介绍请参见通用错误码。

展开
错误码ID 错误信息
401 Parameter error.

示例:

收起
自动换行
深色代码主题
复制
  1. private async handelShareDismiss(): Promise<void> {
  2. const uiContext: UIContext = this.getUIContext();
  3. let shareData: systemShare.SharedData = new systemShare.SharedData({
  4. utd: utd.UniformDataType.PLAIN_TEXT,
  5. content: 'Hello HarmonyOS',
  6. });
  7. let controller: systemShare.ShareController = new systemShare.ShareController(shareData);
  8. const context: common.UIAbilityContext = uiContext.getHostContext() as common.UIAbilityContext;
  9. const callback = () => {
  10. try {
  11. hilog.info(DOMAIN, 'testTag', 'HuaweiShare_ dismiss invoked.');
  12. uiContext.getPromptAction().showToast({ message: 'dismiss' });
  13. } catch (error) {
  14. hilog.error(DOMAIN, 'testTag', `showToast error. Code: ${error?.code}, message: ${error?.message}`);
  15. }
  16. };
  17. controller.on('dismiss', callback);
  18. controller.show(context, {
  19. previewMode: systemShare.SharePreviewMode.DEFAULT,
  20. selectionMode: systemShare.SelectionMode.SINGLE,
  21. }).then(() => {
  22. hilog.info(DOMAIN, 'testTag', 'HuaweiShare_ show');
  23. }).catch((error: BusinessError) => {
  24. hilog.error(DOMAIN, 'testTag', `HuaweiShare_ show error. Code: ${error?.code}, message: ${error?.message}`);
  25. });
  26. }

off('dismiss')

Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+TV5.1.1(19)+

off(event: 'dismiss', callback: () => void): void

取消分享面板关闭事件监听。使用callback异步回调。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.Collaboration.SystemShare

起始版本: 4.1.0(11)

参数:

展开
参数名 类型 必填 说明
event string 是 事件回调类型,支持的事件为'dismiss',取消触发该事件。
callback () => void 是 回调函数。传入on中的callback取消对应的监听。

错误码:

以下错误码的详细介绍请参见通用错误码。

展开
错误码ID 错误信息
401 Parameter error.

示例:

收起
自动换行
深色代码主题
复制
  1. private async handelShareDisableDismiss(): Promise<void> {
  2. const uiContext: UIContext = this.getUIContext();
  3. let shareData: systemShare.SharedData = new systemShare.SharedData({
  4. utd: utd.UniformDataType.PLAIN_TEXT,
  5. content: 'Hello HarmonyOS',
  6. });
  7. let controller: systemShare.ShareController = new systemShare.ShareController(shareData);
  8. const context: common.UIAbilityContext = uiContext.getHostContext() as common.UIAbilityContext;
  9. const callback = () => {
  10. try {
  11. hilog.info(DOMAIN, 'testTag', 'HuaweiShare_ dismiss invoked.');
  12. uiContext.getPromptAction().showToast({ message: 'dismiss' });
  13. } catch (error) {
  14. hilog.error(DOMAIN, 'testTag', `showToast error. Code: ${error?.code}, message: ${error?.message}`);
  15. }
  16. };
  17. controller.on('dismiss', callback);
  18. controller.off('dismiss', callback);
  19. }

on('shareCompleted')

Phone5.1.0(18)+PC/2in15.1.0(18)+Tablet5.1.0(18)+TV5.1.1(19)+

on(type: 'shareCompleted', callback: Callback<ShareOperationResult>): void

注册用户完成分享事件监听。返回用户分享渠道,可用于数据统计等。使用callback异步回调。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.Collaboration.SystemShare

起始版本: 5.1.0(18)

参数:

展开
参数名 类型 必填 说明
type string 是 事件回调类型,支持的事件为'shareCompleted',当用户完成分享时,触发该事件。
callback Callback<ShareOperationResult> 是 事件回调,可通过回调参数获取分享渠道。

错误码:

以下错误码的详细介绍请参见通用错误码。

展开
错误码ID 错误信息
401 Parameter error.

示例:

收起
自动换行
深色代码主题
复制
  1. private async handelShareCompleted(): Promise<void> {
  2. const uiContext: UIContext = this.getUIContext();
  3. const contextFaker: Context = uiContext.getHostContext() as Context;
  4. let filePath = contextFaker.filesDir + '/exampleImage.jpg';
  5. let utdTypeId = utd.getUniformDataTypeByFilenameExtension('.jpg', utd.UniformDataType.IMAGE);
  6. let shareData: systemShare.SharedData = new systemShare.SharedData({
  7. utd: utdTypeId,
  8. uri: fileUri.getUriFromPath(filePath),
  9. title: 'Picture Title',
  10. description: 'Picture Description',
  11. });
  12. let controller: systemShare.ShareController = new systemShare.ShareController(shareData);
  13. const context: common.UIAbilityContext = uiContext.getHostContext() as common.UIAbilityContext;
  14. const callback = (result: systemShare.ShareOperationResult) => {
  15. hilog.info(DOMAIN, 'testTag', `HuaweiShare_ shareCompleted invoked. result: ${result.targetAbilityInfo.name}`);
  16. };
  17. controller.on('shareCompleted', callback);
  18. controller.show(context, {
  19. previewMode: systemShare.SharePreviewMode.DETAIL,
  20. selectionMode: systemShare.SelectionMode.SINGLE,
  21. }).then(() => {
  22. hilog.info(DOMAIN, 'testTag', 'HuaweiShare_ show');
  23. }).catch((error: BusinessError) => {
  24. hilog.error(DOMAIN, 'testTag', `HuaweiShare_ show error. Code: ${error?.code}, message: ${error?.message}`);
  25. });
  26. }

off('shareCompleted')

Phone5.1.0(18)+PC/2in15.1.0(18)+Tablet5.1.0(18)+TV5.1.1(19)+

off(type: 'shareCompleted', callback?: Callback<ShareOperationResult>): void

取消用户完成分享事件监听。使用callback异步回调。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.Collaboration.SystemShare

起始版本: 5.1.0(18)

参数:

展开
参数名 类型 必填 说明
type string 是 事件回调类型,支持的事件为'shareCompleted',取消触发该事件。
callback Callback<ShareOperationResult> 否 回调函数。可以指定传入on中的callback取消对应的监听,也可以不指定callback清空所有监听。

错误码:

以下错误码的详细介绍请参见通用错误码。

展开
错误码ID 错误信息
401 Parameter error.

示例:

收起
自动换行
深色代码主题
复制
  1. private async handelShareDisableCompleted(): Promise<void> {
  2. const uiContext: UIContext = this.getUIContext();
  3. const contextFaker: Context = uiContext.getHostContext() as Context;
  4. let filePath = contextFaker.filesDir + '/exampleImage.jpg';
  5. let utdTypeId = utd.getUniformDataTypeByFilenameExtension('.jpg', utd.UniformDataType.IMAGE);
  6. let shareData: systemShare.SharedData = new systemShare.SharedData({
  7. utd: utdTypeId,
  8. uri: fileUri.getUriFromPath(filePath),
  9. title: 'Picture Title',
  10. description: 'Picture Description',
  11. });
  12. let controller: systemShare.ShareController = new systemShare.ShareController(shareData);
  13. const context: common.UIAbilityContext = uiContext.getHostContext() as common.UIAbilityContext;
  14. const callback = (result: systemShare.ShareOperationResult) => {
  15. hilog.info(DOMAIN, 'testTag', `HuaweiShare_ shareCompleted invoked. result: ${result.targetAbilityInfo.name}`);
  16. };
  17. controller.on('shareCompleted', callback);
  18. controller.off('shareCompleted', callback);
  19. }

getSharedData

Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+TV5.1.1(19)+

getSharedData(want: Want): Promise<SharedData>

通过目标应用获取的want信息,从中解析出分享数据,使用Promise异步回调。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.Collaboration.SystemShare

起始版本: 4.1.0(11)

参数:

展开
参数名 类型 必填 说明
want Want 是 目标应用获取的want信息。

返回值:

展开
类型 说明
Promise<SharedData> Promise对象,返回分享数据。

错误码:

以下错误码的详细介绍请参见通用错误码和分享服务错误码。

展开
错误码ID 错误信息
401 Parameter error.
1003703001 Parse data failed.

示例:

收起
自动换行
深色代码主题
复制
  1. aboutToAppear(): void {
  2. systemShare.getSharedData(this.want).then((data: systemShare.SharedData) => {
  3. let records: systemShare.SharedRecord[] = data.getRecords();
  4. records.forEach(async (record: systemShare.SharedRecord) => {
  5. switch (true) {
  6. case this.belongsToImage(record.utd):
  7. record.uri && (this.imageUri = record.uri);
  8. break;
  9. default:
  10. break;
  11. }
  12. });
  13. }).catch((error: BusinessError) => {
  14. hilog.error(DOMAIN, 'testTag', `getSharedData error. Code: ${error?.code}, message: ${error?.message}`);
  15. });
  16. }

getContactInfo

Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+TV5.1.1(19)+

getContactInfo(want: Want): Promise<ContactInfo>

通过目标应用获取的want信息,从中解析联系人信息,使用Promise异步回调。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.Collaboration.SystemShare

起始版本: 4.1.0(11)

参数:

展开
参数名 类型 必填 说明
want Want 是 目标应用获取的want信息。

返回值:

展开
类型 说明
Promise<ContactInfo> Promise对象,返回联系人信息。

错误码:

以下错误码的详细介绍请参见通用错误码和分享服务错误码。

展开
错误码ID 错误信息
401 Parameter error.
1003703001 Parse data failed.

示例:

收起
自动换行
深色代码主题
复制
  1. aboutToAppear(): void {
  2. systemShare.getContactInfo(this.want).then(async (contact: systemShare.ContactInfo) => {
  3. let data = await systemShare.getSharedData(this.want);
  4. }).catch((error: BusinessError) => {
  5. hilog.error(DOMAIN, 'testTag', `getContactInfo error. Code: ${error?.code}, message: ${error?.message}`);
  6. });
  7. }

getWant

Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+TV5.1.1(19)+

getWant(data: SharedData, options?: ShareControllerOptions): Promise<Want>

基于SharedData和预览模式构造want数据,使用Promise异步回调。

说明

请勿随意修改返回值want数据中的参数,可能会导致未知的错误。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.Collaboration.SystemShare

起始版本: 5.0.0(12)

参数:

展开
参数名 类型 必填 说明
data SharedData 是 分享目标应用的分享数据信息。
options ShareControllerOptions 否 分享控制器配置项。

返回值:

展开
类型 说明
Promise<Want> Promise对象,返回分享目标应用的want信息。

错误码:

以下错误码的详细介绍请参见通用错误码和分享服务错误码。

展开
错误码ID 错误信息
401 Parameter error.
1003703001 Parse data failed.

示例:

不配置预览模式

收起
自动换行
深色代码主题
复制
  1. onSessionCreate(): void {
  2. let data: systemShare.SharedData = new systemShare.SharedData({
  3. utd: utd.UniformDataType.PLAIN_TEXT,
  4. content: 'Hello HarmonyOS'
  5. });
  6. data.addRecord({
  7. utd: utd.UniformDataType.PNG,
  8. uri: 'file://.../test.png'
  9. });
  10. systemShare.getWant(data)
  11. .then((want) => {
  12. })
  13. .catch((error: BusinessError) => {
  14. hilog.error(DOMAIN, 'testTag', `Failed to getWant. Code: ${error?.code}, message: ${error?.message}`);
  15. });
  16. }

配置预览模式

收起
自动换行
深色代码主题
复制
  1. onSessionCreatePreview(): void {
  2. let data: systemShare.SharedData = new systemShare.SharedData({
  3. utd: utd.UniformDataType.PLAIN_TEXT,
  4. content: 'Hello HarmonyOS'
  5. });
  6. data.addRecord({
  7. utd: utd.UniformDataType.PNG,
  8. uri: 'file://.../test.png'
  9. });
  10. let options : systemShare.ShareControllerOptions = {
  11. previewMode: systemShare.SharePreviewMode.DETAIL,
  12. selectionMode: systemShare.SelectionMode.SINGLE
  13. };
  14. systemShare.getWant(data, options)
  15. .then((want) => {
  16. })
  17. .catch((error: BusinessError) => {
  18. hilog.error(DOMAIN, 'testTag', `Failed to getWant. Code: ${error?.code}, message: ${error?.message}`);
  19. });
  20. }