本文献给：

已掌握 Stage 模型基础、理解 UIAbility 生命周期的鸿蒙开发者。Want 是 HarmonyOS 中实现组件间通信与跳转的核心对象，无论是启动 Ability、传递参数还是跨应用调用，都离不开它。本文将深入解析 Want 的结构，重点讲解显式启动与隐式启动的区别、配置方式及应用场景，并通过实战示例帮助你彻底掌握这一关键机制。

你将学到：

1. Want 对象的完整结构及各字段含义
2. 显式 Want 启动：指定 bundleName 和 abilityName
3. 隐式 Want 启动：通过 action、entities、uri 匹配目标 Ability
4. module.json5 中 skills 的配置方法
5. Want 参数的传递与接收
6. startAbilityForResult 获取返回结果
7. 显式与隐式启动的选择策略

---

一、Want 是什么

Want 是 HarmonyOS 中用于描述“意图”的对象，它封装了一次操作的目标信息、需要执行的动-作以及携带的数据。可以将 Want 理解为应用组件之间通信的“信使”，无论是启动 UIAbility、ServiceExtensionAbility，还是发送广播、请求数据，都需要构造合适的 Want。

在 Stage 模型中，Want 由系统提供统一的接口定义，开发者通过填充不同字段来实现多种交互。

1.1 Want 的结构

interface Want {
  deviceId?: string;                        // 目标设备 ID，空字符串表示本机
  bundleName?: string;                      // 目标应用包名
  abilityName?: string;                     // 目标 Ability 名称
  moduleName?: string;                      // 目标模块名称（可选，默认当前模块）
  uri?: string;                             // 统一资源标识符
  type?: string;                            // MIME 类型
  action?: string;                          // 动作（如查看、编辑、发送）
  entities?: string[];                      // 附加类别信息
  flags?: number;                           // 标志位（控制启动行为）
  parameters?: Record<string, Object>;      // 携带的键值对参数
}

各字段并非全部必填，根据启动方式（显式/隐式）的不同，需要配置不同的字段组合。

1.2 Want 的分类

根据是否明确指定目标 Ability，Want 分为两种：

• 显式 Want：直接指定 bundleName 和 abilityName，系统精确启动目标。
• 隐式 Want：不指定具体 Ability，而是通过 action、entities、uri 等描述“想做什么”，由系统匹配符合条件的 Ability。

下面分别详解。

二、显式 Want 启动

显式 Want 是应用内部或已知目标应用的跳转方式，通过 bundleName 和 abilityName 精确定位。

2.1 同应用内启动 Ability

当目标 Ability 和当前 Ability 属于同一个应用（相同 bundleName）时，bundleName 可省略，但建议仍显式写明以保持清晰。

示例：从主页跳转到设置页

import common from '@ohos.app.ability.common';
import Want from '@ohos.app.ability.Want';

// 在 UIAbility 或页面中获取 context
let context = getContext(this) as common.UIAbilityContext;

let want: Want = {
  deviceId: '',
  bundleName: 'com.example.myapp',
  abilityName: 'SettingsAbility',
  parameters: {
    fromPage: 'main',
    userId: 1001
  }
};

context.startAbility(want).then(() => {
  console.log('显式启动成功');
}).catch((err) => {
  console.error('启动失败', JSON.stringify(err));
});

目标 SettingsAbility 接收参数：

export default class SettingsAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
    let from = want.parameters?.fromPage as string;
    let userId = want.parameters?.userId as number;
    console.log(`从 ${from} 跳转，用户 ID：${userId}`);
  }
}

2.2 跨应用显式启动

如果需要启动其他应用的 Ability，同样使用显式 Want，但前提是目标 Ability 在它的 module.json5 中设置了 exported: true，允许外部调用。

let want: Want = {
  deviceId: '',
  bundleName: 'com.other.app',
  abilityName: 'SharedAbility'
};
context.startAbility(want);

注意：跨应用启动需要权限声明，且目标 Ability 必须明确声明 exported: true。

2.3 显式启动的特点

• 精确：直接锁定唯一目标，无歧义。
• 高效：系统无需匹配，直接创建实例。
• 局限性：需要提前知道对方的包名和 Ability 名，不适用于动态发现或通用操作。

