ウィジェットキット

@capgo/capacitor-widget-kitを使用

@capgo/capacitor-widget-kit Capacitorアプリは、2つの方法でウィジェットキットとライブアクティビティのエクスペリエンスを実行します。

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

インストール

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

SVG テンプレートを使用するタイミング

SVG テンプレートを使用する場合、ウィジェットの表面は SVG で表現できる場合に使用します。アプリはテンプレート定義を保存し、ネイティブ ブリッジはプレースホルダーを解決し、ウィジェットのタップは後で状態を変えることができます。

ワークアウトタイマー、配達状況カード、スポーツスコア、またはコンパクトな UI など、名前付きフレーム間で切り替えるだけで十分な 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>`,
          },
        ],
      },
    },
  },
});

アプリ内でウィジェットアクションを処理する

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

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

フルネイティブ セッションを使用するタイミング

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 ウィジェットキットとライブアクティビティの場合、 CapgoWidgetKitAppGroup アプリとウィジェット拡張機能のターゲットにアプリ グループを設定し、 Info.plist 両方のファイルに設定します。

インタラクティブなボタンには、プラグインが提供するネイティブ ブリッジとアクション インテントを接続するウィジェット拡張機能が必要です。

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

Keep going from Using @capgo/capacitor-widget-kit

__CAPGO_KEEP_0__ を使用して @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-widget-kit を使用している場合 capgo を使用して @capgo/capacitor-widget-kit を使用している場合 ネイティブ プラグインの作業を計画するには、@__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-widget-kit を接続する必要があります。 ネイティブ プラグインの作業を計画するには、@capgo/capacitor-widget-kit を接続する必要があります。 Capacitor-ウィジェットキットの実装詳細については@capgo/capacitor-widget-kitを参照してください。 Getting Started Capacitor-ウィジェットキットの実装詳細についてはGetting Startedを参照してください。 Capgo プラグインディレクトリ Capacitor-ウィジェットキットの製品ワークフローについてはCapgo プラグインディレクトリを参照してください。 Capacitor プラグインのCapgo Capacitor-ウィジェットキットの実装詳細についてはCapacitor プラグインのCapgo、 プラグインの追加または更新 Capacitor-ウィジェットキットの実装詳細についてはプラグインの追加または更新を参照してください。