快速入门

安装

你可以使用我们的 AI 辅助设置来安装插件。使用以下命令将 Capgo skills 添加到你的 AI 工具中：

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

然后使用以下 prompt：

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-app-intents` plugin in my project.

如需手动设置，请安装该 package 并同步原生项目：

npm install @capgo/capacitor-app-intents
npx cap sync

导入

import {
  CapgoAppIntents,
  drainPendingInvocations,
  useAppIntentsListener,
} from '@capgo/capacitor-app-intents';

处理调用（冷启动安全）

在清空待处理队列之前注册监听器，确保在 WebView 启动期间触发的 Siri、Shortcuts、Spotlight 和快速操作不会丢失。

const handleInvocation = async (invocation) => {
  console.log(invocation.name, invocation.params, invocation.source);
};

await useAppIntentsListener(handleInvocation);

useAppIntentsListener 附加 appIntentInvoked 然后清空待处理项。你也可以调用 getPendingInvocations() 以及 removePendingInvocation() 如果你更倾向于显式控制，也可以手动操作。

Siri 短语（codegen）

AppShortcut 短语和 SF Symbol 名称必须是 编译时字面量 在 Swift 中。 app-shortcuts.config.json 在你的应用仓库中配置，并将 Swift 代码生成到你的 iOS 应用 target：

node node_modules/@capgo/capacitor-app-intents/scripts/generate-app-shortcuts.mjs \
  --config app-shortcuts.config.json \
  --output ios/App/App/CapgoGeneratedAppShortcuts.swift

将插件 SPM 包链接到应用 target，以便 CapgoDispatchAppIntent 解决。在 Capacitor 8 上，使用以下方式转发 SceneDelegate 快速操作和继续的 Spotlight 活动 CapgoAppIntentsLifecycle （参见插件仓库 docs/ios-scene-integration.md).

capacitor.config

plugins: {
  CapgoAppIntents: {
    appGroupId: 'group.your.app',
    spotlightDomainIdentifier: 'your.app.bundle',
  },
},

API 概览

getPendingInvocations

返回在 JavaScript 就绪前已排队的调用。

import { CapgoAppIntents } from '@capgo/capacitor-app-intents';

const result = await CapgoAppIntents.getPendingInvocations();
console.log(result);

removePendingInvocation

在 handler 处理完后，移除一个待处理的调用。

import { CapgoAppIntents } from '@capgo/capacitor-app-intents';

await CapgoAppIntents.removePendingInvocation({ id: 'id-123' });

setEntityCatalog

为给定的类型字符串持久化实体目录。

为 Siri 和快捷指令的实体参数提供支持，无需为每一行编写新的 Swift 代码。

import { CapgoAppIntents } from '@capgo/capacitor-app-intents';

await CapgoAppIntents.setEntityCatalog({
  type: 'type',
  entries: [
    {
      id: 'id-123',
      title: 'Hello from Capacitor',
    },
  ],
});

setHomeScreenShortcutItems

替换主屏幕快速操作 (UIApplicationShortcutItems)。

import { CapgoAppIntents } from '@capgo/capacitor-app-intents';

await CapgoAppIntents.setHomeScreenShortcutItems({
  items: [
    {
      type: 'type',
      title: 'Hello from Capacitor',
    },
  ],
});

indexSpotlightEntities

为你的 App 域建立 Spotlight 条目索引。

采用 CSSearchableItem 适用于 iOS 16 及更高版本。在 iOS 18 及更高版本上，还会进行捐赠 IndexedEntity 通过值 indexAppEntities 以及 associateAppEntity.

import { CapgoAppIntents } from '@capgo/capacitor-app-intents';

await CapgoAppIntents.indexSpotlightEntities({
  entities: [
    {
      id: 'id-123',
      title: 'Hello from Capacitor',
      actionName: 'action',
    },
  ],
});

removeSpotlightEntities

按 id 删除 Spotlight 项。

import { CapgoAppIntents } from '@capgo/capacitor-app-intents';

await CapgoAppIntents.removeSpotlightEntities({ ids: ['ids'] });

performAppleSchemaTemplate

将 JavaScript 处理程序加入队列，用于 alpha 版 Apple schema template。

这不会调用私有的 Mail 或系统 schema API。它只会将一次调用加入队列（例如 appleSchemaMailCreateDraft）交由你的应用 code 处理。

import { CapgoAppIntents } from '@capgo/capacitor-app-intents';

const result = await CapgoAppIntents.performAppleSchemaTemplate({
  template: 'mail_create_draft',
  params: {},
});
console.log(result);

类型参考

AppIntentInvocation

等待 JavaScript 处理的待处理 App Intent 风格调用。

export interface AppIntentInvocation {
  /**
   * Stable id for this queued invocation.
   *
   * @since 0.1.0
   */
  id: string;

  /**
   * Handler name your JavaScript listens for.
   *
   * @since 0.1.0
   */
  name: string;

  /**
   * Parameters passed from Siri, Shortcuts, Spotlight, or quick actions.
   *
   * @since 0.1.0
   */
  params: Record<string, unknown>;

  /**
   * Origin of the invocation.
   *
   * @since 0.1.0
   */
  source: AppIntentInvocationSource;

  /**
   * Unix timestamp in milliseconds when the invocation was queued.
   *
   * @since 0.1.0
   */
  createdAt: number;
}

EntityCatalogEntry

Siri 和 Shortcuts 参数所用的运行时实体目录中的一行。

export interface EntityCatalogEntry {
  /**
   * Unique id within the catalog type.
   *
   * @since 0.1.0
   */
  id: string;

  /**
   * Primary label shown in Shortcuts and Siri.
   *
   * @since 0.1.0
   */
  title: string;

  /**
   * Optional subtitle.
   *
   * @since 0.1.0
   */
  subtitle?: string;

  /**
   * Optional extra metadata forwarded to JavaScript when the entity is chosen.
   *
   * @since 0.1.0
   */
  metadata?: Record<string, unknown>;
}

HomeScreenShortcutItem

主屏幕快速操作项。

export interface HomeScreenShortcutItem {
  /**
   * Stable type string delivered to JavaScript.
   *
   * @since 0.1.0
   */
  type: string;

  /**
   * Visible title under the icon.
   *
   * @since 0.1.0
   */
  title: string;

  /**
   * Optional subtitle.
   *
   * @since 0.1.0
   */
  subtitle?: string;

  /**
   * Optional SF Symbol name.
   *
   * @since 0.1.0
   */
  iconName?: string;

  /**
   * Optional params merged into the invocation.
   *
   * @since 0.1.0
   */
  params?: Record<string, unknown>;
}

SpotlightEntity

Spotlight 可搜索实体。

export interface SpotlightEntity {
  /**
   * Unique id within your app domain.
   *
   * @since 0.1.0
   */
  id: string;

  /**
   * Title shown in Spotlight.
   *
   * @since 0.1.0
   */
  title: string;

  /**
   * Optional description.
   *
   * @since 0.1.0
   */
  description?: string;

  /**
   * Optional keywords.
   *
   * @since 0.1.0
   */
  keywords?: string[];

  /**
   * Action name delivered when the result is opened.
   *
   * @since 0.1.0
   */
  actionName: string;

  /**
   * Optional params merged into the invocation.
   *
   * @since 0.1.0
   */
  params?: Record<string, unknown>;
}

AppleSchemaTemplate

插件提供的 Alpha 版 Apple schema 模板标识符。

export type AppleSchemaTemplate = 'mail_create_draft';

AppIntentInvokedEvent

export interface AppIntentInvokedEvent {
  /**
   * The invocation that was just queued or replayed to listeners.
   *
   * @since 0.1.0
   */
  invocation: AppIntentInvocation;
}

AppIntentInvocationSource

调用来源。

export type AppIntentInvocationSource = 'app_intent' | 'spotlight' | 'quick_action' | 'apple_schema';

单一事实来源

本页面由插件的 src/definitions.ts生成。当上游的公共 API 发生变化时，请重新运行 sync。