鸿蒙学习实战之路-Share Kit系列(2/17)-宿主应用发起分享全攻略

最近好多朋友问我：“西兰花啊，我想在应用里加个分享按钮，让用户能把内容分享出去，但不知道代码怎么写？” 害，这问题可问对人了！

今天这篇，我就手把手带你实现宿主应用发起分享功能，从零到一，全程不超过 10 分钟（不含调试时间）～

---

宿主应用是啥？

宿主应用就是分享行为的发起者。简单说，就是你的应用里有个"分享"按钮，用户点了之后，你的应用就作为宿主应用，调用系统分享面板，让用户选择分享到哪里。

这就像前端的分享 SDK 调用，只不过 Share Kit 是系统级别的服务，体验更统一。

---

核心接口介绍

在开始写代码之前，先搞清楚两个核心接口：

SharedData - 分享数据描述

SharedData 用于描述要分享的内容，包括类型、URI、标题、预览图、描述等信息。

参数	类型	说明
utd	string	分享数据的类型（遵循 UTD 规范）
uri	string	分享数据的 URI（需为合法的 URI 格式）
title	string	分享数据的标题（在分享面板中显示）
preview	string	分享数据的预览图 URI（在分享面板中显示）
description	string	分享数据的描述信息（在分享面板中显示）

ShareController - 分享控制器

ShareController 用于控制分享面板的显示和隐藏。

方法	说明
show(context, options)	显示分享面板
hide()	隐藏分享面板
on(‘shareCompleted’, callback)	注册分享完成事件监听
off(‘shareCompleted’, callback)	取消分享完成事件监听

---

完整实现步骤

实现宿主应用发起分享，就四步：

步骤 1：构造分享数据

先创建一个 SharedData 对象，描述要分享的内容。

import { systemShare } from "@kit.ShareKit";

// 构造ShareData，需配置一条有效数据信息
let shareData: systemShare.SharedData = new systemShare.SharedData({
  utd: "general.text",
  uri: "file://.../xxx.txt",
  title: "分享文本",
  preview: "file://.../preview.jpg",
  description: "这是一段分享文本",
});

参数说明：

• utd：分享数据的类型，general.text 表示文本类型
• uri：分享数据的 URI，这里是一个文本文件的路径
• title：分享数据的标题，会在分享面板中显示
• preview：预览图的 URI，会在分享面板中显示
• description：分享数据的描述信息，会在分享面板中显示

🥦 西兰花小贴士：
utd 类型需要遵循 UDMF（统一数据管理框架）定义的 UTD（统一类型描述符）规范。常见的类型有：

• general.text：文本
• general.image：图片
• general.video：视频
• general.link：链接

---

步骤 2：构建分享控制器

用 SharedData 创建一个 ShareController 对象。

import { systemShare } from "@kit.ShareKit";

// 构建ShareController
let controller: systemShare.ShareController = new systemShare.ShareController(
  shareData,
);

这个 controller 就像分享面板的"遥控器"，可以控制分享面板的显示、隐藏，还能监听分享完成事件。

---

步骤 3：显示分享面板

调用 ShareController 的 show 方法，显示分享面板。

import { common } from "@kit.AbilityKit";
import { systemShare } from "@kit.ShareKit";

// 获取UIAbility上下文对象
let uiContext: UIContext = this.getUIContext();
let context: common.UIAbilityContext =
  uiContext.getHostContext() as common.UIAbilityContext;

// 进行分享面板显示
controller.show(context, {
  previewMode: systemShare.SharePreviewMode.DEFAULT,
  selectionMode: systemShare.SelectionMode.SINGLE,
});

参数说明：

• context：UIAbility 上下文对象，用于显示分享面板
• previewMode：预览模式，DEFAULT 表示默认预览模式
• selectionMode：选择模式，SINGLE 表示单选模式

🥦 西兰花警告：
我有个朋友第一次写分享功能，忘记获取 UIAbility 上下文对象，结果分享面板一直弹不出来，debug 了两小时！血泪教训啊朋友们！

---

步骤 4：监听分享完成事件（可选）

如果你想监听分享完成事件，可以注册一个回调。

import { systemShare } from "@kit.ShareKit";

// 注册分享完成事件监听
controller.on("shareCompleted", (result: systemShare.ShareResult) => {
  console.log(`分享完成，结果：${result}`);
});

