ウィジェットキット

@capgo/capacitor-widget-kitを使用すると

@capgo/capacitor-widget-kit lets a Capacitor app drive WidgetKit and Live Activity experiences in two ways:

• 解決されたSVGテンプレート表面をフレーム切り替え、タップホットスポット、タイマー停止/再生でレンダリングします。
• アプリとウィジェットはJSONセッション状態と非同期メッセージを共有しながら、完全にネイティブのウィジェットを維持します。

インストール

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

When To Use SVG Templates

SVGテンプレートを使用する場合

ワークアウトタイマーや配達状況のカード、スポーツスコア、または名前付きフレームを切り替えるだけで済むコンパクトなUIなど、適切なフィットはこれらです。

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

const { activity } = await CapgoWidgetKit.startTemplateActivity({
  activityId: 'session-1',
  state: {
    title: 'Chest Day',
    frame: 'summary',
    restDurationMs: 90000,
  },
  definition: {
    id: 'workout-card',
    timers: [{ id: 'rest', durationPath: 'state.restDurationMs' }],
    actions: [
      {
        id: 'next-frame',
        frameMutations: [{ op: 'next', path: 'frame', surface: 'lockScreen' }],
      },
      {
        id: 'toggle-rest',
        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>`,
          },
        ],
      },
    },
  },
});

アプリ内でWidgetアクションを処理する

Widgetアクションはイベントとして保存されます。アプリが再開したときやバックグラウンドシンクステップ後に読み取りおよび承認してください。

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

for (const event of events) {
  console.log(event.actionId, event.state, event.timers);
}

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

When To Use Full-Native Sessions

フルネイティブセッションを使用する場合、Swift、Kotlin、またはJavaで直接UIを構築するのがより適切です。Capacitorはセッションを開始および停止し、共有状態を最新のままにし、codeの間でアプリとWidgetの間で作業をキューイングします。

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

Widgetとアプリの間で非同期作業をキューイング

メッセージはアプリからWidgetまたはWidgetからアプリへの方向に流れます。承認および完了されるまで待機します。

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

ジョブが失敗した場合、エラーとともにメッセージを完了してください:

await CapgoWidgetKit.completeWidgetMessage({
  messageId: message.messageId,
  error: 'Sync failed',
});

セッションをきれいに停止する

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

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

ネイティブセットアップノート

iOS ウィジェットキットとライブアクティビティ用に、 CapgoWidgetKitAppGroup アプリとウィジェット拡張機能のターゲットにアプリ グループを設定し、 Info.plist 両方のファイルに設定します。

インタラクティブなボタンには、

• GitHub: https://github.com/Cap-go/capacitor-widget-kit/
• __CAPGO_KEEP_0__:

https://capgo.com/Cap-go/capacitor-widget-kit/

ドキュメント: /docs/plugins/widget-kit/ Using @capgo/capacitor-widget-kit Capacitor-ウィジェットキットを使用している場合 @capgo/capacitor-widget-kit Capgoの実装詳細については@capgo/capacitor-widget-kitを参照してください。 Getting Started Capgoの実装詳細についてはGetting Startedを参照してください。 Capgo Plugin Directory for the product workflow in Capgo Plugin Directory, Capacitor Plugins by Capgo for the implementation detail in Capacitor Plugins by Capgo, and Capgoプラグインの追加または更新 Capgoプラグインの実装詳細についてはCapgoプラグインの追加または更新を参照してください。