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

Capacitor用のウィジェットキットとライブアクティビティ、SVGドライブのテンプレートまたはフルネイティブのウィジェットステートシンク

スタートする GitHub

概要

@capgo/capacitor-widget-kit Capacitorアプリには、ウィジェットとライブアクティビティを制御する2つの方法があります。

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

SVGテンプレートを使用して、解決されたSVG文字列からウィジェットをレンダリングできる場合に、SVGテンプレートを使用してください。ウィジェットがカスタムネイティブUIを必要とする場合に、フルネイティブセッションを使用してください。

デモ

モードを選択

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

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

SVGテンプレートの機能

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

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

ランタイムは、ネイティブブリッジがレンダリング用のサーフェイスを返す前に、 {{state.title}}, {{timers.rest.remainingText}}プレースホルダーの置き換え、 {{meta.template.kind}} ネイティブブリッジのフルネイティブ機能

セクションのタイトル：フルネイティブブリッジの機能

ネイティブウィジェットの共有状態とメタデータを生成します。

startWidgetSession code
updateWidgetSession 状態をマージまたは置き換え、セッションを再度有効にします。
stopWidgetSession 最終状態を記録し、セッションを停止します。
sendWidgetMessage アプリからウィジェットまたはウィジェットからアプリへの作業をキューにします。
acknowledgeWidgetMessages メッセージを受信としてマークします。
completeWidgetMessage 非同期ジョブのレスポンスまたは失敗を格納します。

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

パブリック API

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

ネイティブピース

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

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

ソースオブトゥルース

「API」参照はプラグインリポジトリから同步されています。 src/definitions.ts 「__CAPGO_KEEP_0__」参照の「__CAPGO_KEEP_1__-widget-kit」から続けてください。

「__CAPGO_KEEP_0__」参照の「__CAPGO_KEEP_1__-widget-kit」を使用してCI/CD オートメーションを計画する場合、Cloudflare との接続を確立してください。 「capgo」参照の「capacitor-widget-kit」を使用してネイティブ機能を計画する場合、Cloudflare との接続を確立してください。 「__CAPGO_KEEP_0__」参照の「__CAPGO_KEEP_1__-widget-kit」を使用してネイティブ機能を計画する場合、Cloudflare との接続を確立してください。 Using @capgo/capacitor-widget-kit for the native capability in Using @capgo/capacitor-widget-kit, Capgo CI/CD Capgoの製品ワークフローにおけるCI/CD Capgo Native Builds Capgoの製品ワークフローにおけるNative Builds Capgo Integrations Capgoの製品ワークフローにおけるIntegrations、 CI/CD Integration CI/CD Integrationの実装詳細