reearth.extension

更新日2026年7月30日

reearth.extension 名前空間は、アクティブなプラグイン拡張の機能とプロパティへのアクセスを提供します。ウィジェット、ブロック、または reearth 環境内の他の拡張インスタンスなど、異なるコンポーネント間の通信メソッドを含みます。

プロパティ

block

block プロパティは、プラグインのストーリーブロックまたはインフォボックスブロックへのアクセスを提供します。ブロックにはメタデータ、プラグインの詳細、プロパティが含まれ、インフォボックスブロックの場合は関連レイヤも含まれます。このプロパティは reearth 環境内のコンテンツブロックを操作する際に有用です。

構文

reearth.extension.block?: PluginStoryBlock | (PluginInfoboxBlock & { layer?: Layer });

戻り値

型 PluginStoryBlock | (PluginInfoboxBlock & { layer?: Layer });

メタデータ、プラグインの詳細、プロパティを含むプラグインブロックオブジェクトです。インフォボックスブロックの場合は、関連レイヤも含まれます。

PluginStoryBlock: プラグイン内でナラティブやシーケンスを作成するために特別に設計されたコンテンツブロックであるストーリーブロックを表します。

PluginInfoboxBlock: 関連レイヤを含む場合があるインフォボックスブロックを表します。

layer?: Layer: インフォボックスブロックに関連付けられたレイヤを表します。メタデータ、データソースの詳細、表示設定を含みます。

使用例

// 例 1: ストーリーブロックの詳細を取得する
const block = reearth.extension.block;

if (block && block.extensionType === "storyBlock") {
  console.log("Story Block ID:", block.id);
  console.log("Plugin ID:", block.pluginId);
  console.log("Block Name:", block.name);
}

// 例 2: インフォボックスブロックに関連付けられたレイヤにアクセスする
const block = reearth.extension.block;

if (block && block.extensionType === "infoboxBlock" && block.layer) {
  const layer = block.layer;
  console.log(`Layer ID: ${layer.id}`);
  console.log(`Layer Title: ${layer.title}`);
  console.log(`Layer Type: ${layer.type}`);
}

widget プロパティは、プラグインのウィジェットに関する情報（ID、レイアウト、表示設定など）へのアクセスを提供します。ウィジェットは reearth 環境内で動的に配置およびスタイル設定できる UI コンポーネントです。

構文

reearth.extension.widget?: Widget;

戻り値

型 Widget

使用例

// ウィジェットの詳細を確認してログ出力する
const widget = reearth.extension.widget;

if (widget) {
  console.log("Widget ID:", widget.id);
  console.log("Plugin ID:", widget.pluginId);
  console.log("Extension ID:", widget.extensionId);
  console.log("Property ID:", widget.propertyId);
  console.log("Extended Horizontally:", widget.extended?.horizontally);
  console.log("Extended Vertically:", widget.extended?.vertically);
}

list

このプロパティは、ウィジェット、ブロック、その他のサポートされているタイプを含む、すべてのプラグイン拡張インスタンスの配列へのアクセスを提供します。各インスタンスには、プラグインと拡張に関するメタデータが含まれます。

構文

reearth.extension.list: PluginExtensionInstance[];

戻り値

型 PluginExtensionInstance[];

list 配列の各エントリは、プラグイン拡張のインスタンスを表します。

使用例

// 例 1: すべての拡張インスタンスとそのメタデータをログ出力する
const extensionInstances = reearth.extension.list;

extensionInstances.forEach((instance) => {
  console.log("Extension Instance ID:", instance.id);
  console.log("Plugin ID:", instance.pluginId);
  console.log("Name:", instance.name);
  console.log("Extension ID:", instance.extensionId);
  console.log("Type:", instance.extensionType);
  console.log("Run Times:", instance.runTimes ?? "Not Available");
});

// 例 2: ウィジェット拡張のみをフィルタリングしてログ出力する
const widgets = reearth.extension.list.filter(
  (instance) => instance.extensionType === "widget"
);

console.log("Widget Extensions:");
widgets.forEach((widget) => {
  console.log(`- ${widget.name} (ID: ${widget.id})`);
});

メソッド

postMessage

このメソッドにより、プラグイン拡張は一意の ID を指定して特定のウィジェット、ブロック、または他の拡張インスタンスにメッセージを送信できます。この機能はプラグイン内のコンポーネント間通信を実現するために有用です。

構文

reearth.extension.postMessage(id: string, message: any) => void;

パラメータ

`id`

型: string

メッセージの送信先となるターゲットインスタンスの拡張 ID です。

`message`

型: any

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

戻り値:

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

使用例

// "my-widget-name" という名前のウィジェットにメッセージを送信する
const extensionInstances = reearth.extension.list;

const targetWidgetId = extensionInstances.find(
  (extension) => extension.name === "my-widget-name"
)?.id;

if (targetWidgetId) {
  reearth.extension.postMessage(targetWidgetId, {
    action: "update",
    data: { key: "value" },
  });
}

イベント

