@capgo/capacitor-widget-kit

概要

@capgo/capacitor-widget-kit Capacitor アプリに 2 つの方法でウィジェットとライブ アクティビティを制御するようにします:

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

SVG テンプレートを使用して、解決された SVG 文字列からウィジェットをレンダリングできます。フルネイティブ セッションを使用して、ウィジェットがカスタム ネイティブ UI を必要とする場合でも、ウィジェットが開始、停止、同期、またはアプリに非同期作業を実行するように求めることができます。

デモ

ウィジェットテンプレートフロー

モードを選択

モード	最適なもの	主なAPI
SVGテンプレートアクティビティ	LiveアクティビティまたはSVG出力からウィジェット表面をレンダリング	startTemplateActivity, performTemplateAction, listTemplateEvents
フルネイティブウィジェットセッション	ネイティブレンダリングのウィジェットが共有状態と非同期ジョブが必要	startWidgetSession, updateWidgetSession, sendWidgetMessage

両モードは同じアプリ内で共存できます。例えば、ワークアウトアプリでは、高速フレーム/タイマーコントロール用にSVGライブアクティビティを使用し、ホーム画面ウィジェット用により豊かなネイティブレイアウトを持つフルネイティブウィジェットセッションを使用できます。

SVGテンプレート機能

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

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

ランタイムはプレースホルダーのような {{state.title}}, {{timers.rest.remainingText}}日本語 {{meta.template.kind}} native ブリッジがレンダリング用の表面を返す前に。

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

フルネイティブ セッションは、UI をレンダリングするためのウィジェットに使用されます。

• startWidgetSession native ウィジェットの code に共有された状態とメタデータを作成します。
• updateWidgetSession 状態とセッションを再度有効にします。
• stopWidgetSession 最後の状態を記録し、セッションを停止します。
• sendWidgetMessage アプリからウィジェットへの作業やウィジェットからアプリへの作業をキューにします。
• acknowledgeWidgetMessages メッセージを受信したことをマークします。
• completeWidgetMessage 非同期ジョブのレスポンスや失敗を格納します。

完了したメッセージは、再試行しても既存の結果を返します。

Public API

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

ネイティブ ピース

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

• CapgoTemplateWidgetBridge SVG テンプレート表面を解決します。 svg, frameId, hotspots、およびメタデータ。
• CapgoTemplateActionIntent iOS ウィジェットのボタンをテンプレートアクションに接続します。
• CapgoNativeWidgetBridge loads full-native sessions and messages from native widget code.
• Android テンプレートヘルパーは、受信アクションとウィジェットブリッジの動作を提供します。

真実の源

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

@capgo/capacitor-widget-kit

Capgoを使用している場合 Capgoの@capgo/capacitor-widget-kit CI/CDの自動化を計画するには、@__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-widget-kitと接続する Capgoの@capgo/capacitor-widget-kitを使用 Capgoの@capgo/capacitor-widget-kitのネイティブ機能 Capgo CI/CD for the product workflow in Capgo CI/CD, Capgo Native Builds for the product workflow in Capgo Native Builds, Capgo Integrations for the product workflow in Capgo Integrations, and CI/CD統合 CI/CD統合の実装詳細についてはこちら