exb-widget

Experience Builder カスタムウィジェット

Developer Edition のカスタムウィジェット開発に関する作業です。ウィジェットコードを書く前に、デプロイ先とコンパイルバージョンを確定してください。実際に読み込まれるランタイムで動作を検証してください。

コードを書く前にターゲットを確定する

1. ワークスペースと既存のウィジェットを確認します。新規ウィジェットか変更か、必要な動作、データ／マップの入力、想定する利用者、デプロイ先を明らかにします。すでに提示されていない、重要な情報だけを質問してください。
2. ローカルの Developer Edition ウィジェット、外部ホスト型の完全なエクスペリエンス、Enterprise に登録されたウィジェットを区別します。Enterprise のデータを利用する Developer Edition アプリには、ポータルウィジェットのコンパイル制約は適用されません。カスタムウィジェットは ArcGIS Online ビルダーにインストールできません。Online コンテンツを使用する外部ホスト型の Developer Edition アプリは、別のターゲットです。ウィジェットとテーマのデプロイを参照して確認してください。
3. client/package.json でインストール済みの ExB バージョンを確認し、拡張機能の配置を調べます。配置や登録の手順に進む前に、Developer Edition か Esri のソースチェックアウトかを確認してください。インストール環境を利用できない場合は、バージョンと関連ファイルを尋ねます。推測で判断せず、環境ゲートを未解決として記録してください。
4. Enterprise に登録されたウィジェットの場合、対象として約束する Enterprise の各バージョンを記録し、VERSIONS.mdを使って対応する Developer Edition を特定します。各ポータルのターゲットと同じ JS SDK バージョンを使用してください。最も古いターゲットに対応するエディションから作成する単一のアーティファクトは、サポート方針の候補にすぎず、将来バージョンとの互換性を保証するものではありません。約束するすべてのターゲットでテストしてください。必要に応じて、ターゲットごとのビルドを使用するか、サポート範囲を狭めてください。
5. ローカル開発または外部ホスト型のエクスペリエンスの場合は、Developer Edition のランタイムを固定し、接続先となる Online／Enterprise サービスを確認します。実装前に、選択したランタイム、ターゲット、ソース URL、検証日、未解決の組み合わせを記録してください。

exbVersion はフレームワークとの互換性を宣言するもので、値を下げても API、依存関係、コンパイル済みコードがバックポートされるわけではありません。WidgetManifest リファレンスでは、2026-09-24 の確認時点で、そのチェックは現在強制されていないと説明されていました。このタスクでその状況を再確認してください。このフィールドも、コンパイルが成功することも、ランタイム互換性の証明にはなりません。

対象リリースのツールチェーンを確認する

依存関係のインストールや起動の前に、VERSIONS.mdを使って、対象の正確なリリースに必要な Node の範囲、推奨 Node バージョン、npm／pnpm の選択肢を確認します。これらをインストール済みのツール、client／server のパッケージメタデータ、ロックファイルと照合してください。コマンドを実行する前に不一致を解消します。依存関係のインストールとスクリプトの実行は区別してください。

影響を受ける契約だけを最小限実装する

• 新規ウィジェット： マニフェストとランタイムを整備し、必要な動作に必要な設定／構成の画面だけを用意します。確認済みのワークスペース内にある近隣のウィジェットに従ってください。
• 既存ウィジェット： 編集前に、ランタイム、設定、構成、近隣のテストを確認します。公開されている構成とフレームワークの規約を維持してください。
• 影響範囲： ローカルの動作変更では、その動作をテストします。設定／データ／マップ／アクションの変更では、影響を受ける契約をテストします。保存スキーマやランタイムのアップグレードでは、移行と対象ランタイムのチェックを含めます。無関係なリファクタリングではなく、影響範囲に応じて検証を拡張してください。

実装ガイダンスが必要な場合は、該当する領域について実装ガイダンスを参照してください。まずこのスキルの環境ゲートを適用し、次に選択した実装ガイダンスを適用してから、以下の検証を行います。任意の補助ツールは、対象ランタイムを選択するものでも、これらのゲートに代わるものでもありません。

マニフェストの不変条件を維持する

