ウィジェット キット __CAPGO_KEEP_0__ リポジトリ

インストール

AI-Assisted Setupを使用してプラグインをインストールできます。AIツールにCapgoスキルを追加するには、以下のコマンドを使用してください。

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

次のプロンプトを使用してください。

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-widget-kit` plugin in my project.

Manual Setup を使用する場合は、以下のコマンドを実行して、下記のプラットフォーム固有の手順に従ってプラグインをインストールしてください。

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

インポート

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

iOS セットアップ

ライブアクティビティやウィジェットキット拡張機能を使用する場合は、ネイティブアプリをまず設定してください:

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

<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 テンプレート Activity

このモードを使用するには、ウィジェットは解決済みの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',
});

ウィジェットイベントを処理

クリップボードにコピー

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:フルネイティブ ウィジェット セッション

Use this mode when the widget UI is built in native code. The plugin gives the app and widget a shared session record and a message queue.

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 __CAPGO_KEEP_0__ は 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.

「始めてから続けてください」セクション

Capgo を使用してネイティブ プラグインの作業を計画している場合、Capgo を Capgo を使用してネイティブ プラグインの作業を計画している場合、Capgo を @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-widget-kit と接続します Capgo を使用してネイティブ プラグインの作業を計画している場合、Capgo を @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-widget-kit と接続します Capgo を使用してネイティブ プラグインの作業を計画している場合、Capgo を @capgo/capacitor-widget-kit と接続します Capacitorのネイティブ機能の使用に@capgo/capacitor-widget-kitを使用します。 Capgo プラグイン ディレクトリ Capgoの製品ワークフローについては、Capgo プラグイン ディレクトリを参照してください。 CapacitorのプラグインはCapgoで提供されています。 Capacitor プラグインの実装詳細については、Capacitor プラグインのCapgoを参照してください。 プラグインの追加または更新 プラグインの追加または更新の実装詳細については、プラグインの追加または更新を参照してください。 Ionic Enterprise プラグインの代替 Ionic Enterprise プラグインの代替の製品ワークフローについては、Ionic Enterprise プラグインの代替を参照してください。