@capgo/capacitor-widget-kit

概要

@capgo/capacitor-widget-kit Capacitor アプリには、ウィジェットと Live Activities を 2 つの方法でドライブする機能が提供されます。

• SVG テンプレート アクティビティ: WidgetKit サーフェイスを SVG で定義し、タップで名前付きフレームを切り替え、タイマーを停止/再生、JSON ステートを変更し、アプリ内でアクション イベントを収集します。
• フルネイティブ ウィジェット セッション: ウィジェット UI を完全に Swift/Kotlin/Java で管理し、Capacitor が共有 JSON ステートとアプリ間のメッセージ、またはウィジェット間のメッセージを所有します。

SVGテンプレートを使用するには、ウィジェットが解決されたSVG文字列からレンダリングできる場合に限ります。フルネイティブセッションを使用するには、ウィジェットがカスタムネイティブUIが必要ですが、開始、停止、同期状態、またはアプリに非同期作業を依頼する必要がある場合に限ります。

モードを選択

最適	主なAPI	SVGテンプレートの活動
ライブアクティビティまたはウィジェット表面がSVG出力からレンダリングされるもの	フルネイティブウィジェットセッション	startTemplateActivity, performTemplateAction, listTemplateEvents
ネイティブレンダリングされたウィジェットが共有状態と非同期ジョブが必要なもの	両方のモードは同じアプリ内で機能することができます。たとえば、トレーニングアプリでは、高速フレーム/タイマーコントロール用にSVGライブアクティビティを使用し、ホームスクリーンウィジェット用にフルネイティブウィジェットセッションを使用できます。	startWidgetSession, updateWidgetSession, sendWidgetMessage

SVGテンプレートの機能

__CAPGO_KEEP_0__

SVG テンプレートには、インタラクティブなウィジェット表面のために必要な部分が含まれています:

• frames 名前付きの SVG バリエーション、 summary, timerまたは details.
• frameMutations ホットスポットアクション後にフレームをスイッチ、タグル、またはステップする。
• timerMutations 開始、停止、再生、タグル、リセット、停止、またはタイマーダイレクションを変更します。
• patches JSON ステートを更新するには、文字列値、テンプレート、タイムスタンプ、増分、タグル、または未設定の操作を使用します。
• hotspots タップエリアをアクション識別子にマップします。
• listTemplateEvents アプリは、ウィジェットから発生したアクションを後で処理できます。

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

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

フルネイティブ セッションは、UI をネイティブでレンダリングするウィジェット用です。

• startWidgetSession code ウィジェットのネイティブ UI をレンダリングするウィジェットのための共有状態とメタデータを生成します。
• updateWidgetSession __CAPGO_KEEP_0__ の状態をマージまたは置き換え、セッションを再度アクティブにします。
• stopWidgetSession __CAPGO_KEEP_0__ の最終状態を記録し、セッションを停止します。
• sendWidgetMessage アプリケーションからウィジェットまたはウィジェットからアプリケーションへの作業をキューにします。
• acknowledgeWidgetMessages メッセージを受信済みとしてマークします。
• completeWidgetMessage 非同期ジョブのレスポンスまたは失敗を格納します。

完了したまたは失敗したメッセージは、再試行しても既存の結果を上書きせずに返します。

パブリック API

メソッド	説明
areActivitiesSupported	現在のデバイスでネイティブ テンプレート アクティビティ ブリッジを実行できるかどうかを確認します。
startTemplateActivity	SVG テンプレート アクティビティを永続化し、ネイティブ ライブ アクティビティ ブリッジを開始します。
updateTemplateActivity	アクティビティ定義、状態、または URL を置き換えます。
endTemplateActivity	実行中のアクティビティを終了し、最後の 1 つの状態スナップショットを永続化するオプションがあります。
performTemplateAction	宣言的パッチ、フレーム マイグレーション、タイマー マイグレーション、イベント ロギングを実行します。
getTemplateActivity	保存されたテンプレート アクティビティを 1 つ読み取ります。
listTemplateActivities	保存されたすべてのテンプレート アクティビティをリストします。
listTemplateEvents	テンプレート アクションから発生したアクション イベントを読み取ります。
acknowledgeTemplateEvents	テンプレート イベントを処理済みとしてマークします。
startWidgetSession	共有 JSON 状態をバックアップするフル ネイティブ ウィジェット セッションを開始します。
updateWidgetSession	完全ネイティブウィジェットセッションをマージまたは上書きします。
stopWidgetSession	完全ネイティブウィジェットセッションを停止し、オプションで最終状態を保存します。
getWidgetSession	完全ネイティブウィジェットセッションを読み取ります。
listWidgetSessions	すべての完全ネイティブウィジェットセッションをリストします。
sendWidgetMessage	アプリとネイティブウィジェットcode間のメッセージをキューに追加します。
listWidgetMessages	キューされたブリッジメッセージをリストします。
acknowledgeWidgetMessages	ブリッジメッセージを認識します。
completeWidgetMessage	非同期ブリッジメッセージを完了または失敗します。
getPluginVersion	プラットフォーム実装バージョンマーカーを返します。

ネイティブピース

プラグインはウィジェットターゲット用にネイティブヘルパーも提供しています。

• CapgoTemplateWidgetBridge SVG テンプレート表面を解決します。 svg, frameId, hotspots, メタデータ。
• CapgoTemplateActionIntent iOS ウィジェットのインタラクティブなボタンをテンプレートアクションに接続します。
• CapgoNativeWidgetBridge ネイティブウィジェット code からフルネイティブセッションとメッセージを読み込みます。
• Android テンプレートヘルパーは、受信アクションとウィジェットブリッジの動作をマッチングします。

真実の源

API リファレンスはプラグインリポジトリから同期されています。 src/definitions.ts プラグインリポジトリ