【共创季稿事节】HarmonyOS 6.1 意图框架（Intent Framework）接入实战

想你依然心痛

458人浏览 · 2026-07-17 10:32:59

想你依然心痛 · 2026-07-17 10:32:59 发布

文章目录

在这里插入图片描述

每日一句正能量

不偏执于一条路，不固执于一种想法，才能在变化的世界中找到属于自己的出路。
世界充满变数，执念是痛苦的根源，也是视野的牢笼。灵活不是善变，而是基于对现实的清醒认知，懂得调整策略。出路往往不在原定计划的终点，而在拐弯处的发现。

摘要

摘要： HarmonyOS 6.1 的意图框架（Intent Framework）是系统级智能分发能力的核心基础设施。它让应用不再依赖固定的图标入口，而是通过"意图"这一语义化的交互契约，被系统在恰当的时机、恰当的入口、以恰当的方式唤起。本文从原理到实践，完整讲解意图的注册、识别、解析与跨应用跳转全链路，并演示如何将应用接入小艺建议、智慧搜索、系统分享面板等关键系统入口。

一、意图框架概述

1.1 从"找应用"到"找能力"

传统移动生态中，用户与应用的交互路径高度依赖"图标记忆"——用户需要知道某个功能在哪个 App 里，然后找到图标、打开应用、再找到具体功能。这种模式的痛点在于：

发现成本高：应用越多，找到目标功能的成本越高；
入口割裂：同样的能力（如"打车"）分散在多个应用中，用户需要反复比较；
场景断裂：用户正在 A 应用中，想使用 B 应用的能力，必须切换上下文。

HarmonyOS 6.1 的意图框架（Intent Framework）试图打破这一困局。它的核心理念是：系统不关心功能在哪个应用里，只关心用户需要什么能力。

1.2 意图框架的三层模型

在这里插入图片描述

上图展示了意图框架的完整流转链路。用户通过自然语言或系统入口表达意图，系统经过意图理解、应用匹配、能力路由，最终唤起目标应用的具体功能页面。

意图框架可分为三层：

层级	职责	核心模块
意图表达层	接收用户意图输入（语音、文字、手势、上下文）	小艺助手、智慧搜索、系统分享面板
意图解析层	理解意图语义，提取实体参数，确定目标能力	Intent Resolver、NLP Engine、Entity Extractor
能力路由层	匹配注册该能力的应用，按优先级排序，执行跳转	Ability Manager、App Ranker、Deep Link Router

1.3 意图框架的核心价值

价值点	说明
去中心化发现	应用能力可被系统全局索引，不依赖用户主动打开应用
场景化触发	基于时间、地点、设备状态等上下文自动推荐能力
跨应用协同	应用 A 可直接唤起应用 B 的某个功能，数据无缝传递
自然语言入口	用户通过说话或打字即可直达功能，无需记忆应用名称

二、意图注册：让系统认识你

2.1 注册原理

意图注册的本质是向系统声明"我的应用能提供什么能力"。开发者需要在 module.json5 中声明意图能力（Intent Ability），并在代码中实现对应的意图处理器（Intent Handler）。

2.2 module.json5 配置详解

{
  "module": {
    "abilities": [
      {
        "name": "OrderDetailAbility",
        "srcEntry": "./ets/entryability/OrderDetailAbility.ets",
        "description": "$string:OrderDetailAbility_desc",
        "icon": "$media:icon",
        "label": "$string:OrderDetailAbility_label",
        "startWindowIcon": "$media:icon",
        "startWindowBackground": "$color:start_window_background",
        "exported": true,
        "skills": [
          {
            "actions": [
              "ohos.intent.action.VIEW_ORDER"
            ],
            "entities": [
              "ohos.intent.entity.FOOD_DELIVERY"
            ],
            "uris": [
              {
                "scheme": "harmonyfood",
                "host": "order",
                "path": "/detail"
              }
            ]
          }
        ],
        "intents": [
          {
            "intentName": "QueryOrderStatus",
            "entities": ["orderId", "shopName"],
            "parameters": [
              {
                "name": "orderId",
                "type": "string",
                "required": true,
                "description": "订单编号"
              },
              {
                "name": "shopName",
                "type": "string",
                "required": false,
                "description": "商家名称"
              }
            ]
          },
          {
            "intentName": "ReorderMeal",
            "entities": ["shopId", "dishList"],
            "parameters": [
              {
                "name": "shopId",
                "type": "string",
                "required": true
              },
              {
                "name": "dishList",
                "type": "array",
                "required": false
              }
            ]
          }
        ]
      }
    ]
  }
}

配置项解析：

skills.actions：声明该 Ability 响应的标准动作，如 VIEW_ORDER（查看订单）、CREATE_ORDER（创建订单）；
skills.entities：声明该 Ability 处理的实体类型，如 FOOD_DELIVERY（外卖）、RIDE_HAILING（打车）；
skills.uris：声明 Deep Link URI，支持自定义 Scheme；
intents：声明意图能力，包括意图名称、实体参数和参数类型约束。

