@capgo/capacitor-widget-kit

SVGフレーム、タイマー、アクションホットスポット、フルネイティブのウィジェット状態同期を使って、Capacitor から WidgetKit と Live Activity のサーフェスを構築。

概要

まずはこちらから areActivitiesSupported() および以下に示すその他のコアメソッド。

プラットフォーム対応

プラットフォーム	サポート	備考
iOSと	はい	ネイティブ
Android	はい	ネイティブ
Web	いいえ	Capacitor.getPlatform() でガード

Siri、ショートカット、App Intents

Widget Kitは、 決して SiriやShortcutsとのブリッジです。WidgetKit、ActivityKitによるLive Activitiesテンプレート、およびiOSのインタラクティブなコントロールを、同梱された LiveActivityIntent 型（CapgoTemplateActionIntent, CompleteSetIntent）を通じてサポートしており、保存されたテンプレートの状態を更新し、テンプレートの イベントログに追記します (listTemplateEvents / acknowledgeTemplateEvents).

また、 決して カスタムショートカットフレーズの登録、 AppShortcutsProviderJavaScriptエンティティカタログ、Spotlightアイテム、またはAppleアプリスキーマ。これらには @capgo/capacitor-app-intents を使用します。以下のようなツールとの詳細な比較は expo-app-intents次を参照してください： Siri、ショートカット、ウィジェット.

デモ

モードを選択

モード	最適な用途	主要API
SVGテンプレート・アクティビティ	SVG出力から描画されるLive Activitiesまたはウィジェット画面	`startTemplateActivity`, `performTemplateAction`, `listTemplateEvents`
フルネイティブ・ウィジェット・セッション	共有状態や非同期ジョブが必要なネイティブ描画ウィジェット	`startWidgetSession`, `updateWidgetSession`, `sendWidgetMessage`

両方のモードを同じアプリ内で併用できます。例えば、ワークアウトアプリにおいて、フレームやタイマーの素早い操作にはSVG Live Activityを使用し、よりリッチなネイティブレイアウトを持つホーム画面ウィジェットにはフルネイティブ・ウィジェット・セッションを使用するといった構成が可能です。

SVGテンプレートの機能

SVGテンプレートには、インタラクティブなウィジェット画面に必要な以下の要素が含まれています：

frames 次のような名前付きSVGバリアントを保持します： summary, timer、または details.
frameMutations ホットスポットのアクション後に、switch、toggle、またはフレームのステップ実行を行います。
timerMutations タイマーの開始、一時停止、再開、切り替え、リセット、停止、または継続時間の変更を行います。
patches リテラル値、テンプレート、タイムスタンプ、インクリメント、トグル、またはunset操作を使用してJSONの状態を更新します。
hotspots タップエリアをアクション識別子にマッピングします。
listTemplateEvents アプリがウィジェット経由のアクションを後で処理できるようにします。

ランタイムは、次のようなプレースホルダーを解決します： {{state.title}}, {{timers.rest.remainingText}}や {{meta.template.kind}} ネイティブブリッジがレンダリング用のサーフェスを返す前に実行されます。

フルネイティブブリッジ機能

フルネイティブセッションは、独自のUIをネイティブで描画するウィジェット向けです：

startWidgetSession ネイティブウィジェット code 用の共有状態とメタデータを作成します。
updateWidgetSession 状態をマージまたは置換し、セッションを再度アクティブにします。
stopWidgetSession 最終状態を記録し、セッションを停止状態にします。
sendWidgetMessage アプリからウィジェット、またはウィジェットからアプリへのタスクをキューに追加します。
acknowledgeWidgetMessages メッセージを受信済みとしてマークします。
completeWidgetMessage 非同期ジョブのレスポンスまたは失敗を保存します。

完了後のメッセージは冪等（べきとう）です。完了または失敗したメッセージを再試行しても、上書きされずに既存の結果が返されます。

公開 API

メソッド	説明
`areActivitiesSupported`	現在のデバイスでネイティブのテンプレートアクティビティブリッジが動作するか確認します。
`startTemplateActivity`	SVGテンプレートアクティビティを保存し、ネイティブの Live Update ブリッジを開始します。
`updateTemplateActivity`	アクティビティの定義、状態、または開くURLを更新します。
`endTemplateActivity`	実行中のアクティビティを終了し、必要に応じて最後に状態のスナップショットを保存します。
`performTemplateAction`	宣言的なパッチ、フレームの変更、タイマーの変更、およびイベントログを実行します。
`getTemplateActivity`	保存されているテンプレートアクティビティを1つ読み込みます。
`listTemplateActivities`	保存されているすべてのテンプレートアクティビティを一覧表示します。
`listTemplateEvents`	テンプレートアクションから発行されたアクションイベントを読み取ります。
`acknowledgeTemplateEvents`	テンプレートイベントを処理済みとしてマークします。
`startWidgetSession`	共有JSON状態を使用したフルネイティブのウィジェットセッションを開始します。
`updateWidgetSession`	フルネイティブのウィジェットセッションの状態をマージまたは置換します。
`stopWidgetSession`	フルネイティブのウィジェットセッションを停止し、必要に応じて最終状態を保存します。
`getWidgetSession`	フルネイティブウィジェットのセッションを1件読み取ります。
`listWidgetSessions`	フルネイティブウィジェットのセッションをすべて一覧表示します。
`sendWidgetMessage`	アプリとネイティブウィジェット code の間のメッセージをキューに追加します。
`listWidgetMessages`	キューにあるブリッジメッセージを一覧表示します。
`acknowledgeWidgetMessages`	ブリッジメッセージを確認済みとしてマークします。
`completeWidgetMessage`	非同期ブリッジメッセージを完了または失敗させます。
`getPluginVersion`	プラットフォーム実装のバージョンマーカーを返します。

ネイティブパーツ

このプラグインには、ウィジェットターゲット向けのネイティブヘルパーも同梱されています：

CapgoTemplateWidgetBridge SVGテンプレートのサーフェスを以下に解決します： svg, frameId, hotspots、およびメタデータ。
CapgoTemplateActionIntent インタラクティブなiOSウィジェットのボタンを、テンプレートのアクションに接続します。
CapgoNativeWidgetBridge ネイティブウィジェットの code から、フルネイティブのセッションとメッセージを読み込みます。
Androidのテンプレートヘルパーは、対応するアクションレシーバーとウィジェットブリッジの動作を提供します。

Source of Truth

API のリファレンスは、以下から同期されます： src/definitions.ts プラグインリポジトリ内。

使用している場合 @capgo/capacitor-widget-kit CI/CD自動化を計画するには、次と連携してください @capgo/capacitor-widget-kit の使用「@capgo/capacitor-widget-kit の使用」のネイティブ機能については、 Capgo での CI/CD 設定 Capgo CI/CDでのプロダクトワークフローについては、 Capgo Native Build Capgo Native Buildsでのプロダクトワークフローについては、 Capgo インテグレーション Capgo Integrations でのプロダクトワークフロー、および CI/CD 連携 CI/CD Integration での実装詳細については。