Widget Kit

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

@capgo/capacitor-widget-kit CapacitorアプリはWidgetKitとLive Activityのエクスペリエンスを2つの方法で制御できます。

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

インストール

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

When To Use SVG Templates

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

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

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

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

ハンドルウィジェットアクションインザアプリ

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

フルネイティブセッションを使用する場合、ウィジェットUIは直接Swift、Kotlin、またはJavaで構築される方が良いでしょう。__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 },
});

アプリからウィジェットへのメッセージやウィジェットからアプリへのメッセージが流れます。メッセージは承認および完了されるまで待機します。

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

フルリファレンス

• GitHub: https://github.com/Cap-go/capacitor-widget-kit/
• ドキュメント: /docs/plugins/widget-kit/

capgoの@capacitor-widget-kitを使用している場合

__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-widget-kitを使用して ネイティブプラグインの作業を計画する場合、@capgo/capacitor-widget-kitと接続します。 Full Reference https://capgo.com/Cap-go/capacitor-widget-kit/ 実装詳細については @capgo/capacitor-widget-kit に Getting Started 実装詳細については Getting Started に Capgo プラグイン ディレクトリ 実装詳細については Capgo プラグイン ディレクトリ に Capacitor プラグイン ( Capgo によって提供) 実装詳細については Capacitor プラグイン ( Capgo によって提供) に プラグインの追加または更新 実装詳細については プラグインの追加または更新 に