2.3 注册配置示意图

在这里插入图片描述

上图直观展示了 module.json5 中意图注册的关键字段。左侧为标准动作与实体声明，右侧为意图参数定义。正确的注册是应用被系统识别的第一步。

三、意图识别：让系统理解用户

3.1 意图解析流程

当用户通过语音或文字表达需求时，系统会经历以下解析流程：

意图分类：NLP 引擎判断用户意图属于哪个大类（查询、下单、导航、播放等）；
实体抽取：从用户输入中提取关键参数（如订单号、商家名、目的地）；
参数校验：检查提取的参数是否满足已注册意图的参数约束；
应用匹配：根据意图名称和实体类型，匹配注册了对应能力的应用；
优先级排序：按应用活跃度、用户偏好、开发者权重排序；
路由执行：构建 Want 对象，唤起目标 Ability。

3.2 自然语言到意图的映射示例

用户输入	解析意图	提取实体	目标 Ability
“帮我查一下订单 12345”	QueryOrderStatus	orderId=12345	OrderDetailAbility
“我想再点一份肯德基”	ReorderMeal	shopName=肯德基	ShopPageAbility
“显示我最近的外卖到哪了”	QueryOrderStatus	orderId=latest	OrderDetailAbility
“打开配送地图”	ViewDeliveryMap	orderId=current	DeliveryMapAbility

3.3 意图参数兜底策略

当用户输入缺少必需参数时，应用应优雅处理：

// entryability/OrderDetailAbility.ets
import { UIAbility, Want } from '@kit.AbilityKit';

export default class OrderDetailAbility extends UIAbility {
  onCreate(want: Want): void {
    const orderId = want.parameters?.['orderId'] as string;

    if (!orderId) {
      // 参数缺失：打开订单列表页，让用户选择
      this.context.startAbility({
        bundleName: 'com.example.food',
        abilityName: 'OrderListAbility'
      });
      return;
    }

    if (orderId === 'latest' || orderId === 'current') {
      // 相对时间词：查询最新订单
      this.loadLatestOrder();
      return;
    }

    // 正常加载指定订单
    this.loadOrderDetail(orderId);
  }

  private async loadLatestOrder(): Promise<void> {
    // 从本地缓存或服务端获取最近订单
    const latestOrder = await OrderService.getLatestOrder();
    this.loadOrderDetail(latestOrder.id);
  }

  private loadOrderDetail(orderId: string): void {
    // 加载订单详情页面
    console.info(`[Intent] 加载订单详情: ${orderId}`);
  }
}

四、跨应用跳转与数据传递

4.1 通过 Intent 唤起其他应用

应用 A 可以通过意图框架唤起应用 B 的特定功能，无需知道应用 B 的具体包名：

// 在应用 A 中唤起外卖订单详情（系统会自动匹配合适的应用）
import { Want } from '@kit.AbilityKit';

async function openOrderDetail(orderId: string): Promise<void> {
  const want: Want = {
    action: 'ohos.intent.action.VIEW_ORDER',
    entities: ['ohos.intent.entity.FOOD_DELIVERY'],
    parameters: {
      orderId: orderId,
      source: 'partner_app'
    }
  };

  const context = getContext(this);
  
  try {
    await context.startAbility(want);
    console.info('[Intent] 跨应用跳转成功');
  } catch (err) {
    // 没有匹配应用时的降级处理
    console.error('[Intent] 跳转失败，可能未安装外卖应用');
    promptAction.showToast({ message: '请先安装外卖应用' });
  }
}

4.2 URI Scheme 深度跳转

除了标准动作，还可以通过自定义 URI Scheme 实现精确跳转：

// 唤起外卖应用并直接打开地图页面
const want: Want = {
  uri: 'harmonyfood://order/map?orderId=12345&showRider=true'
};

// 目标应用 Ability 中解析 URI
onCreate(want: Want): void {
  const uri = want.uri;
  if (uri) {
    const url = new URL(uri);
    const orderId = url.searchParams.get('orderId');
    const showRider = url.searchParams.get('showRider') === 'true';
    this.openMapPage(orderId, showRider);
  }
}

4.3 带返回结果的意图调用

当需要获取目标应用的处理结果时，使用 startAbilityForResult：

// 唤起支付应用并等待支付结果
async function invokePayment(orderId: string, amount: number): Promise<boolean> {
  const want: Want = {
    action: 'ohos.intent.action.PAY',
    entities: ['ohos.intent.entity.PAYMENT'],
    parameters: { orderId, amount }
  };

  const context = getContext(this);
  
  try {
    const result = await context.startAbilityForResult(want, { requestCode: 1001 });
    return result.resultCode === 0;  // 0 表示支付成功
  } catch (err) {
    console.error('[Intent] 支付调用失败:', err);
    return false;
  }
}

