始め方

Install

Capgoの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セットアップを使用する場合は、以下のコマンドを実行してプラグインをインストールし、以下のプラットフォーム固有の指示に従ってください:

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

Import

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

iOS設定

ライブアクティビティやウィジェットキット拡張機能を使用する場合、まずネイティブアプリを設定してください:

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

<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',
});

イベントをWidgetで処理

アクションは、起動または再開後にWidgetのインタラクションを処理できるように、イベントを発行します:

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	ゼロから始めるには、現在の時間を使用します。
pause	__CAPGO_KEEP_0__でタイマーをストアし、クリアします。 startedAt.
resume	一時停止したタイマーを再開するだけです。停止したタイマーは、明示的な開始または再起動まで停止状態のままです。
toggle	実行中のタイマーを一時停止または一時停止中のタイマーを再開します。
reset	__CAPGO_KEEP_0__をクリアし、アイドル状態に戻ります。
stop	実行中の進捗をクリアし、タイマーを停止します。
setDuration	時間の変更後、状態を再計算します。

タイマー バインディングは、SVGの、および関連フィールドに利用可能です。 {{timers.<id>.remainingText}}, {{timers.<id>.elapsedMs}}, {{timers.<id>.status}}オプション 2: フル ネイティブ ウィジェット セッション

「オプション 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 __CAPGO_KEEP_0__は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

真実の源

The full type reference lives in the plugin repository at src/definitions.ts.

Getting Startedから続けてください

Capgoを使用している場合 Getting Started Capgoと連携して Capgoの@capgo/capacitor-widget-kitを使用 Capgoの@capgo/capacitor-widget-kitのnative capability Capgo Plugin Directory for the product workflow in Capgo Plugin Directory, Capacitor Plugins by Capgo for the implementation detail in Capacitor Plugins by Capgo, プラグインの追加または更新 実装詳細の追加または更新の場合の実装詳細について、 Ionic Enterprise プラグインの代替 Ionic Enterprise プラグインの製品ワークフローについて