ガイド
How to use Widget Kit in Capacitor
@capgo/capacitor-widget-kitを使用すると
@capgo/capacitor-widget-kit lets a Capacitor app drive WidgetKit and Live Activity experiences in two ways:
- 解決されたSVGテンプレート表面をレンダリングする
- フレーム切り替え、タップホットスポット、タイマー停止/再生
Install
bun add @capgo/capacitor-widget-kit
bunx cap sync
JSONセッション状態と非同期メッセージを共有します。
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 });
フルネイティブセッションを使用する場合
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/capacitorウィジェットキットから続けて
__CAPGO_KEEP_0__-widget-kitを使用している場合、続けてください。 Using @capgo/capacitor-widget-kit native plugin work を計画するには、を接続する ネイティブのプラグインの作業を計画する場合、@capgo/capacitor-widget-kitと接続してください。 ネイティブのプラグインの作業を計画する場合、@capgo/capacitor-widget-kitと接続してください。 はじめに はじめにの実装詳細について Capgo プラグインディレクトリ Capgo プラグインディレクトリの製品ワークフローについて Capacitor Capgo プラグイン はじめにの実装詳細について、Capacitor Capgo プラグイン、 プラグインの追加または更新 プラグインの追加または更新の実装詳細について