はじめましょう

インストール

AI-Assisted セットアップを使用してプラグインをインストールできます。AIツールに Capgo スキルを追加するには、以下のコマンドを実行してください。

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

次に、以下の質問を使用してください:

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

Manual Setupを使用する場合は、以下のコマンドを実行して、下記のプラットフォーム固有の説明を参照してください。

bun add @capgo/capacitor-widget-kit
bunx cap sync

Import

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

iOSセットアップ

Liveアクティビティとウィジェットキット拡張機能の場合、ネイティブアプリを設定する必要があります:

• 可能な限り、iOS 17+を使用して、インタラクティブなLiveアクティビティボタンを使用してください。
• 追加 NSSupportsLiveActivities アプリに追加 Info.plist ActivityKitを使用する場合
• アプリターゲットとウィジェット拡張ターゲットに同じApp Groupを追加する
• 設定 CapgoWidgetKitAppGroup 両方の Info.plist ファイルに共有App Group識別子を追加する

<key>CapgoWidgetKitAppGroup</key>
<string>group.app.capgo.widgetkit.exampleapp.widgetkit</string>

サポートを確認

const { supported, reason } = await CapgoWidgetKit.areActivitiesSupported();

if (!supported) {
  console.log('WidgetKit bridge unavailable:', reason);
}

オプション1: SVGテンプレートアクティビティ

SVG が解決されたときにウィジェットがレンダリングできるモードを使用します。 プラグインは状態を保存し、プレースホルダーを解決し、タップアクションを適用し、SVG フレームを切り替え、タイマー状態を一貫性を持って維持します。

const { activity } = await CapgoWidgetKit.startTemplateActivity({
  activityId: 'workout-session-1',
  openUrl: 'myapp://workout/session-1',
  state: {
    title: 'Chest Day',
    frame: 'summary',
    restDurationMs: 90000,
  },
  definition: {
    id: 'workout-card',
    timers: [
      {
        id: 'rest',
        durationPath: 'state.restDurationMs',
      },
    ],
    actions: [
      {
        id: 'next-frame',
        eventName: 'widget.frame.changed',
        frameMutations: [
          {
            op: 'next',
            path: 'frame',
            surface: 'lockScreen',
          },
        ],
      },
      {
        id: 'toggle-rest',
        eventName: 'widget.timer.toggled',
        timerMutations: [
          {
            op: 'toggle',
            timerId: 'rest',
          },
        ],
      },
    ],
    layouts: {
      lockScreen: {
        width: 100,
        height: 40,
        frameIdPath: 'state.frame',
        frames: [
          {
            id: 'summary',
            hotspots: [{ id: 'switch', actionId: 'next-frame', x: 0, y: 0, width: 100, height: 40 }],
            svg: `<svg viewBox="0 0 100 40"><text x="6" y="22">{{state.title}}</text></svg>`,
          },
          {
            id: 'timer',
            hotspots: [{ id: 'pause-play', actionId: 'toggle-rest', x: 0, y: 0, width: 100, height: 40 }],
            svg: `<svg viewBox="0 0 100 40"><text x="6" y="22">{{timers.rest.remainingText}}</text></svg>`,
          },
        ],
      },
    },
  },
});

アプリからアクションを実行

ネイティブウィジェットはホットスポット/アクションのワイヤリングを通じて同じアクションをトリガーできます。 アプリは直接実行することもできます:

await CapgoWidgetKit.performTemplateAction({
  activityId: activity.activityId,
  actionId: 'toggle-rest',
  sourceId: 'app-pause-play-button',
});

ウィジェットイベントを処理

アクションはイベントを発行するため、アプリは起動または再開後にウィジェットのインタラクションを処理できます:

const { events } = await CapgoWidgetKit.listTemplateEvents({
  activityId: activity.activityId,
  unacknowledgedOnly: true,
});

for (const event of events) {
  console.log('Widget event:', event.eventName, event.state, event.timers);
}

await CapgoWidgetKit.acknowledgeTemplateEvents({
  activityId: activity.activityId,
});

アクティビティを更新または終了

await CapgoWidgetKit.updateTemplateActivity({
  activityId: activity.activityId,
  state: {
    title: 'Back Day',
    frame: 'summary',
    restDurationMs: 120000,
  },
});

await CapgoWidgetKit.endTemplateActivity({
  activityId: activity.activityId,
  state: { title: 'Workout complete', frame: 'summary' },
});

フレームの変更

フレームの変更は、現在のフレームIDを状態に書き込む。レイアウトは、そのIDを読み取ることができる。 frameIdPath.

