@capgo/capacitor-widget-kit

概要

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

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

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

デモ

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

Aモードを選択

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

両方のモードは同じアプリ内で実行できます。例えば、ワークアウトアプリでは、高速フレーム/タイマーコントロールのためにSVG Liveアクティビティを使用し、ホーム画面ウィジェットにリッチなネイティブレイアウトを使用するためにフルネイティブウィジェットセッションを使用できます。

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 非同期ジョブの応答または失敗を格納します。

メッセージは完了後、idempotent です: 完了したまたは失敗したメッセージを再試行すると、既存の結果が返され、上書きされません。

パブリック API

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

Native Pieces

The plugin also ships native helpers for widget targets:

• CapgoTemplateWidgetBridge SVGテンプレート表面を解決します。 svg, frameId, hotspots、およびメタデータ。
• CapgoTemplateActionIntent iOSウィジェットのインタラクティブなボタンをテンプレートアクションに接続します。
• CapgoNativeWidgetBridge loads full-native sessions and messages from native widget code.
• ネイティブウィジェットの__CAPGO_KEEP_0__。

Androidテンプレートヘルパーは、受信アクションとウィジェットブリッジの動作を提供します。

The API reference is synced from src/definitions.ts __CAPGO_KEEP_0__ リファレンスはプラグインリポジトリからsyncされます。

「@capgo/capacitor-widget-kit」から続けてください。

あなたが使用している場合 @capgo/capacitor-widget-kit CI/CDの自動化を計画する場合、@__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-widget-kitを接続します。 使用する@capgo/capacitor-widget-kit Using @capgo/capacitor-widget-kitのネイティブ機能 Capgo CI/CD Capgo CI/CDの製品ワークフロー Capgo Native Builds Capgo Native Buildsの製品ワークフロー Capgo Integrations Capgo Integrationsの製品ワークフロー CI/CDの統合 CI/CD統合の実装詳細について。