@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}} ネイティブブリッジがレンダリング用の表面を返す前に

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

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

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

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

パブリック API

メソッド	説明
areActivitiesSupported	現在のデバイスでネイティブ テンプレート アクティビティ ブリッジを実行できるかどうかを確認します。
startTemplateActivity	SVG テンプレート アクティビティを保存し、ネイティブ ライブ アクティビティ ブリッジを開始します。
updateTemplateActivity	アクティビティの定義、状態、または URL を置き換えます。
endTemplateActivity	実行中のアクティビティを終了し、最後の 1 つの状態スナップショットを保存することもできます。
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 プラグインリポジトリからsyncされます。

続けてください @capgo/capacitor-widget-kit

Capgoを利用している場合 Capgo (@capgo/capacitor-widget-kit)を使用 Capgo (@__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-widget-kit)と接続 Capgo (@capgo/capacitor-widget-kit)を使用 Capgo (@capgo/capacitor-widget-kit)のネイティブ機能 Capgo (@Capgo/__CAPGO_KEEP_1__-widget-kit)のCI/CD Capgo (@Capgo/__CAPGO_KEEP_1__-widget-kit)のネイティブビルド Capgo (@Capgo/__CAPGO_KEEP_1__-widget-kit)のCI/CD Capgo (@Capgo/__CAPGO_KEEP_1__-widget-kit)のネイティブビルド Capgo (@Capgo/__CAPGO_KEEP_1__-widget-kit)の統合 Capgo (@Capgo/__CAPGO_KEEP_1__-widget-kit)のCI/CD CI/CD統合 Capgo BuilderのCI/CD統合の実装詳細です。