Per iniziare

Installa

Puoi usare il nostro setup assistito dall'IA per installare il plugin. Aggiungi le skill Capgo al tuo strumento di IA usando il seguente comando:

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

Poi usa il seguente prompt:

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

Per una configurazione manuale, installa il pacchetto e sincronizza i progetti nativi:

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

Importa

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

Gestire le invocazioni (sicuro al cold start)

Registra un listener prima di svuotare la coda in attesa, così Siri, Shortcuts, Spotlight e le azioni rapide avviate durante l'avvio del WebView non vengono perse.

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

await useAppIntentsListener(handleInvocation);

useAppIntentsListener attacca appIntentInvoked e poi svuota gli elementi in sospeso. Puoi anche chiamare getPendingInvocations() e removePendingInvocation() manualmente, se preferisci un controllo esplicito.

Frasi Siri (codegen)

AppShortcut le frasi e i nomi dei simboli SF devono essere letterali a compile time in Swift. Configura app-shortcuts.config.json nel repository della tua app e genera Swift nel tuo App target:

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

Collega il pacchetto SPM del plugin al target dell'app in modo che CapgoDispatchAppIntent resolves. Su Capacitor 8, inoltra le azioni rapide di SceneDelegate e le attività Spotlight continue con CapgoAppIntentsLifecycle (vedi il repository del plugin docs/ios-scene-integration.md).

capacitor.config

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

Panoramica API

getPendingInvocations

Restituisce le invocazioni messe in coda prima che JavaScript fosse pronto.

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

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

removePendingInvocation

Rimuovi un'invocazione in sospeso dopo che il tuo handler l'ha elaborata.

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

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

setEntityCatalog

Persisti un catalogo di entità per una determinata stringa di tipo.

Alimenta i parametri delle entità di Siri e Shortcuts senza nuovo Swift per riga.

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

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

setHomeScreenShortcutItems

Sostituisci le quick actions della Home Screen (UIApplicationShortcutItems).

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

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

indexSpotlightEntities

Indicizza gli elementi Spotlight per il dominio della tua app.

Utilizza CSSearchableItem su iOS 16 e versioni successive. Su iOS 18 e versioni successive dona anche IndexedEntity valori tramite indexAppEntities e associateAppEntity.

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

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

removeSpotlightEntities

Rimuovi gli elementi Spotlight tramite ID.

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

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

performAppleSchemaTemplate

Metti in coda un handler JavaScript per un template di schema Apple alpha.

Non chiama le API private di Mail o gli schemi di sistema. Si limita a mettere in coda un'invocazione (ad esempio appleSchemaMailCreateDraft) da gestire per la tua app code.

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

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

Riferimento ai tipi

AppIntentInvocation

Un'invocazione in stile App Intent in sospeso, in attesa di 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

Una riga in un catalogo di entità runtime utilizzato dai parametri di Siri e 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

Elemento di azione rapida della Home Screen.

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à ricercabile in 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

Identificatori del template dello schema Apple in versione alpha, forniti dal 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

Origine dell'invocazione.

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

Fonte di verità

Questa pagina è generata dal src/definitions.ts. Riesegui la sync quando il API pubblico cambia upstream.