capgo/capacitor-ウィジェットキット

ウィジェットキットとライブアクティビティをCapacitorアプリに追加し、SVGドライブのテンプレートまたはフルネイティブのウィジェットステートシンクを使用します。

概要

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

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

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

デモ

モードを選択

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

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

SVG テンプレート機能

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

frames 名前付き SVG のバリアント summary, timer, または details.
frameMutations ホットスポットアクション後にフレームをスイッチ、タグル、またはステップする
timerMutations 開始、停止、リセット、またはタイマー期間を変更する
patches Capgoのライブアップデート
hotspots タップエリアをアクション識別子にマップします。
listTemplateEvents アプリはウィジェットから発生したアクションを後で処理します。

リッチエクスペリエンス {{state.title}}, {{timers.rest.remainingText}}リッチエクスペリエンス {{meta.template.kind}} リッチエクスペリエンス

リッチエクスペリエンス

startWidgetSession creates shared state and metadata for native widget code.
updateWidgetSession リッチエクスペリエンス
stopWidgetSession リッチエクスペリエンス
sendWidgetMessage アプリからウィジェット、またはウィジェットからアプリの作業キュー。
acknowledgeWidgetMessages メッセージを受信したことをマークします。
completeWidgetMessage 非同期ジョブのレスポンスまたは失敗を格納します。

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

Public 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 __CAPGO_KEEP_0__ リポジトリの「__CAPGO_KEEP_1__-widget-kit」から続けてください。

「@__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-widget-kit」を使用している場合 「@capgo/capacitor-widget-kit」を使用してCI/CDの自動化を計画する場合、capgo/capacitor-widget-kitと接続してください。 CI/CD自動化を計画するには、を接続します。 Using @capgo/capacitor-widget-kit Capgoのネイティブ機能の使用に@capgo/capacitor-ウィジェットキットを使用します。「Capgo CI/CD」「Capgo CI/CD」 Capgo 本機ビルド Capgoの製品ワークフロー Capgoの統合 Capgoの製品ワークフロー __CAPGO_KEEP_0__の統合 CI/CD統合