reearth.popup

reearth.popup 名前空間は、reearth 内のポップアップダイアログコンポーネントの構造と機能を定義します。

メソッド

show

show メソッドは、拡張ウィジェットまたはブロックを基準とした指定位置に、カスタム HTML コンテンツを含むポップアップを表示します。ポップアップの外観・位置・オフセットを設定できるため、さまざまな UI ニーズに柔軟に対応できます。

構文

reearth.popup.show: (
  html: string,
  options?: Options
) => void;

パラメータ

html

型: string

ポップアップ内に表示する HTML コンテンツの文字列です。

options

省略可能

ポップアップの外観と配置をカスタマイズするプロパティを持つオブジェクトです。

型:

type Options = {
  width?: number | string;
  height?: number | string;
  position?: PopupPosition;
  offset?: PopupOffset;
};

• width?: number | string;: ポップアップの幅を指定します。
• height?: number | string;: ポップアップの高さを指定します。
• position?: PopupPosition;: 基準点または要素に対するポップアップの表示位置を指定します。

ノート

PopupPosition に含まれるオプションの詳細については、PopupPosition セクションを参照してください。

• offset?: PopupOffset: ポップアップの配置位置からの追加間隔またはオフセットを定義します。

ノート

PopupOffset に含まれるオプションの詳細については、PopupOffset セクションを参照してください。

戻り値:

なし（void）。このメソッドは値を返さずに処理を実行します。

使用例

// 使用例 1. シンプルな通知ポップアップを表示する
reearth.popup.show(`
  <h1 style='color:blue;background:white'>
    You have successfully updated your profile.
  </h1>`, {
  // ポップアップの幅を 300 ピクセルに設定
  width: 300,
  // ポップアップの高さを 100 ピクセルに設定
  height: 100,
  // 基準要素またはビューポートの下端右側にポップアップを配置
  position: "bottom-end",
  // メイン軸とクロス軸に対して特定のオフセットでポップアップの位置を調整
  offset: 10, // ターゲットから 10px のオフセットを設定
});

// 使用例 2. カスタム HTML・幅・両軸のオフセット調整を含むポップアップを表示する
reearth.popup.show(`
  <p style='color:blue;background:white'>
    Custom Popup Content
  </p>`, {
  width: "300px",
  height: "150px",
  position: "top-start", // ターゲットの左上にポップアップを配置
  offset: {
    // 細かな配置調整のためのオフセットオブジェクト
    mainAxis: 15, // メイン軸に沿って 15px オフセット
    crossAxis: 10, // クロス軸に沿って 10px オフセット
    alignmentAxis: null, // アライメント調整なし
  },
});

// 使用例 3. デフォルトのサイズと位置でポップアップを表示する
reearth.popup.show("<p>Simple Popup</p>");

postMessage

このメソッドは、ポップアップの iframe にメッセージを送信する機能を提供します。ポップアップが拡張スクリプトから情報を取得する必要があるシナリオでの通信に役立ちます。

構文

reearth.popup.postMessage: (message: any) => void;

パラメータ

message

型: any

送信するメッセージです。

戻り値:

なし（void）。このメソッドは値を返さずに処理を実行します。

使用例

// 使用例 1. ポップアップからシンプルな文字列メッセージを送信する
reearth.popup.postMessage("Popup completed its task");

// 使用例 2. ユーザー操作の詳細を含むオブジェクトを送信する
const userData = {
  action: "submit",
  details: { name: "John Doe", email: "john@example.com" },
};

reearth.popup.postMessage(userData);

update

このメソッドを使用すると、ポップアップ iframe の外観と位置を変更できます。ポップアップを再作成することなく、幅・高さ・位置・オフセットなどのプロパティを動的に調整できます。

構文

reearth.popup.update: (options: Options) => void;

パラメータ

options

ポップアップのサイズ・位置・オフセットを更新するプロパティを含むオブジェクトです。

型:

type Options = {
  width?: number | string;
  height?: number | string;
  position?: PopupPosition;
  offset?: PopupOffset;
};

• width?: number | string;: ポップアップの新しい幅を設定します。
• height?: number | string;: ポップアップの新しい高さを設定します。
• position?: PopupPosition;: 基準点または要素に対するポップアップの新しい表示位置を指定します。

ノート

PopupPosition に含まれるオプションの詳細については、PopupPosition セクションを参照してください。

• offset?: PopupOffset;: ポップアップの配置位置からの間隔またはオフセットを調整します。

ノート

PopupOffset に含まれるオプションの詳細については、PopupOffset セクションを参照してください。

戻り値:

なし（void）。このメソッドは値を返さずに処理を実行します。

使用例

