ウィジェットキット

@capgo/capacitor-widget-kitを使用します

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

• Render resolved SVG template surfaces with frame switching, tap hotspots, and pause/play timers.
• Keep the widget fully native while the app and widget share JSON session state and async messages.

Install

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

When To Use SVG Templates

SVGテンプレートを使用する場合、ウィジェットの表面は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

Use full-native sessions when the widget UI is better built directly in Swift, Kotlin, or Java. Capacitor still starts and stops the session, keeps shared state current, and queues work between app and widget code.

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 { 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 WidgetKitとLive Activitiesの場合、アプリとウィジェット拡張のターゲットにアプリ グループを設定し、両方のファイルに設定します。 CapgoWidgetKitAppGroup インタラクティブなボタンには、プラグインが提供するネイティブ ブリッジとアクション インテントを接続するウィジェット拡張が必要です。 Info.plist フル リファレンス

__CAPGO_KEEP_0__

• https://GitHub.com/Cap-go/__CAPGO_KEEP_1__-widget-kit/ https://github.com/Cap-go/capacitor-widget-kit/
• 使用中の@__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-widget-kitから続けてください。

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

Capgoを使用している場合 @capgo/capacitor-widget-kitを使用して、ネイティブプラグインの作業計画を立てる ネイティブプラグインの作業計画を立てるには、@__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-widget-kitと接続する @capgo/capacitor-widget-kitの実装詳細 for the implementation detail in @capgo/capacitor-widget-kit, __CAPGO_KEEP_0__ プラグイン ディレクトリ __CAPGO_KEEP_0__ プラグイン ディレクトリの製品ワークフロー Capgo プラグインズ by __CAPGO_KEEP_1__ Capgo プラグインズ by __CAPGO_KEEP_1__の実装詳細 Capacitor Plugins by Capgo for the implementation detail in Capacitor Plugins by Capgo, and プラグインの追加または更新 実装詳細については、プラグインの追加または更新のページを参照してください。