三、隐式 Want 启动

隐式 Want 不指定具体的 Ability，而是描述“意图”，由系统根据 skills 匹配最适合的 Ability。这使得应用间解耦，可以调用系统能力或其他应用提供的通用功能，而无需知道它们的内部名称。

3.1 核心匹配字段

隐式匹配主要依赖三个字段：

• action：表示要执行的操作，如查看、编辑、分享等，通常使用系统预定义常量或自定义字符串。
• entities：附加类别信息，进一步限定匹配范围。
• uri 和 type：指定操作的数据资源及其 MIME 类型。

3.2 系统常用 action 示例

action 常量	含义
ohos.want.action.viewData	查看数据（打开文件、网页等）
ohos.want.action.editData	编辑数据
ohos.want.action.sendData	发送数据（分享）
ohos.want.action.dial	拨打电话
ohos.want.action.search	搜索

完整列表可在官方文档中查阅。

3.3 隐式启动示例

假设用户点击一个网页链接，希望由系统浏览器打开：

let want: Want = {
  action: 'ohos.want.action.viewData',
  entities: ['entity.system.browsable'],
  uri: 'https://www.example.com'
};

context.startAbility(want).then(() => {
  console.log('隐式启动成功');
}).catch((err) => {
  console.error('未找到可处理该操作的应用', JSON.stringify(err));
});

系统会遍历所有已安装的应用，查找其 Ability 的 skills 是否声明了 ohos.want.action.viewData 且能处理 https 协议的 URI，然后启动匹配的 Ability（如果多个，可能弹出选择框）。

3.4 配置目标 Ability 的 skills

为了让自己的应用能够被隐式 Want 唤起，需要在 module.json5 的对应 Ability 中声明 skills。

{
  "abilities": [{
    "name": "MyBrowserAbility",
    "exported": true,  // 隐式启动必须为 true
    "skills": [
      {
        "actions": ["ohos.want.action.viewData"],
        "entities": ["entity.system.browsable"],
        "uris": [
          {
            "scheme": "https",
            "host": "www.example.com",
            "path": "detail"
          }
        ]
      }
    ]
  }]
}

• actions：该 Ability 能响应的操作列表。
• entities：该 Ability 所属的实体类别。
• uris：可处理的 URI 格式，支持 scheme、host、port、path、pathStartWith、pathRegex 等匹配规则。

常用匹配规则：

• "scheme": "https"：仅匹配 https 协议。
• "host": "www.example.com"：主机名精确匹配。
• "path": "detail"：路径精确匹配。
• "pathStartWith": "page"：路径以 page 开头即可。
• "pathRegex": ".*"：任意路径（正则）。

3.5 隐式 Want 的匹配过程

1. 系统解析 Want 中的 action、entities、uri 和 type。
2. 遍历已安装应用的所有 exported: true 的 Ability。
3. 找出 skills 中声明的 actions 包含该 action，且 entities 匹配，且 uris 匹配的 Ability。
4. 若只有一个匹配，直接启动；若有多个，系统根据用户选择或默认设置启动。

四、Want 参数的传递与接收

参数通过 parameters 字段传递，它是一个 Record<string, Object> 类型，可以携带任意可序列化的数据。

4.1 发送方

let want: Want = {
  bundleName: 'com.example.myapp',
  abilityName: 'DetailAbility',
  parameters: {
    id: 42,
    title: '新闻标题',
    tags: ['科技', 'AI'],
    config: { showHeader: true }
  }
};
context.startAbility(want);

4.2 接收方

export default class DetailAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
    let id = want.parameters?.id as number;
    let title = want.parameters?.title as string;
    let tags = want.parameters?.tags as string[];
    let config = want.parameters?.config as Record<string, Object>;

    console.log(`接收参数：id=${id}, title=${title}`);
  }
}

4.3 传递复杂对象

对于自定义类对象，需要确保其可序列化，通常转为 JSON 字符串传递，接收方再反序列化。或者使用 HarmonyOS 支持的 @Sendable 装饰器（较新 API）标记可跨并发发送的类。

五、startAbilityForResult 获取返回结果

有时启动一个 Ability 后，需要它返回处理结果，可以使用 startAbilityForResult。