マニフェスト作成チェックリストに従い、name、type、version、exbVersion、translatedLocalesを確認します。ウィジェットの種類、バージョン値、宣言された依存関係／アクション、ロケールファイルが、選択したリリースに対応していることを検証します。nameは一意で、ウィジェットフォルダーと完全に一致している必要があります。作成チェックリストと、TypeScript宣言におけるオプションプロパティは別々に確認してください。両方を検証します。

意図した成果物をビルドする

• 開発ループ： インストール環境からクライアントとサーバーの起動スクリプトを特定します。拡張機能の検出と再読み込みの動作を確認し、新しいファイルやフォルダーを追加したときに必要であればクライアントを再起動します。
• エクスペリエンス全体： エクスペリエンスのデプロイに従って、アプリ全体を公開／ダウンロードし、ホストします。コンパイル済みウィジェットのディレクトリは、エクスペリエンス全体のエクスポートではありません。
• コンパイル済みウィジェット： インストール環境のビルドスクリプトと参照されているビルド構成を確認し、該当する本番ビルドを実行して、実際の出力を検証します。動的にインポートされるwidgets/chunksと、必要な共有コード／チャンクを、想定される相対配置のまま維持します。過去のコマンド／出力の違いはVERSIONS.mdを参照して解決してください。スクリプト名だけから出力ディレクトリを推測しないでください。

Enterprise に登録されたウィジェットをデプロイする

この対象に限り、doc.arcgis.comで該当するEnterpriseリリースのカスタムウィジェットの追加を開きます。12.1は一例であり、既定の対象ではありません。手順を適用する前に、対象バージョンのURLを特定して検証してください。

1. HTTPSと有効な証明書を備え、匿名でアクセス可能なウィジェットホストであることを確認します。ウィジェットホスティングサーバーでポータルのオリジンからのアクセスをCORSで許可します。.jsonがHTMLのログイン／エラーページではなく、application/jsonとして配信されることを確認します。
2. コンパイル済みウィジェット、動的チャンク、共有コード、ロケールファイル、その他の必要なアセットを、想定されるパスに配置します。マニフェストと依存アセットを取得し、ポータルのオリジンからブラウザーで読み込めることを確認します。HTTPリクエストが成功しただけでは不十分です。
3. ポータル管理者に各ウィジェットのマニフェストURLを登録してもらい、合意した対象ユーザーとアイテムを共有します。拡張機能／ソースのチェックアウトでの登録は、ポータルへの登録とは異なります。同一組織の制約と、アプリを認証済み／匿名でアクセスさせる意図を、匿名でのコードホスティングとは別に確認します。ホスティング、登録、共有を変更する前に、承認を得てください。
4. すべての提供対象ポータルで、想定する対象ユーザーのアクセス権を使ってウィジェットのスモークテストを実施します。既存のデプロイを置き換える際は、ホスト上の更新とキャッシュの動作を確認します。

変更した動作を検証する

インストール環境で該当する型チェック、ビルド、対象を絞ったテストのスクリプトを特定して実行し、変更の影響を受けるウィジェットが含まれていることを確認します。既存のテストヘルパーを使用し、単独で実施する場合は公式の単体テストガイダンスを代替手段として利用します。

• 変更に関連する設定済み、未設定、読み込み中、空、エラーの各状態をテストし、設定の永続化と、影響を受けるデータ／アクションの契約も確認します。
• マップウィジェットでは、ビューの変更とアンマウントをテストします。ウォッチャー、ハイライト、グラフィックス、一時レイヤー、古い非同期コールバックがクリーンアップされることを確認します。
• 永続化されたスキーマを変更する場合は、既存の保存済み設定をアップグレード経路でテストします。互換性ガイドとインストール済みの型に基づいて、リリースに適したバージョンマネージャーを選択します。保存済み設定の移行と、ランタイム間の互換性は別のものです。
• 変更したUIについて、キーボード操作、アクセシブルなラベル、ローカライズ、狭い画面でのレイアウトを確認します。開発サーバーだけでなく、選択した配信環境でビルド成果物を検証します。

完了条件

デプロイモード、検証済みのバージョン／ツールチェーンの根拠、変更された契約、成果物の場所、および該当するビルド／テスト／実行時／デプロイの各チェックの結果を報告します。実行時環境として提示するものすべてについて、裏付けとなるテストの証拠が必要です。実施できなかったチェックと、妨げとなった前提条件を明示してください。型チェックまたはビルドに合格しただけでは、互換性やデプロイについての主張はできません。