@capgo/capacitor-widget-kit

概要

@capgo/capacitor-widget-kit Capacitorアプリには、ウィジェットとLive Activitiesを2つの方法でドライブすることができます。

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

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

デモ

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

モードを選択

モード	最適	主なAPI
SVGテンプレートアクティビティ	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}} ネイティブブリッジのフル機能

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

状態をマージまたは置き換え、セッションを再度有効にします。

• startWidgetSession creates shared state and metadata for native widget code.
• updateWidgetSession アプリからウィジェットまたはウィジェットからアプリへの作業をキューにします。
• stopWidgetSession メッセージを受信済みとしてマークします。
• sendWidgetMessage 非同期ジョブのレスポンスまたは失敗を格納します。
• acknowledgeWidgetMessages 完了後はメッセージはidempotentです: 完了したまたは失敗したメッセージを再試行すると、既存の結果が返され、上書きされません。
• completeWidgetMessage Full-Native Bridge Capabilities

Section titled “Full-Native Bridge Capabilities”

公開 API

メソッド	説明
areActivitiesSupported	現在のデバイスでネイティブ テンプレート アクティビティ ブリッジを実行できるかどうかを確認します。
startTemplateActivity	SVG テンプレート アクティビティを保存し、ネイティブ ライブ アクティビティ ブリッジを開始します。
updateTemplateActivity	アクティビティの定義、状態、または URL を置き換えます。
endTemplateActivity	実行中のアクティビティを終了し、最後の 1 つの状態のスナップショットを保存するオプションがあります。
performTemplateAction	宣言的パッチ、フレームの変化、タイマーの変化、イベントのログを実行します。
getTemplateActivity	保存されたテンプレート アクティビティを 1 つ読み取ります。
listTemplateActivities	保存されたテンプレート アクティビティのリストを取得します。
listTemplateEvents	テンプレート アクションから発生したアクション イベントを読み取ります。
acknowledgeTemplateEvents	イベントをマークして処理済みとします。
startWidgetSession	共有されたJSONステートをバックアップすることで、フルネイティブウィジェットセッションを開始します。
updateWidgetSession	フルネイティブウィジェットセッションのステートをマージまたは置き換えます。
stopWidgetSession	オプションで最終ステートを保存することで、フルネイティブウィジェットセッションを停止します。
getWidgetSession	フルネイティブウィジェットセッションを1つ読み取ります。
listWidgetSessions	フルネイティブウィジェットセッションをすべてリストします。
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

Keep going from @capgo/capacitor-widget-kit

使用中の場合は @capgo/capacitor-widget-kit CI/CDの自動化を計画する場合、@__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-widget-kitを接続してください @capgo/capacitor-widget-kitを使用して ネイティブ機能を使用する@capgo/capacitor-widget-kitの場合 @Capgo CI/CD 製品ワークフロー内で@Capgo CI/CDを使用してください @Capgo Native Builds 製品ワークフロー内で@Capgo Native Buildsを使用してください @Capgo Integrations 製品ワークフロー内で@Capgo Integrationsを使用してください CI/CD統合 CI/CD統合の実装詳細についてはこちらのドキュメントを参照してください。