はじめに

インストール

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

インポート

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

iOS セットアップ

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

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

<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で処理

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

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__内で作成されたウィジェットUIを使用する場合に、このモードを使用してください。 startedAt.
resume	一時停止したタイマーは、明示的な開始または再起動まで停止状態のままです。
toggle	実行中のタイマーを一時停止または一時停止したタイマーを再開します。
reset	経過時間をクリアし、アイドル状態に戻ります。
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);

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

__CAPGO_KEEP_0__には、後で返信が必要な作業をカバーするメッセージが含まれます。例えば、ウィジェットがアプリにデータの同期を求めるメッセージです。

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

ジョブを失敗させるには、"To fail the job, pass"を実行してください。 error の代わりに response:

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

completeWidgetMessage __CAPGO_KEEP_0__は、既に完了したまたは失敗したメッセージの場合も、再度呼び出しても既存のメッセージのスナップショットを返します。

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

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.