Siri、快捷指令、小组件和系统意图

Expo 最近发布了 expo-app-intents，它将 Apple 的 App Intents 框架接入 JavaScript：支持 Siri 和快捷指令短语、运行时实体目录、面向 Apple Intelligence 的 Apple 应用 schema、Spotlight 索引，以及一个原生队列，用于处理 JavaScript 启动前到达的调用。

@capgo/capacitor-app-intents 是面向 Apple 的 Capacitor 桥接 App Intents：Siri 和快捷指令短语（通过编译期代码生成）、运行时实体目录、Spotlight 索引、主屏幕快捷操作，以及用于冷启动的待处理调用队列。Widget Kit、Live Activities、Share Target 和 Intent Launcher 仍然涵盖 相邻 界面。本页梳理了它们的协作方式，助你发布系统集成功能，同时避免混淆 Android Intent API 与 Apple App Intents。

快速地图

系统界面	Capgo 插件	插件的实际功能
主屏幕小组件、锁屏 Live Activities、灵动岛（SVG 或原生小组件 code）	@capgo/capacitor-widget-kit	持久化模板活动，执行声明式操作，记录小组件或 Live Activity 点击，通过 App Groups 同步全原生小组件会话。
使用 JSON 布局树的 Live Activities	@capgo/capacitor-live-activities	从 Capacitor 启动、更新和结束 ActivityKit 活动；计时器序列；App Group 中的共享图片。
接收其他应用的分享	@capgo/capacitor-share-target	shareReceived 通过 Android intents 或 iOS Share Extension 以及 App Group 接收标题、文本和文件事件。
打开 Android 设置或 Activity；打开 iOS 设置 URL	@capgo/capacitor-intent-launcher	startActivityAsync, openIOSSettings, openApplication。这是 不会 Apple App Intents。
Siri 短语、Shortcuts、Spotlight、快速操作、App Intent 队列	@capgo/capacitor-app-intents	Dispatch 桥接， setEntityCatalog, indexSpotlightEntities, setHomeScreenShortcutItems, getPendingInvocations, useAppIntentsListener。iOS 16+。
设备端 LLM（支持机型上的 Apple Intelligence）	@capgo/capacitor-llm	聊天和模型 API。无 App Intent 或 schema 桥接。

与 expo-app-intents 的对比

评估功能对等性时请使用此表。标记为 部分 的项表示仅有一小部分功能重叠。

