始めて

インストール

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

インポート

import { CapgoWidgetKit } from '@capgo/capacitor-widget-kit';

iOS セットアップ

Live アクティビティとウィジェットキット拡張機能の場合、ネイティブアプリを最初に設定してください:

• iOS 17+ を使用して、可能な限りインタラクティブなライブアクティビティボタンを使用します。
• 追加 NSSupportsLiveActivities アプリ Info.plist に追加する場合
• ActivityKit を使用する場合、
• 同じアプリ グループをアプリのターゲットとウィジェット拡張のターゲットに追加してください。 CapgoWidgetKitAppGroup アプリ Info.plist と両方のファイルに、共有アプリ グループ識別子を設定します。

<key>CapgoWidgetKitAppGroup</key>
<string>group.app.capgo.widgetkit.exampleapp.widgetkit</string>

サポートを確認

const { supported, reason } = await CapgoWidgetKit.areActivitiesSupported();

if (!supported) {
  console.log('WidgetKit bridge unavailable:', reason);
}

オプション 1: SVG テンプレート アクティビティ

ウィジェットが解決された SVG をレンダリングできる場合にこのモードを使用します。 プラグインは状態を保存し、プレースホルダーを解決し、タップ アクションを適用し、SVG フレームを切り替え、タイマー状態を一貫性を持って維持します。

const { activity } = await CapgoWidgetKit.startTemplateActivity({
  activityId: 'workout-session-1',
  openUrl: 'myapp://workout/session-1',
  state: {
    title: 'Chest Day',
    frame: 'summary',
    restDurationMs: 90000,
  },
  definition: {
    id: 'workout-card',
    timers: [
      {
        id: 'rest',
        durationPath: 'state.restDurationMs',
      },
    ],
    actions: [
      {
        id: 'next-frame',
        eventName: 'widget.frame.changed',
        frameMutations: [
          {
            op: 'next',
            path: 'frame',
            surface: 'lockScreen',
          },
        ],
      },
      {
        id: 'toggle-rest',
        eventName: 'widget.timer.toggled',
        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>`,
          },
        ],
      },
    },
  },
});

アプリからアクションを実行

ネイティブ ウィジェットはホットスポット/アクション ワイヤリングを通じて同じアクションをトリガーできます。 アプリケーションは直接実行することもできます:

await CapgoWidgetKit.performTemplateAction({
  activityId: activity.activityId,
  actionId: 'toggle-rest',
  sourceId: 'app-pause-play-button',
});

イベントをWidgetで処理

アクションは、起動または再開後にWidgetのインタラクションを処理できるように、イベントを発行します：

const { events } = await CapgoWidgetKit.listTemplateEvents({
  activityId: activity.activityId,
  unacknowledgedOnly: true,
});

for (const event of events) {
  console.log('Widget event:', event.eventName, event.state, event.timers);
}

await CapgoWidgetKit.acknowledgeTemplateEvents({
  activityId: activity.activityId,
});

アクティビティを更新または終了

await CapgoWidgetKit.updateTemplateActivity({
  activityId: activity.activityId,
  state: {
    title: 'Back Day',
    frame: 'summary',
    restDurationMs: 120000,
  },
});

await CapgoWidgetKit.endTemplateActivity({
  activityId: activity.activityId,
  state: { title: 'Workout complete', frame: 'summary' },
});

フレームの変更

フレームの変更は、現在のフレームIDを状態に書き込む。レイアウトは、そのIDを読み取ることができます。 frameIdPath.

オペレーション	行動
set	特定のフレームIDを設定します。 {{...}} プレーン文字列は、リテラルフレームIDとして扱われます。テンプレートは最初に解決されます。
next	次のフレームに移動します。 frameIds または、宣言されたフレーム surface.
previous	前のフレームに移動します。
toggle	最初の2つのフレームの間を切り替えます、または現在のフレームと frameId.

不正なフレームIDは、選択可能なフレームリストがわかっている場合の変異には無視されます。したがって、レンダリングされた表面と状態は同期されます。

タイマーミューテーション

タイマーミューテーションは、 definition.timers.

操作	動作
start / restart	ゼロから始めるには、現在の時間を使用します。
pause	経過時間を保存し、クリアします。 startedAt.
resume	一時停止したタイマーだけを再開します。停止したタイマーは、明示的な開始または再起動まで停止状態のままです。
toggle	実行中のタイマーを一時停止するか、再開するタイマーを再開します。
reset	経過時間をクリアし、アイドル状態に戻ります。
stop	実行中の進捗をクリアし、タイマーを停止します。
setDuration	時間の変更後のステータスを再計算します。

タイマー バインディングは、SVG、、および関連フィールドで利用可能です。 {{timers.<id>.remainingText}}, {{timers.<id>.elapsedMs}}, {{timers.<id>.status}}オプション 2: フル ネイティブ ウィジェット セッション

セクションのタイトル “オプション 2: フル ネイティブ ウィジェット セッション”

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 { sessions } = await CapgoWidgetKit.listWidgetSessions();
console.log('Known widget sessions:', sessions);

非同期ウィジェットメッセージ

メッセージは、後で返信が必要な作業をカバーします。たとえば、ウィジェットがデータを同期するようにアプリに要求する場合です。

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

ジョブを失敗させるには error 代わりに response:

await CapgoWidgetKit.completeWidgetMessage({
  messageId: message.messageId,
  error: 'Network unavailable',
});

completeWidgetMessage is idempotentです。メッセージが既に完了または失敗している場合、繰り返し呼び出しは既存のメッセージ スナップショットを返します。

ネイティブセッションを停止

await CapgoWidgetKit.stopWidgetSession({
  widgetId: session.widgetId,
  state: { isRunning: false },
});

API グループ

グループ	API
機能	areActivitiesSupported, getPluginVersion
SVG アクティビティ ライフサイクル	startTemplateActivity, updateTemplateActivity, endTemplateActivity, getTemplateActivity, listTemplateActivities
SVG アクションとイベント	performTemplateAction, listTemplateEvents, acknowledgeTemplateEvents
ネイティブ ウィジェット セッション	startWidgetSession, updateWidgetSession, stopWidgetSession, getWidgetSession, listWidgetSessions
ネイティブ ウィジェット メッセージ	sendWidgetMessage, listWidgetMessages, acknowledgeWidgetMessages, completeWidgetMessage

真実の源

プラグイン リポジトリのフル タイプ リファレンスはここにあります src/definitions.ts.

Getting Startedから続けてください

Capacitorを使用している場合 Capacitorを使用して native pluginの作業計画に使用するには、Capacitorを @capgo/capacitor-widget-kitを使用してCapacitorのnative機能と接続する @capgo/capacitor-widget-kitの使用におけるnative機能 @Capgo Plugin Directory @Capgo Plugin Directoryにおける製品ワークフロー @Capacitor Plugins by Capgo @Capacitor Plugins by Capgoにおける実装詳細 プラグインの追加または更新 実装詳細の追加または更新の場合の詳細について イオニック エンタープライズ プラグインの代替 イオニック エンタープライズ プラグインの製品ワークフローについて