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で名前付きフレームを切り替えるだけで十分な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と接続します。 Docs: /docs/plugins/widget-kit/ Using @capgo/capacitor-widget-kit 実装詳細については @capgo/capacitor-widget-kit に Getting Started 実装詳細については Getting Started に Capgo プラグイン ディレクトリ 実装詳細については Capgo プラグイン ディレクトリ に Capacitor プラグイン ( Capgo によって提供 ) 実装詳細については Capacitor プラグイン ( Capgo によって提供 ) に プラグインの追加または更新 実装詳細については プラグインの追加または更新 に