ウィジェット キット __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

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	最初の2つのフレームの間を切り替える、または現在のフレームと切り替える
toggle	Copy to clipboard 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 は 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を Using @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-widget-kit Using @capgo/capacitor-widget-kit Capacitorのネイティブ機能の使用に@capgo/capacitor-widget-kitを使用します。 Capgo プラグインディレクトリ Capgoの製品ワークフローについて CapacitorのCapgoによるプラグイン CapacitorのCapgoによるプラグインの実装詳細 プラグインの追加または更新 __CAPGO_KEEP_0__のプラグインの__CAPGO_KEEP_1__による実装詳細 Ionic Enterprise プラグインの代替 __CAPGO_KEEP_0__のIonic Enterprise プラグイン代替の製品ワークフロー