// 使用例 1. 両軸に対して特定のオフセット調整を加えてポップアップを更新する
reearth.popup.update({
  width: "250px",
  height: "100px",
  position: "bottom", // ターゲットの下に配置
  offset: {
    // 詳細な調整のためのオフセットオブジェクト
    mainAxis: 10, // メイン軸でターゲットから 10px オフセット
    crossAxis: 5, // クロス軸に沿って 5px オフセット
  },
});

// 使用例 2. 新しいコンテンツや UI レイアウト変更に合わせてオフセットを調整する
reearth.popup.update({
  offset: { mainAxis: 25, crossAxis: 15 }, // メイン軸とクロス軸の両方のオフセットを調整
  // 幅・高さ・位置は更新せず、オフセットのみ変更
});

// 使用例 3. 他のプロパティを維持したままポップアップの高さを調整する
reearth.popup.update({
  height: 200, // 高さを 200px に設定
});

close

このメソッドは、現在表示中のポップアップをプログラムから閉じるシンプルな手段を提供します。タスクの完了・論理的な条件・その他のユーザー操作に基づいてポップアップを非表示にできます。

構文

reearth.popup.close: () => void

パラメータ

なし

戻り値:

なし（void）。このメソッドは値を返さずに処理を実行します。

使用例

// 現在開いているポップアップを閉じる
reearth.popup.close();

イベント

ノート

共通イベントメソッド（on・off）の詳細については、Events ページを参照してください。

close

close イベントは、reearth 内のポップアップが閉じられたときに発火します。このイベントを利用することで、ポップアップが非表示になった際にリソースの解放・UI の更新・他コンポーネントへの通知といった特定の処理を実行できます。

構文

reearth.popup.on("close", () => void): void;

使用例

reearth.popup.on("close", () => {
  console.log("The Popup was closed.");
});

型定義

PopupPosition

PopupPosition 型は、ターゲット要素に対してポップアップを表示する位置を制御します。拡張ウィジェットまたはブロックの上・下・左右に配置するための各種オプションと、アライメント調整（start・center・end）のオプションを提供します。

type PopupPosition =
  | "top"
  | "top-start"
  | "top-end"
  | "right"
  | "right-start"
  | "right-end"
  | "bottom"
  | "bottom-start"
  | "bottom-end"
  | "left"
  | "left-start"
  | "left-end";

top: ターゲットの真上にポップアップを配置します。

top-start: ターゲットの左上にポップアップを揃えます。

top-end: ターゲットの上かつ右側にポップアップを揃えます。

right: ターゲットの真右にポップアップを揃えます。

right-start: ターゲットの右側かつ上端にポップアップを揃えます。

right-end: ターゲットの右側かつ下端にポップアップを揃えます。

bottom: ターゲットの真下にポップアップを配置します。

bottom-start: ターゲットの下かつ左側にポップアップを揃えます。

bottom-end: ターゲットの下かつ右側にポップアップを揃えます。

left: ターゲットの真左にポップアップを配置します。

left-start: ターゲットの左側かつ上端にポップアップを揃えます。

left-end: ターゲットの左側かつ下端にポップアップを揃えます。

PopupOffset

PopupOffset 型を使用すると、拡張ウィジェットまたはブロックからのポップアップの距離を制御できます。メイン軸に沿ったオフセットを調整する数値と、メイン軸・クロス軸・アライメント軸など各軸を細かく制御するオブジェクトの 2 種類の指定方法があります。

type PopupOffset =
  | number
  | {
      mainAxis?: number;
      crossAxis?: number;
      alignmentAxis?: number | null;
    };

オプション

数値

• 単一の数値を指定すると、ポップアップがメイン軸に沿ってターゲットに近づく方向または遠ざかる方向にシフトします。
• 使用例: 10 を指定すると、ポップアップがメイン軸に沿って 10 ピクセルシフトします。

オブジェクト

以下のプロパティを持つ細かな制御が可能なオブジェクトです。

mainAxis?: number: ターゲットからのポップアップの距離をメイン軸に沿って調整します。正の値はポップアップをターゲットから遠ざけ、負の値は近づけます。

crossAxis?: number: メイン軸に垂直なクロス軸に沿ってポップアップの距離を調整します。正の値はポップアップを一方向に、負の値は逆方向に移動させます（方向は向きに依存します）。

alignmentAxis?: number | null: crossAxis と同じ軸ですが、アライメントが指定された配置にのみ適用され、end アライメントを反転させます。数値を設定すると crossAxis の値を上書きします。正の値はフローティング要素をアライメントされた辺の反対側の辺の方向に移動させ、負の値はその逆方向に移動させます。