5.1 调用方

let want: Want = {
  bundleName: 'com.example.myapp',
  abilityName: 'SelectImageAbility'
};

context.startAbilityForResult(want).then((result) => {
  if (result.resultCode === 0) { // 成功
    let imageUri = result.want?.parameters?.imageUri as string;
    console.log('选择的图片：', imageUri);
  }
});

5.2 目标方返回结果

在 SelectImageAbility 中，处理完后调用 terminateSelfWithResult：

export default class SelectImageAbility extends UIAbility {
  onImageSelected(imageUri: string) {
    let resultWant: Want = {
      parameters: {
        imageUri: imageUri
      }
    };
    // 关闭自身并返回结果
    this.context.terminateSelfWithResult(resultWant);
  }
}

terminateSelfWithResult 会关闭当前 Ability，并将 resultWant 传回给调用方。

六、显式与隐式 Want 的选择策略

场景	推荐方式	原因
应用内部页面跳转	显式 Want 或 router.pushUrl	内部固定目标，显式简单高效
跨应用调用已知 Ability	显式 Want	如果确知包名和能力名，显式最直接
打开网页、查看文件等通用操作	隐式 Want	让用户选择或系统默认，不绑定特定应用
需要调用系统能力（打电话、发短信）	隐式 Want	系统已预置对应 action
对外提供功能给其他应用调用	配置 skills 支持隐式 Want	使自己的 Ability 可被发现

最佳实践：

• 应用内的跳转优先使用显式 Want 或 Navigation 组件，保持高效和可控。
• 当需要利用系统生态、提供通用操作时，为 Ability 配置完整的 skills，并设置 exported: true。
• 隐式 Want 匹配时，注意 URI 的精确度，避免过于宽泛导致被其他应用拦截或匹配失败。

七、常见错误与注意事项

7.1 隐式启动时目标 Ability 的 exported 为 false

"exported": false  // 系统不会将该 Ability 纳入隐式匹配范围

必须设为 true，否则隐式 Want 永远找不到它。

7.2 skills 配置不全导致匹配失败

检查 actions、entities、uris 是否与 Want 完全吻合。例如 uri 的 scheme 不匹配，或 path 正则未涵盖目标路径。

7.3 忽略 deviceId 导致无法跨设备

若希望启动其他设备上的 Ability，需设置 deviceId 为目标设备的网络 ID，并确保分布式能力已激活。本机调用时，设为空字符串 '' 或不填。

7.4 参数传递包含不可序列化对象

函数、Symbol、不可序列化的自定义实例不能直接作为 parameters。优先传递基础类型、数组、简单对象或 JSON 字符串。

7.5 忘记在 onCreate 中处理首次 Want 和后续 onNewWant

当启动模式为 singleton 时，重复启动不会走 onCreate，而是走 onNewWant，需在此方法中处理新 Want 的参数更新。

export default class MainAbility extends UIAbility {
  onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam) {
    // 处理新 Want
    console.log('收到新 Want:', want.parameters?.data);
  }
}

八、小结

概念	关键点
Want 结构	bundleName、abilityName（显式），action、entities、uri（隐式），parameters 携带参数
显式启动	精确指定包名和能力名，高效直接，适用于应用内部或已知外部 Ability
隐式启动	通过 action + entities + uri 匹配，解耦应用，适用于通用操作和系统服务
skills 配置	actions、entities、uris，exported: true 为必要条件
参数传递	parameters 传递键值对，接收方从 want.parameters 取出
返回结果	startAbilityForResult + terminateSelfWithResult
注意事项	隐式需配置 exported，注意 onNewWant 处理，避免不可序列化参数

掌握 Want 的显式与隐式用法，是打通 HarmonyOS 应用内与应用间通信的关键。灵活运用两种方式，能让你的应用更好地融入系统生态，提供更丰富的交互体验。

---

觉得文章有帮助？别忘了：

👍 点赞 👍 – 给我一点鼓励
⭐ 收藏 ⭐ – 方便以后查看
🔔 关注 🔔 – 获取更新通知

---

标签： #HarmonyOS #Want #显式启动 #隐式启动 #Ability通信 #学习笔记 #鸿蒙开发