expo-app-intents 功能	Capgo 当前状态
在 Siri 和快捷指令 App 中通过语音短语执行自定义操作	是 配合 @capgo/capacitor-app-intents. 短语位于 编译时字面量 生成的 Swift 中 (AppShortcutsProvider)，而非运行时 JavaScript 字符串。
由 JS 实体目录支持的快捷指令参数 (AppEntity, EntityQuery)	是 配合 @capgo/capacitor-app-intents 通过 setEntityCatalog() 以及原生 EntityQuery 接线。
Apple 应用 Schema（例如用于 Apple Intelligence 的邮件草稿意图）	部分支持。 App Intents 暴露 performAppleSchemaTemplate 作为 仅 JavaScript 队列 （无原生 Mail API）。您需在应用中实现撰写 UI 或深度链接。
Spotlight 索引和可搜索的应用内容	是 配合 @capgo/capacitor-app-intents 通过 indexSpotlightEntities() (CSSearchableItem，以及 IndexedEntity 在 iOS 18+ 上）。
将屏幕内容与实体关联，用于系统智能	部分支持。 实体目录为 Shortcuts 参数提供支持；完整的屏幕关联 API 尚未开放。
用于 JavaScript 就绪前触发操作的原生队列	是 通过 App Intents 实现 @capgo/capacitor-app-intents (getPendingInvocations, appIntentInvoked）。Share Target 和 Widget Kit 在分享和模板事件方面仍使用各自的保留模型。
通过 App Intents 实现交互式 Live Activity 或小组件按钮	部分支持。 Widget Kit 提供 CapgoTemplateActionIntent 以及 CompleteSetIntent 命名为 LiveActivityIntent 类型，适用于 模板、 热点和体能训练操作（iOS 17+）。它们会更新原生状态和事件日志；但不会从 JavaScript 暴露任意 Siri 短语。
在应用 JavaScript 中访问 WidgetKit 和 ActivityKit	是的。 Widget Kit 和 Live Activities 插件（见下文）。
Android Intent 操作（设置、VIEW、SEND 等）	是 用于通过 Intent Launcher 和 Share Target 启动和接收。

Widget Kit：小组件、Live Activities 和模板操作

@capgo/capacitor-widget-kit 最接近 系统可见 UI 位于 WebView 之外。您可以从 Capacitor 驱动锁屏和灵动岛界面，从 SVG 模板或原生 Swift/Kotlin code 渲染主屏幕小组件，并在事后处理点击。

启动模板 Live Activity，并用 JavaScript 处理操作

在应用启动时注册监听器，然后在 App 恢复后轮询或调用，因为小组件点击可能在 WebView 仍在加载时运行：

import { App } from '@capacitor/app';
import { CapgoWidgetKit } from '@capgo/capacitor-widget-kit';

const ACTIVITY_ID = 'order-tracker';

async function drainTemplateEvents() {
  const { events } = await CapgoWidgetKit.listTemplateEvents({
    activityId: ACTIVITY_ID,
    unacknowledgedOnly: true,
  });

  for (const event of events) {
    if (event.actionId === 'mark-delivered') {
      // Update your app state from event.state or event.payload
    }
    await CapgoWidgetKit.acknowledgeTemplateEvents({
      eventIds: [event.eventId],
    });
  }
}

await CapgoWidgetKit.startTemplateActivity({
  activityId: ACTIVITY_ID,
  state: { status: 'On the way' },
  definition: {
    id: 'delivery-card',
    actions: [
      {
        id: 'mark-delivered',
        eventName: 'delivery.marked',
      },
    ],
    layouts: {
      lockScreen: {
        width: 200,
        height: 80,
        svg: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 80"><text x="8" y="40">{{state.status}}</text></svg>',
        hotspots: [
          {
            id: 'deliver',
            actionId: 'mark-delivered',
            x: 120,
            y: 20,
            width: 70,
            height: 40,
            label: 'Mark delivered',
          },
        ],
      },
    },
  },
});

App.addListener('resume', () => {
  void drainTemplateEvents();
});

void drainTemplateEvents();

在 iOS 上，小组件扩展中的交互式控件可以调用捆绑的 CapgoTemplateActionIntent (LiveActivityIntent). 这条路径会更新存储的模板状态，并追加到你的 JavaScript 读取的同一个事件日志中。它 不会 与在“快捷指令”App 中添加用户可见的快捷指令短语相同。

查看 Widget Kit 入门指南 用于 App Group 配置和全原生 Widget 会话。

Live Activities：来自 Capacitor 的 JSON 布局

@capgo/capacitor-live-activities 重点介绍 ActivityKit 使用声明式布局 JSON（文本、图像、计时器、仪表、灵动岛区域）。它不会注册 App Intents 或 Siri 快捷指令。

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

const { supported } = await CapgoLiveActivities.areActivitiesSupported();
if (!supported) {
  return;
}

const { activityId } = await CapgoLiveActivities.startActivity({
  layout: {
    type: 'container',
    direction: 'vertical',
    children: [
      { type: 'text', content: 'Order {{orderId}}', fontWeight: 'bold' },
      { type: 'text', content: '{{status}}' },
    ],
  },
  data: { orderId: '42', status: 'Preparing' },
});

await CapgoLiveActivities.updateActivity({
  activityId,
  data: { orderId: '42', status: 'Out for delivery' },
});

选择 实时活动 当你想用布局 DSL 和图像辅助工具时，选择 Widget Kit 入门指南 当你需要主屏幕小组件、SVG 框架，或模板事件日志和 LiveActivityIntent 按钮。

Share Target：传入的分享（不是发出的 Shortcuts）

@capgo/capacitor-share-target 让其他应用把内容发送到 为 你的应用。在 iOS 上，你需要添加一个写入 App Group 的 Share Extension；主应用插件会读取并清除该 payload，然后发出 shareReceived.

iOS 上会处理冷启动：原生插件会调用 notifyListeners(..., retainUntilConsumed: true) 因此，第一个 JavaScript 监听器仍能收到该事件。

import { CapacitorShareTarget } from '@capgo/capacitor-share-target';

await CapacitorShareTarget.addListener('shareReceived', (event) => {
  const firstText = event.texts[0] ?? '';
  const firstFile = event.files[0];
  console.log(event.title, firstText, firstFile?.uri);
});

这与 Android 的 SEND intent filters 互补。它确实会 不会 从你的 App 中发布分享快捷方式或 Siri 操作。

Intent Launcher：Android intents 与 iOS 设置（非 App Intents）

这个名字很容易和 Apple 的 App Intents. @capgo/capacitor-intent-launcher 仅启动 Android Activity（包括 ActivityAction.CREATE_SHORTCUT 用于旧版启动器快捷方式）并打开 iOS 设置 URL scheme。

import { IntentLauncher, ActivityAction, IOSSettings } from '@capgo/capacitor-intent-launcher';

await IntentLauncher.startActivityAsync({
  action: ActivityAction.WIFI_SETTINGS,
});

await IntentLauncher.openIOSSettings({ option: IOSSettings.App });

对于 Siri、快捷指令 App 以及 AppIntent 类型，请使用 @capgo/capacitor-app-intents。Intent Launcher 仅启动 Android Activity 和 iOS 设置 URL。

建议组合

目标	从这里开始
锁屏和灵动岛，支持 SVG 与点击日志	Widget Kit 入门指南
丰富的 JSON 布局与定时器序列	实时活动
用户将链接或文件分享到您的 App	分享目标
用 Deep link 将用户引导到 WiFi 或 App 设置	意图启动器
用 Siri 短语运行带实体参数的 JS handler	App Intents (短语的 codegen, setEntityCatalog, useAppIntentsListener)

剩余缺口（用于规划）

领域	状态
Widget Kit 自定义 AppShortcut 与模板事件日志绑定的短语	Widget Kit 仍只打包 LiveActivityIntent 辅助工具；任意 Siri 短语应归入 App Intents 代码生成。
Share Target 轮询 API	目前仅支持事件；使用 addListener('shareReceived') 启动早期。
Apple Mail 原生 schema intents	第三方应用无法使用；App Intents 会改为将 JS handler 入队。
Android App Intents 功能对齐	App Intents 仅支持 iOS 16+；Android 会返回明确错误。

继续

• App Intents 概览
• Widget Kit 概览
• Live Activities 概览
• Share Target 概览
• Intent Launcher 概览