message

message イベントは、拡張に対してメッセージが送信されるたびにトリガーされます。このイベントは**現在の拡張の UI（またはモーダル、ポップアップ）**からのメッセージを受信するために使用されます。

構文

reearth.extension.on("message", (message: unknown)  => void): void;

使用例

reearth.extension.on("message", (message) => {
  console.log("Received message:", message);
});

extensionMessage

extensionMessage イベントは、別の拡張インスタンスからメッセージが送信されたときにトリガーされます。データペイロードと送信者の ID を含む追加のコンテキストを提供します。

構文

reearth.extension.on("extensionMessage", (props: ExtensionMessage)  => void): void;

使用例

reearth.extension.on("extensionMessage", (props) => {
  console.log("Message from:", props.sender);
  console.log("Message data:", props.data);
});

型定義

PluginStoryBlock

type PluginStoryBlock = Omit<
  StoryBlock,
  "propertyForPluginAPI" | "propertyItemsForPluginBlock"
>;

type StoryBlock = {
  id: string;
  name?: string | null;
  pluginId: string;
  extensionId: string;
  extensionType?: "storyBlock";
  propertyId?: string;
  property?: any;
  propertyForPluginAPI?: any;
  propertyItemsForPluginBlock?: Item[];
};

id: string;: ストーリーブロックの一意の識別子です。複数のブロックを扱う際に各ブロックを区別するために必要です。

name?: string | null;: ストーリーブロックの名前です。省略可能で、指定されない場合は null になることがあります。

pluginId: string;: このストーリーブロックが属するプラグインの一意の ID です。ブロックを親プラグインに関連付けるために使用します。

extensionId: string;: このブロックを作成したプラグイン拡張の一意の ID です。プラグイン内でブロックのソースを追跡するために有用です。

extensionType?: "storyBlock";: 拡張のタイプを "storyBlock" として指定します。このプロパティにより、infoboxBlock などの他のブロックタイプと区別できます。

propertyId?: string;: ブロックの設定や他の場所に保存されたメタデータにリンクする省略可能なプロパティ ID です。

property?: any;: ブロックに関連付けられたカスタムプロパティです。

PluginInfoboxBlock

type PluginInfoboxBlock = Omit<
  InfoboxBlock,
  "propertyForPluginAPI" | "propertyItemsForPluginBlock"
>;

type InfoboxBlock<P = any> = {
  id: string;
  name?: string;
  pluginId?: string;
  extensionId?: string;
  extensionType?: "infoboxBlock";
  propertyId?: string;
  property?: P;
  propertyForPluginAPI?: any;
  propertyItemsForPluginBlock?: Item[];
};

id: string;: インフォボックスブロックの一意の識別子です。各ブロックを容易に識別できるようにします。

name?: string;: インフォボックスブロックの省略可能な名前です。インフォボックスのラベルやタイトルを表すことがあります。

pluginId?: string;: このインフォボックスブロックが属するプラグインの一意の ID です。省略可能で、常に存在するとは限りません。

extensionId: string;: このインフォボックスブロックを作成したプラグイン拡張の一意の ID です。その出所を識別するために使用します。

extensionType?: "infoboxBlock";: 拡張のタイプを "infoboxBlock" として指定します。処理するブロックのタイプを判別するために重要なプロパティです。

propertyId?: string;: ブロックの設定やメタデータにリンクする省略可能なプロパティ ID です。PluginStoryBlock と同様に、動的なプロパティ管理を可能にします。

property?: P;: ブロックに関連付けられたカスタムプロパティを表します。型はジェネリックパラメータ P によって決定され、プラグインの特定のニーズに合わせて動的に適応できます。

Layer

type Layer = {
  id: string; // A unique identifier for the layer.
  title?: string;
  visible?: boolean; // Flag indicating whether the layer is visible by default. Default is true
  infobox?: Infobox<IBP>; // An infobox that can display additional interactive or informational content
  type: "simple";
  data?: {
    type:
      | "geojson"
      | "3dtiles"
      | "osm-buildings"
      | "google-photorealistic"
      | "czml"
      | "csv"
      | "wms"
      | "mvt"
      | "kml"
      | "gpx"
      | "shapefile"
      | "gtfs"
      | "gml"
      | "georss"
      | "gltf"
      | "tiles"
      | "tms"
      | "heatMap";
    url?: string; // URL of data source
    value?: any;
    layers?: string | string[];
    jsonProperties?: string[];
    isSketchLayer?: boolean;
    updateInterval?: number; // milliseconds
    parameters?: Record<string, any>;
    idProperty?: string;
    time?: {
      property?: string;
      interval?: number; // milliseconds
      updateClockOnLoad?: boolean;
    };
    csv?: {
      idColumn?: string | number;
      latColumn?: string | number;
      lngColumn?: string | number;
      heightColumn?: string | number;
      noHeader?: boolean;
      disableTypeConversion?: boolean;
    };
    geojson?: {
      useAsResource?: boolean;
    };
  };
  properties?: any;
  defines?: Record<string, string>;
  events?: Events;
  layerStyleId?: string;
  marker?: MarkerAppearance;
  polyline?: PolylineAppearance;
  polygon?: PolygonAppearance;
  model?: ModelAppearance;
  "3dtiles"?: Cesium3DTilesAppearance;
};

