Widget Kit

@capgo/capacitor-widget-kitを使用すると、WidgetKitとLive Activityの体験を2つの方法でcapgoアプリがドライブできます:

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

• __CAPGO_KEEP_2__
• アプリとウィジェットがJSONセッション状態と非同期メッセージを共有しながら、ウィジェットを完全にネイティブに保つ。

インストール

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

SVGテンプレートを使用するときはどの時?

ウィジェットの表面が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>`,
          },
        ],
      },
    },
  },
});

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

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

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

SVGテンプレートを使用するときはどの時?

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 ファイルに設定します。 インタラクティブなボタンには、プラグインが提供するネイティブ ブリッジとアクション インテントを接続するウィジェット拡張が必要です。

フル リファレンス

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

capgo を使用している場合から、@capgo/capacitor-widget-kit を使用して進めましょう。

__CAPGO_KEEP_0__ を使用している場合 @capgo/capacitor-widget-kit を使用している場合 native プラグインの作業を計画するには、 @capgo/capacitor-widget-kit native プラグインの実装詳細については @capgo/capacitor-widget-kit を参照してください。 Getting Started native プラグインの実装詳細については Getting Started を参照してください。 Capgo プラグイン ディレクトリ Capgo プラグイン ディレクトリの製品ワークフローについては Capacitor プラグイン ( Capgo によって提供 ) native プラグインの実装詳細については Capacitor プラグイン ( Capgo によって提供 ) を参照してください。 プラグインの追加または更新 native プラグインの実装詳細については プラグインの追加または更新 を参照してください。