这样当用户完成分享后，你就能知道分享的结果了。

---

完整代码示例

把上面的步骤整合起来，就是一个完整的分享功能实现：

import { common } from "@kit.AbilityKit";
import { systemShare } from "@kit.ShareKit";

// 步骤1：构造分享数据
let shareData: systemShare.SharedData = new systemShare.SharedData({
  utd: "general.text",
  uri: "file://.../xxx.txt",
  title: "分享文本",
  preview: "file://.../preview.jpg",
  description: "这是一段分享文本",
});

// 步骤2：构建分享控制器
let controller: systemShare.ShareController = new systemShare.ShareController(
  shareData,
);

// 步骤3：注册分享完成事件监听（可选）
controller.on("shareCompleted", (result: systemShare.ShareResult) => {
  console.log(`分享完成，结果：${result}`);
});

// 步骤4：显示分享面板
let uiContext: UIContext = this.getUIContext();
let context: common.UIAbilityContext =
  uiContext.getHostContext() as common.UIAbilityContext;

controller.show(context, {
  previewMode: systemShare.SharePreviewMode.DEFAULT,
  selectionMode: systemShare.SelectionMode.SINGLE,
});

---

在实际项目中怎么用？

上面的代码是基础实现，但在实际项目中，你可能会这样用：

示例：在按钮点击事件中触发分享

import { common } from '@kit.AbilityKit';
import { systemShare } from '@kit.ShareKit';

@Entry
@Component
struct SharePage {
  // 分享按钮点击事件
  onShareButtonClick() {
    // 构造分享数据
    let shareData: systemShare.SharedData = new systemShare.SharedData({
      utd: 'general.text',
      uri: 'file://.../xxx.txt',
      title: '分享文本',
      preview: 'file://.../preview.jpg',
      description: '这是一段分享文本'
    });

    // 构建分享控制器
    let controller: systemShare.ShareController = new systemShare.ShareController(shareData);

    // 注册分享完成事件监听
    controller.on('shareCompleted', (result: systemShare.ShareResult) => {
      console.log(`分享完成，结果：${result}`);
    });

    // 显示分享面板
    let uiContext: UIContext = this.getUIContext();
    let context: common.UIAbilityContext = uiContext.getHostContext() as common.UIAbilityContext;

    controller.show(context, {
      previewMode: systemShare.SharePreviewMode.DEFAULT,
      selectionMode: systemShare.SelectionMode.SINGLE
    });
  }

  build() {
    Column() {
      Text('分享示例')
        .fontSize(20)
        .fontWeight(FontWeight.Bold)
        .margin(20)
        .fontColor(Color.Black);

      Button('分享')
        .onClick(() => {
          this.onShareButtonClick();
        })
        .margin(20);
    }
    .width('100%')
    .height('100%');
  }
}

---

常见问题

Q1：分享面板弹不出来怎么办？

检查以下几点：

1. 是否正确获取了 UIAbility 上下文对象：

   let uiContext: UIContext = this.getUIContext();
   let context: common.UIAbilityContext =
     uiContext.getHostContext() as common.UIAbilityContext;
   

2. 分享数据是否有效：

   • uri 是否为合法的 URI 格式
   • utd 类型是否正确

3. 是否有权限：

   • 检查是否申请了必要的权限

Q2：如何分享不同类型的内容？

不同的内容类型，只需要修改 SharedData 的参数即可：

• 文本：utd: 'general.text'
• 图片：utd: 'general.image'
• 视频：utd: 'general.video'
• 链接：utd: 'general.link'

具体实现我会在后面的文章中详细讲解。

Q3：如何隐藏分享面板？

调用 ShareController 的 hide 方法：

controller.hide();

---

下一步学什么？

看完这篇，你应该已经能实现基本的分享功能了。接下来可以深入学习：

1. 分享不同类型的内容：文本、图片、视频、链接的具体实现
2. 自定义分享面板：屏蔽系统操作、自定义操作区
3. 获取分享结果：监听分享完成事件，处理分享结果
4. 高级功能：共享联系人到推荐区、配置目标应用名单

---

推荐资料

📚 官方文档：

• 通过分享面板发起分享
• Share Kit API 参考
• Share Kit SampleCode

---

我是盐焗西兰花，
不教理论，只给你能跑的代码和避坑指南。
下期见！🥦