オペレーション	ビヘイビア
set	特定のフレームIDを設定。プレーン文字列は、文字列として扱われ、リテラルフレームIDとして扱われる。 {{...}} テンプレートは先に解決される。
next	次のフレームに移動する frameIds または、宣言されたフレーム surface.
previous	前のフレームに移動する
toggle	フレームを最初の2つ、または現在のフレームと切り替えます。 frameId.

不正なフレームIDは、選択可能なフレームリストが知られている場合、変異がレンダリングされた表面と同期するので無視されます。

タイマーミューテーション

タイマーミューテーションは、指定された名前のタイマーを対象とします。 definition.timers.

操作	動作
start / restart	現在の時間を0から始めます。
pause	経過時間を保存し、クリアします。 startedAt.
resume	一時停止したタイマーを再開します。停止したタイマーは、明示的な開始または再起動まで停止状態のままです。
toggle	実行中のタイマーを一時停止するか、再開します。
reset	経過時間をクリアし、アイドル状態に戻します。
stop	実行時間の進行をクリアし、タイマーを停止します。
setDuration	期間の変更後、ステータスを再計算します。

タイマー バインディングはSVGに利用可能であり、 {{timers.<id>.remainingText}}, {{timers.<id>.elapsedMs}}, {{timers.<id>.status}}、関連フィールドとともに。

オプション 2: フル ネイティブ ウィジェット セッション

Use this mode when the widget UI is built in native code. The plugin gives the app and widget a shared session record and a message queue.

const { session } = await CapgoWidgetKit.startWidgetSession({
  widgetId: 'native-session-1',
  kind: 'workout-controls',
  state: { isRunning: true, selectedSetId: 'set-1' },
  metadata: { accent: '#00d69c' },
});

await CapgoWidgetKit.updateWidgetSession({
  widgetId: session.widgetId,
  merge: true,
  state: { isRunning: false },
});

const { sessions } = await CapgoWidgetKit.listWidgetSessions();
console.log('Known widget sessions:', sessions);

非同期ウィジェット メッセージ

メッセージは、後で応答が必要な作業をカバーします。 たとえば、ウィジェットがアプリにデータを同期するように求めるメッセージです。

const { message } = await CapgoWidgetKit.sendWidgetMessage({
  widgetId: session.widgetId,
  direction: 'widgetToApp',
  name: 'syncWorkoutSet',
  payload: { setId: 'set-1' },
  expectsResponse: true,
});

await CapgoWidgetKit.acknowledgeWidgetMessages({
  messageIds: [message.messageId],
});

await CapgoWidgetKit.completeWidgetMessage({
  messageId: message.messageId,
  response: { synced: true },
});

ジョブを失敗させるには、パスします。 error 代わりに response:

await CapgoWidgetKit.completeWidgetMessage({
  messageId: message.messageId,
  error: 'Network unavailable',
});

completeWidgetMessage は idempotent です。メッセージが既に完了または失敗している場合、繰り返し呼び出しは既存のメッセージ スナップショットを返します。

ネイティブ セッションを停止

await CapgoWidgetKit.stopWidgetSession({
  widgetId: session.widgetId,
  state: { isRunning: false },
});

API グループ

グループ	API
機能	areActivitiesSupported, getPluginVersion
SVGのライフサイクル	startTemplateActivity, updateTemplateActivity, endTemplateActivity, getTemplateActivity, listTemplateActivities
SVGのアクションとイベント	performTemplateAction, listTemplateEvents, acknowledgeTemplateEvents
ネイティブウィジェットセッション	startWidgetSession, updateWidgetSession, stopWidgetSession, getWidgetSession, listWidgetSessions
ネイティブウィジェットメッセージ	sendWidgetMessage, listWidgetMessages, acknowledgeWidgetMessages, completeWidgetMessage

真実の源

プラグインリポジトリのフルタイプ参照は src/definitions.ts.

Getting Startedから続けてください

Capgoを使用している場合 Getting Started ネイティブプラグインの作業を計画するには、 Capgoで使用する@capgo/capacitorウィジェットキット Capgoのネイティブ機能のために@capgo/capacitor-ウィジェットキットを使用します。 Capgo プラグインディレクトリ for the product workflow in Capgo Plugin Directory, Capacitor プラグインは Capgo によって提供されます。 Capgoのプラグインの実装詳細については、CapacitorプラグインによってCapgoで実装されます。 プラグインの追加または更新 プラグインの追加または更新で実装詳細 Capacitorエンタープライズプラグインの代替 Capacitorエンタープライズプラグインの代替で製品ワークフロー