Prise en main

Installer

Vous pouvez utiliser notre configuration assistée par IA pour installer le plugin. Ajoutez les skills Capgo à votre outil d'IA avec la commande suivante :

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

Utilisez ensuite le prompt suivant :

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

Pour une configuration manuelle, installez le package et synchronisez les projets natifs :

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

Importer

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

Gérer les invocations (compatible cold start)

Enregistrez un écouteur avant de vider la file d'attente en attente pour ne pas perdre les requêtes Siri, Shortcuts, Spotlight et les actions rapides qui se déclenchent lors du démarrage de la WebView.

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

await useAppIntentsListener(handleInvocation);

useAppIntentsListener attache appIntentInvoked puis vide les éléments en attente. Vous pouvez aussi appeler getPendingInvocations() et removePendingInvocation() manuellement si vous préférez un contrôl’explicite.

Phrases Siri (codegen)

AppShortcut les phrases et les noms de SF Symbol doivent être littéraux à la compilation en Swift. Configurez app-shortcuts.config.json dans le repo de votre app et générez du Swift dans votre cible cible iOS :

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

Liez le package SPM du plugin à la cible de l’app afin que CapgoDispatchAppIntent résout. Sur Capacitor 8, transmettez les actions rapides de SceneDelegate et les activités Spotlight poursuivies avec CapgoAppIntentsLifecycle (voir le dépôt du plugin docs/ios-scene-integration.md).

capacitor.config

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

Aperçu de API

getPendingInvocations

Return invocations queued before JavaScript was ready.

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

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

removePendingInvocation

Supprime une invocation en attente après que votre gestionnaire l’a traitée.

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

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

setEntityCatalog

Persistez un catalogue d'entités pour une chaîne de type donnée.

Alimente les paramètres d'entités de Siri et Shortcuts sans nouveau code Swift par ligne.

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

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

setHomeScreenShortcutItems

Remplacez les actions rapides de l'écran d'accueil (UIApplicationShortcutItems).

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

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

indexSpotlightEntities

Indexez les éléments Spotlight pour le domaine de votre app.

Utilise CSSearchableItem on iOS 16 and later. On iOS 18 and later also donates IndexedEntity de valeurs via indexAppEntities et associateAppEntity.

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

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

removeSpotlightEntities

Supprime les éléments Spotlight par identifiant.

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

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

performAppleSchemaTemplate

Mettre en file d’attente un handler JavaScript pour un modèle de schéma Apple alpha.

Cela n’appelle pas les API privées de Mail ou les schémas système. Il ne fait que mettre en file d’attente une appleSchemaMailCreateDraft) pour que votre application code le gère.

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

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

Référence de type

AppIntentInvocation

Une invocation de type App Intent en attente de JavaScript.

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

Une ligne dans un catalogue d'entités runtime utilisé par Siri et les paramètres 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

Élément d'action rapide de l'écran d'accueil.

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

Entité recherchable via 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

Identifiants de templates de schéma Apple alpha fournis par le plugin.

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

L'origine de l'invocation.

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

Source de vérité

Cette page est générée à partir de src/definitions.ts. Relancez la synchronisation lorsque l’API public change en amont.