Getting Started

インストール

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

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.

コピー

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

コピー

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

コピーをクリップボードにコピーするにはクリックしてください:「iOS セットアップ」

iOS 17 以降を使用する場合は、可能な限りインタラクティブなライブ アクティビティ ボタンを使用します。

• ActivityKit を使用する場合にのみ、App への追加
• App への追加 NSSupportsLiveActivities App グループを同じ App グループをアプリターゲットとウィジェット拡張ターゲットに追加します。 Info.plist App グループ ID を共有する両方のファイルに、App グループ ID を設定します。
• コピー
• サポートを確認 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',
});

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

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

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

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

__CAPGO_KEEP_0__

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

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 Groups

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

真実の源

The full type reference lives in the plugin repository at src/definitions.ts.

Capgoから始めて続ける

あなたが使用している場合 Getting Started ネイティブ プラグインの作業を計画するには、 @capgo/capacitor-widget-kitと接続する @capgo/capacitor-widget-kitのネイティブ機能の場合 Capgo プラグイン ディレクトリ Capgo プラグイン ディレクトリの製品ワークフロー Capacitor Plugins by Capgo for the implementation detail in Capacitor Plugins by Capgo, __CAPGO_KEEP_0__ プラグインの追加または更新 __CAPGO_KEEP_0__ プラグインの追加または更新の実装詳細 Ionic Enterprise プラグインの代替 __CAPGO_KEEP_0__