ガイド
Capacitor での Widget Kit の使い方
@capgo/capacitor-widget-kit の使用
@capgo/capacitor-widget-kit Capacitor アプリから、2つの方法で WidgetKit と Live Activity を制御できます：
- フレーム切り替え、タップ可能なホットスポット、一時停止/再生タイマーを備えた、解決済みの SVG テンプレートを描画します。
- アプリとウィジェット間で 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>`,
},
],
},
},
},
});
アプリ内での 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 });
Full-Nativeセッションを使用すべきケース
WidgetのUIをSwift、Kotlin、またはJavaで直接構築する方が適している場合は、full-nativeセッションを使用してください。Capacitor は引き続きセッションの開始と停止を管理し、共有状態を最新に保ち、アプリと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 },
});
Widgetとアプリ間で非同期処理をキューイングする
メッセージはアプリからWidget、またはWidgetからアプリへと送受信できます。メッセージは、確認および完了されるまで保留状態となります。
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では、アプリとWidget extensionの両方のターゲットでApp Groupを設定し、以下をセットしてください： CapgoWidgetKitAppGroup の両方に Info.plist ファイル。インタラクティブなボタンには、プラグインが提供するネイティブブリッジとaction intentを接続するwidget extensionが必要です。
リファレンス全文
- GitHub: https://github.com/Cap-go/capacitor-widget-kit/
- ドキュメント: /docs/plugins/widget-kit/
@capgo/capacitor-widget-kit の使用方法から次へ
使用している場合 @capgo/capacitor-widget-kit の使用 ネイティブプラグインの作業を計画するには、次と連携してください： @capgo/capacitor-widget-kit @capgo/capacitor-widget-kit の実装詳細については、 スタートガイド スタートガイドの実装詳細については、 Capgo プラグインディレクトリ Capgo プラグインディレクトリのプロダクトワークフローについては、 Capgo による Capacitor プラグイン Capgo による Capacitor Plugins の実装詳細、および プラグインの追加または更新 プラグインの追加または更新に関する実装詳細についてはこちら。