type Widget = {
  readonly id: string;
  readonly pluginId?: string;
  readonly extensionId?: string;
  readonly property?: unknown;
  readonly propertyId?: string;
  readonly extended?: {
    horizontally: boolean;
    vertically: boolean;
  };
  readonly layout?: WidgetLayout;
};

id: string;: ウィジェットの一意の識別子です。

pluginId?: string;:（省略可能）このウィジェットを所有するプラグインの ID です。ウィジェットがどのプラグインに属するかを識別するために有用です。

extensionId?: string;:（省略可能）ウィジェットを作成したプラグイン拡張の ID です。同じプラグインの異なる拡張によって作成されたウィジェットを区別するために使用できます。

property?: unknown;:（省略可能）ウィジェットに関連付けられたカスタムプロパティです。プロパティの正確な構造は、特定のプラグインの実装に依存します。

propertyId?: string;:（省略可能）ウィジェットの設定またはメタデータの一意の識別子です。外部設定や保存されたプロパティへのリンクに使用します。

extended?: { horizontally: boolean; vertically: boolean };:（省略可能）ウィジェットが特定の方向に拡張されているかどうかを示します。このプロパティはウィジェットのレイアウトと動作を判断するために有用です。

horizontally: boolean: ウィジェットが水平方向に拡張されている場合は true、そうでない場合は false。
vertically: boolean: ウィジェットが垂直方向に拡張されている場合は true、そうでない場合は false。

このプロパティは省略可能で、常に存在するとは限りません。省略された場合、ウィジェットはいずれの方向にも拡張されません。

layout?: WidgetLayout;:（省略可能）Reearth UI 内でのウィジェットの位置と配置を指定します。以下の WidgetLayout の定義を参照してください。

WidgetLayout

type WidgetLayout = {
  location: WidgetLocation;
  align?: WidgetAlignment;
};

WidgetLayout 型は、Reearth インターフェース内でウィジェットがどのように配置されるかを定義します。

location: WidgetLocation;: インターフェース内でのウィジェットの正確な位置を指定します。詳細については WidgetLocation を参照してください。

align?: WidgetAlignment;:（省略可能）ウィジェットのエリア内での配置方法を決定します。指定しない場合はデフォルトの配置になります。詳細については WidgetAlignment を参照してください。

WidgetLocation

type WidgetLocation = {
  zone: "inner" | "outer";
  section: "left" | "center" | "right";
  area: "top" | "middle" | "bottom";
};

WidgetLocation 型は、reearth インターフェース内でのウィジェットの階層的な位置を定義します。UI ゾーンに対するウィジェットの配置位置を記述します。

zone: "inner" | "outer";: ウィジェットが配置される UI ゾーンを指定します:

"inner": ウィジェットがメインコンテンツエリア内にあることを示します。
"outer": ウィジェットが周辺 UI（例: サイドバー、ヘッダー）にあることを示します。

section: "left" | "center" | "right";: ゾーン内のセクションを示します:

"left": 左セクション。
"center": 中央セクション。
"right": 右セクション。

area: "top" | "middle" | "bottom";: セクション内の垂直エリアを定義します:

"top": セクションの上部。
"middle": セクションの中央。
"bottom": セクションの下部。

WidgetAlignment

type WidgetAlignment = "start" | "centered" | "end";

WidgetAlignment 型は、ウィジェットがそのエリア内でどのように整列されるかを指定します。

"start";: ウィジェットをエリアの先頭（例: 左上隅）に整列させます。

"centered";: ウィジェットをエリアの中央に配置します。

"end";: ウィジェットをエリアの末尾（例: 右下隅）に整列させます。

PluginExtensionInstance

type PluginExtensionInstance = {
  readonly id: string;
  readonly pluginId: string;
  readonly name: string;
  readonly extensionId: string;
  readonly extensionType: "widget" | "block" | "infoboxBlock" | "storyBlock";
};

id: string;: 拡張インスタンスの一意の識別子です。この ID は reearth 環境内でインスタンスを参照するために使用されます。

pluginId: string;: 拡張インスタンスが属するプラグインの一意の ID です。インスタンスを親プラグインにリンクします。

name: string;: 拡張インスタンスの名前です。通常、インスタンスを識別するための人が読める名前です。

extensionId: string;: インスタンスを作成したプラグイン拡張の一意の ID です。同じプラグイン内の拡張を区別するために使用します。

extensionType: "widget" | "block" | "infoboxBlock" | "storyBlock";: インスタンスが表す拡張のタイプです。指定可能な値は以下の通りです:

"widget": ウィジェット拡張。
"infoboxBlock": インフォボックスブロック拡張。
"storyBlock": ストーリーブロック拡張。