五、系统级入口接入实战

5.1 接入小艺建议（Celia Suggestions）

小艺建议是系统级智能推荐卡片，会根据用户习惯在桌面、负一屏等位置展示建议。

// services/CeliaSuggestion.ets
import { suggestion } from '@kit.IntelligenceKit';

export class CeliaSuggestionHelper {
  // 向小艺建议注册动态内容
  static async registerOrderSuggestion(order: Order): Promise<void> {
    const suggestionItem = {
      id: `order_${order.id}`,
      title: `${order.shopName} 订单`,
      subtitle: `预计 ${order.etaMinutes} 分钟送达`,
      icon: $r('app.media.ic_delivery'),
      intent: {
        action: 'ohos.intent.action.VIEW_ORDER',
        parameters: { orderId: order.id }
      },
      // 展示规则
      displayRules: {
        timeRange: { start: Date.now(), end: Date.now() + 60 * 60 * 1000 },
        scenario: ['lock_screen', 'negative_screen', 'notification_center']
      }
    };

    await suggestion.publish(suggestionItem);
  }

  // 订单完成后移除建议
  static async removeSuggestion(orderId: string): Promise<void> {
    await suggestion.revoke(`order_${orderId}`);
  }
}

5.2 接入智慧搜索

让应用内容可被系统全局搜索索引：

// 在 Ability 中处理搜索意图
onCreate(want: Want): void {
  const action = want.action;
  
  if (action === 'ohos.intent.action.SEARCH') {
    const query = want.parameters?.['query'] as string;
    this.handleGlobalSearch(query);
  }
}

private handleGlobalSearch(query: string): void {
  // 在应用内执行搜索
  SearchService.search(query).then((results) => {
    // 将搜索结果返回给系统搜索页面
    this.context.terminateSelfWithResult({
      resultCode: 0,
      want: {
        parameters: {
          searchResults: JSON.stringify(results)
        }
      }
    });
  });
}

5.3 接入系统分享面板

让应用的能力出现在系统分享菜单中：

// module.json5 中注册分享能力
{
  "abilities": [
    {
      "name": "ShareAbility",
      "skills": [
        {
          "actions": ["ohos.intent.action.SEND"],
          "entities": ["ohos.intent.entity.SHARE"],
          "uris": [{ "scheme": "harmonyfood", "host": "share" }]
        }
      ]
    }
  ]
}

// ShareAbility.ets
export default class ShareAbility extends UIAbility {
  onCreate(want: Want): void {
    const sharedText = want.parameters?.['sharedText'] as string;
    const sharedImage = want.parameters?.['sharedImage'] as string;

    // 打开分享编辑页
    this.context.startAbility({
      bundleName: 'com.example.food',
      abilityName: 'ShareEditAbility',
      parameters: { sharedText, sharedImage }
    });
  }
}

六、跳转效果与交互体验

6.1 跳转动画配置

意图框架支持自定义跳转动画，提升跨应用跳转的连贯性：

import { window } from '@kit.WindowManager';

onWindowStageCreate(windowStage: window.WindowStage): void {
  windowStage.getMainWindow().then((win) => {
    win.setTransitionAnimation({
      type: window.TransitionType.SLIDE,
      direction: window.TransitionDirection.RIGHT,
      duration: 300,
      curve: Curve.EaseInOut
    });
  });
}

6.2 跳转效果示意图

在这里插入图片描述

上图展示了通过意图框架从系统搜索直达应用订单详情页的跳转效果。整个过程流畅自然，用户无需手动打开应用、无需在应用内再次搜索，实现了"意图即入口"的体验闭环。

七、意图框架最佳实践

7.1 注册规范

实践	说明
意图命名标准化	遵循 `Verb + Noun` 结构，如 `QueryOrderStatus`、`CreateAppointment`
参数最小化	仅声明业务必需的参数，可选参数标记 `required: false`
URI 稳定性	自定义 Scheme 一旦发布不得变更，避免已有外部链接失效
动作复用	优先使用系统标准动作（如 `VIEW`、`SEND`、`SEARCH`），减少自定义动作

7.2 体验优化

优化项	说明
参数兜底	缺少必需参数时，不要直接报错，而是引导用户补全
加载态	意图跳转涉及跨应用调度，需展示加载指示器
返回路径	跨应用跳转后，用户按返回键应回到原应用，而非桌面
上下文保留	唤起目标应用时，传递来源标识，便于目标应用做个性化处理

7.3 安全与隐私

注意点	措施
参数校验	所有通过 Intent 传入的参数必须做合法性校验
权限控制	敏感操作（如支付、删除）需在 Intent Handler 中再次校验权限
exported 控制	仅将需要对外暴露的 Ability 标记 `exported: true`
数据脱敏	通过 Intent 传递的数据避免包含用户敏感信息