(
type: T,
callback: (...args: EventType[T]) => void
): void
```
#### パラメータ
[Section titled “パラメータ”](#パラメータ-1)
* **type**: 登録を解除するイベントタイプ
* **callback**: `on` で登録した関数
#### 使用例
[Section titled “使用例”](#使用例-1)
```javascript
// コールバック関数を定義する
const handleClose = () => {
console.log("Popup was closed");
};
// イベントリスナーを登録する
reearth.popup.on("close", handleClose);
// リスニングを停止する場合
reearth.popup.off("close", handleClose);
```
## イベントタイプ
[Section titled “イベントタイプ”](#イベントタイプ)
Re:Earth Visualizer の各コンポーネントには独自のイベントタイプがあります。特定のイベントの詳細については、各コンポーネントのドキュメントを参照してください。
# reearth.extension
> `reearth.extension` の API リファレンスです。
**`reearth.extension`** 名前空間は、アクティブなプラグイン拡張の機能とプロパティへのアクセスを提供します。ウィジェット、ブロック、または `reearth` 環境内の他の拡張インスタンスなど、異なるコンポーネント間の通信メソッドを含みます。
## プロパティ
[Section titled “プロパティ”](#プロパティ)
### block
[Section titled “block”](#block)
`block` プロパティは、プラグインのストーリーブロックまたはインフォボックスブロックへのアクセスを提供します。ブロックにはメタデータ、プラグインの詳細、プロパティが含まれ、インフォボックスブロックの場合は関連レイヤも含まれます。このプロパティは `reearth` 環境内のコンテンツブロックを操作する際に有用です。
注意
このプロパティは、`storyBlock` または `infoboxBlock` タイプの拡張内で実行された場合のみ利用可能です。
#### 構文
[Section titled “構文”](#構文)
```ts
reearth.extension.block?: PluginStoryBlock | (PluginInfoboxBlock & { layer?: Layer });
```
#### 戻り値
[Section titled “戻り値”](#戻り値)
**型** `PluginStoryBlock | (PluginInfoboxBlock & { layer?: Layer });`
メタデータ、プラグインの詳細、プロパティを含むプラグインブロックオブジェクトです。インフォボックスブロックの場合は、関連レイヤも含まれます。
**`PluginStoryBlock`**: プラグイン内でナラティブやシーケンスを作成するために特別に設計されたコンテンツブロックであるストーリーブロックを表します。
ノート
`PluginStoryBlock` に含まれるオプションの詳細については、[PluginStoryBlock](#pluginstoryblock) セクションを参照してください。
**`PluginInfoboxBlock`**: 関連レイヤを含む場合があるインフォボックスブロックを表します。
ノート
`PluginInfoboxBlock` に含まれるオプションの詳細については、[PluginInfoboxBlock](#plugininfoboxblock) セクションを参照してください。
**`layer?: Layer`**: インフォボックスブロックに関連付けられたレイヤを表します。メタデータ、データソースの詳細、表示設定を含みます。
ノート
`Layer` に含まれるオプションの詳細については、[Layer](#layer) セクションを参照してください。
#### 使用例
[Section titled “使用例”](#使用例)
```javascript
// 例 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
[Section titled “widget”](#widget)
`widget` プロパティは、プラグインのウィジェットに関する情報（ID、レイアウト、表示設定など）へのアクセスを提供します。ウィジェットは `reearth` 環境内で動的に配置およびスタイル設定できる UI コンポーネントです。
注意
このプロパティは、`widget` タイプの拡張内で実行された場合のみ利用可能です。
#### 構文
[Section titled “構文”](#構文-1)
```ts
reearth.extension.widget?: Widget;
```
#### 戻り値
[Section titled “戻り値”](#戻り値-1)
**型** `Widget`
ノート
`Widget` の詳細については、[Widget](#widget-1) セクションを参照してください。
#### 使用例
[Section titled “使用例”](#使用例-1)
```javascript
// ウィジェットの詳細を確認してログ出力する
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
[Section titled “list”](#list)
このプロパティは、ウィジェット、ブロック、その他のサポートされているタイプを含む、すべてのプラグイン拡張インスタンスの配列へのアクセスを提供します。各インスタンスには、プラグインと拡張に関するメタデータが含まれます。
#### 構文
[Section titled “構文”](#構文-2)
```ts
reearth.extension.list: PluginExtensionInstance[];
```
#### 戻り値
[Section titled “戻り値”](#戻り値-2)
**型** `PluginExtensionInstance[];`
`list` 配列の各エントリは、プラグイン拡張のインスタンスを表します。
ノート
`PluginExtensionInstance` に含まれるオプションの詳細については、[PluginExtensionInstance](#pluginextensioninstance) セクションを参照してください。
#### 使用例
[Section titled “使用例”](#使用例-2)
```javascript
// 例 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})`);
});
```
## メソッド
[Section titled “メソッド”](#メソッド)
### postMessage
[Section titled “postMessage”](#postmessage)
このメソッドにより、プラグイン拡張は一意の ID を指定して特定のウィジェット、ブロック、または他の拡張インスタンスにメッセージを送信できます。この機能はプラグイン内のコンポーネント間通信を実現するために有用です。
#### 構文
[Section titled “構文”](#構文-3)
```ts
reearth.extension.postMessage(id: string, message: any) => void;
```
#### パラメータ
[Section titled “パラメータ”](#パラメータ)
##### `id`
[Section titled “id”](#id)
**型**: `string`
メッセージの送信先となるターゲットインスタンスの拡張 ID です。
##### `message`
[Section titled “message”](#message)
**型**: `any`
送信するメッセージです。
#### 戻り値:
[Section titled “戻り値:”](#戻り値-3)
なし（void）。このメソッドは値を返さずに処理を実行します。
#### 使用例
[Section titled “使用例”](#使用例-3)
```javascript
// "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" },
});
}
```
## イベント
[Section titled “イベント”](#イベント)
ノート
共通のイベントメソッド（`on`、`off`）の詳細については、[イベント](/ja/developer/plugin/api-reference/events) ページを参照してください。
### message
[Section titled “message”](#message-1)
`message` イベントは、拡張に対してメッセージが送信されるたびにトリガーされます。このイベントは\*\*現在の拡張の UI（またはモーダル、ポップアップ）\*\*からのメッセージを受信するために使用されます。
#### 構文
[Section titled “構文”](#構文-4)
```ts
reearth.extension.on("message", (message: unknown) => void): void;
```
#### 使用例
[Section titled “使用例”](#使用例-4)
```javascript
reearth.extension.on("message", (message) => {
console.log("Received message:", message);
});
```
### extensionMessage
[Section titled “extensionMessage”](#extensionmessage)
`extensionMessage` イベントは、**別の拡張インスタンス**からメッセージが送信されたときにトリガーされます。データペイロードと送信者の ID を含む追加のコンテキストを提供します。
#### 構文
[Section titled “構文”](#構文-5)
```ts
reearth.extension.on("extensionMessage", (props: ExtensionMessage) => void): void;
```
#### 使用例
[Section titled “使用例”](#使用例-5)
```javascript
reearth.extension.on("extensionMessage", (props) => {
console.log("Message from:", props.sender);
console.log("Message data:", props.data);
});
```
## 型定義
[Section titled “型定義”](#型定義)
### PluginStoryBlock
[Section titled “PluginStoryBlock”](#pluginstoryblock)
```javascript
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
[Section titled “PluginInfoboxBlock”](#plugininfoboxblock)
```javascript
type PluginInfoboxBlock = Omit<
InfoboxBlock,
"propertyForPluginAPI" | "propertyItemsForPluginBlock"
>;
type InfoboxBlock = {
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
[Section titled “Layer”](#layer)
```javascript
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; // 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;
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;
events?: Events;
layerStyleId?: string;
marker?: MarkerAppearance;
polyline?: PolylineAppearance;
polygon?: PolygonAppearance;
model?: ModelAppearance;
"3dtiles"?: Cesium3DTilesAppearance;
};
```
### Widget
[Section titled “Widget”](#widget-1)
```javascript
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;`**:（省略可能）Re:Earth UI 内でのウィジェットの位置と配置を指定します。以下の [WidgetLayout](#widgetlayout) の定義を参照してください。
### WidgetLayout
[Section titled “WidgetLayout”](#widgetlayout)
```javascript
type WidgetLayout = {
location: WidgetLocation;
align?: WidgetAlignment;
};
```
`WidgetLayout` 型は、Re:Earth インターフェース内でウィジェットがどのように配置されるかを定義します。
**`location: WidgetLocation;`**: インターフェース内でのウィジェットの正確な位置を指定します。詳細については [WidgetLocation](#widgetlocation) を参照してください。
**`align?: WidgetAlignment;`**:（省略可能）ウィジェットのエリア内での配置方法を決定します。指定しない場合はデフォルトの配置になります。詳細については [WidgetAlignment](#widgetalignment) を参照してください。
### WidgetLocation
[Section titled “WidgetLocation”](#widgetlocation)
```javascript
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
[Section titled “WidgetAlignment”](#widgetalignment)
```javascript
type WidgetAlignment = "start" | "centered" | "end";
```
`WidgetAlignment` 型は、ウィジェットがそのエリア内でどのように整列されるかを指定します。
**`"start";`**: ウィジェットをエリアの先頭（例: 左上隅）に整列させます。
**`"centered";`**: ウィジェットをエリアの中央に配置します。
**`"end";`**: ウィジェットをエリアの末尾（例: 右下隅）に整列させます。
### PluginExtensionInstance
[Section titled “PluginExtensionInstance”](#pluginextensioninstance)
```javascript
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"`: ストーリーブロック拡張。
# reearth.layers
> `reearth.layers` の API リファレンスです。
**`reearth.layers`** 名前空間は、reearth シーン内のレイヤを管理・操作するためのメソッド群を提供します。プラグイン開発者はこれらのメソッドを使用して、レイヤのプログラム的な追加・検索・変更・削除を行うことができます。
## プロパティ
[Section titled “プロパティ”](#プロパティ)
### layers
[Section titled “layers”](#layers)
このプロパティは、**`reearth`** シーンに現在存在するすべてのレイヤのリストを提供します。プラグイン開発者はこれを使用して、必要に応じてレイヤへのアクセスや操作を行うことができます。このプロパティは **`LazyLayer`** オブジェクトの配列を返し、各オブジェクトはシーン内の個別のレイヤを表します。
#### 構文
[Section titled “構文”](#構文)
```ts
reearth.layers.layers: LazyLayer[];
```
#### 戻り値
[Section titled “戻り値”](#戻り値)
**型** `LazyLayer[]`
各要素がシーン内の個別のレイヤを表す **`LazyLayer`** オブジェクトの配列です。
ノート
**`LazyLayer`** オブジェクトはレイヤの軽量な表現形式です。プロパティへのアクセスは必要に応じて明示的に行う必要があります。 LazyLayer 型の詳細については、[LazyLayer 型](#lazylayer-%E5%9E%8B) セクションを参照してください。
### overridden
[Section titled “overridden”](#overridden)
これは省略可能なプロパティで、`reearth` シーン内でプロパティがオーバーライドされたレイヤを提供します。このメソッドを使用することで、レイヤのオーバーライド状態を確認できます。ユーザー操作、アプリケーション状態の変化、または外部データの更新に応じてレイヤプロパティを調整する必要がある場合に特に有用です。
#### 構文
[Section titled “構文”](#構文-1)
```ts
reearth.layers.overridden: OverriddenLayer[];
```
#### 戻り値
[Section titled “戻り値”](#戻り値-1)
**型** `Omit`
`Layer` 型定義から `type` と `children` を除いた型です。
#### 使用例
[Section titled “使用例”](#使用例)
```javascript
// Check if there are any overridden properties defined
if (reearth.layers.overridden) {
console.log("Overridden properties are defined.");
// Iterate through the overridden properties and log each one
for (const layer of reearth.layers.overridden) {
console.log(`Layer ID: ${layer.id}, Overridden Properties:`, layer);
}
} else {
console.log("No overridden properties are defined.");
}
```
### selected
[Section titled “selected”](#selected)
これは `reearth` プロジェクト内で現在選択されているレイヤを表します。レイヤが選択されている場合は `ComputedLayer` オブジェクトを保持し、選択されていない場合は `undefined` となる省略可能なプロパティです。このプロパティを使用することで、選択中のレイヤの詳細に直接アクセスでき、特定のレイヤデータの照会、プロパティの変更、または UI コンポーネントへの追加情報の表示など、ユーザーの選択に依存した操作を容易に行うことができます。
#### 構文
[Section titled “構文”](#構文-2)
```ts
reearth.layers.selected?: computedLayer;
```
#### 戻り値
[Section titled “戻り値”](#戻り値-2)
**型** `ComputedLayer`
すべての処理が完了した後に得られるレイヤで、元の地理データと処理済みの地理データの両方、および適用・評価済みのスタイルと状態を含みます。
ノート
**`ComputedLayer`** オブジェクトはレイヤの軽量な表現形式です。プロパティへのアクセスは必要に応じて明示的に行う必要があります。 ComputedLayer 型の詳細については、[ComputedLayer 型](#computedlayer-%E5%9E%8B) セクションを参照してください。
#### 使用例
[Section titled “使用例”](#使用例-1)
```javascript
// Check if there is a selected layer and log its details
if (reearth.layers.selected) {
console.log("Selected Layer ID:", reearth.layers.selected.id);
console.log("Selected Layer Title:", reearth.layers.selected.layer?.title);
} else {
console.log("No layer is currently selected.");
}
```
### selectedFeature
[Section titled “selectedFeature”](#selectedfeature)
これは `reearth` プロジェクト内で現在選択されているフィーチャーを表します。フィーチャーが選択されている場合は `feature` オブジェクトを保持し、選択されていない場合は `undefined` となる省略可能なプロパティです。このプロパティを使用することで、選択中のフィーチャーの詳細に直接アクセスでき、特定のフィーチャーデータの照会やプラグイン拡張への追加情報の表示など、ユーザーの選択に依存した操作を容易に行うことができます。
#### 構文
[Section titled “構文”](#構文-3)
```ts
reearth.layers.selectedFeature?: computedFeature;
```
#### 戻り値
[Section titled “戻り値”](#戻り値-3)
**型** `ComputedFeature`
すべての最終評価済みプロパティとスタイルが適用された、単一の地理的フィーチャー（点、線、ポリゴン等）です。
ノート
ComputedFeature 型の詳細については、[ComputedFeature 型](#computedfeature-%E5%9E%8B) セクションを参照してください。
#### 使用例
[Section titled “使用例”](#使用例-2)
```javascript
// Check if there is a selected feature and log its details
if (reearth.layers.selectedFeature) {
console.log("Selected Feature ID:", reearth.layers.selectedFeature.id);
} else {
console.log("No Feature is currently selected.");
}
```
## メソッド
[Section titled “メソッド”](#メソッド)
### add
[Section titled “add”](#add)
このメソッドは、**`reearth`** シーンに新しいレイヤを追加するために使用します。画像、データ表現、インタラクティブウィジェットなどの追加コンテンツレイヤでシーンを動的に拡張するために欠かせないメソッドです。主な引数として **`Layer`** オブジェクトを受け取り、追加するレイヤの特性とプロパティを定義します。
#### 構文
[Section titled “構文”](#構文-4)
```ts
reearth.layers.add: (layer: Layer) => string | undefined;
```
#### パラメータ
[Section titled “パラメータ”](#パラメータ)
##### `layer`
[Section titled “layer”](#layer)
**型**: `Layer`
レイヤの作成と管理に必要なすべてのデータとメタデータを含むオブジェクトです。シーンに追加するレイヤの特性とプロパティを定義します。
ノート
Layer 型およびレイヤアピアランス型の詳細については、[Layer 型](#layer-%E5%9E%8B) および [レイヤアピアランス型](#%E3%83%AC%E3%82%A4%E3%83%A4%E3%82%A2%E3%83%94%E3%82%A2%E3%83%A9%E3%83%B3%E3%82%B9%E5%9E%8B) セクションを参照してください。
#### 戻り値
[Section titled “戻り値”](#戻り値-4)
**型** `string | undefined`
操作が成功した場合、新しく追加されたレイヤの一意の識別子 `id` を返します。この識別子は以降の操作や照会に使用できます。操作が失敗した場合は `undefined` を返します。
#### 使用例
[Section titled “使用例”](#使用例-3)
* マーカーの追加
```javascript
const newLayerId = reearth.layers.add({
type: "simple",
data: {
type: "geojson",
value: {
type: "FeatureCollection",
features: [
{
type: "Feature",
properties: {},
geometry: {
coordinates: [139.97422779688281, 35.74642872517698],
type: "Point",
},
},
],
},
},
// marker property is required to indicate that the layer needs a marker appearance
marker: {},
});
if (newLayerId) {
console.log("Layer added successfully with ID:", newLayerId);
} else {
console.log("Failed to add layer.");
}
```
* ポリラインの追加
```javascript
const newLayerId = reearth.layers.add({
type: "simple",
data: {
type: "geojson",
value: {
type: "FeatureCollection",
features: [
{
type: "Feature",
properties: {},
geometry: {
coordinates: [
[139.93007825346956, 35.81332779614391],
[139.8105822019014, 35.730789521095986],
],
type: "LineString",
},
},
],
},
},
// polyline property is required to indicate that the layer needs a polyline appearance
polyline: {},
});
if (newLayerId) {
console.log("Layer added successfully with ID:", newLayerId);
} else {
console.log("Failed to add layer.");
}
```
* ポリゴンの追加
```javascript
const newLayerId = reearth.layers.add({
type: "simple",
data: {
type: "geojson",
value: {
type: "FeatureCollection",
features: [
{
type: "Feature",
properties: {},
geometry: {
coordinates: [
[
[139.56560369329821, 35.859787461762906],
[139.56560369329821, 35.586320662892106],
[139.73648312259508, 35.586320662892106],
[139.73648312259508, 35.859787461762906],
[139.56560369329821, 35.859787461762906],
],
],
type: "Polygon",
},
},
],
},
},
// polygon property is required to indicate that the layer needs a polygon appearance
polygon: {},
});
if (newLayerId) {
console.log("Layer added successfully with ID:", newLayerId);
} else {
console.log("Failed to add layer.");
}
```
* 3D モデルの追加
```javascript
const model3D = {
type: "simple",
data: {
type: "geojson",
value: {
type: "Feature",
geometry: {
type: "Point",
coordinates: [139.6917, 35.6895],
},
},
},
model: {
url: "https://api.visualizer.test.reearth.dev/assets/01j90myth0wy2kq5agry8rh4fd.gltf", // 'Re:Earth' logo from asset
heightReference: "relative",
heading: 270,
pitch: 0,
roll: 0,
scale: 100,
silhouette: true,
silhouetteColor: "red",
},
};
reearth.layers.add(model3D);
```
* 3dtiles の追加
```javascript
// Define a 3D tile. This is a 3D tile of Chiyoda yard building in Tokyo. The co-ordinates are Latitude: 35.69393005 Longitude: 139.75371138.
const tile3d = {
type: "simple",
data: {
type: "3dtiles",
url: "https://plateau.geospatial.jp/main/data/3d-tiles/bldg/13100_tokyo/13101_chiyoda-ku/notexture/tileset.json",
},
"3dtiles": {
show: true,
color: {
expression: {
conditions: [
["${_zmax} > 100", "color('red')"],
["true", "color('green')"],
],
},
},
edgeWidth: 10,
edgeColor: "#ffffff",
selectedFeatureColor: "blue",
},
};
reearth.layers.add(tile3d);
```
### find
[Section titled “find”](#find)
このメソッドは、カスタム検索関数を適用して Reearth シーン内のレイヤを効率的に検索します。特定の属性、プロパティ、または条件など、動的に定義された基準を満たすレイヤを特定する際に有用です。各レイヤを評価するコールバック関数を受け取り、指定された条件を満たすレイヤに対して `true` を返します。これにより、シーンの特定部分を対象とした精密な操作や分析が可能となり、レイヤ管理の柔軟性と制御性が向上します。
#### 構文
[Section titled “構文”](#構文-5)
```ts
reearth.layers.find: (
fn: (layer: LazyLayer, index: number) => boolean,
) => LazyLayer | undefined
```
#### パラメータ
[Section titled “パラメータ”](#パラメータ-1)
##### `fn`
[Section titled “fn”](#fn)
**型**: `(layer: LazyLayer, index: number) => boolean`
シーン内の各レイヤを評価するためのコールバック関数です。この関数は以下の引数を受け取ります。
* **`layer: LazyLayer`**: レイヤのすべてのデータを含むオブジェクト。
* **`index: number`**: 現在のレイヤのインデックス。
#### 戻り値
[Section titled “戻り値”](#戻り値-5)
**型** `LazyLayer | undefined`
指定されたテスト関数を満たす最初の **`LazyLayer`** オブジェクトを返します。条件を満たすレイヤが存在しない場合は **`undefined`** を返します。
#### 使用例
[Section titled “使用例”](#使用例-4)
```javascript
//1. Define a search function to find the first visible layer
const searchFunction = (layer, index) => {
return layer.isVisible === true;
};
// Use the find method to locate the first visible layer
const foundLayer = reearth.layers.find(searchFunction);
// Log the result or handle the case where no layer is found
if (foundLayer) {
console.log(`Found visible layer with ID: ${foundLayer.id}`);
} else {
console.log("No visible layer found.");
}
//2. Search for the first layer that is a 3D Tiles with the title "Re:Earth" and assign it to a variable.
reearth.layers.find(
(layer) => layer.data.type === "3dtiles" && layer.title === "Re:Earth"
);
```
### findAll
[Section titled “findAll”](#findall)
このメソッドは、プロジェクト内のすべてのレイヤを対象に包括的な検索を実行し、指定された条件に一致するレイヤの配列を返します。プロジェクト内の各レイヤに適用するコールバック関数を受け取ります。
#### 構文
[Section titled “構文”](#構文-6)
```ts
reearth.layers.findAll: (layer: LazyLayer, index: number) => boolean) => LazyLayer[]
```
#### パラメータ
[Section titled “パラメータ”](#パラメータ-2)
##### `layer`
[Section titled “layer”](#layer-1)
**型** `LazyLayer`
レイヤの作成と管理に必要なすべてのデータとメタデータを含むオブジェクトです。
##### `index`
[Section titled “index”](#index)
**型** `number`
階層内における現在のレイヤのインデックスです。
#### 戻り値
[Section titled “戻り値”](#戻り値-6)
**型** `LazyLayer[]`
コールバック関数で指定された条件を満たす `LazyLayer` オブジェクトの配列を返します。条件を満たすレイヤが存在しない場合は空の配列を返します。
#### 使用例
[Section titled “使用例”](#使用例-5)
```javascript
//1. Define a search function to find all layers with a specific visibility setting
const searchVisibleLayers = (layer) => layer.isVisible;
// Use the findAll method to get all visible layers
const visibleLayers = reearth.layers.findAll(searchVisibleLayers);
// Output the IDs of the found layers
console.log(
"Visible layers found:",
visibleLayers.map((layer) => layer.id)
);
//2. Filter out layers where the type is "GeoJSON" and the title is exactly "sample".
let filteredLayers = reearth.layers.findAll(
(layer) => layer.data.type === "geojson" && layer.title === "sample"
);
// Log the array of filtered layers to the console. This array contains all layers that meet the specified conditions.
console.log("filteredLayers: ", filteredLayers);
```
### findById
[Section titled “findById”](#findbyid)
このメソッドは、一意の識別子（ID）に基づいて特定のレイヤオブジェクトを取得するために設計されています。ID が既知のレイヤに直接アクセスする際に欠かせないメソッドで、プロパティの編集、表示のオン/オフ切り替え、またはレイヤ固有データの分析などを効率的かつ精密に行うことができます。レイヤ階層全体を検索・反復する必要なく、個別のレイヤへの直接アクセスを可能にします。検索対象のレイヤ ID を表す単一の文字列パラメータを受け取ります。
#### 構文
[Section titled “構文”](#構文-7)
```ts
reearth.layers.findById: (layerId: string) => LazyLayer | undefined;
```
#### パラメータ
[Section titled “パラメータ”](#パラメータ-3)
##### `layerId`
[Section titled “layerId”](#layerid)
**型** `string`
シーン内で検索対象となるレイヤの一意の識別子です。
#### 戻り値
[Section titled “戻り値”](#戻り値-7)
**型** `LazyLayer | undefined`
指定された ID を持つレイヤが見つかった場合、その `LazyLayer` オブジェクトを返します。一致するレイヤが存在しない場合は `undefined` を返します。
#### 使用例
[Section titled “使用例”](#使用例-6)
```javascript
// Define the layer ID you are searching for
const targetLayerId = "01j1rx8xhxsk2wdydew3m8hr6q";
// Attempt to find the layer by its ID
const layer = reearth.layers.findById(targetLayerId);
// Check if the layer was found and log the result or handle it accordingly
if (layer) {
console.log(`Layer found: ${layer.title}`);
} else {
console.log("No layer found with the specified ID:", targetLayerId);
}
```
### findByIds
[Section titled “findByIds”](#findbyids)
このメソッドは、レイヤ ID の配列に基づいて `reearth` シーンから複数のレイヤを同時に取得します。プロパティの一括更新、エフェクトの適用、グループ表示の管理など、複数の特定レイヤを同時に操作する必要があるアプリケーションに特に有用です。文字列引数のスプレッドを受け取り（各引数がレイヤ ID を表します）、各要素が `Layer` オブジェクトまたは `undefined` に対応する配列を返します。
#### 構文
[Section titled “構文”](#構文-8)
```ts
reearth.layers.findByIds: (...layerIds: string[]) => (LazyLayer | undefined)[];
```
#### パラメータ
[Section titled “パラメータ”](#パラメータ-4)
##### `...layerIds`
[Section titled “...layerIds”](#layerids)
**型** `...string[]`
取得するレイヤの一意の識別子を表すレイヤ ID の配列です。1つまたは複数の ID を柔軟に入力できます。
使用時は配列を複数の引数としてスプレッドする必要があります。
#### 戻り値
[Section titled “戻り値”](#戻り値-8)
**型** `(LazyLayer | undefined)[]`
各入力 ID に対応する `LazyLayer` オブジェクトまたは `undefined` を含む配列を返します。シーン内に ID に対応するレイヤが存在するかどうかに応じて値が決まります。返される配列の各位置は入力リストの ID の位置に直接対応しており、順序の一貫性が保たれます。指定した ID を持つレイヤが存在しない場合、その位置に `undefined` が返されます。
#### 使用例
[Section titled “使用例”](#使用例-7)
```javascript
// Define an array of layer IDs to be searched
const layerIds = ["01j1rx8xhxsk2wdydew3m8hr6q", "01j90ed9m6bxagb6bvfg4sk49q"];
// Retrieve the layers by their IDs
const layers = reearth.layers.findByIds(...layerIds);
// Process the results, handling both found and not found cases
layers?.forEach((layer, index) => {
if (layer) {
console.log(`Layer found: ID = ${layer.id}, Title = ${layer.title}`);
} else {
console.log(`No layer found for ID: ${layerIds[index]}`);
}
});
```
### findFeatureById
[Section titled “findFeatureById”](#findfeaturebyid)
このメソッドは、フィーチャー ID に関連するフィーチャーを取得する手段を提供します。レイヤ ID とフィーチャー ID を受け取り、指定されたレイヤ ID とフィーチャー ID に一致する `Feature` オブジェクトを返します。
#### 構文
[Section titled “構文”](#構文-9)
```ts
reearth.layers.findFeatureById: (layerId: string, featureId: string) => Feature | undefined;
```
#### パラメータ
[Section titled “パラメータ”](#パラメータ-5)
##### `layerId`
[Section titled “layerId”](#layerid-1)
**型** `string`
シーン内で検索対象となるレイヤの一意の識別子です。
##### `featureId`
[Section titled “featureId”](#featureid)
**型** `string`
レイヤ内のフィーチャーの一意の識別子です。
#### 戻り値
[Section titled “戻り値”](#戻り値-9)
**型** `Feature | undefined`
指定されたレイヤ内で指定された ID を持つフィーチャーが見つかった場合、その `Feature` オブジェクトを返します。一致するフィーチャーが存在しない場合は `undefined` を返します。
ノート
Feature 型の詳細については、[Feature 型](#feature-%E5%9E%8B) セクションを参照してください。
#### 使用例
[Section titled “使用例”](#使用例-8)
```javascript
// Define the layer ID and feature ID you are searching for
const targetLayerId = "01j90ed9m6bxagb6bvfg4sk49q";
const targetFeatureId = "6167fcb5-9564-4c8e-a4d3-d0b419f54ec6";
// Attempt to find the layer by its ID
const feature = reearth.layers.findFeatureById(targetLayerId, targetFeatureId);
// Check if the feature was found and log the result or handle it accordingly
if (feature) {
console.log(`feature found: ${feature.type}`);
} else {
console.log("No feature found with the specified ID:", targetFeatureId);
}
```
### findFeaturesByIds
[Section titled “findFeaturesByIds”](#findfeaturesbyids)
このメソッドは、1つ以上の指定されたフィーチャー ID でラベル付けされたすべてのフィーチャーを取得するために設計されています。単一のレイヤ ID と複数のフィーチャー ID を受け取り、指定されたレイヤ ID とフィーチャー ID に一致する `Feature` オブジェクトの配列を返します。
#### 構文
[Section titled “構文”](#構文-10)
```ts
reearth.layers.findFeaturesByIds: (layerId: string, featureId: string[]) => Feature[] | undefined;
```
#### パラメータ
[Section titled “パラメータ”](#パラメータ-6)
##### `layerId`
[Section titled “layerId”](#layerid-2)
**型** `string`
シーン内で検索対象となるレイヤの一意の識別子です。
##### `featureId`
[Section titled “featureId”](#featureid-1)
**型** `string[]`
レイヤ内のフィーチャーの一意の識別子です。1つまたは複数の ID を柔軟に入力できます。
#### 戻り値
[Section titled “戻り値”](#戻り値-10)
**型** `(Feature[] | undefined)`
指定されたレイヤ内で見つかったフィーチャー ID を持つ `Feature` オブジェクトの配列を返します。一致するフィーチャーが存在しない場合は `undefined` を返します。
#### 使用例
[Section titled “使用例”](#使用例-9)
```javascript
// Define an array of layer IDs to be searched
const layerId = "01j90ed9m6bxagb6bvfg4sk49q";
const featureIds = [
"6167fcb5-9564-4c8e-a4d3-d0b419f54ec6",
"abae3164-f8b3-42bb-b194-0379ecc4c653",
];
// Retrieve the layers by their IDs
const features = reearth.layers.findFeaturesByIds(layerId, featureIds);
// Process the results, handling both found and not found cases
features.forEach((feature, index) => {
if (feature) {
console.log(`Feature found: ID = ${feature.id}, Type = ${feature.type}`);
} else {
console.log(`No Feature found for ID: ${feature[index]}`);
}
});
```
### hide
[Section titled “hide”](#hide)
このメソッドは、提供されたレイヤ ID の配列に基づいて1つ以上のレイヤを非表示にするために設計されています。文字列引数のスプレッドを受け取り（各引数がレイヤの一意の識別子を表します）、呼び出されると指定された各レイヤの表示状態を `false` に設定し、プロジェクト内のビューから効果的に非表示にします。特定の条件やユーザー操作に基づいて、エンドユーザーに表示される要素を動的に制御するために特に有用です。
#### 構文
[Section titled “構文”](#構文-11)
```ts
reearth.layers.hide : (...layerIds: string[]) => void
```
#### パラメータ
[Section titled “パラメータ”](#パラメータ-7)
##### `...layerIds`
[Section titled “...layerIds”](#layerids-1)
**型** `...string[]`
非表示にするレイヤの ID をそれぞれ表す文字列のスプレッドパラメータです。
#### 戻り値
[Section titled “戻り値”](#戻り値-11)
**型** `なし（void）`
このメソッドは値を返しません。
#### 使用例
[Section titled “使用例”](#使用例-10)
```javascript
// Define the IDs of layers to be hidden
const layerIdsToHide = [
"01j1rx8xhxsk2wdydew3m8hr6q",
"01j90ed9m6bxagb6bvfg4sk49q",
];
// Hide the specified layers in the Reearth scene
reearth.layers.hide(...layerIdsToHide);
```
### show
[Section titled “show”](#show)
このメソッドは、`reearth` シーン内の指定されたレイヤの表示状態を `true` に設定するために使用します。ユーザーに表示するレイヤをプログラム的に制御でき、マップまたはシーン上のさまざまなデータセット、フィーチャー、またはグラフィック要素の表示を管理するための重要なツールです。ユーザー操作、アプリケーション状態、または特定の条件に基づいてレイヤを動的に表示・非表示にするシナリオに特に有用です。
#### 構文
[Section titled “構文”](#構文-12)
```ts
reearth.layers.show: (...layerId: string[]) => void;
```
#### パラメータ
[Section titled “パラメータ”](#パラメータ-8)
##### `...layerIds`
[Section titled “...layerIds”](#layerids-2)
**型** `...string[]`
表示するレイヤの ID をそれぞれ表す文字列のスプレッドパラメータです。
#### 戻り値
[Section titled “戻り値”](#戻り値-12)
**型** `なし（void）`
このメソッドは値を返しません。
#### 使用例
[Section titled “使用例”](#使用例-11)
```javascript
// Define the IDs of layers to be shown
const layerIdsToShow = [
"01j1rx8xhxsk2wdydew3m8hr6q",
"01j90ed9m6bxagb6bvfg4sk49q",
];
// Show the specified layers in the Reearth scene
reearth.layers.show(...layerIdsToShow);
```
### delete
[Section titled “delete”](#delete)
このメソッドは、`reearth` シーン内の指定されたレイヤを削除するために使用します。プラグインAPI によって追加された一時的なレイヤのみを削除します。レイヤの ID を主な引数として受け取ります。
#### 構文
[Section titled “構文”](#構文-13)
```ts
reearth.layers.delete: (...layerId: string[]) => void;
```
#### パラメータ
[Section titled “パラメータ”](#パラメータ-9)
##### `...layerIds`
[Section titled “...layerIds”](#layerids-3)
**型** `...string[]`
削除するレイヤの ID をそれぞれ表す文字列のスプレッドパラメータです。
#### 戻り値
[Section titled “戻り値”](#戻り値-13)
**型** `なし（void）`
このメソッドは値を返しません。
#### 使用例
[Section titled “使用例”](#使用例-12)
```javascript
// Define the IDs of layers to be deleted
const layerIdsToDelete = [
"ed5cade3-4049-4626-a4c6-4e84baaef987",
"0cdc12f8-4096-4a3c-84fa-0cc984130559",
];
// Show the specified layers in the Reearth scene
reearth.layers.delete(...layerIdsToDelete);
```
### override
[Section titled “override”](#override)
このメソッドは、ID によって指定されたレイヤのプロパティを動的にオーバーライドします。レイヤプロパティを変更することができます。表示状態、色、またはレイヤ構造で定義されたカスタム属性など、レイヤプロパティをオンザフライで変更できます。この動的な操作は、元のレイヤ設定を永続的に変更することなく、ユーザー操作、データ更新、またはその他のアプリケーションロジックに応じてレイヤ属性を変化させる必要があるレスポンシブなアプリケーションに不可欠です。レイヤの ID と部分的なレイヤオブジェクトの2つのパラメータを受け取ります。
#### 構文
[Section titled “構文”](#構文-14)
```ts
reearth.layers.override: (layerId: string, properties: Partial) => void;
```
#### パラメータ
[Section titled “パラメータ”](#パラメータ-10)
##### `layerId`
[Section titled “layerId”](#layerid-3)
**型** `string`
プロパティをオーバーライドするレイヤの一意の識別子です。
##### `properties`
[Section titled “properties”](#properties)
**型** `Partial`
Layer 型のいずれかのプロパティを省略可能な形で含むことができるオブジェクトです。
#### 戻り値
[Section titled “戻り値”](#戻り値-14)
**型** `なし（void）`
このメソッドは入力パラメータを必要とせず、値を返さずに処理を実行します。
#### 使用例
[Section titled “使用例”](#使用例-13)
```javascript
// add a sample layer
const sampleLayer = {
type: "simple",
data: {
type: "geojson",
value: {
type: "Feature",
geometry: {
type: "Point",
coordinates: [139.6917, 35.6895],
},
},
},
marker: {
style: "image",
imageSize: 1,
imageColor: "blue",
},
};
const layerId = reearth.layers.add(sampleLayer);
// Example to modify the style
// We should hav a big red marker instead of a small blue one
reearth.layers.override(layerId, {
marker: {
imageSize: 5,
imageColor: "red",
},
});
```
### select
[Section titled “select”](#select)
このメソッドは、`reearth` シーン内の特定のレイヤをプログラム的に選択するために使用します。
#### 構文
[Section titled “構文”](#構文-15)
```ts
reearth.layers.select: (layerId?: string) => void;
```
#### パラメータ
[Section titled “パラメータ”](#パラメータ-11)
##### `layerId`
[Section titled “layerId”](#layerid-4)
**型** `string`
選択するレイヤの一意の識別子です。
#### 戻り値
[Section titled “戻り値”](#戻り値-15)
**型** `なし（void）`
このメソッドは入力パラメータを必要とせず、値を返さずに処理を実行します。
#### 使用例
[Section titled “使用例”](#使用例-14)
```javascript
// Select a layer by ID
reearth.layers.select("01j1rx8xhxsk2wdydew3m8hr6q");
```
### selectFeature
[Section titled “selectFeature”](#selectfeature)
このメソッドは、`reearth` シーン内の特定のフィーチャーをプログラム的に選択するために使用します。特定のフィーチャーをハイライトまたはフォーカスするために不可欠で、インフォボックスやその他のコンテキスト情報の表示など、追加の UI 要素やアクションをトリガーすることができます。
#### 構文
[Section titled “構文”](#構文-16)
```ts
reearth.layers.selectFeature: (layerId?: string, featureId?: string) => void;
```
#### パラメータ
[Section titled “パラメータ”](#パラメータ-12)
##### `layerId`
[Section titled “layerId”](#layerid-5)
**型** `string`
選択するレイヤの一意の識別子です。
##### `featureId`
[Section titled “featureId”](#featureid-2)
**型** `string`
レイヤ内のフィーチャーの一意の識別子です。
#### 戻り値
[Section titled “戻り値”](#戻り値-16)
**型** `なし（void）`
このメソッドは入力パラメータを必要とせず、値を返さずに処理を実行します。
#### 使用例
[Section titled “使用例”](#使用例-15)
```javascript
// Layer ID and feature ID to be selected
const layerId = "01j90ed9m6bxagb6bvfg4sk49q";
const featureId = "6167fcb5-9564-4c8e-a4d3-d0b419f54ec6";
// Select the layer
reearth.layers.selectFeature(layerId, featureId);
```
### selectFeatures
[Section titled “selectFeatures”](#selectfeatures)
このメソッドは、`reearth` シーン内の特定の複数フィーチャーをプログラム的に選択するために使用します。特定のフィーチャーをハイライトまたはフォーカスするために不可欠で、インフォボックスやその他のコンテキスト情報の表示など、追加の UI 要素やアクションをトリガーすることができます。
#### 構文
[Section titled “構文”](#構文-17)
```ts
reearth.layers.selectFeatures: (targets: { layerId?: string; featureId?: string[] }[]) => void;
```
#### パラメータ
[Section titled “パラメータ”](#パラメータ-13)
##### `targets`
[Section titled “targets”](#targets)
**型** `{ layerId?: string; featureId?: string[] }[]`
* **`layerId: string`**: 選択するレイヤの一意の識別子。
* **`featureId: string[]`**: 各要素がフィーチャーの ID を表す文字列の配列。
#### 戻り値
[Section titled “戻り値”](#戻り値-17)
**型** `なし（void）`
このメソッドは入力パラメータを必要とせず、値を返さずに処理を実行します。
#### 使用例
[Section titled “使用例”](#使用例-16)
```javascript
// add a sample layer
const chiyodaLayerId = reearth.layers.add({
type: "simple",
data: {
type: "3dtiles",
url: "https://assets.cms.plateau.reearth.io/assets/ca/ee4cb0-9ce4-4f6c-bca1-9c7623e84cb1/13100_tokyo23-ku_2022_3dtiles_1_1_op_bldg_13101_chiyoda-ku_lod2_no_texture/tileset.json",
},
["3dtiles"]: {
selectedFeatureColor: "red",
},
});
const chuoLayerId = reearth.layers.add({
type: "simple",
data: {
type: "3dtiles",
url: "https://assets.cms.plateau.reearth.io/assets/4a/30f295-cd07-46b0-b0ab-4a4b1b3af06b/13100_tokyo23-ku_2022_3dtiles_1_1_op_bldg_13102_chuo-ku_lod2_no_texture/tileset.json",
},
["3dtiles"]: {
selectedFeatureColor: "red",
},
});
// NOTE: After 3dtiles been loaded, we can use this to select features
// Select features by layer IDs and feature IDs
reearth.layers.selectFeatures([
{
layerId: chiyodaLayerId,
featureId: [
"f9f2275bcf13a9674ba81473bc129ed6",
"b9a4fd90ca6112eccd43bfffd4aeb2fe",
],
},
{
layerId: chuoLayerId,
featureId: [
"acf77feceabce515700a47021bfe63dc",
"4dcf088a80f1eaaf73b1f356f7446298",
],
},
]);
```
## イベント
[Section titled “イベント”](#イベント)
ノート
共通イベントメソッド（`on`、`off`）の詳細については、[イベント](/ja/developer/plugin/api-reference/events) ページを参照してください。
### select
[Section titled “select”](#select-1)
このイベントは、`reearth` シーン内でレイヤが選択されたときにトリガーされます。レイヤ選択イベントを監視し、カスタムアクションや動作で応答する手段を提供します。
#### 構文
[Section titled “構文”](#構文-18)
```ts
reearth.layers.on('select', (selection: LayerSelection) => void)
```
#### パラメータ
[Section titled “パラメータ”](#パラメータ-14)
##### selection
[Section titled “selection”](#selection)
**型** `LayerSelection:[layerId: string | undefined, featureId: string | undefined]`
* **`layerId: string | undefined`**: 選択されたレイヤの一意の識別子。
* **`featureId: string | undefined`**: 選択されたフィーチャーの一意の識別子。
#### 使用例
[Section titled “使用例”](#使用例-17)
```javascript
const layerId = reearth.layers.add({
type: "simple",
data: {
type: "geojson",
value: {
type: "FeatureCollection",
features: [
{
type: "Feature",
properties: {},
geometry: {
coordinates: [139.97422779688281, 35.74642872517698],
type: "Point",
},
},
],
},
},
marker: {},
});
reearth.camera.lookAt({
lat: 35.74642872517698,
lng: 139.97422779688281,
height: 1000,
});
reearth.layers.on("select", (layerId, featureId) => {
console.log(
`Layer selection: Layer ID: ${layerId}, Feature ID: ${featureId}`
);
});
```
## 型定義
[Section titled “型定義”](#型定義)
### Layer 型
[Section titled “Layer 型”](#layer-型)
レイヤの作成と管理に必要なすべてのデータとメタデータを含むオブジェクトです。
```javascript
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; // An infobox that can display additional interactive or informational content
type: "simple";
data?: {
type:
| "geojson"
| "3dtiles"
| "osm-buildings"
| "reearth-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;
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;
events?: Events;
layerStyleId?: string;
marker?: MarkerAppearance;
polyline?: PolylineAppearance;
polygon?: PolygonAppearance;
model?: ModelAppearance;
"3dtiles"?: Cesium3DTilesAppearance;
};
```
### LazyLayer 型
[Section titled “LazyLayer 型”](#lazylayer-型)
レイヤの軽量な表現形式です。
```javascript
type LazyLayer = Readonly & {
computed?: Readonly;
isTempLayer?: boolean;
pluginId?: string;
extensionId?: string;
property?: any;
propertyId?: string;
isVisible?: boolean;
};
```
### ComputedLayer 型
[Section titled “ComputedLayer 型”](#computedlayer-型)
すべての処理が完了した後に得られるレイヤで、元の地理データと処理済みの地理データの両方、および適用・評価済みのスタイルと状態を含みます。
```javascript
type ComputedLayer = {
id: string;
status: "fetching" | "ready";
layer: Layer;
originalFeatures: Feature[];
features: ComputedFeature[];
properties?: any;
};
```
### レイヤアピアランス型
[Section titled “レイヤアピアランス型”](#レイヤアピアランス型)
各レイヤタイプのプロパティです。
* Marker
```javascript
type MarkerAppearance = {
show?: boolean;
height?: number;
heightReference?: "none" | "clamp" | "relative";
style?: "none" | "point" | "image";
pointSize?: number;
pointColor?: string;
pointOutlineColor?: string;
pointOutlineWidth?: number;
image?: string;
imageSize?: number;
imageSizeInMeters?: boolean;
imageHorizontalOrigin?: "left" | "center" | "right";
imageVerticalOrigin?: "top" | "center" | "baseline" | "bottom";
imageColor?: string;
imageCrop?: "none" | "rounded" | "circle";
imageShadow?: boolean;
imageShadowColor?: string;
imageShadowBlur?: number;
imageShadowPositionX?: number;
imageShadowPositionY?: number;
label?: boolean;
labelText?: string;
labelPosition?:
| "left"
| "right"
| "top"
| "bottom"
| "lefttop"
| "leftbottom"
| "righttop"
| "rightbottom";
labelTypography?: {
fontFamily?: string;
fontSize?: number;
fontWeight?: number;
color?: string;
italic?: boolean;
underline?: boolean;
};
labelBackground?: boolean;
labelBackgroundColor?: string;
labelBackgroundPaddingHorizontal?: number;
labelBackgroundPaddingVertical?: number;
extrude?: boolean;
near?: number; //The unit is meter
far?: number; //The unit is meter
hideIndicator?: boolean;
selectedFeatureColor?: string; // This doesn't support expression
};
```
* Polyline
```javascript
type PolylineAppearance = {
show?: boolean;
clampToGround?: boolean;
strokeColor?: string;
strokeWidth?: number;
shadows?: "disabled" | "enabled" | "cast_only" | "receive_only";
near?: number;
far?: number;
classificationType?: "both" | "terrain" | "3dtiles";
hideIndicator?: boolean;
selectedFeatureColor?: string; // This doesn't support expression
};
```
* Polygon
```javascript
type PolygonAppearance = {
show?: boolean;
fill?: boolean;
fillColor?: string;
stroke?: boolean;
strokeColor?: string;
strokeWidth?: number;
heightReference?: "none" | "clamp" | "relative";
shadows?: "disabled" | "enabled" | "cast_only" | "receive_only";
near?: number;
far?: number;
extrudedHeight?: number;
classificationType?: "both" | "terrain" | "3dtiles";
hideIndicator?: boolean;
selectedFeatureColor?: string; // This doesn't support expression
};
```
* Model
```javascript
type ModelAppearance = {
show?: boolean;
url?: string;
heightReference?: "none" | "clamp" | "relative";
heading?: number;
pitch?: number;
roll?: number;
scale?: number;
maximumScale?: number;
minimumPixelSize?: number;
animation?: boolean;
shadows?: "disabled" | "enabled" | "cast_only" | "receive_only";
colorBlend?: "none" | "highlight" | "replace" | "mix";
color?: string;
colorBlendAmount?: number;
lightColor?: string;
near?: number;
far?: number;
pbr?: boolean;
imageBasedLightIntensity?: number;
};
```
* 3dtiles
```javascript
type Cesium3DTilesAppearance = {
show?: boolean;
color?: string;
styleUrl?: string; // url of style json file
shadows?: "disabled" | "enabled" | "cast_only" | "receive_only";
colorBlendMode?: "highlight" | "replace" | "mix" | "default";
selectedFeatureColor?: string; // This doesn't support expression
tileset?: string;
pbr?: boolean; // physically-based rendering
showWireframe?: boolean;
showBoundingVolume?: boolean;
};
```
### Feature 型
[Section titled “Feature 型”](#feature-型)
フィーチャーの作成と管理に必要なすべてのデータとメタデータを含むオブジェクトです。
```javascript
type Feature = {
type: "feature" | "computedFeature";
id: string; // feature ID
geometry?: Geometry;
interval?: [start: Date, end?: Date];
properties?: any;
// Map engine specific information.
metaData?: {
description?: string;
};
range?: DataRange;
};
```
### ComputedFeature 型
[Section titled “ComputedFeature 型”](#computedfeature-型)
すべての最終評価済みプロパティとスタイルが適用された、単一の地理的フィーチャー（点、線、ポリゴン等）です。
```javascript
type ComputedFeature = {
type: "computedFeature";
id: string; // feature ID
geometry?: Geometry;
interval?: [start: Date, end?: Date];
properties?: any;
// Map engine specific information.
metaData?: {
description?: string;
};
range?: DataRange;
// AppearanceTypes
marker?: MarkerAppearance;
polyline?: PolylineAppearance;
polygon?: PolygonAppearance;
model?: ModelAppearance;
"3dtiles"?: Cesium3DTilesAppearance;
};
```
# reearth.modal
> `reearth.modal` の API リファレンスです。
**`reearth.modal`** 名前空間は、`reearth` 内のモーダルダイアログコンポーネントの構造と機能を定義します。
## メソッド
[Section titled “メソッド”](#メソッド)
### show
[Section titled “show”](#show)
このメソッドは、**`reearth`** 内でカスタマイズ可能な HTML コンテンツを持つモーダルウィンドウを表示します。開発者はモーダルのサイズ・背景・モーダル外クリック時の動作を定義できます。
#### 構文
[Section titled “構文”](#構文)
```ts
reearth.modal.show: (
html: string,
options?: Options
) => void;
```
#### パラメータ
[Section titled “パラメータ”](#パラメータ)
##### `html`
[Section titled “html”](#html)
**型**: `string`
モーダル内に表示する HTML コンテンツの文字列です。
##### `options`
[Section titled “options”](#options)
**省略可能**
モーダルの外観と動作をカスタマイズするオブジェクトです。
**型**:
```ts
type Options = {
width?: number | string;
height?: number | string;
background?: string;
clickBgToClose?: boolean;
};
```
* **`width?: number | string;`**: モーダルの幅を指定します。指定しない場合はデフォルトの幅が使用されます。
* **`height?: number | string;`**: モーダルの高さを指定します。省略するとデフォルトの高さが適用されます。
* **`background?: string;`**: モーダルの背景色または CSS 値を指定します（例: `"#fff"`、`"rgba(0, 0, 0, 0.5)"`）。
* **`clickBgToClose?: boolean;`**: モーダルの背景をクリックしたときにモーダルを閉じるかどうかを設定します。`true` にするとこの機能が有効になります。デフォルトは `false` です。
#### 戻り値:
[Section titled “戻り値:”](#戻り値)
なし（void）。このメソッドは値を返さずに処理を実行します。
#### 使用例
[Section titled “使用例”](#使用例)
```javascript
// 使用例 1: カスタム HTML コンテンツを含むモーダルを表示する
reearth.modal.show("Welcome to Reearth!
", {
width: 400,
height: 300,
background: "rgba(0, 0, 0, 0.5)",
clickBgToClose: true,
});
// 使用例 2: 大きめの固定サイズとソリッドな背景でモーダルを表示する
reearth.modal.show(
"Important Information
Details about the project...
",
{
width: 600,
height: 400,
background: "#f8f8f8",
clickBgToClose: false,
}
);
```
### postMessage
[Section titled “postMessage”](#postmessage)
このメソッドは、モーダルウィンドウと **`reearth`** の他の部分との間、またはモーダル内のコンポーネント間の通信を可能にします。モーダル内のユーザー操作を reearth に通知したり、他のコンポーネントにデータや処理を要求したりするなど、さまざまな用途に利用できます。
#### 構文
[Section titled “構文”](#構文-1)
```ts
reearth.modal.postMessage: (message: any) => void;
```
#### パラメータ
[Section titled “パラメータ”](#パラメータ-1)
##### `message`
[Section titled “message”](#message)
**型**: `any`
モーダルに送信するメッセージです。
#### 戻り値:
[Section titled “戻り値:”](#戻り値-1)
なし（void）。このメソッドは値を返さずに処理を実行します。
#### 使用例
[Section titled “使用例”](#使用例-1)
```javascript
// 使用例 1: シンプルなテキストメッセージを送信する
reearth.modal.postMessage("Hello, Re:Earth!");
// 使用例 2: Reearth アプリケーションにシンプルな文字列メッセージを送信する
reearth.modal.postMessage("User clicked the button!");
// 使用例 3: オブジェクトメッセージを送信する
reearth.modal.postMessage({ message: "greeting" });
// 使用例 4: ユーザーデータを含むオブジェクトを送信する
reearth.modal.postMessage({
eventType: "userAction",
details: {
action: "submit",
userId: 12345,
},
});
```
### update
[Section titled “update”](#update)
このメソッドは、**`reearth`** 内で現在開いているモーダルの外観と動作を変更します。モーダルのサイズ・背景色・クリックで閉じる動作などのプロパティを動的に調整できます。
#### 構文
[Section titled “構文”](#構文-2)
```ts
reearth.modal.update: (options: Options) => void;
```
#### パラメータ
[Section titled “パラメータ”](#パラメータ-2)
##### `options`
[Section titled “options”](#options-1)
モーダルの外観と動作を更新するプロパティを含むオブジェクトです。
**型**:
```ts
type Options = {
width?: number | string;
height?: number | string;
background?: string;
clickBgToClose?: boolean;
};
```
* **`width?: number | string;`**: モーダルの新しい幅を設定します。
* **`height?: number | string;`**: モーダルの新しい高さを設定します。
* **`background?: string;`**: モーダルの新しい背景を設定します。
* **`clickBgToClose?: boolean;`**: モーダル外をクリックしたときに閉じるかどうかを設定します。`true` にするとユーザーが背景をクリックしたときにモーダルが閉じます。`false` にすると背景クリックでモーダルが閉じなくなります。
#### 戻り値:
[Section titled “戻り値:”](#戻り値-2)
なし（void）。このメソッドは値を返さずに処理を実行します。
#### 使用例
[Section titled “使用例”](#使用例-2)
```javascript
// 使用例 1: 幅 300px・高さ 400px・ライトブルーの背景にリサイズする
reearth.modal.update({
width: 300,
height: 400,
background: "#ADD8E6",
clickBgToClose: true,
});
// 使用例 2: カスタム背景色・大きめのサイズに更新し、クリックで閉じる機能を無効にする
reearth.modal.update({
width: 600,
height: 450,
background: "rgba(0, 128, 128, 0.8)",
clickBgToClose: false, // 背景クリックによるモーダルのクローズを防止
});
// 使用例 3: 背景クリックでモーダルを閉じられるようにする
reearth.modal.update({
clickBgToClose: true,
});
// 使用例 4: 他のプロパティを維持したままモーダルの幅のみ 300px に変更する
reearth.modal.update({
width: 300,
});
```
### close
[Section titled “close”](#close)
このメソッドは、開いているモーダルを閉じるために使用します。タスクの完了・論理的な条件・その他のユーザー操作に基づいてモーダルを非表示にできます。パラメータは不要です。
#### 構文
[Section titled “構文”](#構文-3)
```ts
reearth.modal.close: () => void
```
#### パラメータ
[Section titled “パラメータ”](#パラメータ-3)
なし
#### 戻り値:
[Section titled “戻り値:”](#戻り値-3)
なし（void）。このメソッドは値を返さずに処理を実行します。
#### 使用例
[Section titled “使用例”](#使用例-3)
```ts
// 現在開いているモーダルを閉じる
reearth.modal.close();
```
## イベント
[Section titled “イベント”](#イベント)
ノート
共通イベントメソッド（`on`・`off`）の詳細については、[Events](/ja/developer/plugin/api-reference/events) ページを参照してください。
### close
[Section titled “close”](#close-1)
close イベントは、**`reearth`** 内のモーダルが閉じられたときに発火します。このイベントを利用することで、モーダルが閉じられた際にリソースの解放・データの保存・UI の更新といった処理を実行できます。提供するオプションに応じて、リスナーを一度だけ実行するか繰り返し実行するかを設定できます。
#### 構文
[Section titled “構文”](#構文-4)
```ts
reearth.modal.on("close", () => void): void;
```
#### 使用例
[Section titled “使用例”](#使用例-4)
```javascript
reearth.modal.on("close", () => {
console.log("The Modal was closed.");
});
```
# reearth.popup
> `reearth.popup` の API リファレンスです。
**`reearth.popup`** 名前空間は、`reearth` 内のポップアップダイアログコンポーネントの構造と機能を定義します。
## メソッド
[Section titled “メソッド”](#メソッド)
### show
[Section titled “show”](#show)
show メソッドは、拡張ウィジェットまたはブロックを基準とした指定位置に、カスタム HTML コンテンツを含むポップアップを表示します。ポップアップの外観・位置・オフセットを設定できるため、さまざまな UI ニーズに柔軟に対応できます。
#### 構文
[Section titled “構文”](#構文)
```ts
reearth.popup.show: (
html: string,
options?: Options
) => void;
```
#### パラメータ
[Section titled “パラメータ”](#パラメータ)
##### `html`
[Section titled “html”](#html)
**型**: `string`
ポップアップ内に表示する HTML コンテンツの文字列です。
##### `options`
[Section titled “options”](#options)
**省略可能**
ポップアップの外観と配置をカスタマイズするプロパティを持つオブジェクトです。
**型**:
```ts
type Options = {
width?: number | string;
height?: number | string;
position?: PopupPosition;
offset?: PopupOffset;
};
```
* **`width?: number | string;`**: ポップアップの幅を指定します。
* **`height?: number | string;`**: ポップアップの高さを指定します。
* **`position?: PopupPosition;`**: 基準点または要素に対するポップアップの表示位置を指定します。
ノート
PopupPosition に含まれるオプションの詳細については、[PopupPosition](#popupposition) セクションを参照してください。
* **`offset?: PopupOffset`**: ポップアップの配置位置からの追加間隔またはオフセットを定義します。
ノート
PopupOffset に含まれるオプションの詳細については、[PopupOffset](#popupoffset) セクションを参照してください。
#### 戻り値:
[Section titled “戻り値:”](#戻り値)
なし（void）。このメソッドは値を返さずに処理を実行します。
#### 使用例
[Section titled “使用例”](#使用例)
```javascript
// 使用例 1. シンプルな通知ポップアップを表示する
reearth.popup.show(`
You have successfully updated your profile.
`, {
// ポップアップの幅を 300 ピクセルに設定
width: 300,
// ポップアップの高さを 100 ピクセルに設定
height: 100,
// 基準要素またはビューポートの下端右側にポップアップを配置
position: "bottom-end",
// メイン軸とクロス軸に対して特定のオフセットでポップアップの位置を調整
offset: 10, // ターゲットから 10px のオフセットを設定
});
// 使用例 2. カスタム HTML・幅・両軸のオフセット調整を含むポップアップを表示する
reearth.popup.show(`
Custom Popup Content
`, {
width: "300px",
height: "150px",
position: "top-start", // ターゲットの左上にポップアップを配置
offset: {
// 細かな配置調整のためのオフセットオブジェクト
mainAxis: 15, // メイン軸に沿って 15px オフセット
crossAxis: 10, // クロス軸に沿って 10px オフセット
alignmentAxis: null, // アライメント調整なし
},
});
// 使用例 3. デフォルトのサイズと位置でポップアップを表示する
reearth.popup.show("Simple Popup
");
```
### postMessage
[Section titled “postMessage”](#postmessage)
このメソッドは、ポップアップの iframe にメッセージを送信する機能を提供します。ポップアップが拡張スクリプトから情報を取得する必要があるシナリオでの通信に役立ちます。
#### 構文
[Section titled “構文”](#構文-1)
```ts
reearth.popup.postMessage: (message: any) => void;
```
#### パラメータ
[Section titled “パラメータ”](#パラメータ-1)
##### `message`
[Section titled “message”](#message)
**型**: `any`
送信するメッセージです。
#### 戻り値:
[Section titled “戻り値:”](#戻り値-1)
なし（void）。このメソッドは値を返さずに処理を実行します。
#### 使用例
[Section titled “使用例”](#使用例-1)
```javascript
// 使用例 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
[Section titled “update”](#update)
このメソッドを使用すると、ポップアップ iframe の外観と位置を変更できます。ポップアップを再作成することなく、幅・高さ・位置・オフセットなどのプロパティを動的に調整できます。
#### 構文
[Section titled “構文”](#構文-2)
```ts
reearth.popup.update: (options: Options) => void;
```
#### パラメータ
[Section titled “パラメータ”](#パラメータ-2)
##### `options`
[Section titled “options”](#options-1)
ポップアップのサイズ・位置・オフセットを更新するプロパティを含むオブジェクトです。
**型**:
```ts
type Options = {
width?: number | string;
height?: number | string;
position?: PopupPosition;
offset?: PopupOffset;
};
```
* **`width?: number | string;`**: ポップアップの新しい幅を設定します。
* **`height?: number | string;`**: ポップアップの新しい高さを設定します。
* **`position?: PopupPosition;`**: 基準点または要素に対するポップアップの新しい表示位置を指定します。
ノート
PopupPosition に含まれるオプションの詳細については、[PopupPosition](#popupposition) セクションを参照してください。
* **`offset?: PopupOffset;`**: ポップアップの配置位置からの間隔またはオフセットを調整します。
ノート
PopupOffset に含まれるオプションの詳細については、[PopupOffset](#popupoffset) セクションを参照してください。
#### 戻り値:
[Section titled “戻り値:”](#戻り値-2)
なし（void）。このメソッドは値を返さずに処理を実行します。
#### 使用例
[Section titled “使用例”](#使用例-2)
```javascript
// 使用例 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
[Section titled “close”](#close)
このメソッドは、現在表示中のポップアップをプログラムから閉じるシンプルな手段を提供します。タスクの完了・論理的な条件・その他のユーザー操作に基づいてポップアップを非表示にできます。
#### 構文
[Section titled “構文”](#構文-3)
```ts
reearth.popup.close: () => void
```
#### パラメータ
[Section titled “パラメータ”](#パラメータ-3)
なし
#### 戻り値:
[Section titled “戻り値:”](#戻り値-3)
なし（void）。このメソッドは値を返さずに処理を実行します。
#### 使用例
[Section titled “使用例”](#使用例-3)
```ts
// 現在開いているポップアップを閉じる
reearth.popup.close();
```
## イベント
[Section titled “イベント”](#イベント)
ノート
共通イベントメソッド（`on`・`off`）の詳細については、[Events](/ja/developer/plugin/api-reference/events) ページを参照してください。
### close
[Section titled “close”](#close-1)
close イベントは、**`reearth`** 内のポップアップが閉じられたときに発火します。このイベントを利用することで、ポップアップが非表示になった際にリソースの解放・UI の更新・他コンポーネントへの通知といった特定の処理を実行できます。
#### 構文
[Section titled “構文”](#構文-4)
```ts
reearth.popup.on("close", () => void): void;
```
#### 使用例
[Section titled “使用例”](#使用例-4)
```javascript
reearth.popup.on("close", () => {
console.log("The Popup was closed.");
});
```
## 型定義
[Section titled “型定義”](#型定義)
### PopupPosition
[Section titled “PopupPosition”](#popupposition)
`PopupPosition` 型は、ターゲット要素に対してポップアップを表示する位置を制御します。拡張ウィジェットまたはブロックの上・下・左右に配置するための各種オプションと、アライメント調整（start・center・end）のオプションを提供します。
```javascript
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
[Section titled “PopupOffset”](#popupoffset)
`PopupOffset` 型を使用すると、拡張ウィジェットまたはブロックからのポップアップの距離を制御できます。メイン軸に沿ったオフセットを調整する数値と、メイン軸・クロス軸・アライメント軸など各軸を細かく制御するオブジェクトの 2 種類の指定方法があります。
```javascript
type PopupOffset =
| number
| {
mainAxis?: number;
crossAxis?: number;
alignmentAxis?: number | null;
};
```
#### オプション
[Section titled “オプション”](#オプション)
###### 数値
[Section titled “数値”](#数値)
* 単一の数値を指定すると、ポップアップがメイン軸に沿ってターゲットに近づく方向または遠ざかる方向にシフトします。
* 使用例: 10 を指定すると、ポップアップがメイン軸に沿って 10 ピクセルシフトします。
###### オブジェクト
[Section titled “オブジェクト”](#オブジェクト)
以下のプロパティを持つ細かな制御が可能なオブジェクトです。
**`mainAxis?: number`**: ターゲットからのポップアップの距離をメイン軸に沿って調整します。正の値はポップアップをターゲットから遠ざけ、負の値は近づけます。
**`crossAxis?: number`**: メイン軸に垂直なクロス軸に沿ってポップアップの距離を調整します。正の値はポップアップを一方向に、負の値は逆方向に移動させます（方向は向きに依存します）。
**`alignmentAxis?: number | null`**: `crossAxis` と同じ軸ですが、アライメントが指定された配置にのみ適用され、`end` アライメントを反転させます。数値を設定すると `crossAxis` の値を上書きします。正の値はフローティング要素をアライメントされた辺の反対側の辺の方向に移動させ、負の値はその逆方向に移動させます。
# reearth.sketch
> reearth.sketch の API リファレンスです。
Re:Earth Visualizer には強力なスケッチ機能が搭載されており、ユーザーはカスタムのマーカー、ポリライン、ポリゴンなどをマップ上に直接動的に描画できます。この機能は、プラグイン API の `reearth.sketch` を通じてアクセスできます。
## プロパティ
[Section titled “プロパティ”](#プロパティ)
### tool
[Section titled “tool”](#tool)
現在のスケッチツールを取得します。
#### 構文
[Section titled “構文”](#構文)
```ts
reearth.sketch.tool: SketchType;
```
#### 戻り値
[Section titled “戻り値”](#戻り値)
**型** `SketchType = | "marker" | "polyline" | "circle" | "rectangle" | "polygon" | "extrudedCircle" | "extrudedRectangle" | "extrudedPolygon"`
### options
[Section titled “options”](#options)
現在のスケッチオプションを取得します。
#### 構文
[Section titled “構文”](#構文-1)
```ts
reearth.sketch.options: SketchOptions;
```
#### 戻り値
[Section titled “戻り値”](#戻り値-1)
**型**
```ts
type SketchOptions = {
color?: string;
appearance?: SketchAppearance;
dataOnly?: boolean;
disableShadow?: boolean;
rightClickToAbort?: boolean;
autoResetInteractionMode?: boolean;
};
```
* **color:** スケッチジオメトリの基本色を指定します。
* **appearance:** 描画完了後にスケッチジオメトリに適用されるスタイルを定義します。
* **dataOnly:** `true` に設定すると、描画後にマップへ新しいレイヤが追加されません。デフォルト: `false`（注意: Re:Earth Visualizer エディター内ではこのオプションは `true` に設定されます）。
* **disableShadow:** 描画されたジオメトリに影を表示するかどうかを設定します。デフォルト: `false`。
* **rightClickToAbort:** 右クリックで現在の描画を中止できるようにします。デフォルト: `true`（注意: Re:Earth Visualizer エディター内ではこのオプションは `false` に設定されます）。
* **autoResetInteractionMode:** 描画完了後にビューアのインタラクションモードを自動的にデフォルトにリセットします。デフォルト: `true`。
ノート
SketchAppearance は LayerAppearance の部分的な実装です。詳細については、[レイヤアピアランス型](/ja/developer/plugin/api-reference/layers/#%E3%83%AC%E3%82%A4%E3%83%A4%E3%82%A2%E3%83%94%E3%82%A2%E3%83%A9%E3%83%B3%E3%82%B9%E5%9E%8B) を参照してください。
## メソッド
[Section titled “メソッド”](#メソッド)
### setTool
[Section titled “setTool”](#settool)
スケッチツールを特定のタイプに設定します。`undefined` を指定するとスケッチモードを終了します。
#### 構文
[Section titled “構文”](#構文-2)
```ts
reearth.sketch.setTool: (type: SketchType | undefined) => void;
```
#### パラメータ
[Section titled “パラメータ”](#パラメータ)
##### type
[Section titled “type”](#type)
**型** `SketchType | undefined`
#### 戻り値
[Section titled “戻り値”](#戻り値-2)
なし（void）。このメソッドは値を返しません。
### overrideOptions
[Section titled “overrideOptions”](#overrideoptions)
現在のスケッチオプションを上書きします。
#### 構文
[Section titled “構文”](#構文-3)
```ts
reearth.sketch.overrideOptions: (options: SketchOptions) => void;
```
#### パラメータ
[Section titled “パラメータ”](#パラメータ-1)
##### options
[Section titled “options”](#options-1)
**型** `SketchOptions`
#### 戻り値
[Section titled “戻り値”](#戻り値-3)
なし（void）。このメソッドは値を返しません。
## イベント
[Section titled “イベント”](#イベント)
ノート
共通のイベントメソッド（`on`、`off`）の詳細については、[イベント](/ja/developer/plugin/api-reference/events) ページを参照してください。
### create
[Section titled “create”](#create)
このイベントは、スケッチ描画が正常に完了したときにトリガーされます。
#### 構文
[Section titled “構文”](#構文-4)
```ts
reearth.sketch.on("create", (prop: SketchEventProps) => void);
```
#### パラメータ
[Section titled “パラメータ”](#パラメータ-2)
##### prop
[Section titled “prop”](#prop)
**型**
```ts
type SketchEventProps = {
layerId?: string;
featureId?: string;
feature?: SketchFeature;
};
```
* **layerId:** スケッチレイヤの ID です。`dataOnly` オプションが有効な場合、このプロパティは利用できません。
* **featureId:** スケッチフィーチャーの ID です。`dataOnly` オプションが有効な場合も利用できません。
* **feature:** `properties` に `id`、`type`、`positions`、`extrudedHeight` を含む `GeoJSON` オブジェクトです。
#### 使用例
[Section titled “使用例”](#使用例)
```ts
reearth.sketch.setTool("polygon");
reearth.sketch.on("create", (props) => {
console.log(`New sketch feature created:`, props);
});
```
### toolChange
[Section titled “toolChange”](#toolchange)
このイベントは、スケッチツールが変更されたときにトリガーされます。
#### 構文
[Section titled “構文”](#構文-5)
```ts
reearth.sketch.on("toolChange", (type: SketchType | undefined) => void);
```
#### パラメータ
[Section titled “パラメータ”](#パラメータ-3)
##### type
[Section titled “type”](#type-1)
**型** `SketchType | undefined`
#### 使用例
[Section titled “使用例”](#使用例-1)
```ts
reearth.sketch.on("toolChange", (tool) => {
console.log(`Sketch tool changed:`, tool);
});
// イベントを確認するために非同期で以下を実行してください:
reearth.sketch.setTool("polygon");
reearth.sketch.setTool(undefined);
```
# reearth.timeline
> `reearth.timeline` の API リファレンスです。
**`reearth.timeline`** 名前空間は、`reearth` 環境でタイムライン機能を管理・操作するためのメソッドとプロパティを提供します。時間ベースのデータやアニメーションを制御・監視・同期する必要があるシナリオ向けに設計されています。
## プロパティ
[Section titled “プロパティ”](#プロパティ)
### startTime
[Section titled “startTime”](#starttime)
startTime プロパティは、`reearth` 環境におけるタイムラインの開始点を表します。タイムラインが開始する時刻を定義するオプションの Date オブジェクトです。このプロパティは、プラグインが時間固有のデータやアニメーションを扱う必要がある場合に便利です。
#### 構文
[Section titled “構文”](#構文)
```ts
reearth.timeline.startTime?: Date;
```
###### `Date`
[Section titled “Date”](#date)
タイムラインの開始時刻を表す JavaScript Date オブジェクトです。startTime が定義されていない場合、タイムラインの開始時刻は関係ないか、動的に決定されます。
#### 使用例
[Section titled “使用例”](#使用例)
```javascript
// 使用例: タイムラインの開始時刻を確認してログに出力する
if (reearth.timeline.startTime) {
console.log("Timeline Start Time:", reearth.timeline.startTime.toISOString());
} else {
console.log("Timeline Start Time is not set.");
}
```
### stopTime
[Section titled “stopTime”](#stoptime)
stopTime プロパティは、`reearth` 環境におけるタイムラインの終了点を表します。タイムラインが停止する時刻を定義するオプションの Date オブジェクトです。このプロパティは、プラグイン内で時間制限のあるデータやアニメーションを管理する際に便利です。
#### 構文
[Section titled “構文”](#構文-1)
```ts
reearth.timeline.stopTime?: Date;
```
###### `Date`
[Section titled “Date”](#date-1)
タイムラインの停止時刻を表す JavaScript Date オブジェクトです。stopTime が定義されていない場合、タイムラインに固定の終了点がないか、動的に決定されることを示している場合があります。
#### 使用例
[Section titled “使用例”](#使用例-1)
```javascript
// 使用例: タイムラインの停止時刻を確認してログに出力する
if (reearth.timeline.stopTime) {
console.log("Timeline Stop Time:", reearth.timeline.stopTime.toISOString());
} else {
console.log("Timeline Stop Time is not set.");
}
```
### currentTime
[Section titled “currentTime”](#currenttime)
currentTime プロパティは、`reearth` 環境におけるタイムライン上の現在時刻を表します。タイムラインが進行するにつれて更新されるオプションの Date オブジェクトです。このプロパティは、プラグインのイベントやデータビジュアライゼーションをタイムラインの現在位置と同期させる際に便利です。
#### 構文
[Section titled “構文”](#構文-2)
```ts
reearth.timeline.currentTime?: Date;
```
###### `Date`
[Section titled “Date”](#date-2)
タイムライン上の現在時刻を表す JavaScript Date オブジェクトです。currentTime が定義されていない場合、タイムラインが初期化されていないか、現在非アクティブであることを示している場合があります。
#### 使用例
[Section titled “使用例”](#使用例-2)
```javascript
// 使用例: タイムラインの現在時刻を確認してログに出力する
if (reearth.timeline.currentTime) {
console.log(
"Current Timeline Time:",
reearth.timeline.currentTime.toISOString()
);
} else {
console.log("Current Timeline Time is not set.");
}
```
### isPlaying
[Section titled “isPlaying”](#isplaying)
このプロパティは、タイムラインが現在再生中かどうかを示します。タイムラインの再生状態を反映するブール値です。このプロパティは、タイムラインのアニメーションやイベントを制御・監視する際に便利です。
#### 構文
[Section titled “構文”](#構文-3)
```ts
reearth.timeline.isPlaying?: boolean;
```
**型** `boolean`
* `true`：タイムラインは現在再生中です。
* `false`：タイムラインは一時停止中です。
`isPlaying` が定義されていない場合、タイムラインが初期化されていないことを示している場合があります。
#### 使用例
[Section titled “使用例”](#使用例-3)
```javascript
// 使用例 1: タイムラインが再生中か一時停止中かをログに出力する
if (reearth.timeline.isPlaying === true) {
console.log("The timeline is currently playing.");
} else if (reearth.timeline.isPlaying === false) {
console.log("The timeline is paused.");
} else {
console.log("The timeline state is not set or unavailable.");
}
// 使用例 2: タイムラインが再生中のときにアニメーションをトリガーする
if (reearth.timeline.isPlaying) {
console.log("Playing animation linked to the timeline...");
}
// 使用例 3: タイムラインの再生状態をトグルする
if (reearth.timeline.isPlaying) {
reearth.timeline.pause?.();
} else {
reearth.timeline.play?.();
}
```
### speed
[Section titled “speed”](#speed)
speed プロパティは、`reearth` 環境におけるタイムラインの再生速度を表します。タイムラインがリアルタイムに対してどれだけ速く進行するかを決定する数値です。このプロパティは、タイムラインに紐づいたアニメーションやデータ更新のペースを制御する際に便利です。
#### 構文
[Section titled “構文”](#構文-4)
```ts
reearth.timeline.speed?: number;
```
**型** `number`
タイムラインの再生速度を表す数値です。例：`1.0`：リアルタイム再生、`>1.0`：リアルタイムより速い、`<1.0`：リアルタイムより遅い。speed が定義されていない場合、タイムラインの再生速度が設定または初期化されていないことを示している場合があります。
#### 使用例
[Section titled “使用例”](#使用例-4)
```javascript
// 使用例 1: タイムラインの現在の再生速度をログに出力する
if (reearth.timeline.speed !== undefined) {
console.log("Timeline Playback Speed:", reearth.timeline.speed);
} else {
console.log("Timeline speed is not set.");
}
// 使用例 2: タイムラインの再生速度を2倍に上げる
reearth.timeline.setSpeed(2.0);
console.log("Playback speed set to:", reearth.timeline.speed);
```
### stepType
[Section titled “stepType”](#steptype)
このプロパティは、タイムラインが時間を進行させるステップの種類を定義します。タイムラインが可変レート（時間に比例）で進むか、固定間隔で進むかを決定します。タイムラインに紐づいたデータやアニメーションの更新方法を制御する際に便利です。
#### 構文
[Section titled “構文”](#構文-5)
```ts
reearth.timeline.stepType?: "rate" | "fixed";
```
**型** `rate`
タイムラインは可変レートで進行します。タイムラインは継続的に進み、進行速度は speed プロパティによって決定されます。
**型** `fixed`
タイムラインは固定時間間隔（例：毎秒、毎分、毎時）で進行します。この種類は、離散的なステップや均等間隔の更新を持つタイムラインに最適です。
stepType が定義されていない場合、デフォルトのステップ種類はプラグインの設定または Re:Earth 環境によって異なる場合があります。
#### 使用例
[Section titled “使用例”](#使用例-5)
```javascript
// 使用例 1: タイムラインのステップ種類をログに出力する
if (reearth.timeline.stepType) {
console.log("Timeline Step Type:", reearth.timeline.stepType);
} else {
console.log("Timeline step type is not set.");
}
// 使用例 2: 連続進行のためにステップ種類を 'rate' に設定する
reearth.timeline.setStepType("rate");
console.log("Timeline step type set to 'rate'.");
// 使用例 3: 離散ステップのためにステップ種類を 'fixed' に設定する
reearth.timeline.setStepType("fixed");
console.log("Timeline step type set to 'fixed'.");
```
### rangeType
[Section titled “rangeType”](#rangetype)
rangeType プロパティは、タイムラインが時間進行の範囲をどのように扱うかを定義します。タイムラインが定義された startTime と stopTime を超えて拡張できるか、特定の範囲内に制限されるかを決定します。このプロパティは、タイムラインに紐づいたアニメーションやイベントの動作を制御するために重要です。
#### 構文
[Section titled “構文”](#構文-6)
```ts
reearth.timeline.rangeType?: "unbounded" | "clamped" | "bounced";
```
**型** `unbounded`
タイムラインは定義された startTime と stopTime を超えて拡張できます。境界を超えても無制限に進行できます。この種類は、継続的なアニメーションやデータ更新に便利です。
**型** `clamped`
タイムラインは startTime と stopTime の範囲内に制限されます。開始時刻より前や停止時刻より後には進行できません。この種類は、時間制限のあるアニメーションやイベントに便利です。
**型** `bounced`
タイムラインは startTime と stopTime の間で「バウンス」し、ループのような効果を生み出します。タイムラインが終端に達すると方向を逆転させ、開始点に向かって戻ります。この種類は、継続的なアニメーションやサイクルを作成する際に便利です。
rangeType が定義されていない場合、動作はタイムラインの設定にデフォルトするか、制限なしのままになる場合があります。
#### 使用例
[Section titled “使用例”](#使用例-6)
```javascript
// 使用例 1: タイムラインの範囲種類をログに出力する
if (reearth.timeline.rangeType) {
console.log("Timeline Range Type:", reearth.timeline.rangeType);
} else {
console.log("Timeline range type is not set.");
}
// 使用例 2: タイムラインを無制限に進行させる
reearth.timeline.setRangeType("unbounded");
console.log("Timeline range type set to 'unbounded'.");
// 使用例 3: タイムラインを開始・停止時刻内に制限する
reearth.timeline.setRangeType("clamped");
console.log("Timeline range type set to 'clamped'.");
// 使用例 4: タイムラインのバウンス動作を有効にする
reearth.timeline.setRangeType("bounced");
console.log("Timeline range type set to 'bounced'.");
```
## メソッド
[Section titled “メソッド”](#メソッド)
### tick
[Section titled “tick”](#tick)
tick メソッドは、タイムラインの現在のティック値を Date オブジェクトとして取得します。このメソッドは、アニメーションやプラグイン固有のイベントをタイムラインの進行と同期させる際に便利です。
#### 構文
[Section titled “構文”](#構文-7)
```ts
reearth.timeline.tick?: () => Date | undefined;
```
#### 戻り値:
[Section titled “戻り値:”](#戻り値)
**型** `Date | undefined`
* `"Date"`：タイムライン上の現在のティック値を Date オブジェクトとして表します。
* `"undefined"`：タイムラインが初期化されていないか非アクティブの場合、メソッドは undefined を返します。
#### 使用例
[Section titled “使用例”](#使用例-7)
```javascript
// 使用例: 現在のティック値を取得してログに出力する
const tickValue = reearth.timeline.tick?.();
if (tickValue) {
console.log("Current Tick Value:", tickValue.toISOString());
} else {
console.log("Timeline tick is not set or the timeline is inactive.");
}
```
### play
[Section titled “play”](#play)
play メソッドは、タイムラインの再生を開始します。タイムラインが現在の状態から範囲を進行し始めるようにトリガーするために使用します。このメソッドは、アニメーション、時間ベースのデータビジュアライゼーション、またはユーザーによるタイムライン操作のシナリオに便利です。
#### 構文
[Section titled “構文”](#構文-8)
```ts
reearth.timeline.play?: () => void;
```
#### 戻り値:
[Section titled “戻り値:”](#戻り値-1)
なし `(void)`。このメソッドは値を返さずに操作を実行します。
#### 使用例
[Section titled “使用例”](#使用例-8)
```javascript
// 使用例: タイムラインを再生する
if (reearth.timeline.play) {
reearth.timeline.play();
console.log("Timeline playback started.");
} else {
console.log("The play method is not available.");
}
```
### pause
[Section titled “pause”](#pause)
pause メソッドは、現在位置をリセットせずにタイムラインの再生を停止します。このメソッドは、タイムラインに紐づいたアニメーションや時間ベースの処理を一時的に停止し、後で同じ位置から再開できるようにする際に便利です。
#### 構文
[Section titled “構文”](#構文-9)
```ts
reearth.timeline.pause?: () => void;
```
#### 戻り値:
[Section titled “戻り値:”](#戻り値-2)
なし `(void)`。このメソッドは値を返さずに操作を実行します。
#### 使用例
[Section titled “使用例”](#使用例-9)
```javascript
// 使用例: タイムラインを一時停止する
if (reearth.timeline.pause) {
reearth.timeline.pause();
console.log("Timeline playback paused.");
} else {
console.log("The pause method is not available.");
}
```
### setTime
[Section titled “setTime”](#settime)
このメソッドを使用すると、タイムラインの開始・停止・現在時刻を設定できます。このメソッドは、アニメーションの同期や時間ベースのデータビジュアライゼーションの調整など、タイムラインの範囲と位置を動的に制御する際に便利です。
#### 構文
[Section titled “構文”](#構文-10)
```ts
reearth.timeline.setTime?: (time: Options) => void;
```
#### パラメータ
[Section titled “パラメータ”](#パラメータ)
##### `time`
[Section titled “time”](#time)
setTime メソッドの time オブジェクトを使用すると、タイムラインの3つの重要なポイントを定義できます。
**型**:
```ts
type Options = {
start: Date | string;
stop: Date | string;
current: Date | string;
};
```
* **`start: Date | string;`**：タイムラインの開始点を定義します。
* **`stop: Date | string;`**：タイムラインの終了点を定義します。
* **`current: Date | string;`**：タイムライン上の現在の時点を定義します。
#### 戻り値:
[Section titled “戻り値:”](#戻り値-3)
なし `(void)`。このメソッドは値を返さずに操作を実行します。
#### 使用例
[Section titled “使用例”](#使用例-10)
```javascript
// 使用例: カスタムタイムライン時刻を設定する
if (reearth.timeline.setTime) {
reearth.timeline.setTime({
start: new Date("2023-01-01T00:00:00Z"),
stop: new Date("2023-12-31T23:59:59Z"),
current: new Date("2023-06-01T12:00:00Z"),
});
console.log("Timeline times set successfully.");
} else {
console.log("The setTime method is not available.");
}
```
### setSpeed
[Section titled “setSpeed”](#setspeed)
このメソッドを使用すると、タイムラインの再生速度を動的に調整できます。このメソッドは、タイムラインが範囲をどれだけ速く進行するかを制御し、アニメーションや時間ベースのデータビジュアライゼーションに柔軟性を提供します。
#### 構文
[Section titled “構文”](#構文-11)
```ts
reearth.timeline.setSpeed?: (speed: number) => void;
```
#### パラメータ
[Section titled “パラメータ”](#パラメータ-1)
##### `speed`
[Section titled “speed”](#speed-1)
**型**: `number`
タイムラインの再生速度を表す数値です。`1.0`：リアルタイム再生、`>1.0`：リアルタイムより速い（例：2.0 で2倍速）、`<1.0`：リアルタイムより遅い（例：0.5 で半速）。
#### 戻り値:
[Section titled “戻り値:”](#戻り値-4)
なし `(void)`。このメソッドは値を返さずに操作を実行します。
#### 使用例
[Section titled “使用例”](#使用例-11)
```javascript
// 使用例 1: 再生速度をリアルタイム（1.0）に設定する
if (reearth.timeline.setSpeed) {
reearth.timeline.setSpeed(1.0);
console.log("Timeline speed set to real-time (1.0).");
} else {
console.log("The setSpeed method is not available.");
}
// 使用例 2: ユーザー入力からタイムライン速度を動的に調整する
const userSelectedSpeed = 3.0; // ユーザー入力の例
if (reearth.timeline.setSpeed) {
reearth.timeline.setSpeed(userSelectedSpeed);
console.log(`Timeline speed dynamically set to ${userSelectedSpeed}.`);
} else {
console.log("The setSpeed method is unavailable.");
}
```
### setStepType
[Section titled “setStepType”](#setsteptype)
setStepType メソッドを使用すると、タイムラインのステップ動作を動的に調整できます。タイムラインが可変レート（rate）で進むか、固定間隔（fixed）で進むかを制御します。アニメーションやデータ更新など、タイムラインの時間進行処理をカスタマイズする際に便利です。
#### 構文
[Section titled “構文”](#構文-12)
```ts
reearth.timeline.setStepType?: (stepType: "rate" | "fixed") => void;
```
#### パラメータ
[Section titled “パラメータ”](#パラメータ-2)
##### `stepType`
[Section titled “stepType”](#steptype-1)
ステップ動作を指定します。
**型**: `"rate" | "fixed"`
* **`rate`**：タイムラインは時間に比例した可変レートで進行し、通常は再生速度（speed プロパティ）の影響を受けます。
* **`fixed`**：タイムラインは固定時間間隔（例：毎秒、毎分、毎時）で進行します。
#### 戻り値:
[Section titled “戻り値:”](#戻り値-5)
なし `(void)`。このメソッドは値を返さずに操作を実行します。
#### 使用例
[Section titled “使用例”](#使用例-12)
```javascript
// 使用例 1: タイムラインのステップを 'rate' に設定する
if (reearth.timeline.setStepType) {
reearth.timeline.setStepType("rate");
console.log("Timeline step type set to 'rate'.");
} else {
console.log("The setStepType method is not available.");
}
// 使用例 2: タイムラインのステップを 'fixed' に設定する
reearth.timeline.setStepType?.("fixed");
console.log("Timeline step type set to 'fixed'.");
// 使用例 3: データ要件に基づいてタイムラインのステップ種類を動的に設定する
const requiresContinuousUpdates = true;
if (reearth.timeline.setStepType) {
if (requiresContinuousUpdates) {
reearth.timeline.setStepType("rate");
console.log("Timeline step type dynamically set to 'rate'.");
} else {
reearth.timeline.setStepType("fixed");
console.log("Timeline step type dynamically set to 'fixed'.");
}
}
```
### setRangeType
[Section titled “setRangeType”](#setrangetype)
setRangeType メソッドを使用すると、タイムラインが時間進行の範囲をどのように扱うかを動的に定義できます。このメソッドは、タイムラインが定義された startTime と stopTime を超えて拡張できるか、その範囲内に制限されるか、またはループ効果を生み出しながら開始・停止時刻の間で「バウンス」するかを決定します。
#### 構文
[Section titled “構文”](#構文-13)
```ts
reearth.timeline.setRangeType?: (
rangeType: "unbounded" | "clamped" | "bounced"
) => void;
```
#### パラメータ
[Section titled “パラメータ”](#パラメータ-3)
##### `rangeType`
[Section titled “rangeType”](#rangetype-1)
範囲の動作を指定します。
**型**: `"unbounded" | "clamped" | "bounced"`
* **`unbounded`**：タイムラインは startTime と stopTime を超えて無制限に拡張できます。
* **`clamped`**：タイムラインは定義された startTime と stopTime の範囲内に制限されます。
* **`bounced`**：タイムラインは startTime と stopTime の間で「バウンス」し、ループのような効果を生み出します。
#### 戻り値:
[Section titled “戻り値:”](#戻り値-6)
なし `(void)`。このメソッドは値を返さずに操作を実行します。
#### 使用例
[Section titled “使用例”](#使用例-13)
```javascript
// 使用例 1: タイムラインを無制限に進行させる
if (reearth.timeline.setRangeType) {
reearth.timeline.setRangeType("unbounded");
console.log("Timeline range type set to 'unbounded'.");
} else {
console.log("The setRangeType method is not available.");
}
// 使用例 2: タイムラインを定義された範囲内に制限する
reearth.timeline.setRangeType?.("clamped");
console.log("Timeline range type set to 'clamped'.");
// 使用例 3: タイムラインのバウンス動作を有効にする
if (reearth.timeline.setRangeType) {
reearth.timeline.setRangeType("bounced");
console.log("Timeline range type set to 'bounced'.");
}
// 使用例 4: アプリケーションの要件に基づいて範囲種類を動的に設定する
const useInfiniteTimeline = true;
if (reearth.timeline.setRangeType) {
if (useInfiniteTimeline) {
reearth.timeline.setRangeType("unbounded");
console.log("Timeline range type dynamically set to 'unbounded'.");
} else {
reearth.timeline.setRangeType("clamped");
console.log("Timeline range type dynamically set to 'clamped'.");
}
}
```
## イベント
[Section titled “イベント”](#イベント)
ノート
共通のイベントメソッド（`on`、`off`）の詳細については、[イベント](/ja/developer/plugin/api-reference/events) ページを参照してください。
### tick
[Section titled “tick”](#tick-1)
tick イベントは、タイムラインの現在時刻が更新されるたびに発火します。これは通常、タイムラインが進行するか、手動で調整されたときにトリガーされます。
#### 構文
[Section titled “構文”](#構文-14)
```ts
reearth.timeline.on("tick", (event: Date) => void): void;
```
#### パラメータ
[Section titled “パラメータ”](#パラメータ-4)
**event:** Date
tick イベント中のタイムラインの現在時刻を表す JavaScript Date オブジェクトです。
#### 使用例
[Section titled “使用例”](#使用例-14)
```javascript
// タイムラインの現在時刻の各ティックをログに出力する
reearth.timeline.on("tick", (e) => {
console.log("Timeline tick at:", e.toISOString());
});
// 特定のティック値に基づいてアクションを実行する
reearth.timeline.on("tick", (e) => {
const targetTime = new Date("2023-12-25T00:00:00Z");
if (e.getTime() === targetTime.getTime()) {
console.log("Merry Christmas! Timeline reached the target time.");
}
});
```
### commit
[Section titled “commit”](#commit)
commit イベントは、ウィジェット、プラグイン、またはその他のタイムラインブロックからの更新など、アクションによってタイムラインが変更されるたびに発火します。
#### 構文
[Section titled “構文”](#構文-15)
```ts
reearth.timeline.on("commit", (event: TimelineCommitter) => void): void;
```
#### パラメータ
[Section titled “パラメータ”](#パラメータ-5)
**event:** TimelineCommitter
タイムライン変更のソースと追加のメタデータを記述するオブジェクトです。
```ts
type TimelineCommitter = {
source:
| "widgetContext" // ウィジェット操作によるタイムライン変更
| "pluginAPI" // プラグイン API を通じた変更
| "storyTimelineBlock" // ストーリー内のタイムラインブロックによる変更
| "storyPage"; // ストーリーページナビゲーションによってトリガーされた変更
id?: string;
};
```
* **`source: string`**：コミットアクションの起点を指定します。
* **`id?: string`**：コミットのソースに対するオプションの識別子です。
#### 使用例
[Section titled “使用例”](#使用例-15)
```javascript
// タイムラインが変更されたときにコミットのソースと ID をログに出力する
reearth.timeline.on("commit", (e) => {
console.log(`Timeline commit from source: ${e.source}`);
if (e.id) {
console.log(`Commit ID: ${e.id}`);
}
});
// コミットのソースに基づいて特定のアクションを実行する
reearth.timeline.on("commit", (e) => {
if (e.source === "pluginAPI") {
console.log("Timeline updated via Plugin API.");
} else if (e.source === "storyPage") {
console.log("Timeline updated by a story page.");
}
});
```
# reearth.ui
> `reearth.ui` の API リファレンスです。
**`reearth.ui`** 名前空間は、プラグイン拡張（ウィジェットまたはブロック）のユーザーインターフェース要素を管理するための幅広い機能を提供します。
## メソッド
[Section titled “メソッド”](#メソッド)
### show
[Section titled “show”](#show)
このメソッドは、カスタム HTML コンテンツをプラグイン拡張（プラグイン設定に基づくウィジェットまたはブロック）として `reearth` に表示します。iframe の表示状態やサイズを動的に制御でき、iframe を視覚的に表示しないモードにも対応しています。パラメータは 2 つです。表示する HTML コンテンツと、省略可能なオプションオブジェクトです。
#### 構文
[Section titled “構文”](#構文)
```ts
reearth.ui.show: (
html: string,
options?: Options
) => void;
```
#### パラメータ
[Section titled “パラメータ”](#パラメータ)
##### `html`
[Section titled “html”](#html)
**型**: `string`
レンダリングする HTML コンテンツの文字列です。
##### `options`
[Section titled “options”](#options)
**省略可能**
**型**:
```ts
type Options = {
visible?: boolean;
width?: number | string;
height?: number | string;
extended?: boolean;
};
```
* **`visible?: boolean`**: `true` の場合、iframe を表示します。`false` の場合、iframe を非表示にし、プラグインはヘッドレスモードで動作します。デフォルト値は `true` です。
* **`width?: number | string;`**: ウィジェットの iframe の初期幅です。指定しない場合、iframe はコンテンツに合わせて自動リサイズされます。数値を指定した場合はピクセル単位として扱われます。このオプションは水平方向に拡張されていないウィジェットにのみ有効です。
* **`height?: number | string;`**: ウィジェットの iframe の初期高さです。指定しない場合、iframe はコンテンツに合わせて自動リサイズされます。数値を指定した場合はピクセル単位として扱われます。このオプションは垂直方向に拡張されていないウィジェットにのみ有効です。
* **`extended?: boolean;`**: iframe がより広い領域を占有するかどうかを示します。`true` の場合、iframe はコンテナ内の利用可能なスペースを埋めるように拡張されます。このオプションは、ウィジェットアラインシステムの拡張可能エリアに配置されたウィジェットにのみ有効です。
#### 戻り値
[Section titled “戻り値”](#戻り値)
なし（void）。このメソッドは値を返しません。
#### 使用例
[Section titled “使用例”](#使用例)
```javascript
const html = `
Hello world
`;
// HTML UI のみ表示する
reearth.ui.show(html);
// HTML UI を非表示状態で表示する
reearth.ui.show(html, { visible: false });
// 幅と高さを指定して HTML UI を表示する
reearth.ui.show(html, { width: 400, height: 200 });
// 拡張可能エリアで iframe を拡張する
reearth.ui.show(`Extended widget content
`, { extended: true });
```
### postMessage
[Section titled “postMessage”](#postmessage)
このメソッドは、プラグインの UI コンポーネント（iframe）にメッセージを送信します。
#### 構文
[Section titled “構文”](#構文-1)
```ts
reearth.ui.postMessage: (message: any) => void;
```
#### パラメータ
[Section titled “パラメータ”](#パラメータ-1)
##### `message`
[Section titled “message”](#message)
**型**: `any`
message には、構造化クローン可能な任意の型を指定できます。
#### 戻り値
[Section titled “戻り値”](#戻り値-1)
なし（void）。このメソッドは値を返しません。
#### 使用例
[Section titled “使用例”](#使用例-1)
```javascript
//使用例 1: UI iframe にメッセージを送信する
reearth.ui.postMessage("Hello, Re:Earth!");
//使用例 2: オブジェクト形式のメッセージを送信する
reearth.ui.postMessage({ type: "greeting", text: "Hello, World!" });
```
### resize
[Section titled “resize”](#resize)
プラグインが使用する iframe のサイズを調整します。width または height が undefined の場合は自動リサイズされます。数値を指定した場合はピクセル単位として扱われます。パラメータは 3 つです。width、height、および省略可能な extended です。
UI iframe はコンテンツサイズに基づいて自動的にリサイズされます。このメソッドは、iframe のサイズを手動で設定したい場合に便利です。
#### 構文
[Section titled “構文”](#構文-2)
```ts
reearth.ui.resize(
width: string | number | undefined,
height: string | number | undefined,
extended?: boolean | undefined
) => void;
```
#### パラメータ
[Section titled “パラメータ”](#パラメータ-2)
##### `width`
[Section titled “width”](#width)
**型**: `string | number | undefined`
ウィジェットの iframe の幅です。このフィールドは水平方向に拡張されていないウィジェットにのみ有効です。
##### `height`
[Section titled “height”](#height)
**型**: `string | number | undefined`
ウィジェットの iframe の高さです。このフィールドは垂直方向に拡張されていないウィジェットにのみ有効です。
##### `extended?`
[Section titled “extended?”](#extended)
**省略可能**
**型**: `boolean | undefined`
省略可能なパラメータです。iframe を拡張するかどうかを示すブール値です。このオプションは、ウィジェットアラインシステムの拡張可能エリアに配置されたウィジェットにのみ有効です。
* `true`: UI 要素を拡張します。
* `false`: UI 要素を拡張しません。
* `undefined`: 拡張状態を変更しません。
#### 使用例
[Section titled “使用例”](#使用例-2)
```javascript
// 使用例 1: UI を 400px × 300px にリサイズする
reearth.ui.resize(400, 300);
// 使用例 2: サイズを変更せずに UI 要素を拡張する
reearth.ui.resize(undefined, undefined, true);
// 使用例 3: 高さのみ 500px に変更し、他のプロパティは変更しない
reearth.ui.resize(undefined, 500);
```
### close
[Section titled “close”](#close)
このメソッドは、現在の UI ウィジェットを閉じるために使用します。クローズ操作をプログラムからトリガーする手段を提供します。パラメータはありません。
#### 構文
[Section titled “構文”](#構文-3)
```ts
reearth.ui.close: () => void
```
#### パラメータ
[Section titled “パラメータ”](#パラメータ-3)
なし
#### 戻り値
[Section titled “戻り値”](#戻り値-2)
なし（void）。このメソッドは値を返しません。
#### 使用例
[Section titled “使用例”](#使用例-3)
```ts
// 現在の UI ウィジェットを閉じる
reearth.ui.close();
```
## イベント
[Section titled “イベント”](#イベント)
ノート
共通のイベントメソッド（`on`、`off`）の詳細については、[イベント](/ja/developer/plugin/api-reference/events) ページを参照してください。
### update
[Section titled “update”](#update)
update イベントは、UI の状態またはコンテンツが変化するたびにトリガーされます。UI の状態の変化を追跡したり、最新のデータに基づいてコンテンツを更新したりする際に便利です。
#### 構文
[Section titled “構文”](#構文-4)
```ts
reearth.ui.on("update", () => void): void;
```
#### 使用例
[Section titled “使用例”](#使用例-4)
```javascript
reearth.ui.on("update", () => {
console.log("UI updated!");
});
```
### close
[Section titled “close”](#close-1)
close イベントは、UI が閉じられたときにトリガーされます。このイベントは、クリーンアップ処理の実行、データの保存、または UI が非アクティブになったことを他のコンポーネントに通知する際に使用できます。
#### 構文
[Section titled “構文”](#構文-5)
```ts
reearth.ui.on("close", () => void): void;
```
#### 使用例
[Section titled “使用例”](#使用例-5)
```javascript
reearth.ui.on("close", () => {
console.log("The UI was closed.");
});
```
# reearth.viewer
> reearth.viewer
`reearth.viewer` 名前空間は、ビューアと対話するための関数群を提供します。
## プロパティ
[Section titled “プロパティ”](#プロパティ)
### property
[Section titled “property”](#property)
`property` は、グローブ・地形・シーン・タイル・空など、ビューアに関する各種プロパティを提供します。
#### 構文
[Section titled “構文”](#構文)
```ts
reearth.viewer.property: ViewerProperty;
```
#### 戻り値
[Section titled “戻り値”](#戻り値)
**型** `ViewerProperty`
現在、`property` は明示的に設定されたプロパティのみを返します。デフォルト値は含まれません。
ノート
`ViewerProperty` は Re:Earth Core からインポートされています。詳細は [ViewerProperty](https://github.com/reearth/core/blob/alpha/src/Map/types/viewerProperty.ts) を参照してください。
### viewport
[Section titled “viewport”](#viewport)
`viewport` は、マップ領域に関連するプロパティと、現在のビューポート（ページ）の URL クエリパラメータを提供するために設計されています。
#### 構文
[Section titled “構文”](#構文-1)
```ts
reearth.viewer.viewport: Viewport;
```
#### 戻り値
[Section titled “戻り値”](#戻り値-1)
**型**
```ts
type Viewport = {
width: number;
height: number;
isMobile: boolean;
query: Record;
};
```
* **width:** ビューポートの幅です。
* **height:** ビューポートの高さです。
* **isMobile:** ビューポートがモバイルデバイスかどうかを示す真偽値です。bowser のユーザーエージェント検出に基づき判定されます。
* **query:** 現在のページの URL クエリパラメータです。
### env
[Section titled “env”](#env)
`env` は、現在実行中の Re:Earth Visualizer の環境情報を提供します。
#### 構文
[Section titled “構文”](#構文-2)
```ts
reearth.viewer.env: Env;
```
#### 戻り値
[Section titled “戻り値”](#戻り値-2)
**型**
```ts
type Env = {
inEditor: boolean;
isBuilt: boolean;
};
```
`inEditor` と `isBuilt` は、実行されているページやタブによって異なる値を持ちます。プラグインはこれらの値に基づいて動作を切り替えることができます。
| プロパティ | エディタ - マップ/ストーリー/ウィジェットタブ | エディタ - 公開タブ | 公開済みページ |
| -------- | ------------------------- | ----------- | ------- |
| inEditor | true | false | false |
| isBuilt | false | false | true |
### interactionMode
[Section titled “interactionMode”](#interactionmode)
`interactionMode` は、Re:Earth Visualizer におけるビューアのインタラクションモードを管理するプロパティとメソッドの集合を提供します。
#### interactionMode.mode
[Section titled “interactionMode.mode”](#interactionmodemode)
ビューアの現在のインタラクションモードです。
#### 構文
[Section titled “構文”](#構文-3)
```ts
reearth.viewer.interactionMode.mode: InteractionModeType
```
#### 戻り値
[Section titled “戻り値”](#戻り値-3)
**型** `InteractionModeType = "default" | "move" | "selection" | "sketch" | "spatialId"`
* **`default`**: デフォルトのインタラクションモードです。
* **`move`**: 移動インタラクションモードです。このモードでは選択が無効になります。
* **`selection`**: 選択インタラクションモードです。このモードでは移動が無効になります。
* **`sketch`**: スケッチインタラクションモードです。スケッチはこのモードでのみ有効にできます。
* **`spatialId`**: Spatial ID を扱うためのインタラクションモードです。Spatial ID の選択時に使用します。
#### interactionMode.override
[Section titled “interactionMode.override”](#interactionmodeoverride)
ビューアのインタラクションモードを上書きします。
#### 構文
[Section titled “構文”](#構文-4)
```ts
reearth.viewer.interactionMode.override: (
mode: InteractionModeType
) => void;
```
#### パラメータ
[Section titled “パラメータ”](#パラメータ)
##### `mode`
[Section titled “mode”](#mode)
**型**: `InteractionModeType`
設定するインタラクションモードです。
#### 戻り値
[Section titled “戻り値”](#戻り値-4)
なし（void）。このメソッドは値を返しません。
## メソッド
[Section titled “メソッド”](#メソッド)
### overrideProperty
[Section titled “overrideProperty”](#overrideproperty)
`overrideProperty` は、ビューアのプロパティを上書きするために使用します。
#### 構文
[Section titled “構文”](#構文-5)
```ts
reearth.viewer.overrideProperty: (property: ViewerProperty) => void;
```
#### パラメータ
[Section titled “パラメータ”](#パラメータ-1)
##### property
[Section titled “property”](#property-1)
**型** `ViewerProperty`
ノート
`ViewerProperty` は Re:Earth Core からインポートされています。詳細は [ViewerProperty](https://github.com/reearth/core/blob/alpha/src/Map/types/viewerProperty.ts) を参照してください。
#### 戻り値
[Section titled “戻り値”](#戻り値-5)
**型** `void`
このメソッドは戻り値を持ちません。
#### 使用例
[Section titled “使用例”](#使用例)
```javascript
// 地形を有効にする
reearth.viewer.overrideProperty({
terrain: {
enabled: true,
},
});
```
### capture
[Section titled “capture”](#capture)
`capture` 関数は、現在のビューアの画像を生成します。
#### 構文
[Section titled “構文”](#構文-6)
```ts
reearth.viewer.capture: (
type?: string,
encoderOptions?: number
) => string | undefined;
```
#### パラメータ
[Section titled “パラメータ”](#パラメータ-2)
##### type
[Section titled “type”](#type)
**型** `string`（省略可能）
画像フォーマットを示す文字列です。デフォルトのフォーマットは `image/png` であり、指定したフォーマットがサポートされていない場合もこのフォーマットが使用されます。
##### encoderOptions
[Section titled “encoderOptions”](#encoderoptions)
**型** `number`（省略可能）
`image/jpeg` や `image/webp` など非可逆圧縮をサポートするファイルフォーマットで画像を作成する際の画質を表す、0 から 1 の数値です。このオプションを指定しない場合、または値が許容範囲外の場合は、ユーザーエージェントのデフォルト品質値が使用されます。
ノート
このメソッドは内部的に `canvas.toDataURL` を呼び出しています。詳細は [HTMLCanvasElement: toDataURL() method](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/toDataURL) を参照してください。
#### 戻り値
[Section titled “戻り値”](#戻り値-6)
**型** `string | undefined`
リクエストされたデータ URL を含む文字列です。
#### 使用例
[Section titled “使用例”](#使用例-1)
```javascript
// 現在のマップのキャプチャを取得します。
// 返された画像文字列をウィジェット UI に送信してダウンロードをトリガーできます。
console.log(reearth.viewer.capture("image/png"));
```
### open
[Section titled “open”](#open)
`open` メソッドは、URL を新しいタブで開くために使用します。
#### 構文
[Section titled “構文”](#構文-7)
```ts
reearth.viewer.open: (url: string) => void;
```
#### パラメータ
[Section titled “パラメータ”](#パラメータ-3)
##### url
[Section titled “url”](#url)
**型** `string`
新しいタブで開く URL です。
#### 戻り値
[Section titled “戻り値”](#戻り値-7)
**型** `void`
### reload
[Section titled “reload”](#reload)
`reload` メソッドは、現在の Visualizer ページを再読み込みします。
#### 構文
[Section titled “構文”](#構文-8)
```ts
reearth.viewer.reload: () => void;
```
#### 戻り値
[Section titled “戻り値”](#戻り値-8)
**型** `void`
### tools
[Section titled “tools”](#tools)
`tools` モジュールは、グローブおよびシーン周辺のさまざまな計算を行うためのヘルパー関数のコレクションを提供します。
### > getLocationFromScreenCoordinate
[Section titled “> getLocationFromScreenCoordinate”](#-getlocationfromscreencoordinate)
スクリーン座標から地球上の位置を返します。
#### 構文
[Section titled “構文”](#構文-9)
```ts
reearth.viewer.tools.getLocationFromScreenCoordinate: (
x: number,
y: number,
withTerrain?: boolean
) => { lat: number; lng: number; height: number } | undefined;
```
#### パラメータ
[Section titled “パラメータ”](#パラメータ-4)
##### x
[Section titled “x”](#x)
**型** `number`
ビューア上の x ピクセル座標です。
##### y
[Section titled “y”](#y)
**型** `number`
ビューア上の y ピクセル座標です。
##### withTerrain
[Section titled “withTerrain”](#withterrain)
**型** `boolean`（省略可能）
地形の高さを考慮するかどうかを示す真偽値です。デフォルト値は `false` です。
#### 戻り値
[Section titled “戻り値”](#戻り値-9)
**型** `{ lat: number; lng: number; height: number } | undefined`
地球上の位置です。
### > getScreenCoordinateFromPosition
[Section titled “> getScreenCoordinateFromPosition”](#-getscreencoordinatefromposition)
地球上の位置からスクリーン座標を返します。
#### 構文
[Section titled “構文”](#構文-10)
```ts
reearth.viewer.tools.getScreenCoordinateFromPosition: (
position: [x: number, y: number, z: number]
) => [x: number, y: number] | undefined;
```
#### パラメータ
[Section titled “パラメータ”](#パラメータ-5)
##### position
[Section titled “position”](#position)
**型** `[x: number, y: number, z: number]`
地球上の位置（デカルト座標）です。
#### 戻り値
[Section titled “戻り値”](#戻り値-10)
**型** `[x: number, y: number] | undefined`
ビューア上のピクセル座標です。
### > getTerrainHeightAsync
[Section titled “> getTerrainHeightAsync”](#-getterrainheightasync)
指定した位置の地形の高さを返します。これは非同期関数です。
#### 構文
[Section titled “構文”](#構文-11)
```ts
reearth.viewer.tools.getTerrainHeightAsync: (
lng: number,
lat: number
) => Promise;
```
#### パラメータ
[Section titled “パラメータ”](#パラメータ-6)
##### lng
[Section titled “lng”](#lng)
**型** `number`
位置の経度です。
##### lat
[Section titled “lat”](#lat)
**型** `number`
位置の緯度です。
#### 戻り値
[Section titled “戻り値”](#戻り値-11)
**型** `Promise`
指定した位置の地形の高さです。
### > getGlobeHeight
[Section titled “> getGlobeHeight”](#-getglobeheight)
指定した位置の地表の高さを返します。
#### 構文
[Section titled “構文”](#構文-12)
```ts
reearth.viewer.tools.getGlobeHeight: (
lng: number,
lat: number
) => number | undefined;
```
#### パラメータ
[Section titled “パラメータ”](#パラメータ-7)
##### lng
[Section titled “lng”](#lng-1)
**型** `number`
位置の経度です。
##### lat
[Section titled “lat”](#lat-1)
**型** `number`
位置の緯度です。
#### 戻り値
[Section titled “戻り値”](#戻り値-12)
**型** `number | undefined`
指定した位置の地表の高さです。
### > getCurrentLocationAsync
[Section titled “> getCurrentLocationAsync”](#-getcurrentlocationasync)
ユーザーの現在位置を返します。これはブラウザの Geolocation API を使用する非同期関数です。
#### 構文
[Section titled “構文”](#構文-13)
```ts
reearth.viewer.tools.getCurrentLocationAsync: (
options?: Options
) => Promise;
```
#### パラメータ
[Section titled “パラメータ”](#パラメータ-8)
##### options
[Section titled “options”](#options)
**型** `Options`（省略可能）
以下のパラメータを含むオプションオブジェクトです。
* **maximumAge:** キャッシュされた位置情報の最大有効期間（ミリ秒）です。デフォルト値は `0` です。
* **timeout:** 位置情報の取得を待機する最大時間（ミリ秒）です。デフォルト値は `10,000ms` です。
* **enableHighAccuracy:** 高精度の位置情報をリクエストするかどうかです。デフォルト値は `false` です。
ノート
オプションの詳細については [Geolocation.getCurrentPosition()](https://developer.mozilla.org/docs/Web/API/Geolocation/getCurrentPosition) を参照してください。
#### 戻り値
[Section titled “戻り値”](#戻り値-13)
**型** `Promise`
```ts
type Location = {
lat: number;
lng: number;
height: number;
};
```
ユーザーの現在位置です。
### > cartographicToCartesian
[Section titled “> cartographicToCartesian”](#-cartographictocartesian)
地理座標をデカルト座標に変換します。
#### 構文
[Section titled “構文”](#構文-14)
```ts
reearth.viewer.tools.cartographicToCartesian: (
lng: number,
lat: number,
height: number,
options?: { useGlobeEllipsoid?: boolean }
) => [x: number, y: number, z: number] | undefined;
```
#### パラメータ
[Section titled “パラメータ”](#パラメータ-9)
##### lng
[Section titled “lng”](#lng-2)
**型** `number`
位置の経度です。
##### lat
[Section titled “lat”](#lat-2)
**型** `number`
位置の緯度です。
##### height
[Section titled “height”](#height)
**型** `number`
位置の高さです。
##### options
[Section titled “options”](#options-1)
**型** `{ useGlobeEllipsoid?: boolean }`（省略可能）
* **useGlobeEllipsoid:** グローブの楕円体を使用するかどうかを示す真偽値です。デフォルト値は `false` です。
#### 戻り値
[Section titled “戻り値”](#戻り値-14)
**型** `[x: number, y: number, z: number] | undefined`
デカルト座標の位置です。
### > cartesianToCartographic
[Section titled “> cartesianToCartographic”](#-cartesiantocartographic)
デカルト座標を地理座標に変換します。
#### 構文
[Section titled “構文”](#構文-15)
```ts
reearth.viewer.tools.cartesianToCartographic: (
x: number,
y: number,
z: number,
options?: { useGlobeEllipsoid?: boolean }
) => [lng: number, lat: number, height: number] | undefined;
```
#### パラメータ
[Section titled “パラメータ”](#パラメータ-10)
##### x
[Section titled “x”](#x-1)
**型** `number`
位置の x 座標です。
##### y
[Section titled “y”](#y-1)
**型** `number`
位置の y 座標です。
##### z
[Section titled “z”](#z)
**型** `number`
位置の z 座標です。
##### options
[Section titled “options”](#options-2)
**型** `{ useGlobeEllipsoid?: boolean }`（省略可能）
* **useGlobeEllipsoid:** グローブの楕円体を使用するかどうかを示す真偽値です。デフォルト値は `false` です。
#### 戻り値
[Section titled “戻り値”](#戻り値-15)
**型** `[lng: number, lat: number, height: number] | undefined`
地理座標の位置です。
### > transformByOffsetOnScreen
[Section titled “> transformByOffsetOnScreen”](#-transformbyoffsetonscreen)
スクリーン上のオフセットによって位置を変換します。
#### 構文
[Section titled “構文”](#構文-16)
```ts
reearth.viewer.tools.transformByOffsetOnScreen: (
rawPosition: [x: number, y: number, z: number],
screenOffset: [x: number, y: number]
) => [x: number, y: number, z: number] | undefined;
```
#### パラメータ
[Section titled “パラメータ”](#パラメータ-11)
##### rawPosition
[Section titled “rawPosition”](#rawposition)
**型** `[x: number, y: number, z: number]`
地球上の元の位置です。
##### screenOffset
[Section titled “screenOffset”](#screenoffset)
**型** `[x: number, y: number]`
スクリーン上のオフセットです。
#### 戻り値
[Section titled “戻り値”](#戻り値-16)
**型** `[x: number, y: number, z: number] | undefined`
変換後の位置です。
### > isPositionVisibleOnGlobe
[Section titled “> isPositionVisibleOnGlobe”](#-ispositionvisibleonglobe)
指定した位置がグローブ上で表示可能かどうかを確認します。
#### 構文
[Section titled “構文”](#構文-17)
```ts
reearth.viewer.tools.isPositionVisibleOnGlobe: (
position: [x: number, y: number, z: number]
) => boolean;
```
#### パラメータ
[Section titled “パラメータ”](#パラメータ-12)
##### position
[Section titled “position”](#position-1)
**型** `[x: number, y: number, z: number]`
地球上の位置です。
#### 戻り値
[Section titled “戻り値”](#戻り値-17)
**型** `boolean`
指定した位置がグローブ上で表示可能かどうかを示す真偽値です。
## イベント
[Section titled “イベント”](#イベント)
ノート
共通イベントメソッド（`on`、`off`）の詳細については、[イベント](/ja/developer/plugin/api-reference/events) ページを参照してください。
### resize
[Section titled “resize”](#resize)
`resize` イベントは、ビューアがリサイズされたときにトリガーされます。
#### 構文
[Section titled “構文”](#構文-18)
```ts
reearth.viewer.on("resize", ({width: number, height: number, isMobile:boolean}) => void);
```
#### パラメータ
[Section titled “パラメータ”](#パラメータ-13)
* **width:** ビューポートの幅です。
* **height:** ビューポートの高さです。
* **isMobile:** ビューポートがモバイルデバイスかどうかを示す真偽値です。bowser のユーザーエージェント検出に基づき判定されます。
#### 使用例
[Section titled “使用例”](#使用例-2)
```javascript
reearth.viewer.on("resize", ({ width, height, isMobile }) => {
console.log(`width: ${width}, height: ${height}, isMobile: ${isMobile}`);
});
```
### マウスイベント
[Section titled “マウスイベント”](#マウスイベント)
ビューアにはリッスン可能なマウスイベントのセットがあります。これらはすべて同じパラメータを持ちます。
サポートされているイベントは以下のとおりです。
* click
* doubleClick
* mouseDown
* mouseUp
* rightClick
* rightDown
* rightUp
* middleClick
* middleDown
* middleUp
* mouseMove
* mouseEnter
* mouseLeave
* wheel
#### 構文
[Section titled “構文”](#構文-19)
```ts
reearth.viewer.on("click", (event: MouseEvent)=> void);
```
#### パラメータ
[Section titled “パラメータ”](#パラメータ-14)
**event:** MouseEvent
```ts
type MouseEvent = {
x?: number;
y?: number;
lat?: number;
lng?: number;
height?: number;
layerId?: string;
delta?: number;
};
```
* **x:** ビューアを基準としたカーソルの x 座標です。
* **y:** ビューアを基準としたカーソルの y 座標です。
* **lat:** 地球上のカーソルの緯度です。
* **lng:** 地球上のカーソルの経度です。
* **height:** 地球上のカーソルの高さです。
* **layerId:** カーソルが乗っているオブジェクトのレイヤ ID です。
* **delta:** ホイールイベントのデルタ値です。
#### 使用例
[Section titled “使用例”](#使用例-3)
```javascript
reearth.viewer.on("mouseMove", ({ lat, lng, height }) => {
console.log(`lat: ${lat}, lng: ${lng}, height: ${height}`);
});
```
# 例
> 機能別に Visualizer プラグインの例を紹介します。
プラグインプレイグラウンドには、すぐに動かせるサンプルプラグイン（プリセット）が用意されています。ブラウザ上で開いて実行し、そのまま編集して試せるため、動作する実例を見て学ぶのに最適です。
[プラグインプレイグラウンド](https://visualizer.reearth.io/plugin-playground?plugin-id=my-plugin) を開き、**Plugins** パネルからプリセットを選択してコードを読み込み、実行してください。例は Playground 内と同じカテゴリで分類しています。
各プリセットは、**Share** ボタンで共有リンクをコピーするか、**Export** ボタンで `.zip` をダウンロードできます。非常に大きいプリセットはリンク共有できず、エクスポートのみ対応します。
## User Interface
[Section titled “User Interface”](#user-interface)
`reearth.ui` および関連 API による、パネル、ナビゲーション、ポップアップ、ダイアログなどのカスタム UI 構築。
* **Responsive Panel**: ユーザーがリスト項目を追加／削除できるパネルウィジェット
* **Sidebar**: 検索バーとメニュー項目を持つ折りたたみ式サイドバー
* **Header**: ロゴとメニューリンクを備えた固定トップナビゲーションバー
* **Popup**: ポップアップウィンドウの開閉、再配置、メッセージング（`reearth.popup` も使用）
* **Modal Window**: モーダルダイアログの表示と、メッセージ受信によるクローズ（`reearth.modal` を使用）
## Data
[Section titled “Data”](#data)
プラグイン、UI、Visualizer 間でのデータ受け渡し、およびクライアント側でのデータ保存。
* **Messenger Between Extension and Visualizer**: マップクリック座標を取得し、そこへカメラを飛ばす（`reearth.viewer`、`reearth.extension` を使用）
* **Messenger Between Extensions**: 2 つのウィジェット拡張間で双方向メッセージング（`reearth.extension` を使用）
* **Extension Property**: `reearth.yml` の schema で定義したプロパティを読み取り表示（`reearth.extension` を使用）
* **Client Storage**: ライト／ダークテーマの選択を保存し、次回も維持（`reearth.data` を使用）
## Viewer & Scene Settings
[Section titled “Viewer & Scene Settings”](#viewer--scene-settings)
`reearth.viewer` を使ったシーン環境の制御と、ビューア状態の取得。
* **Enable Shadow Style**: スイッチでシーンの影描画を切り替える
* **Enable Terrain**: Cesium World Terrain と depth testing を切り替える
* **Take Screenshot**: 現在の 3D ビューを PNG としてダウンロード
* **Mouse Events**: クリック地点の緯度・経度・高さを表示
* **Get Current Location**: デバイスの現在地を取得してカメラを移動（`reearth.camera` も使用）
## Manage Layer
[Section titled “Manage Layer”](#manage-layer)
`reearth.layers` による、多様な形式のデータレイヤの追加と制御。
* **Add GeoJSON**: GeoJSON レイヤ（インライン／URL）＋ マーカー／ポリゴン／ポリライン
* **Add Large GeoJSON**: `useAsResource` フラグで大規模 GeoJSON を最適化
* **Add CZML**: CZML レイヤ（data URI／URL）
* **Add KML**: KML レイヤ（data URI／URL）
* **Add CSV**: URL の CSV からレイヤ追加（lat/lng 列をマーカーにマッピング）
* **Add 3D Tiles**: 3Dタイルレイヤ（基本色／PBR スタイル）
* **Add Photogrammetric 3D Model**: 写真測量 3Dタイルデータセット
* **Add Point Cloud**: 3Dタイル形式の点群データセット
* **Add OSM 3D Tiles**: 組み込み `osm-buildings` タイプによる OSM 建物表示
* **Add WMS**: リモートサーバーの WMS タイルレイヤ
* **Add Google Photorealistic 3D Tiles**: Google のフォトリアルタイル（Google Maps API キーが必要）
* **Hide, Fly To, Delete Layer**: レイヤ単位の表示／非表示、fly-to、削除操作（`reearth.camera` も使用）
* **Override Layer Data**: ポリゴンのジオメトリをその場で更新
* **Show Selected Feature Information**: 選択フィーチャーのプロパティを選択時に表示
* **Add Infobox to Show All Properties**: すべてのプロパティを表示するインフォボックス
* **Add Infobox to Show Specific Properties**: 指定したプロパティのみ表示するインフォボックス
* **Add Infobox to Show Rich Blocks**: テキスト／画像／Markdown／動画などのリッチブロックを持つインフォボックス
## Manage Layer Style
[Section titled “Manage Layer Style”](#manage-layer-style)
共有プロパティから条件分岐、フィーチャーベースのルールまで、レイヤスタイルの適用。
* **Layer Styling Examples**: GeoJSON / CZML / KML / CSV に同じスタイリングを適用
* **Feature Style 3D Tiles**: 3Dタイルの color / PBR / shadows / highlight / wireframe
* **Feature Style 3D Model**: タイムライン駆動のアニメーション GLTF モデルのスタイリング（`reearth.timeline` も使用）
* **Override Style**: 高さに応じた 2 種のカラーグラデーションを切り替える
* **Style With Condition**: 高さ範囲に応じて色を割り当てる条件式
* **Filter Features by Style**: プロパティ条件でマーカーを表示／非表示
## Camera
[Section titled “Camera”](#camera)
`reearth.camera` によるカメラ移動と制御。
* **Zoom In Out**: ズームイン／ズームアウトボタン
* **Camera Rotation**: ターゲットの周りにカメラを連続回転
* **Camera Position**: ライブなカメラ位置を追跡し、手動で新しい値を適用
## Timeline
[Section titled “Timeline”](#timeline)
`reearth.timeline` による時間再生制御と、時間ベースのアニメーション。
* **Playback Control**: play/pause、速度、range-type の制御＋ライブ時計
* **Time Driven Features**: 時間とともに押し出し高さが変わる CZML ポリゴン（`reearth.layers` も使用）
* **Time Driven Path**: 時間サンプル位置により 3D 列車モデルをルートに沿ってアニメーション（`reearth.layers` も使用）
# 公式プラグイン
> Re:Earth チームが管理するプラグインを紹介します。
公式プラグインは Re:Earth チームが開発・保守しているプラグインです。すぐにインストールして利用でき、プラグイン開発の実用的な参考にもなります。以下は Re:Earth Visualizer Plugins Hub で公開されているものです。
## CMS Data Visualizer
[Section titled “CMS Data Visualizer”](#cms-data-visualizer)
CMS のデータを 3D マップ上に可視化し、マーカーや情報表示をカスタマイズできます。
[View on GitHub](https://github.com/reearth-plugins/cms-data-visualizer-plugin)
## CMS CSV Importer
[Section titled “CMS CSV Importer”](#cms-csv-importer)
Visualizer エディタから CSV データを CMS のモデルへ直接インポートします。
[View on GitHub](https://github.com/reearth-plugins/cms-csv-importer)
## Legend Panel
[Section titled “Legend Panel”](#legend-panel)
分かりやすい地図凡例を作成するためのカスタマイズ可能な凡例パネル。React / TypeScript / Tailwind CSS で構築されています。
[View on GitHub](https://github.com/reearth-plugins/legend-panel-plugin)
## Navigation Panel
[Section titled “Navigation Panel”](#navigation-panel)
滑らかなカメラ移動とズーム操作を、視覚的なフィードバック付きで提供する直感的なナビゲーションコントロールパネル。
[View on GitHub](https://github.com/reearth-plugins/navigation-panel-plugin)
***
公式プラグインに加え、コミュニティ製プラグインも含む最新一覧は、[Re:Earth Visualizer Plugins Hub](https://github.com/reearth-plugins/visualizer-plugin-hub) を参照してください。
# プラグインプレイグラウンドで動かす
> ローカル開発環境を準備せずにプラグインを実行、編集します。
## プラグインプレイグラウンドで動かす
[Section titled “プラグインプレイグラウンドで動かす”](#プラグインプレイグラウンドで動かす)
プラグインプレイグラウンドは、Re:Earth Visualizer プラグインを**ブラウザ上で**作成・検証できるインタラクティブ環境です。コードを書いて実行し、結果をライブマップ上で即座に確認できます。Playground の核心はこの「変更 → 実行 → 観察」の高速ループにあり、すべてが 1 画面で完結するため、パッケージングやインストールなしにアイデアを試してすぐ効果を確認できます。インストール作業やローカル環境構築が不要なため、プラグインに初めて触れる場合でも、アイデアのプロトタイピングでも、最速で試せます。
Playground は次のリンクから開けます：[プラグインプレイグラウンド](https://visualizer.reearth.io/plugin-playground?plugin-id=my-plugin)
## Playground のレイアウト
[Section titled “Playground のレイアウト”](#playground-のレイアウト)
Playground は 3 つのカラムに分かれています。
* **Viewer**（左）— プラグインがリアルタイムに動作するライブマップ。下には現在のシーンの **Layers** / **Settings** / **Extension Settings** パネルがあります。
* **Plugins**（中央）— 利用可能なプラグインと、選択したプラグインを構成するファイル（`reearth.yml` や各拡張の JavaScript ファイルなど）を一覧表示します。上部にはプラグイン／ファイル管理のボタン列があります。
* **Code**（右）— 選択したファイル内容を表示するコードエディタ。ここでプラグインコードを編集します。
Playground を開くと、**Custom** カテゴリに **My Plugin** というデフォルトプラグインが既にロードされています。`reearth.yml` とサンプル拡張ファイルが事前に用意されているので、そのまま実行することも、出発点として改変することもできます。
## Plugins パネルのボタン
[Section titled “Plugins パネルのボタン”](#plugins-パネルのボタン)
**Plugins** パネル上部のボタン列で作業を管理できます。
* **Add file** — 現在のプラグインに新しいファイルを追加します。
* **Import plugin** — 既存のプラグインを Playground に読み込みます。
* **Export plugin** — 現在のプラグインを `reearth.yml` と JavaScript ファイルを含む `.zip` としてダウンロードします。これは Re:Earth Visualizer にインストールするのと同じ形式です。
* **Share plugin** — プラグインの共有リンクをクリップボードにコピーし、他の人に送れるようにします。
## プリセット例を動かす
[Section titled “プリセット例を動かす”](#プリセット例を動かす)
Playground には、**User Interface**、**Data**、**Viewer & Scene Settings**、**Manage Layer**、**Camera**、**Timeline** などのカテゴリに分かれた、すぐに動かせるサンプルプラグイン（プリセット）が用意されています。これらは動作する実例として最適で、実際のコードから学べます。
プリセットを実行する手順：
1. **Plugins** パネルでカテゴリを選び、プリセットを 1 つ選択します。コードが **Code** エディタに読み込まれます。
2. **Code** パネル上部の **run** ボタンをクリックします。プラグインが実行され、**Viewer** のマップ上に表示されます。
3. **Code** エディタでコードを編集し、再度 **run** をクリックすると変更が反映されます。
この「ロード → 実行 → 編集」のループが Playground 作業の中心で、各変更の効果をすぐに確認できます。
## HTML Editor で UI を編集する
[Section titled “HTML Editor で UI を編集する”](#html-editor-で-ui-を編集する)
拡張の UI は、JavaScript ファイル内のバッククォート（\`）文字列として HTML を記述します。数行なら問題ありませんが、長くなると編集しづらくなります。
その場合、**Code** パネル上部の **HTML Editor** ボタンをクリックしてください。UI 用の専用エディタが開き、通常のコードエディタと同様に HTML / CSS / JavaScript を書けます（シンタックスハイライトあり）。編集後に **Submit** をクリックすると、変更がプラグインに反映されます。
## プラグインをエクスポートする
[Section titled “プラグインをエクスポートする”](#プラグインをエクスポートする)
プラグインが期待通りに動作したら、**Plugins** パネルの **Export plugin** をクリックして `.zip` としてダウンロードします。
* ダウンロードした `.zip` は、任意の Re:Earth Visualizer プロジェクトにインストールできます。
* あるいは、「[ローカル開発環境をセットアップする](/ja/developer/plugin/get-started/set-up-a-local-development-environment/)」を参照して、ローカル環境で開発を続けることもできます。
# ローカル開発環境をセットアップする
> Visualizer プラグイン開発用のローカル環境を準備します。
ノート
このセクションでは、現在のテンプレートベースのワークフローを説明します。Re:Earth Visualizer のプラグイン CLI は現在利用できません。
プラグインプレイグラウンドは素早い試作に最適ですが、本格的なプラグインを作る場合はローカル開発環境が適しています。自分のエディタでコードを書き、`.zip` を手動でビルドして再インストールすることなく、Re:Earth Visualizer 上でほぼ即時に変更を確認できます。
このワークフローは次の 2 つで構成されます：
* テンプレートから作成するプラグインプロジェクト
* DEV\_PLUGIN 機能を使い、プレビューサーバーからプラグインを直接読み込むローカル版 Re:Earth Visualizer
## 前提条件
[Section titled “前提条件”](#前提条件)
このガイドでは、Re:Earth Visualizer がローカルで起動しており `http://localhost:3000` でアクセスできることを前提とします。Visualizer 本体（サーバー／DB を含む）のセットアップは別の手順です。詳細は [reearth-visualizer repository](https://github.com/reearth/reearth-visualizer) を参照してください。
また、[Node.js](https://nodejs.org/) と [Yarn](https://yarnpkg.com/) がインストールされている必要があります。
## テンプレートからプラグインを作成する
[Section titled “テンプレートからプラグインを作成する”](#テンプレートからプラグインを作成する)
推奨する開始点は、React / ShadCN / Tailwind CSS を用いた [Re:Earth Visualizer Plugin ShadCN Template](https://github.com/reearth-plugins/reearth-visualizer-plugin-shadcn-template) です。
ノート
このテンプレートは便利な出発点ですが必須ではありません。どのフレームワークやライブラリを使っても構いません。重要なのは DEV\_PLUGIN 機能で、ローカルのプレビューサーバーからプラグインを読み込める点です。
テンプレートからプロジェクトを作成し、ターミナルでそのディレクトリを開いたら：
1. プロジェクトディレクトリへ移動：
```bash
cd your-new-plugin
```
2. 依存関係をインストール：
```bash
yarn install
```
3. 必要ファイルを生成するため、初回ビルドを実行：
```bash
yarn build
```
4. 開発／プレビューサーバーを起動：
```bash
yarn dev-build
```
この最後のコマンドは、保存のたびに自動でビルドし、`http://localhost:5005` のプレビューサーバーから配信します。
## Re:Earth Visualizer で DEV\_PLUGIN を有効化する
[Section titled “Re:Earth Visualizer で DEV\_PLUGIN を有効化する”](#reearth-visualizer-で-dev_plugin-を有効化する)
次に、ローカル Visualizer がそのプレビューサーバーからプラグインをロードするよう設定します。
1. ローカル Re:Earth Visualizer プロジェクトの `web` ディレクトリへ移動し、まだ存在しなければ `.env` ファイルを作成します：
```bash
cd web
touch .env
```
2. `env` にプレビューサーバー URL を追加します：
```bash
REEARTH_WEB_DEV_PLUGIN_URLS='["http://localhost:5005"]'
```
`.env` を保存すると Web サーバーは自動的に再起動します。
## ウィジェットプラグインをプロジェクトに追加する
[Section titled “ウィジェットプラグインをプロジェクトに追加する”](#ウィジェットプラグインをプロジェクトに追加する)
両方のサーバーが起動したら、Visualizer 上でプラグインをホストするプロジェクトを用意します。
1. `http://localhost:3000` でローカル Re:Earth Visualizer を開きます。
2. ダッシュボードから新しいプロジェクトを作成します。
3. プロジェクトをダブルクリックして開きます。
4. エディタのヘッダーで **Install Dev Plugins** をクリックし、プレビューサーバーからプラグインを取得してインストールします。
5. **Widgets** タブを開き、シーンにプラグインのウィジェットを追加します。
ノート
この手順はウィジェット拡張向けです。InfoboxBlock や StoryBlock の拡張を持つプラグインもインストール手順（ステップ 1〜4）は同じですが、シーンへの追加は **Widgets** タブではなく、レイヤのインフォボックス設定やストーリーページから行います。各拡張タイプがどこに表示されるかは「[拡張タイプの違い](/ja/developer/plugin/overview/extension-types/)」を参照してください。
## 開発ループ
[Section titled “開発ループ”](#開発ループ)
接続できると、日々の作業はとても短くなります。
1. プラグインコードを変更して保存すると、自動的に再ビルドされます。
2. Visualizer のエディタヘッダーで **Reload Dev Plugin Extensions** をクリックすると、更新された拡張コードが読み込まれます。
ページ全体を再読み込みするのではなく、プラグインだけが再読み込みされるため、変更はほぼ即時に反映されます。
## DEV\_PLUGIN の 2 つのボタン
[Section titled “DEV\_PLUGIN の 2 つのボタン”](#dev_plugin-の-2-つのボタン)
DEV\_PLUGIN ワークフローでは、Visualizer のエディタヘッダーに 2 つのボタン（どちらもパズルピースアイコン）が追加されます。
* **Install Dev Plugins** — プレビューサーバーからプラグインを取得し、`.zip` にパッケージ化してインストールします。
* **Reload Dev Plugin Extensions** — ページを再読み込みせずに、プレビューサーバーから拡張コードを再読み込みします。
どちらを押すべきかは、変更内容に応じて次の表で判断してください。
| 変更したもの | 使用するボタン |
| ------------------------------ | ---------------------------- |
| プロジェクトへの初回セットアップ | Install Dev Plugins |
| 拡張コード（TypeScript / JavaScript） | Reload Dev Plugin Extensions |
| `reearth.yml`（プラグインマニフェスト） | Install Dev Plugins |
# ユーザーが設定できるプロパティを受け取る
> インスペクターでユーザーが設定したプロパティを読み取ります。
このガイドを終えると、Re:Earth Visualizer のインスペクターパネルからユーザーが設定できる項目をプラグインに追加し、拡張コードからその値を読み取れるようになります。このガイドは、`reearth.yml` と拡張ファイルの基本的な構造を把握していることを前提としています。
ユーザーが設定できるプロパティを追加するには、`reearth.yml` でスキーマを宣言します。Re:Earth Visualizer がそのスキーマをインスペクターパネルに表示し、拡張コードからは `reearth.extension` を使って値を読み取れます。
## サンプルコード
[Section titled “サンプルコード”](#サンプルコード)
この例では、ユーザーが背景色を選択できるカラーピッカーを追加します。拡張コードはその色を読み取り、UI に渡してパネルの背景に適用します。
**reearth.yml**
```yaml
id: accept-props-plugin
name: Accept Props Plugin
version: 1.0.0
extensions:
- id: accept-props
type: widget
name: Accept Props
schema:
groups:
- id: appearance
fields:
- id: primary_color
type: string
ui: color
title: Primary color
defaultValue: "#3a86ff"
```
**accept-props.js**
```javascript
const color =
reearth.extension.widget?.property?.appearance?.primary_color ?? "#3a86ff";
reearth.ui.show(`
`);
```
## 結果
[Section titled “結果”](#結果)
パネルが地図上に表示されます。インスペクターパネルで別の色を選択すると、プラグインをリロードした際にその色がパネルに反映されます。
地図データ提供：[OpenStreetMap](https://www.openstreetmap.org/copyright)
## 仕組み
[Section titled “仕組み”](#仕組み)
**`reearth.yml` でスキーマを宣言する**
スキーマはウィジェットの `schema` キーの下に記述します。`groups` は設定パネルのセクションを定義し、各 `fields` がひとつの設定項目に対応します。
```yaml
schema:
groups:
- id: appearance
fields:
- id: primary_color
type: string
ui: color
title: Primary color
defaultValue: "#3a86ff"
```
* **`id`**: コードでフィールドを参照するために使う識別子。
* **`type`**: フィールドの値の型。`string`、`number`、`bool` などが使えます。
* **`ui`**: インスペクターに表示するウィジェットの種類。`color` を指定するとカラーピッカーが表示されます。
* **`title`**: インスペクターに表示されるラベル。
* **`defaultValue`**: 初期値。
**コードで値を読み取る**
`reearth.extension` を通じてプロパティにアクセスします。パスは `widget → property → <グループ ID> → <フィールド ID>` の順になります。
```javascript
const color =
reearth.extension.widget?.property?.appearance?.primary_color ?? "#3a86ff";
```
オプショナルチェーン（`?.`）を使うのは、ウィジェット・グループ・フィールドがどれかひとつでも未設定の場合に `undefined` を返すためです。`??` はフォールバック値として機能します。
## 次のステップ
[Section titled “次のステップ”](#次のステップ)
* [reearth.extension API リファレンス](/ja/developer/plugin/api-reference/extension/): ウィジェット・インフォボックスブロック・ストーリーブロックのプロパティの完全な一覧
* [プラグインの構造](/ja/developer/plugin/overview/plugin-structure/): スキーマフィールドの完全なリストと各タイプの説明
# レイヤを追加する
> データをレイヤとして Visualizer のシーンに追加します。
このガイドを終えると、プラグインから地図にレイヤを追加できるようになります（例：特定の座標にマーカーを配置する）。このガイドは、`reearth.yml` と拡張ファイルの基本的な構造を把握していることを前提としています。
レイヤを追加するには、レイヤのデータと表示方法を記述したレイヤオブジェクトを `reearth.layers.add` に渡します。このメソッドは新しいレイヤの ID を返します。この ID を保持しておくと、後でレイヤを変更・削除できます。
## サンプルコード
[Section titled “サンプルコード”](#サンプルコード)
この例では、東京の座標に赤いマーカーをひとつ追加します。
**reearth.yml**
```yaml
id: add-layer-plugin
name: Add Layer Plugin
version: 1.0.0
extensions:
- id: add-layer
type: widget
name: Add Layer
```
**add-layer.js**
```javascript
const layerId = reearth.layers.add({
type: "simple",
data: {
type: "geojson",
value: {
type: "FeatureCollection",
features: [
{
type: "Feature",
properties: {},
geometry: {
type: "Point",
coordinates: [139.97422779688281, 35.74642872517698],
},
},
],
},
},
marker: {
style: "point",
pointColor: "#ff0000",
pointSize: 12,
},
});
if (layerId) {
console.log("レイヤを追加しました。ID:", layerId);
} else {
console.log("レイヤの追加に失敗しました。");
}
reearth.camera.flyTo(
{
lat: 35.74642872517698,
lng: 139.97422779688281,
height: 200000,
},
{ duration: 2 }
);
```
## 結果
[Section titled “結果”](#結果)
ウィジェットがロードされると、カメラが東京に移動し、指定した座標に赤いマーカーが表示されます。
地図データ提供：[OpenStreetMap](https://www.openstreetmap.org/copyright)
## 仕組み
[Section titled “仕組み”](#仕組み)
`reearth.layers.add` にレイヤオブジェクトをひとつ渡します。オブジェクトには 3 つの重要な部分があります。
* **`type`**: レイヤの種類。データを直接提供するレイヤには `"simple"` を使います。ほとんどの場合これで対応できます。
* **`data`**: レイヤのソースデータを記述します。
* **`type`**: データ形式。この例では `"geojson"` を使用。他にも `"czml"`、`"csv"`、`"3dtiles"`、`"kml"` などがサポートされています。
* **`value`**: データ本体をインラインで指定。外部ソースからデータを読み込む場合は `value` の代わりに `url` を指定できます。
* **外観キー**: Re:Earth Visualizer にデータのレンダリング方法を指示します。この例では `marker` に `style: "point"`、`pointColor`、`pointSize` を指定。他の外観キーには `polyline`、`polygon`、`model` などがあります。
`reearth.layers.add` は新しいレイヤの ID を文字列で返します。レイヤを追加できなかった場合は `undefined` を返します。後で `reearth.layers.override` でレイヤを変更したり、`reearth.layers.delete` で削除したりする場合は、この ID を保持しておいてください。
ノート
`reearth.layers.delete` で削除できるのは、プラグイン API 経由で一時的に追加したレイヤのみです。保存済みプロジェクトの一部であるレイヤは削除できません。
## 次のステップ
[Section titled “次のステップ”](#次のステップ)
* [reearth.layers API リファレンス](/ja/developer/plugin/api-reference/layers/): レイヤオブジェクトの全項目、すべてのデータ型、外観オプション
* [reearth.camera API リファレンス](/ja/developer/plugin/api-reference/camera/): `flyTo` とその他のカメラ操作
* [レイヤにインフォボックスを設定する](/ja/developer/plugin/guides/configure-an-infobox-for-a-layer/): ユーザーがレイヤをクリックしたときにフィーチャの詳細を表示する
# 背景地図を変更する
> プラグインから組み込みまたはカスタムの背景地図を変更します。
このガイドを終えると、プラグインから背景地図（地球上に表示されるベース画像）を変更できるようになります。このガイドは、`reearth.yml` と拡張ファイルの基本的な構造を把握していることを前提としています。
背景地図を変更するには、`tiles` 配列を指定して `reearth.viewer.overrideProperty` を呼び出します。各エントリがひとつのタイルソースを表します。Re:Earth Visualizer にはいくつかの組み込み背景地図が用意されており、名前で選択できます。また、URL を指定してカスタムのタイルサーバーを使うこともできます。
ノート
`overrideProperty` で行った変更は一時的なものです。プロジェクトには保存されず、ページをリロードすると元に戻ります。
## サンプルコード
[Section titled “サンプルコード”](#サンプルコード)
この例では、背景地図を国土地理院標準地図に切り替えます。
**reearth.yml**
```yaml
id: basemap-plugin
name: Basemap Plugin
version: 1.0.0
extensions:
- id: basemap-demo
type: widget
name: Basemap Demo
```
**basemap-demo.js**
```javascript
reearth.viewer.overrideProperty({
tiles: [
{
id: "gsi",
type: "japan_gsi_standard",
},
],
});
```
## 結果
[Section titled “結果”](#結果)
ウィジェットがロードされると、地球のベース画像が国土地理院標準地図に切り替わります。
## 仕組み
[Section titled “仕組み”](#仕組み)
`reearth.viewer.overrideProperty` は実行時にビューアのプロパティを設定します。背景地図を変更するには `tiles` 配列を渡します。指定した画像が現在の背景地図と置き換わります。各タイルエントリには `id`（任意の一意な識別子）と、組み込みの `type` またはカスタムの `url` が必要です。
### 組み込み背景地図を使う
[Section titled “組み込み背景地図を使う”](#組み込み背景地図を使う)
Re:Earth Visualizer の組み込み背景地図を使うには、`type` に背景地図の名前を設定します。URL は不要で、各組み込み背景地図はタイルの読み込み先を既に知っています。
| タイプ | 背景地図 | Cesium Ion トークンが必要 |
| -------------------- | ------------------ | ------------------ |
| `open_street_map` | OpenStreetMap | いいえ |
| `japan_gsi_standard` | 国土地理院標準地図 | いいえ |
| `carto_light` | CARTO ライト | いいえ |
| `default` | Cesium Ion デフォルト画像 | はい |
| `default_road` | Cesium Ion ロードマップ | はい |
| `default_label` | Cesium Ion ラベル付き画像 | はい |
| `black_marble` | 夜の地球 | はい |
「はい」と表示されている背景地図は Cesium Ion から画像を読み込むため、シーンに Cesium Ion のアクセストークンが設定されている場合のみ使用できます。
### カスタム背景地図を使う
[Section titled “カスタム背景地図を使う”](#カスタム背景地図を使う)
上記のリストにないタイルサーバーを使う場合は、標準の `{z}/{x}/{y}` テンプレート形式で `url` を指定します。
```javascript
reearth.viewer.overrideProperty({
tiles: [
{
id: "custom",
url: "https://example.com/tiles/{z}/{x}/{y}.png",
},
],
});
```
注意
各背景地図にはそれぞれ利用規約と帰属表示の要件があります。組み込み・カスタムを問わず、背景地図を使用する際はプロバイダーの帰属表示ルールに従い、公開前に利用規約を確認してください。
## 次のステップ
[Section titled “次のステップ”](#次のステップ)
* [reearth.viewer API リファレンス](/ja/developer/plugin/api-reference/viewer/): `overrideProperty` とその他のビューアメソッド
# プラグインと Re:Earth の間で通信する
> プラグインと Re:Earth の間でメッセージを送受信します。
このガイドを終えると、プラグインの UI（iframe）とロジック（拡張コード）の間でメッセージを双方向に送受信できるようになります。このガイドは、`reearth.yml` と拡張ファイルの基本的な構造を把握していることを前提としています。
Re:Earth Visualizer のプラグインは、ロジックを担う拡張コードと UI を担う iframe の 2 つの部分で構成されています。これらは `postMessage` / `on("message")` のパターンを使って通信します。
## サンプルコード
[Section titled “サンプルコード”](#サンプルコード)
この例では、ボタンがひとつある UI パネルを作ります。ボタンをクリックするとロジック側にメッセージが送られ、ロジック側はカメラを東京に向け、確認メッセージを UI に返します。
**reearth.yml**
```yaml
id: communicate-plugin
name: Communicate Plugin
version: 1.0.0
extensions:
- id: communicate-demo
type: widget
name: Communicate Demo
```
**communicate-demo.js**
```javascript
reearth.ui.show(`
`);
reearth.extension.on("message", (message) => {
if (message?.action === "flyToTokyo") {
reearth.camera.flyTo(
{ lat: 35.6762, lng: 139.6503, height: 150000 },
{ duration: 2 }
);
reearth.ui.postMessage({
action: "done",
message: "東京へ移動しました！",
});
}
});
```
## 結果
[Section titled “結果”](#結果)
地図上にパネルが表示されます。ボタンをクリックするとカメラが東京に向かい、ステータスメッセージが「東京へ移動しました！」に変わります。
地図データ提供：[OpenStreetMap](https://www.openstreetmap.org/copyright)
## 仕組み
[Section titled “仕組み”](#仕組み)
プラグインには 2 つのメッセージの流れがあります。
**UI → ロジック**
UI（iframe）は `parent.postMessage` を使って拡張コードにメッセージを送ります。
```javascript
parent.postMessage({ action: "flyToTokyo" }, "*");
```
拡張コード側では `reearth.extension.on("message", handler)` で受け取ります。
```javascript
reearth.extension.on("message", (message) => {
if (message?.action === "flyToTokyo") {
// 処理
}
});
```
**ロジック → UI**
拡張コードは `reearth.ui.postMessage` を使って UI にメッセージを送ります。
```javascript
reearth.ui.postMessage({ action: "done", message: "東京へ移動しました！" });
```
UI 側では `window.addEventListener("message", handler)` で受け取ります。
```javascript
window.addEventListener("message", function (e) {
if (e.data?.action === "done") {
document.getElementById("status").textContent = e.data.message;
}
});
```
メッセージのペイロードには任意のシリアライズ可能な値を使えます。`action` フィールドはあくまでも規約です。何を送るかは自由に決められます。
## 次のステップ
[Section titled “次のステップ”](#次のステップ)
* [reearth.ui API リファレンス](/ja/developer/plugin/api-reference/ui/): `show`、`postMessage` などの完全な一覧
* [reearth.extension API リファレンス](/ja/developer/plugin/api-reference/extension/): メッセージイベントとプロパティアクセス
* [プラグインシステムの仕組み](/ja/developer/plugin/overview/how-the-plugin-system-works/): 2 つの部分がどのように分離されているかの詳細
# レイヤにインフォボックスを設定する
> レイヤの情報を表示するインフォボックスを設定します。
このガイドを終えると、レイヤにインフォボックスを付与できるようになります。ユーザーがそのレイヤのフィーチャをクリックすると、フィーチャの情報を表示するパネルが開きます。このガイドは、レイヤの追加に慣れていることを前提としています（[レイヤを追加する](/ja/developer/plugin/guides/add-a-layer/)を参照）。
インフォボックスはレイヤ自体の `infobox` プロパティとして設定します。インフォボックスにひとつ以上のブロックを追加すると、ユーザーがそのレイヤのフィーチャを選択したときに Re:Earth Visualizer がそれらを表示します。
## サンプルコード
[Section titled “サンプルコード”](#サンプルコード)
この例では、いくつかのプロパティを持つマーカーをひとつ追加し、フィーチャが選択されたときにそのすべてのプロパティを自動で表示するインフォボックスを付与します。
**reearth.yml**
```yaml
id: infobox-demo-plugin
name: Infobox Demo Plugin
version: 1.0.0
extensions:
- id: infobox-demo
type: widget
name: Infobox Demo
```
**infobox-demo.js**
```javascript
reearth.layers.add({
type: "simple",
data: {
type: "geojson",
value: {
type: "FeatureCollection",
features: [
{
type: "Feature",
properties: {
name: "東京タワー",
height: "333 m",
category: "ランドマーク",
},
geometry: {
type: "Point",
coordinates: [139.7454, 35.6586],
},
},
],
},
},
infobox: {
blocks: [
{
pluginId: "reearth",
extensionId: "propertyInfoboxBetaBlock",
},
],
},
marker: {
style: "point",
pointColor: "#ff0000",
pointSize: 12,
},
});
reearth.camera.setView({
lat: 35.6586,
lng: 139.7454,
height: 80000,
heading: 0,
pitch: -1.5708,
roll: 0,
});
```
## 結果
[Section titled “結果”](#結果)
東京タワーの位置にマーカーが表示されます。クリックするとインフォボックスが開き、フィーチャのプロパティ（名前、高さ、カテゴリ）が一覧表示されます。
地図データ提供：[OpenStreetMap](https://www.openstreetmap.org/copyright)
## 仕組み
[Section titled “仕組み”](#仕組み)
インフォボックスはレイヤ自体に設定します。`reearth.layers.add` に渡す `infobox` プロパティを通じて定義します。
```javascript
infobox: {
blocks: [
{ pluginId: "reearth", extensionId: "propertyInfoboxBetaBlock" }
]
}
```
* **`blocks`**: インフォボックスに表示するブロックのリスト（順番通り）。
* **`pluginId`** と **`extensionId`**: 表示するブロックを識別します。ここでは `reearth` / `propertyInfoboxBetaBlock` という組み込みブロックを使用しており、選択されたフィーチャのすべてのプロパティを自動で一覧表示します。ブロックのコードを書かなくても完全なプロパティ表示が得られます。
インフォボックスに表示されるプロパティは、GeoJSON の各フィーチャの `properties` オブジェクトから取得されます。ここでは `name`、`height`、`category` です。プロパティを追加するとインフォボックスにも表示されます。
インフォボックスはレイヤに属しているため、ユーザーがそのレイヤのフィーチャを選択したときだけ表示されます。フィーチャをクリックするまでは何も表示されません。
## 次のステップ
[Section titled “次のステップ”](#次のステップ)
* [レイヤを追加する](/ja/developer/plugin/guides/add-a-layer/): このガイドの土台となるレイヤの基本
* [reearth.layers API リファレンス](/ja/developer/plugin/api-reference/layers/): インフォボックスとブロックのオプションを含む完全なレイヤオブジェクト
* [拡張タイプの違い](/ja/developer/plugin/overview/extension-types/): InfoboxBlock 拡張タイプとここで作ったものの関係
# UI を表示する
> Visualizer プラグインからユーザーインターフェースを表示します。
このガイドを終えると、Re:Earth Visualizer 内でプラグインのカスタム UI を描画できるようになります。ここでは、`reearth.yml` と拡張ファイルからなる基本的なプラグイン構成を理解していることを前提とします。
プラグインは `reearth.ui.show` に HTML を渡すことで UI を表示します。Re:Earth Visualizer はその HTML を iframe 内にレンダリングします。iframe は通常の Web ページのように振る舞うため、標準の HTML / CSS / JavaScript を使って任意の UI を構築できます。
## サンプルコード
[Section titled “サンプルコード”](#サンプルコード)
この例では、見出しとスタイル付きボックスを持つシンプルなパネルを描画します。
**reearth.yml**
```yaml
id: ui-demo-plugin
name: UI Demo Plugin
version: 1.0.0
extensions:
- id: ui-demo
type: widget
name: UI Demo
```
**ui-demo.js**
```javascript
reearth.ui.show(`
Hello from my plugin
This UI is rendered inside an iframe.
`);
```
## 結果
[Section titled “結果”](#結果)
このウィジェットをシーンに追加すると、メインビューにパネルが表示されます。
## 仕組み
[Section titled “仕組み”](#仕組み)
**`reearth.ui.show` は HTML をレンダリングします**
UI は HTML 文字列として `reearth.ui.show` に渡します。UI に必要なマークアップ、スタイル、スクリプトはすべてこの文字列内に含めます。
```javascript
reearth.ui.show(`...
`);
```
HTML は iframe 内で実行されるため、Visualizer 本体のページから隔離されます。これにより、スタイルが競合しにくく、独立した UI を作れます。
**CSS でサイズを設定します**
iframe はコンテンツに合わせてサイズが決まります。ルート要素に対して `width: 240px` のように CSS で寸法を指定してください。`html, body` に `margin: 0` を設定すると、ブラウザ既定の余白が消え、UI が端まで詰まって表示されます。
## 次に読む
[Section titled “次に読む”](#次に読む)
* [reearth.ui API リファレンス](/ja/developer/plugin/api-reference/ui/) — `show` / `resize` / `close` など表示関連 API の一覧
* [ユーザーが設定できるプロパティを受け取る](/ja/developer/plugin/guides/accept-user-configurable-properties/) — インスペクターから UI を設定可能にする
# 大規模データセットを最適化してレンダリングする
> 大規模データセットのレンダリング性能を改善します。
このガイドを終えると、パフォーマンスオプションを有効にして大規模な GeoJSON データセットを効率的に読み込めるようになります。このガイドは、レイヤの追加に慣れていることを前提としています（[レイヤを追加する](/ja/developer/plugin/guides/add-a-layer/)を参照）。
座標が何千もある非常に大きな GeoJSON ファイルは、通常の方法で読み込むとレンダリングが遅くなることがあります。Re:Earth Visualizer には `useAsResource` というパフォーマンスオプションがあり、大規模な GeoJSON データをより効率的に処理できます。フィーチャが約 6,000 を超える GeoJSON にはこのオプションを使用してください。
## サンプルコード
[Section titled “サンプルコード”](#サンプルコード)
この例では、パフォーマンスオプションを有効にして東京エリアの境界を表す大規模な GeoJSON レイヤを追加します。
**reearth.yml**
```yaml
id: large-dataset-plugin
name: Large Dataset Plugin
version: 1.0.0
extensions:
- id: large-dataset
type: widget
name: Large Dataset
```
**large-dataset.js**
```javascript
reearth.layers.add({
type: "simple",
data: {
type: "geojson",
url: "https://reearth.github.io/visualizer-plugin-sample-data/public/geojson/tokyo-boundary.geojson",
geojson: {
useAsResource: true,
},
},
polygon: {},
});
reearth.camera.flyTo(
{ lat: 35.68, lng: 139.40, height: 176000 },
{ duration: 2 }
);
```
## 結果
[Section titled “結果”](#結果)
GeoJSON の境界データが読み込まれ、東京エリア全体にレンダリングされます。`useAsResource` が有効になっているため、Visualizer 側からのスタイリングは適用されず、デフォルトの色で表示されます。外観を変更するには、GeoJSON ファイル自体にスタイルを定義してください（下記参照）。
地図データ提供：[OpenStreetMap](https://www.openstreetmap.org/copyright)
## 仕組み
[Section titled “仕組み”](#仕組み)
パフォーマンスオプションはレイヤの `data` ブロック内の `geojson` キーに設定します。
```javascript
data: {
type: "geojson",
url: "https://example.com/large-data.geojson",
geojson: {
useAsResource: true,
},
}
```
`useAsResource: true` を設定すると、Re:Earth Visualizer は大規模データセット向けに最適化された方法で GeoJSON をレンダリングします。フィーチャが約 6,000 を超える GeoJSON に推奨されます。
注意
`useAsResource` が有効な場合、Visualizer 側からレイヤをスタイリングできません（例：`polygon`、`marker`、`polyline` の外観オプション）。代わりに、GeoJSON ファイルの各フィーチャに標準のスタイルプロパティを直接定義してください。例：
```json
"properties": {
"stroke": "#fb0404",
"stroke-width": 2,
"stroke-opacity": 1
}
```
ノート
このサンプルで使用している境界データは、国土交通省（MLIT）のオープンデータです。外部データを使用する際は、利用規約を確認し、帰属表示の要件に従ってください。
## 次のステップ
[Section titled “次のステップ”](#次のステップ)
* [レイヤを追加する](/ja/developer/plugin/guides/add-a-layer/): このガイドの土台となるレイヤの基本
* [reearth.layers API リファレンス](/ja/developer/plugin/api-reference/layers/): 完全なレイヤとデータオブジェクト
# タイムラインを再生する
> プラグインからタイムラインの再生を設定、制御します。
このガイドを終えると、プラグインから Re:Earth Visualizer のタイムラインを制御できるようになります。時間範囲の設定、再生・一時停止、速度の調整、時間の進行に応じた処理が可能になります。このガイドは、`reearth.yml` と拡張ファイルの基本的な構造を把握していることを前提としています。
タイムラインは、シーンの時系列データとアニメーションを駆動します。`reearth.timeline` を通じて、プラグインはタイムラインの範囲設定、再生・一時停止、速度変更、進行に応じたイベント受信ができます。
## サンプルコード
[Section titled “サンプルコード”](#サンプルコード)
この例では、時計と **再生** ボタン・**一時停止** ボタンを持つ小さなパネルを表示します。**再生** をクリックすると 2023 年を通じてタイムラインが進み、時計が現在時刻をリアルタイムで更新します。
**reearth.yml**
```yaml
id: timeline-plugin
name: Timeline Plugin
version: 1.0.0
extensions:
- id: timeline-demo
type: widget
name: Timeline Demo
```
**timeline-demo.js**
```javascript
reearth.ui.show(`
`);
reearth.timeline?.setTime?.({
start: new Date("2023-01-01T00:00:00Z"),
stop: new Date("2023-12-31T23:59:59Z"),
current: new Date("2023-01-01T00:00:00Z"),
});
reearth.timeline?.setSpeed?.(3600 * 2);
reearth.extension.on("message", (message) => {
if (message?.action === "play") {
reearth.timeline?.play?.();
}
if (message?.action === "pause") {
reearth.timeline?.pause?.();
}
});
reearth.timeline?.on?.("tick", (currentTime) => {
reearth.ui.postMessage({ action: "tick", time: currentTime.toISOString() });
});
```
## 結果
[Section titled “結果”](#結果)
時計と **再生** ボタン・**一時停止** ボタンを持つパネルが表示されます。**再生** をクリックするまでは何も動きません。クリックすると 2023 年を通じて時計が進みます。**一時停止** をクリックすると、その時点で止まります。
地図データ提供：[OpenStreetMap](https://www.openstreetmap.org/copyright)
## 仕組み
[Section titled “仕組み”](#仕組み)
`reearth.timeline` 名前空間は、タイムラインの範囲設定、再生制御、時間進行への反応のためのメソッドを提供します。
**時間範囲を設定する**
`setTime` はタイムラインの範囲と開始位置を定義します。3 つの `Date` 値を持つオブジェクトを渡します。
```javascript
reearth.timeline?.setTime?.({
start: new Date("2023-01-01T00:00:00Z"),
stop: new Date("2023-12-31T23:59:59Z"),
current: new Date("2023-01-01T00:00:00Z"),
});
```
* **`start`**: タイムラインの開始時刻。
* **`stop`**: タイムラインの終了時刻。
* **`current`**: 再生を開始する位置。
**再生を制御する**
`play` は現在位置からタイムラインを開始し、`pause` はリセットせずに停止します。
```javascript
reearth.timeline?.play?.();
reearth.timeline?.pause?.();
```
**速度を設定する**
`setSpeed` はリアルタイムに対するタイムラインの進行速度を制御します。値はリアル 1 秒あたりのタイムライン秒数です。`1` はリアルタイム、`3600 * 2` は 1 秒あたり 2 時間です。
```javascript
reearth.timeline?.setSpeed?.(3600 * 2);
```
**時間の変化に反応する**
`tick` イベントは再生中に現在時刻が進むたびに発火します。ハンドラは現在時刻を `Date` として受け取ります。ハンドラは軽量に保ち、ティックごとに重い処理やログ出力を行わないようにしてください。
```javascript
reearth.timeline?.on?.("tick", (currentTime) => {
reearth.ui.postMessage({ action: "tick", time: currentTime.toISOString() });
});
```
ノート
タイムラインのメソッドはオプショナルチェーン（`?.`）を使って呼び出します。タイムラインはすべてのコンテキストで利用できるとは限らないためです。
## 次のステップ
[Section titled “次のステップ”](#次のステップ)
* [reearth.timeline API リファレンス](/ja/developer/plugin/api-reference/timeline/): `stepType`、`rangeType` を含むタイムラインメソッド・プロパティ・イベントの全一覧
* [プラグインと Re:Earth の間で通信する](/ja/developer/plugin/guides/communicate-between-a-plugin-and-reearth/): UI ボタンが拡張ロジックにメッセージを送る仕組み
# 拡張タイプの違い
> ウィジェット、InfoboxBlock、StoryBlock の拡張タイプを比較します。
プラグインは拡張を通じて機能を提供します。Re:Earth Visualizer がサポートする拡張タイプは、ウィジェット、InfoboxBlock、StoryBlock の 3 種類です。それぞれインターフェース内の異なる場所に表示され、適した用途も異なります。
拡張タイプによって表示場所とユーザーの操作方法が決まるため、適切なタイプを選ぶことはプラグインを設計する際の最初の判断になります。
| 拡張タイプ | 表示場所 | 適した用途 |
| ------------ | -------------------- | -------------------------- |
| ウィジェット | メインの地図ビュー上にフローティング表示 | 常に表示する操作パネルや情報 |
| InfoboxBlock | 地物のインフォボックス内 | ユーザーが特定の地物を選択したときに表示する詳細情報 |
| StoryBlock | ストーリーページ内 | ガイド付きのストーリーに埋め込むリッチコンテンツ |
## ウィジェット
[Section titled “ウィジェット”](#ウィジェット)
ウィジェットは、Visualizer のメインビュー上にフローティング表示される拡張です。Widget Align System を使って、画面の端や隅に配置できます。
シーンを開いている間は常に表示されるため、検索ボックス、凡例、ライブデータパネル、シーン内の操作を実行するボタンなど、継続的にアクセスする必要がある操作や情報に適しています。
ユーザーのシーン内での操作にかかわらず、地図上に常に表示したい操作や情報にはウィジェットを使用します。
## InfoboxBlock
[Section titled “InfoboxBlock”](#infoboxblock)
InfoboxBlock は、ユーザーがレイヤ上の地物を選択したときに開くパネルであるインフォボックス内に表示される拡張です。その地物に関する情報の一部として表示されます。
InfoboxBlock は地物の選択に連動するため、整形されたデータカード、地物の属性から作成したグラフ、外部ソースから取得した詳細など、特定の地物に関連するコンテンツの表示に適しています。
ユーザーが地図上の特定の地物を選択したときだけ、その地物に関する情報を表示したい場合は InfoboxBlock を使用します。
## StoryBlock
[Section titled “StoryBlock”](#storyblock)
StoryBlock は、ストーリーページに埋め込まれる拡張です。ストーリーのコンテンツの一部となり、ユーザーが物語を進めるとインラインで表示されます。
StoryBlock は、インタラクティブなグラフ、タイムライン、データに基づく図など、通常のテキストや画像を超えるカスタムコンテンツをストーリーに加える用途に適しています。
メインの地図ビューや地物のインフォボックスではなく、ストーリーページ内にカスタムコンテンツを追加したい場合は StoryBlock を使用します。
# プラグインシステムの仕組み
> Visualizer プラグインを構成する WebAssembly と iframe の環境を説明します。
Visualizer のプラグインは、単一のコードとして動作するわけではありません。各プラグインは、別々の環境で動作して相互に通信する 2 つの部分に分かれています。この構成により、コードが実行される場所ごとに、できることとできないことが決まります。
## プラグインの実行方法
[Section titled “プラグインの実行方法”](#プラグインの実行方法)
プラグインが読み込まれると、Visualizer はコードを次の 2 つの環境で実行します。
* Visualizer のデータとプラグインAPIに直接アクセスできる **WebAssembly** 環境
* すべての UI 描画を担当し、標準のブラウザ API を利用できる **iframe** 環境
どちらか一方だけですべてを実行することはできません。WebAssembly 側は Visualizer のデータを読み取って操作できますが、HTML の描画や多くのブラウザ API の利用はできません。iframe 側は HTML の描画やブラウザ API の利用ができますが、Visualizer のデータへ直接アクセスできません。2 つの環境が互いを補完します。
両者は、異なる実行コンテキスト間で安全に通信するための標準的なブラウザ機能である `postMessage` を使って通信します。UI が Visualizer のデータを必要とするときは、WebAssembly 側にデータを要求します。WebAssembly 側はデータを取得し、iframe 側へ送信します。
## WebAssembly 側
[Section titled “WebAssembly 側”](#webassembly-側)
WebAssembly 側はプラグインのエントリーポイントです。プラグインが読み込まれたときに最初に実行され、Visualizer と同じスレッドで同期的に動作します。
**できること:**
* Visualizer のシーンデータへアクセスする。
* プラグインAPIを呼び出す。
* レイヤのプロパティの更新など、Visualizer のシーンを部分的に変更する。
* シーンのイベントを購読する。
* `postMessage` を使って iframe 側とデータを送受信する。
**できないこと:**
* HTML や UI を直接描画する。UI の描画は iframe 側で行う必要があります。
* 多くのブラウザ API を利用する。利用できるのは `console.log` など一部に限られます。
* 外部サーバーへ HTTP リクエストを送信する。
ノート
WebAssembly 側の JavaScript は [QuickJS](https://bellard.org/quickjs/) で実行されます。ユーザーが使用するブラウザにかかわらず、ECMAScript 2020 をサポートします。
## iframe 側
[Section titled “iframe 側”](#iframe-側)
iframe 側は、プラグインの視覚的な要素をすべて処理します。通常のウェブページと同じように動作し、ブラウザ API を利用できます。
**できること:**
* 通常のウェブページと同じように HTML を描画する。
* DOM API、Canvas、`fetch` などのブラウザ API を利用する。
* サーバーのレスポンスヘッダーに `Access-Control-Allow-Origin: *` が含まれている場合、外部サーバーへ HTTP リクエストを送信する。
* `postMessage` を使って WebAssembly 側とデータを送受信する。
**できないこと:**
* Visualizer のデータへ直接アクセスしたり変更したりする。`postMessage` を通じて WebAssembly 側へ要求する必要があります。
* Visualizer のバックエンドと直接通信する。
* レスポンスヘッダーに `Access-Control-Allow-Origin: *` が含まれていないサーバーへ HTTP リクエストを送信する。iframe は null オリジンでサンドボックス化されています。
* 同じサンドボックス上の理由により、ローカルストレージを利用する。
* 親ページから明示的な権限を必要とするブラウザ API を利用する。たとえば、Clipboard API はサンドボックス化された iframe ではデフォルトで利用できません。
## 要点
[Section titled “要点”](#要点)
| 機能 | WebAssembly 側 | iframe 側 |
| ------------------- | ------------- | -------- |
| サンドボックス化 | ✅ | ✅ |
| エントリーポイント（最初に実行） | ✅ | ❌ |
| プラグインAPIへのアクセス | ✅ | ❌ |
| HTML の描画 | ❌ | ✅ |
| ブラウザ API の利用 | ❌ | ✅ |
| `postMessage` による通信 | ✅ | ✅ |
## 制約事項
[Section titled “制約事項”](#制約事項)
**`postMessage` のシリアライズ:** `postMessage` で送信できるのは、JSON としてシリアライズ可能なデータだけです。`ArrayBuffer` や `Blob` などのオブジェクトは直接送信できません。バイナリーデータは、送信前に base64 文字列へエンコードしてください。
**プラグインのサイズ:** プラグインは 10 MB 以下の `.zip` ファイルとしてパッケージ化する必要があります。
**静的アセット:** 画像、HTML、CSS などの JavaScript 以外のファイルは、プラグイン内に含めることができません。JavaScript に文字列として埋め込むか、一般公開されたサーバーに配置して URL で参照してください。
**ローカルストレージ:** ローカルストレージは両方の環境で利用できません。データを永続化するには、プラグインAPIが提供するストレージ API または外部サーバーを使用してください。
# プラグイン構成
> マニフェストと拡張のファイルから Visualizer プラグインを構成する仕組みを説明します。
Re:Earth Visualizer のプラグインは、1 つの `reearth.yml` 設定ファイルと、拡張ごとに 1 つ用意する JavaScript ファイルで構成される `.zip` ファイルです。`reearth.yml` はプラグインの情報と拡張を定義し、各 JavaScript ファイルには対応する拡張のロジックを記述します。Visualizer は、これらのファイルを使ってプラグインを読み込み、実行します。
## `reearth.yml`
[Section titled “reearth.yml”](#reearthyml)
すべてのプラグインは、`.zip` のルートに `reearth.yml` という名前のファイルを含める必要があります。この YAML ファイルには、名前、バージョン、説明、拡張など、プラグインのメタデータを記述します。
reearth.yml
```yaml
id: demo-plugin
name: Demo Plugin
version: 1.0.0
extensions:
- id: demo-widget
type: widget
name: Demo Widget
```
注意
`id` フィールドで使用できる文字は、英字（`a-zA-Z`）、数字（`0-9`）、ハイフン（`-`）、アンダースコア（`_`）のみで、最大 100 文字です。`reearth` は予約されているため、ID として使用できません。
サポートされているフィールドの一覧については、[プラグインマニフェストのスキーマ](https://github.com/reearth/reearth-visualizer/blob/main/server/schemas/plugin_manifest.json)を参照してください。
## 拡張の JavaScript
[Section titled “拡張の JavaScript”](#拡張の-javascript)
`reearth.yml` で宣言した各拡張には、対応する JavaScript ファイルが必要です。ファイル名は拡張の `id` と完全に一致させてください。たとえば、`id: demo-widget` の拡張には `demo-widget.js` というファイルが必要です。
注意
拡張の `id` と JavaScript のファイル名は、完全に一致させてください。どちらにも空白や特殊文字を使用しないでください。
JavaScript ファイルには、その拡張のロジックを記述します。コードは WebAssembly 側で実行され、グローバルに公開されたプラグインAPIを利用できます。
demo-widget.js
```javascript
reearth.ui.show(`Hello, World!
`);
```
ノート
拡張の JavaScript は [QuickJS](https://bellard.org/quickjs/) で実行されます。ECMAScript 2020 と互換性のあるコードを使用してください。
## パッケージ化とインストール
[Section titled “パッケージ化とインストール”](#パッケージ化とインストール)
`reearth.yml` とすべての拡張の JavaScript ファイルを用意したら、1 つの `.zip` ファイルにまとめます。この `.zip` は、任意の Re:Earth Visualizer プロジェクトにインストールできます。
```text
my-plugin.zip
├── reearth.yml
└── demo-widget.js
```
複数の拡張がある場合は、それぞれに対応する JavaScript ファイルを含めます。
```text
my-plugin.zip
├── reearth.yml
├── demo-widget.js
└── demo-infobox-block.js
```
ノート
プラグインのサイズは 10 MB 以下である必要があります。画像や CSS など、JavaScript 以外のファイルを `.zip` に含めることはできません。詳しくは[制約事項](/ja/developer/plugin/overview/how-the-plugin-system-works/#%E5%88%B6%E7%B4%84%E4%BA%8B%E9%A0%85)を参照してください。
`.zip` を繰り返し作成してインストールする手間を省き、効率よく開発する方法については、[ローカル開発環境をセットアップする](/ja/developer/plugin/get-started/set-up-a-local-development-environment/)を参照してください。
# プラグインとは？
> プラグインとは何か、Re:Earth Visualizer で何ができるかを説明します。
プラグインとは、既存のアプリケーションのコアコードを変更せずに、新しい機能を追加するソフトウェアコンポーネントです。機能がプラットフォーム本体に実装されるのを待つ代わりに、自分でプラグインを開発したり、他の人が開発したプラグインをインストールしたりできます。ホストアプリケーションは、実行時にそのプラグインを読み込みます。
プラグインは、日常的に使うさまざまなソフトウェアに存在します。広告をブロックしたりパスワードを保存したりするブラウザ拡張、VS Code に言語サポートを追加するエディター拡張、背景地図に独自データを重ねる地図オーバーレイなどです。いずれも、明確に定義されたインターフェースを通じてホストアプリケーションに接続し、その機能を拡張する自己完結型のコードパッケージです。
## Re:Earth Visualizer におけるプラグイン
[Section titled “Re:Earth Visualizer におけるプラグイン”](#reearth-visualizer-におけるプラグイン)
Re:Earth Visualizer のプラグインは、カスタム UI の追加、シーンの操作、データの利用などによって、プラットフォームの機能を拡張します。コードと設定ファイルをまとめたパッケージとしてプロジェクトに追加します。
インストールされたプラグインは、1 つ以上の\*\*拡張（Extension）\*\*を通じて機能を提供します。拡張は、Visualizer のインターフェース内でプラグインの動作を構成する個別の単位です。拡張タイプにはウィジェット、InfoboxBlock、StoryBlock の 3 種類があり、それぞれ目的と表示場所が異なります。
システムレベルでは、Visualizer プラグインはコアアプリケーションを変更せずに機能を追加する拡張の集まりであり、WebAssembly と iframe の 2 つの環境で動作します。詳しくは[拡張タイプの違い](/ja/developer/plugin/overview/extension-types/)を参照してください。
## プラグインでできること
[Section titled “プラグインでできること”](#プラグインでできること)
プラグインを使うと、Re:Earth Visualizer のソースコードに手を加えずに、組み込み機能を超えた機能を追加できます。たとえば、次のことができます。
* 外部 API やサービスから取得したデータを、地図上やインフォボックスに表示する。
* フィルター、スライダー、検索入力など、シーンを操作するためのカスタムコントロールを作成する。
* 選択したレイヤのデータを使い、地物の選択に応じた情報を表示する。
* 静的なコンテンツだけでなく、データに応じて変化する要素をストーリーページに追加する。
* ユーザー入力やリアルタイムイベントに応じて、Visualizer 内の操作を自動化する。
## 代表的なユースケース
[Section titled “代表的なユースケース”](#代表的なユースケース)
### ナビゲーション操作
[Section titled “ナビゲーション操作”](#ナビゲーション操作)
ナビゲーションウィジェットは、画面上のボタンでカメラを任意の方向へ滑らかに移動し、初期表示へ戻したり、ズームイン・ズームアウトしたりできます。キーボードショートカットや地球を直接操作する方法に代わる、直感的なナビゲーションを提供します。
地図データ： [OpenStreetMap](https://www.openstreetmap.org/copyright)
### 画像オーバーレイ
[Section titled “画像オーバーレイ”](#画像オーバーレイ)
このウィジェットは、設定可能な画像とキャプションを地図上に直接表示します。画像 URL とキャプションのテキストは **インスペクター** パネルで設定できるため、プラグインのコードを変更せずに更新できます。
地図データ： [OpenStreetMap](https://www.openstreetmap.org/copyright)
### ライブ天気表示
[Section titled “ライブ天気表示”](#ライブ天気表示)
天気ウィジェットは、指定した場所の最新の気象情報を取得し、気温、天気、湿度、風、最終更新時刻を地図上に表示します。
地図データ： [OpenStreetMap](https://www.openstreetmap.org/copyright)
### カメラのブックマーク
[Section titled “カメラのブックマーク”](#カメラのブックマーク)
カメラブックマークウィジェットは、名前を付けて場所を保存し、クリック 1 回で保存した位置へカメラを移動できます。大規模なシーン内の注目地点を簡単に行き来できます。
地図データ： [OpenStreetMap](https://www.openstreetmap.org/copyright)
# プラグインAPIとは？
> プラグインが Re:Earth Visualizer と通信するための API を説明します。
プラグインAPIは、プラグインが Re:Earth Visualizer と通信するための仕組みです。Visualizer のソースコードへアクセスしなくても、データの読み取り、ユーザー操作への応答、地図上の表示制御、独自 UI の管理などを行えます。
API 全体は、`reearth` という 1 つのグローバルオブジェクトを通じて利用できます。プラグインに必要なすべての機能は、このオブジェクトからアクセスします。たとえば、カメラの操作には `reearth.camera`、レイヤの操作には `reearth.layers` を使用します。
API は、プラグインが行うことを基準に構成されています。プラグインはユーザーにインターフェースを提供し、地図、レイヤ、データから成るシーンを操作します。API の各要素には次の役割があります。
* **プラグイン自身（`reearth.extension`）**: 設定されたプロパティ、UI とのメッセージ通信、ライフサイクルイベントなど、プラグイン自身のコンテキストを扱います。
* **プラグインのインターフェース（`reearth.ui`、`reearth.modal`、`reearth.popup`）**: メイン UI パネル、ダイアログ、小さなアンカーウィンドウなど、ユーザーが見て操作する要素を扱います。
* **シーン（`reearth.viewer`、`reearth.camera`、`reearth.timeline`）**: ビューアの環境と設定、視点、時間に基づく再生など、ユーザーが見ている空間を扱います。
* **コンテンツ（`reearth.layers`、`reearth.data`）**: 地図レイヤやクライアント側のデータストレージなど、地図に表示するデータとプラグインが保持するデータを扱います。
* **描画・位置ツール（`reearth.sketch`、`reearth.spatialId`）**: 地図上への図形の描画や、空間 ID による位置参照を扱います。
* **システム情報（`reearth.version`、`reearth.apiVersion`、`reearth.engine`）**: Visualizer のバージョンやレンダリングエンジンなど、プラグインが動作する環境の基本情報を提供します。
これらの要素は、どのプラグインでも連携して動作します。イベントも同じ構成に含まれます。`reearth.viewer` はマウスイベント、`reearth.timeline` は `tick`、`reearth.extension` はメッセージを発行します。イベントを監視するときは、そのイベントに対応するオブジェクトへリスナーを登録します。
たとえば、保存した場所へ移動するプラグインでは、`reearth.extension` から設定を読み取り、`reearth.ui` でクリック可能な一覧を表示し、場所が選択されたときに `reearth.camera` で視点を移動します。
利用できるすべてのプロパティとメソッドについては、[API リファレンス](/ja/developer/plugin/api-reference/)を参照してください。
# FAQ
> Visualizer プラグイン開発でよくある質問への回答を紹介します。
この FAQ では、個別のガイドを必要としない短い横断的な質問を扱います。目的別の手順は「ガイド」、プロパティやメソッドの詳細は「API リファレンス」を参照してください。
## はじめに
[Section titled “はじめに”](#はじめに)
**Q: プラグイン開発を始めるのに、何かインストールが必要ですか？**
不要です。プラグインは 2 つの方法で作れます。1 つはブラウザだけで完結するプラグインプレイグラウンド、もう 1 つはローカル開発環境（自分のエディタ）を使う方法です。Playground は最も早く試せる方法で、ローカル環境はより大きく複雑なプラグインに向いています。
**Q: プラグインにはどんなファイルが必要ですか？**
最低限必要なのは、プラグインと拡張を記述する `reearth.yml` と、拡張ごとに 1 つの JavaScript ファイルです。これらをまとめて `.zip` としてパッケージ化します。
**Q: ウィジェット / InfoboxBlock / StoryBlock の違いは？**
ウィジェットは Widget Align System を使ってメインマップビューに配置します。InfoboxBlock は、レイヤ上のフィーチャを選択したときに開くインフォボックス内に表示されます。StoryBlock はストーリーページに埋め込まれます。詳細は[拡張タイプの違い](/ja/developer/plugin/overview/extension-types/)を参照してください。
## 開発
[Section titled “開発”](#開発)
**Q:「Install Dev Plugins」と「Reload Dev Plugin Extensions」はいつ使い分けますか？**
初回セットアップと `reearth.yml` を変更したときは **Install Dev Plugins** を使用します。拡張コードを変更した後は **Reload Dev Plugin Extensions** を使用します。`reearth.yml` の変更は、プラグイン構造の再登録が必要なため、完全インストールが必要です。
**Q: プラグインの UI が表示されないのはなぜですか？**
プラグイン UI は `reearth.ui.show` に HTML を渡すことで表示します。何も表示されない場合は、呼び出しが行われているか、また拡張 JavaScript のファイル名が `reearth.yml` 内の `id` と完全一致しているかを確認してください。UI は表示されているが真っ白に見える場合は、スタイルの問題の可能性があります。文字色が背景色と同じだと見えないため、UI 側で文字色と背景色を明示的に指定してください。
**Q: TypeScript は使えますか？**
はい。Visualizer が実行するのは JavaScript ですが、TypeScript で書いて JavaScript にコンパイルできます。推奨テンプレートは TypeScript に対応しています。
## 機能と制限
[Section titled “機能と制限”](#機能と制限)
**Q: 外部 API からデータを取得できないのはなぜですか？**
外部サーバーへのリクエストは、拡張ロジック（WebAssembly 側）ではなく、プラグイン UI（iframe 側）から行う必要があります。また、外部サーバーはレスポンスヘッダーに `Access-Control-Allow-Origin` を含めて CORS を許可していなければなりません。そうでない場合、リクエストは失敗します。
**Q: 特定の背景地図やタイルサーバーが読み込めないのはなぜですか？**
一部の背景地図は Cesium Ion のアクセストークンを必要とします。それ以外でも、タイルサーバーが利用できない、または CORS によりブロックされる場合があります。背景地図が表示されない場合、原因はコードではなくタイルソース側にあることが多いです。
**Q: プラグインのサイズ制限はありますか？**
あります。プラグインは 10 MB 以下の `.zip` としてパッケージ化する必要があります。画像や CSS などの非 JavaScript ファイルは `.zip` に同梱できません。JavaScript の文字列として埋め込むか、公開サーバーにホストして URL で参照してください。
**Q: プラグインで永続化できるデータを保存できますか？**
ローカルストレージは利用できません（プラグイン UI がサンドボックス化された iframe 内で動作するため）。永続化には、プラグイン API が提供するストレージ API、または外部サーバーを利用してください。
## 公開と共有
[Section titled “公開と共有”](#公開と共有)
**Q: Playground で作ったプラグインはどう共有できますか？**
**Share** ボタンで共有リンクをコピーするか、**Export** ボタンで `.zip` をダウンロードしてください。非常に大きいプラグインはリンク共有できず、エクスポートのみです。
# ツール
> Visualizer プラグイン開発用ツールのドキュメントは準備中です。
注意
このセクションは現在メンテナンス中です。
# Re:Earth Flow ドキュメント
> Re:Earth Flow のドキュメントは現在準備中です。
このドキュメントは現在準備中です。公開をお待ちください。
# チュートリアル
> Re:Earth のプロダクトを実際に触りながら進めるチュートリアルの一覧です。
プロダクトで絞り込む
\[ ] CMS \[ ] Visualizer
* 
CMS Visualizer 所要時間 60分 難易度 初級
## [パブリックAPI で、1つのモデルからグラフと地図を作る](/ja/tutorials/public-api-chart-and-map/)
Re:Earth CMS にモデルとスキーマを作り、パブリックAPI で配信して、表計算ソフトのグラフと Re:Earth Visualizer の地図で扱うまでを実践します。
* 
Visualizer 所要時間 45分 開発 難易度 初級
## [シンプルな UI プラグインを作成してインストールする](/ja/tutorials/simple-ui-plugin/)
プラグインプレイグラウンドで Welcome ウィジェットを作成し、ZIP としてエクスポートし、Re:Earth Visualizer にインストールして、シーンに追加します。
* 
CMS 所要時間 30分 開発 難易度 中級
## [パブリックAPI で作る フィードバック収集・閲覧アプリ](/ja/tutorials/public-api-feedback-app/)
バックエンド不要で、ブラウザから直接 Re:Earth CMS にデータを投稿・表示する 1 ページのフィードバックアプリを作る。
* 
CMS Visualizer 所要時間 45分 開発 難易度 中級
## [インテグレーションAPI で作るインフラ点検マップ](/ja/tutorials/infrastructure-inspection-map/)
インテグレーションAPI を使うバックエンド経由で、点検担当者が地図上からインフラの状態を報告するアプリを作る。
* 
Visualizer 所要時間 60分 開発 難易度 中級
## [経路検索プラグインを作成する](/ja/tutorials/route-search-plugin/)
レイヤAPI・カメラAPI・外部の経路検索サービスを使って、2 地点間の経路を検索し地球儀上に描画するウィジェットを作成します。
* 
CMS 所要時間 60分 開発 難易度 上級
## [Re:Earth CMS の Webhook を受信するローカルサーバーを作る](/ja/tutorials/cms-webhook-receiver/)
Re:Earth CMS の Webhook を受信して署名を検証し、変更内容を表示するローカルサーバーを作り、その上に独自の通知を設計する。
* 
Visualizer 所要時間 90分 開発 難易度 上級
## [React と TypeScript で ISS Tracker プラグインを作成する](/ja/tutorials/iss-tracker-plugin/)
ISS の現在位置を取得して追跡する Visualizer ウィジェットを作成し、テスト、パッケージ化、インストールします。
# Re:Earth CMS の Webhook を受信するローカルサーバーを作る
> Re:Earth CMS の Webhook を受信して署名を検証し、変更内容を表示するローカルサーバーを作り、その上に独自の通知を設計する。
Re:Earth CMS でアイテムやアセットが変更されると、[Webhook](/ja/developer/cms/overview/webhook/) がその変更を HTTP `POST` で自分のサーバーへ送ります。このチュートリアルでは、自分のマシン上で小さな TypeScript サーバーを動かし、そのリクエストを受信して、本当に自分の CMS から届いたものかを確かめ、変更内容を読みやすい形で表示します。コンソールへの表示は出発点です。最後に、受信したイベントを誰にどう知らせるかを自分で設計します。
## 作るもの
[Section titled “作るもの”](#作るもの)
CMS でアイテムを編集すると、数秒後にターミナルへ、何が・誰によって・いつ変更されたかが表示されます。
```plaintext
[item.update] YYYY-MM-DD hh:mm:ss UTC
model: webhook-test
item: 01abc…
changed: title: "draft" → "final"
by: user 01xyz…
event: 01def…
received: YYYY-MM-DD hh:mm:ss UTC
```
CMS からは `localhost` に届かないため、トンネルを使って自分のマシンに一時的な公開アドレスを用意し、届いたリクエストを受信サーバーへ転送します。
```plaintext
Re:Earth CMS ──POST + Reearth-Signature──► cloudflared トンネル ──► localhost:3000/webhook
```
[完成版のソースコードと自分のプロジェクトを比較する](https://github.com/eukarya-biz/cms-webhook-tutorial)
注意
この受信サーバーは CMS の Webhook を学ぶためのもので、本番環境での利用を想定していません。正しい署名が付いたリクエストだけを受け付けますが、それ以外の認証はなく、ここで使うトンネルも開発用です。このままの状態でデプロイしないでください。
## 前提条件
[Section titled “前提条件”](#前提条件)
始める前に、次のものを用意してください。
* Node.js 20.6 以降。受信サーバーは Node 組み込みの `--env-file` で設定を読み込むため、このバージョンが必要です。
* Git
* **所有者**または**管理者**の役割を持つ Re:Earth CMS のワークスペース。インテグレーションをワークスペースに連携するには、どちらかの役割が必要です。自分が所有者であるパーソナルワークスペースなら問題ありません。
* TypeScript の基本的な知識
## ステップ1 — CMS を準備する
[Section titled “ステップ1 — CMS を準備する”](#ステップ1--cms-を準備する)
Webhook はインテグレーションに属するため、まずインテグレーションを作成してワークスペースに連携し、変更を加えるための小さなモデルを作成します。
Webhook はワークスペース内のすべてのプロジェクトのイベントを受信します
Webhook は、1つのプロジェクトだけでなく、インテグレーションを連携したワークスペース内のすべてのプロジェクトからイベントを受信します。このチュートリアルで行う変更だけがターミナルに届くよう、パーソナルワークスペースなど、ほかのプロジェクトがないワークスペースを使ってください。
### インテグレーションを作成して連携する
[Section titled “インテグレーションを作成して連携する”](#インテグレーションを作成して連携する)
パーソナルアカウントでインテグレーションを作成し、使用するワークスペースに連携します。
1. パーソナルアカウントで、**マイインテグレーション**タブを開いてください。
2. **新規インテグレーションを作成**ボタンをクリックしてください。
3. 名前に `CMS Webhook Tutorial` と入力してください。
4. **作成**ボタンをクリックしてください。
5. 使用するワークスペースで、**インテグレーション**タブを開いてください。
6. **インテグレーションを接続**ボタンをクリックしてください。
7. `CMS Webhook Tutorial` を選択してください。
8. **接続**ボタンをクリックしてください。
ワークスペースの**インテグレーション**画面に、連携したインテグレーションが表示されます。このチュートリアルでは役割はどれでも構いません。CMS は、役割に関係なく、連携しているすべてのインテグレーションに Webhook のイベントを送ります。手順と役割の詳細は [インテグレーションの作成](/ja/developer/cms/getting-started/integration-setup/) を参照してください。
Webhook そのものは、受信サーバーに CMS から届くアドレスができてから、ステップ4で追加します。
### テスト用のプロジェクトとモデルを作成する
[Section titled “テスト用のプロジェクトとモデルを作成する”](#テスト用のプロジェクトとモデルを作成する)
同じワークスペースに `webhook-tutorial-test` という名前の[プロジェクトを作成](/ja/cms/how-to/project-create-configure-delete/)してください。その中に `webhook-test` という名前の[モデルを作成](/ja/cms/how-to/models/)し、キーが `title` の **テキスト**[フィールドを追加](/ja/cms/how-to/fields/)してください。
ステップ5では、このモデルに変更を加えてイベントを発生させます。
## ステップ2 — 受信サーバーを自分のマシンで動かす
[Section titled “ステップ2 — 受信サーバーを自分のマシンで動かす”](#ステップ2--受信サーバーを自分のマシンで動かす)
完成版の受信サーバーをクローンし、依存パッケージをインストールします。
```bash
git clone https://github.com/eukarya-biz/cms-webhook-tutorial.git
cd cms-webhook-tutorial
npm install
cp .env.example .env
```
Windows（コマンドプロンプト）では、`cp .env.example .env` の代わりに `copy .env.example .env` を使ってください。
受信サーバーには、CMS と受信サーバーの両方が知っているランダムな値、シークレットが必要です。次のコマンドで生成します。
```bash
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
```
`.env` を開き、`CMS_WEBHOOK_SECRET` に表示された値を設定してください。`PORT` は `3000` のまま、`CMS_PROJECT_ID` は空のままにしてください。このシークレットはステップ4で CMS にも同じ値を入力するので、手元に控えておいてください。
注意
`.env` をコミットしたり、内容を共有したりしないでください。シークレットを知っている人は、受信サーバーが本物として受け付けるリクエストに署名できてしまいます。
CMS とつなぐ前に、署名の検証が動くことを確認します。リポジトリにはそのためのテストが含まれています。
```bash
npm test
```
8件のテストがすべて成功します。正しく署名されたリクエストは受け付けられ、本文が変更されたもの、別のシークレットで署名されたもの、タイムスタンプが5分を超えてずれているもの、形式が正しくないヘッダーはすべて拒否されることを確認しています。
受信サーバーを起動します。
```bash
npm run dev
```
ターミナルに `CMS Webhook Receiver listening on http://localhost:3000` と表示されます。そのまま起動しておき、同じフォルダで2つ目のターミナルを開いてテストイベントを送ってください。リポジトリのテスト用スクリプトは、CMS と同じ方法でサンプルイベントにシークレットで署名します。
```bash
npm run send-test
```
2つ目のターミナルに `Sent item.create (test-…) → 200` と表示され、1つ目のターミナルに最初の要約が表示されます。
```plaintext
[item.create] YYYY-MM-DD hh:mm:ss UTC
model: webhook-test
item: test-item
field: title = "hello from the test script"
by: user test-user
event: test-…
received: YYYY-MM-DD hh:mm:ss UTC
```
受信サーバーが、正しく署名されたリクエストを受け付けました。次は、表示する前に受信サーバーがリクエストをどう扱っているかを見ていきましょう。
## ステップ3 — 受信サーバーがリクエストを確認する仕組みを見る
[Section titled “ステップ3 — 受信サーバーがリクエストを確認する仕組みを見る”](#ステップ3--受信サーバーがリクエストを確認する仕組みを見る)
リクエストはすべて、`src/server.ts` の `POST /webhook` に届きます。受信サーバーは次のようにリクエストを読み取ります。
src/server.ts
```ts
app.post(
"/webhook",
express.raw({ type: () => true, limit: "1mb" }),
(req, res) => {
const rawBody = Buffer.isBuffer(req.body) ? req.body : Buffer.alloc(0);
const result = verifySignature(
rawBody,
req.get("Reearth-Signature"),
secret,
);
if (!result.ok) {
console.warn(`Rejected webhook: ${result.reason}`);
res.sendStatus(401);
return;
}
// Then: parse the JSON, reply 200, and handle the event.
},
);
```
ここには、見た目以上に大事な点が2つあります。
**本文をそのままのバイト列で読み取ります。** CMS は送信するバイト列そのものに署名するため、受信サーバーは何かを解析する前に、そのバイト列で署名を確認する必要があります。また、CMS は `Content-Type` ヘッダーを送りません。パーサーに `type: () => true` を指定しているのはそのためです。よく使われる `type: "*/*"` の場合、Express は `Content-Type` ヘッダーがあるときにしか本文を読み取りません。すると、CMS からのリクエストはすべて本文が空のまま届き、署名の確認がすべて失敗します。
**署名は `Reearth-Signature` ヘッダーに入っています。** 形式は `v1,t=,` で、バージョン、CMS がリクエストを送った時刻（1970年からの秒数）、署名そのものが並んでいます。`src/verify.ts` は、シークレットを使って署名を計算し直し、2つを比較します。
src/verify.ts
```ts
const expected = createHmac("sha256", secret)
.update(`v1:${timestamp}:`)
.update(rawBody)
.digest("hex");
// timingSafeEqual throws if the lengths differ, so check that first.
const received = Buffer.from(signature);
const computed = Buffer.from(expected);
if (
received.length !== computed.length ||
!timingSafeEqual(received, computed)
) {
return { ok: false, reason: "signature mismatch" };
}
```
署名は、`v1:`、タイムスタンプ、`:`、本文をこの順につなげたものを、シークレットを鍵として HMAC-SHA256 で計算した値です。一致する署名を作れるのはシークレットを持つ人だけなので、一致すれば、リクエストが自分の CMS から届き、途中で変更されていないことがわかります。`verifySignature` は、この比較の前に、現在時刻から5分を超えてずれたタイムスタンプも拒否します。これにより、誰かが記録したリクエストをあとから再送されても受け付けません。
確認が済むと、受信サーバーはすぐに `200` を返し、そのあとでイベントを処理します。CMS は返答を最大30秒しか待たず、`300` を超えるステータスはすべて配信失敗として扱うため、時間のかかる処理を返答より先に行うことはありません。
イベントの処理は `handleEvent()` が行います。すでに処理したイベントと、扱わない種類のイベントを読み飛ばしたうえで、`src/notify.ts` の `notify()` にイベントを渡します。先ほどの要約を表示したのはこの関数で、ステップ6で再び取り上げます。
## ステップ4 — トンネル経由で CMS とつなぐ
[Section titled “ステップ4 — トンネル経由で CMS とつなぐ”](#ステップ4--トンネル経由で-cms-とつなぐ)
CMS はインターネット上で動いているため、`localhost` には届きません。[Cloudflare のクイックトンネル](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/do-more-with-tunnels/trycloudflare/)は、自分のマシンに一時的な公開アドレスを用意し、届いたリクエストを変更せずにそのまま転送します。署名の確認はこの点を前提にしています。無料で、Cloudflare のアカウントも不要です。
使用している OS に合わせて [cloudflared をインストール](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/downloads/)してください。受信サーバーを起動したまま、新しいターミナルでトンネルを開始してください。
```bash
cloudflared tunnel --url http://localhost:3000
```
数秒後、末尾が trycloudflare.com のアドレスを含む枠が表示されます。そのアドレスをコピーし、このターミナルは起動したままにしておきます。閉じるとトンネルが終了し、アドレスは cloudflared を起動するたびに変わります。
インターネットからのリクエストが受信サーバーに届くこと、そして署名のないリクエストが拒否されることを確認します。`` をコピーしたアドレス全体に置き換えて、次のコマンドを実行してください。
```bash
curl -i -X POST /webhook --data '{"hello":"world"}'
```
レスポンスは `401 Unauthorized` になり、受信サーバーのターミナルに `Rejected webhook: missing Reearth-Signature header` と表示されます。
このアドレスを CMS に登録します。**マイインテグレーション**で `CMS Webhook Tutorial` インテグレーションを開き、**Webhook** タブを開いて **新規Webhook** ボタンをクリックしてください。
フォームに次のように入力してください。
* **名前**：`local-receiver`
* **URL**：トンネルのアドレスの末尾に `/webhook` を付けたもの（`/webhook`）
* **シークレット**：`.env` の `CMS_WEBHOOK_SECRET` と同じ値
* **トリガーイベント**：アイテムとアセットのイベントすべて
**保存**ボタンをクリックし、新しい Webhook のスイッチが **オン** になっていることを確認してください。
## ステップ5 — 実際のイベントが届くのを確認する
[Section titled “ステップ5 — 実際のイベントが届くのを確認する”](#ステップ5--実際のイベントが届くのを確認する)
受信サーバーのターミナルが見える状態にしておいてください。`webhook-tutorial-test` プロジェクトで次の変更を1つずつ行い、そのたびにターミナルを確認してください。
1. `webhook-test` モデルで、タイトルが `draft` の[アイテムを作成](/ja/cms/how-to/items/)してください。`[item.create]` の要約が表示され、`field:` 行に `title = "draft"` と表示されます。
2. タイトルを `final` に変更して保存してください。`[item.update]` の要約が表示され、`changed:` 行に変更前と変更後の値 `title: "draft" → "final"` が表示されます。
3. [アイテムを公開](/ja/cms/how-to/item-publish-unpublish/)してください。`[item.publish]` の要約が表示されます。
4. アイテムを非公開にしてください。`[item.unpublish]` の要約が表示されます。
5. プロジェクトのアセットに小さな画像を[アップロード](/ja/cms/how-to/assets/)してください。`[asset.create]` の要約が、ファイル名とサイズとともに表示されます。
要約は、変更から数秒以内に表示されます。1行目の時刻と `received:` を比べてみてください。前者は CMS で変更が発生した時刻、後者は受信サーバーが受け取った時刻です。
どのイベントが届くかについて、次のことにも気づくはずです。
* **保存するたびに、別々のイベントになります。** アイテムを2回保存すると、`item.update` の要約が2つ届きます。
* **CMS でアイテムやアセットを削除しても、イベントは送られません。** `item.delete` はモデル全体を削除したときに、そのモデル内のアイテムごとに1つずつ送られます。`asset.delete` は、インテグレーションAPI でアセットを削除したときに送られます。
* **配信に失敗すると、あとで再送されます。** 受信サーバーが停止していたり、リクエストを拒否したりした場合、同じイベントがしばらく経ってから、より新しいイベントのあとに届くことがあります。受信サーバーは、処理済みのイベント ID を読み飛ばし、順序には依存しません。
作業を終えたら、Webhook のスイッチを **オフ** にしてください。トンネルを停止するとそのアドレスは使えなくなり、ワークスペースでの変更がすべて配信失敗となって、CMS があとで再送することがあります。次回は、トンネルを起動して新しいアドレスを Webhook の設定に入力し、スイッチを再び **オン** にしてください。
## ステップ6 — 独自の通知を設計する
[Section titled “ステップ6 — 独自の通知を設計する”](#ステップ6--独自の通知を設計する)
コンソールへの表示で、全体の経路が動くことを確認できました。実際の受信サーバーなら、誰かに知らせるはずです。このステップでは設計を指定しません。受信サーバーに何をさせるか、そしてそれが動いているとどう判断するかは、自分で決めます。
変更する場所は、`src/notify.ts` の `notify()` です。検証済みで、フィルターを通過したイベントごとに1回呼ばれます。`async` にできるので、ほかのサービスの応答を待つこともできます。
src/notify.ts
```ts
export async function notify(event: WebhookEvent): Promise {
console.log(formatEvent(event));
}
```
コードを書く前に、次の問いを考えてみてください。
* **誰に、どのイベントを知らせる必要があるか。** レビュー担当者は特定のモデルの `item.publish` だけに関心があり、編集者は `item.update` に関心があるかもしれません。`event.type`、`event.data.model.key`、アイテムのフィールドは、すべてイベントに含まれています。
* **いつ知らせるか。** すぐに知らせるのか、1時間ごとにまとめて1つのメッセージにするのか。1つのアイテムを続けて保存すると、イベントも続けて届きます。
* **送信に失敗したらどうするか。** 受信サーバーはすでに `200` を返しているため、CMS はそのイベントを再送しません。再試行するのか、ログに残すのか、失われてもよいとするのかを決めます。
* **認証情報をどこに置くか。** Slack の Webhook URL やメールのパスワードもシークレットです。コードには書かず、`CMS_WEBHOOK_SECRET` と同じく `.env` に置きます。
* **CMS なしでどうテストするか。** `npm run send-test` は `--type`、`--id`、`--project` を受け付けるので、設計で扱うイベントを送れます。
よく使われる2つの通知先については、次の公式ガイドが出発点になります。
* Slack：[Sending messages using incoming webhooks](https://docs.slack.dev/messaging/sending-messages-using-incoming-webhooks)
* Node.js からのメール送信：[Nodemailer](https://nodemailer.com/)
作り始める前に、自分の設計にとっての「完成」を、確認できる形で決めておきましょう。たとえば、「`webhook-test` モデルのアイテムを公開すると、そのアイテム名を含む Slack メッセージが1件投稿され、投稿に失敗した場合はログに記録される」のように決めます。そのうえで、受信サーバーがそれを満たしているか確認します。
## トラブルシューティング
[Section titled “トラブルシューティング”](#トラブルシューティング)
**受信サーバーに `Rejected webhook: signature mismatch` と表示される**
Webhook の**シークレット**と `.env` の `CMS_WEBHOOK_SECRET` が完全には一致していません。余分なスペースや欠けている文字がないか、両方を確認してください。受信サーバーの起動中に `.env` を編集した場合は、いったん停止して `npm run dev` を実行し直してください。受信サーバーは起動時にしか `.env` を読み込みません。
**アイテムを変更しても何も表示されない**
Webhook のスイッチが **オン** になっているか、**URL** の末尾が `/webhook` になっているか、発生させているイベントが選択されているか、作業しているワークスペースにインテグレーションが連携されているかを確認してください。
**トンネルのターミナルに `Unable to reach the origin service` と表示される**
トンネルは動いていますが、受信サーバーが動いていません。`npm run dev` で起動し直してください。
**受信サーバーに `Ignored … from another project` と表示される**
`.env` の `CMS_PROJECT_ID` に別のプロジェクトが設定されています。空にすると、ワークスペース内のすべてのプロジェクトからのイベントを受け付けます。
## 完了チェックリスト
[Section titled “完了チェックリスト”](#完了チェックリスト)
* [ ] トンネルのアドレスへの署名のないリクエストが `401` で拒否される。
* [ ] CMS でアイテムを作成・編集・公開・非公開にすると、それぞれの要約がターミナルに表示される。
* [ ] 受信サーバーが本文をそのままのバイト列で読み取る理由と、イベントを処理する前に返答する理由を説明できる。
* [ ] 通知で何をするか、そしてその「完成」が何かを決めている。
# インテグレーションAPI で作るインフラ点検マップ
> インテグレーションAPI を使うバックエンド経由で、点検担当者が地図上からインフラの状態を報告するアプリを作る。
インテグレーションAPI を使って、公共インフラ（マンホール・街灯・標識・ベンチ）の状態を報告する地図アプリを作ります。小さなバックエンドがインテグレーションAPI のトークンを保持し、CMS へのリクエストをすべて代行するため、トークンがブラウザに渡ることはありません。
## 作るもの
[Section titled “作るもの”](#作るもの)
点検担当者が地図を開き、インフラの資産をクリックして、問題の種別・深刻度・メモ・任意の写真を添えた状態レポートを送信します。レポートを送信すると、インテグレーションAPI を通じて CMS にアイテムが作成・公開され、続けてその資産自身の状態と最終点検日が更新されます。「レポート履歴を見る」ボタンから、これまで送信されたレポートを一覧できます。
 
[完成したソースコードと見比べる](https://github.com/eukarya-biz/infrastructure-inspection-tutorial)
注意
このアプリはインテグレーションAPI を学ぶためのもので、本番利用を想定していません。バックエンドに認証がなく、URL を知っている人なら誰でもレポートの作成や資産データの変更ができます。独自の認証とアクセス制御を加えないまま公開しないでください。
## 前提条件
[Section titled “前提条件”](#前提条件)
* Node.js 20 以降
* Git
* Re:Earth CMS のワークスペース
* TypeScript の基礎知識
## ステップ1 — CMS プロジェクトを準備する
[Section titled “ステップ1 — CMS プロジェクトを準備する”](#ステップ1--cms-プロジェクトを準備する)
ヒント
手作業でのクリックを省略したい場合は、アプリのリポジトリにある[セットアップスクリプト](https://github.com/eukarya-biz/infrastructure-inspection-tutorial#cms-project)が、インテグレーションAPI を通じてプロジェクト・両モデル・各フィールドをまとめて作成します。実行方法はリポジトリの README を参照してください。
### モデルを作成する
[Section titled “モデルを作成する”](#モデルを作成する)
Re:Earth CMS の管理画面でプロジェクトを作成し、モデルを2つ追加します。
1. プロジェクトの **モデル** 画面で [**新規モデル**](/ja/cms/how-to/models/) をクリックし、名前を入力して **OK** をクリックします
2. モデルの **スキーマ** 画面で、[**フィールドを追加**](/ja/cms/how-to/fields/) から型をクリックして、以下の各フィールドを追加します
注意
下の2つの表にある **フィールドキー**・**フィールド型**・**選択肢** は、表のとおり正確に設定してください。バックエンドのコード（ステップ3）はこれらの値をそのまま前提にしています。キーの誤字・フィールド型の選び間違い・選択肢の誤字があると、原因がわかりにくいまま CMS へのリクエストが失敗します。
**`infrastructure-assets`** — 地図に表示する資産。
| フィールドキー | フィールド型 | 選択肢 | 必須 |
| ------------------- | --------- | ----------------------------------------------------------- | --- |
| `asset-id` | テキスト | — | はい |
| `asset-name` | テキスト | — | はい |
| `asset-type` | 選択肢 | `manhole` / `streetlight` / `traffic_sign` / `public_bench` | はい |
| `location` | ジオメトリエディタ | ポイント | はい |
| `current-condition` | 選択肢 | `good` / `fair` / `poor` / `critical` / `Not inspected` | いいえ |
| `last-inspected-at` | 日付 | — | いいえ |
| `reference-photo` | アセット | — | いいえ |
`current-condition` は、資産を新規作成した時点では `Not inspected` が初期値として入ります。自分で設定する必要はありません。
ノート
ここでの `reference-photo` は CMS の **アセット** フィールド型（ファイル添付）です。このチュートリアルが「資産」と呼んでいるインフラ資産（マンホール・街灯など）とは別物です。下の `inspection-reports` にある `photos` フィールドも同じフィールド型です。
**`inspection-reports`** — 点検担当者が送信するレポート。
| フィールドキー | フィールド型 | 選択肢 | 必須 |
| ----------------- | --------------- | ----------------------------------------------------------------------------------------------------------- | --- |
| `asset-id` | テキスト | — | はい |
| `asset-type` | 選択肢 | `manhole` / `streetlight` / `traffic_sign` / `public_bench` | はい |
| `location` | ジオメトリエディタ | ポイント | はい |
| `inspection-date` | 日付 | — | はい |
| `condition` | 選択肢 | `good` / `fair` / `poor` / `critical` | はい |
| `issue-category` | 選択肢 | `no_issue` / `damage` / `obstruction` / `missing_component` / `malfunction` / `cleaning_required` / `other` | はい |
| `severity` | 選択肢 | `low` / `medium` / `high` / `urgent` / `not_applicable` | はい |
| `notes` | テキストエリア | — | いいえ |
| `photos` | アセット（複数値の設定を許可） | — | いいえ |
| `report-status` | 選択肢 | `pending` / `approved` / `resolved` | はい |
### インテグレーションを作成して連携する
[Section titled “インテグレーションを作成して連携する”](#インテグレーションを作成して連携する)
1. パーソナルアカウントで **マイインテグレーション** を開き、新規インテグレーションを作成します — 手順の全体は [インテグレーションの作成](/ja/developer/cms/getting-started/integration-setup/) を参照してください
2. プロジェクトのあるワークスペースで **インテグレーション** を開き、作成したインテグレーションを連携します
3. 役割を **maintainer（管理者）** に設定します
ノート
ここでは **writer（編集者）** では足りません。編集者は自分が作成したアイテムしか更新・削除できませんが、このアプリのバックエンドは CMS コンソールで手作業で作成した `infrastructure-assets` のアイテムを更新します — インテグレーションが作成したアイテムではありません。これを満たす最小の役割が **maintainer（管理者）** です。[インテグレーションの作成](/ja/developer/cms/getting-started/integration-setup/#%E5%BD%B9%E5%89%B2) の権限表のとおり、maintainer と owner（所有者）は現時点で権限がまったく同じなので、owner を選ぶ理由はありません。
インテグレーションのトークンをコピーします。パスワードと同様に扱い、コミットしたり、フロントエンドのコードに書いたりしないでください。
### curl でインテグレーションAPI を試す
[Section titled “curl でインテグレーションAPI を試す”](#curl-でインテグレーションapi-を試す)
アプリに触れる前に、まずリクエストを1つ直接送ってみます。ステップ3 のバックエンドのコードが組み立てているのも、これと同じ形です。``・``・``・``・`` を、それぞれ自分の値に置き換えてください。`` は `https://api.cms.reearth.io/api` です。`` と `` は、CMS の管理画面でそのワークスペースやプロジェクトを開いているときのブラウザの URL バーに表示されています。`` は、上で `infrastructure-assets` を作成したときに表示された **モデルキー** です。`` は、今コピーしたインテグレーションのトークンです。
```bash
curl -X POST \
'//projects//models//items' \
-H 'Authorization: Bearer ' \
-H 'Content-Type: application/json' \
-d '{
"fields": [
{ "key": "asset-id", "type": "text", "value": "MH-001" },
{ "key": "asset-name", "type": "text", "value": "Demo Manhole 001" },
{ "key": "asset-type", "type": "select", "value": "manhole" },
{ "key": "location", "type": "geometryEditor", "value": "{\"type\":\"Point\",\"coordinates\":[138.26,36.06]}" }
]
}'
```
CMS は作成したアイテムを返します。次のリクエストで使う `id` もここに含まれています。
```json
{
"id": "01...",
"fields": [
{ "key": "asset-id", "type": "text", "value": "MH-001" },
{ "key": "asset-name", "type": "text", "value": "Demo Manhole 001" },
{ "key": "asset-type", "type": "select", "value": "manhole" },
{ "key": "location", "type": "geometryEditor", "value": "{\"type\":\"Point\",\"coordinates\":[138.26,36.06]}" },
{ "key": "current-condition", "type": "select", "value": "Not inspected" }
],
"refs": ["latest"]
}
```
新規に作成したアイテムは **ドラフト** の状態です — `refs` には `latest` だけが入っています。アプリがステップ3 で行っているのと同じ方法で公開します。
```bash
curl -X POST \
'//projects//models//items//publish' \
-H 'Authorization: Bearer '
```
`refs` に `public` が `latest` と並んで入るようになります — パブリックAPI からもこのアイテムを取得できる状態です。
これで資産を1件作成できました。残りは curl を繰り返す代わりに、CMS のコンソールから直接追加します — 街灯・標識・ベンチをそれぞれ用意してください。**コンテンツ** でモデルを選び、**新規アイテム** をクリックして値を入力し、**保存** します。アプリは、資産が何件か存在しない限り地図に何も表示しません。
## ステップ2 — リポジトリをクローンしてバックエンドを設定する
[Section titled “ステップ2 — リポジトリをクローンしてバックエンドを設定する”](#ステップ2--リポジトリをクローンしてバックエンドを設定する)
```bash
git clone https://github.com/eukarya-biz/infrastructure-inspection-tutorial.git
cd infrastructure-inspection-tutorial/backend
npm install
cp .env.example .env
```
Windows（コマンドプロンプト）では、`cp .env.example .env` の代わりに `copy .env.example .env` を使ってください。
`.env` に、ステップ1 で確認した値を入力します。
| 変数 | 値 |
| ----------------------- | ------------------------------ |
| `PORT` | バックエンドのポート番号（デフォルト `3000`） |
| `CMS_BASE_URL` | Re:Earth CMS の API ベース URL |
| `CMS_WORKSPACE_ID` | ステップ1 のワークスペース ID |
| `CMS_PROJECT_ID` | ステップ1 のプロジェクト ID |
| `CMS_ASSETS_MODEL` | `infrastructure-assets` のモデルキー |
| `CMS_REPORTS_MODEL` | `inspection-reports` のモデルキー |
| `CMS_INTEGRATION_TOKEN` | ステップ1 のインテグレーショントークン |
注意
これらの値は入力後によく確認してください。`CMS_WORKSPACE_ID`・`CMS_PROJECT_ID`・各モデルキーのいずれかが間違っていると、ステップ3 の CMS へのリクエストがすべて失敗します。また `.env` はコミットしたり内容を共有したりしないでください。`CMS_INTEGRATION_TOKEN` は、あなたの CMS プロジェクトに対して **maintainer（管理者）** ロールと同じ読み書き権限を持っています。
```bash
npm run dev
```
バックエンドが `http://localhost:3000` で起動します。
## ステップ3 — バックエンドがインテグレーションAPI をどう使うか
[Section titled “ステップ3 — バックエンドがインテグレーションAPI をどう使うか”](#ステップ3--バックエンドがインテグレーションapi-をどう使うか)
最初の2つのステップは、ここに来るための準備でした。このアプリが CMS に書き込む処理はすべて、`.env` のトークンを使ってインテグレーションAPI を呼びだす、いくつかのルートハンドラーを通ります。
### 共通のリクエストヘルパー
[Section titled “共通のリクエストヘルパー”](#共通のリクエストヘルパー)
`backend/src/cms.ts` は、CMS へのリクエストをすべて同じ形で組み立てます。プロジェクトのベース URL に、`Authorization: Bearer ` ヘッダーを添えるだけです。
```ts
export function cmsProjectUrl(config: CmsConfig, path: string): string {
return `${config.baseUrl}/${config.workspaceId}/projects/${config.projectId}${path}`;
}
export function cmsHeaders(
config: CmsConfig,
extra?: Record,
): Record {
return {
Authorization: `Bearer ${config.token}`,
Accept: "application/json",
...extra,
};
}
```
### レポートを作成する
[Section titled “レポートを作成する”](#レポートを作成する)
`POST /api/reports`（`backend/src/routes/reports.ts`）は `fields` の配列を組み立て、レポートモデルの `items` エンドポイントに送信します。
```ts
const fields = [
{ key: "asset-id", type: "text", value: assetId },
{ key: "asset-type", type: "select", value: assetType },
{ key: "location", type: "geometryEditor", value: JSON.stringify(location) },
{ key: "inspection-date", type: "date", value: `${inspectionDate}T00:00:00+09:00` },
{ key: "condition", type: "select", value: condition },
{ key: "issue-category", type: "select", value: issueCategory },
{ key: "severity", type: "select", value: severity },
{ key: "report-status", type: "select", value: "pending" },
];
if (validPhotoIds.length > 0) {
fields.push({ key: "photos", type: "asset", value: validPhotoIds });
}
await fetch(cmsProjectUrl(config, `/models/${modelKey}/items`), {
method: "POST",
headers: cmsHeaders(config, { "Content-Type": "application/json" }),
body: JSON.stringify({ fields }),
});
```
インテグレーションAPI の複数値アセットフィールド
`photos` のように複数のファイルを受け取るフィールドは、各写真を `POST /assets` で個別にアップロードしたあと、その ID をそのまま配列にして `value` に渡します。配列を何かのオブジェクトで包む必要はなく、空の配列は拒否されます。上のコードが、写真が1件以上アップロードされたときだけこのフィールドを追加しているのはこのためです。
新規アイテムは **ドラフト** として作成されます。アプリは作成の直後、同じインテグレーションAPI のトークンを使って公開します。
```ts
await fetch(`${itemUrl}/publish`, {
method: "POST",
headers: cmsHeaders(config),
});
```
### 資産を更新する
[Section titled “資産を更新する”](#資産を更新する)
レポートが公開されたあと、`PATCH /api/assets/:itemId`（`backend/src/routes/assets.ts`）が資産自身の `current-condition` と `last-inspected-at` を更新し、続けて再公開してパブリックAPI 側でも変更が見えるようにします。
```ts
await fetch(itemUrl, {
method: "PATCH",
headers: cmsHeaders(config, { "Content-Type": "application/json" }),
body: JSON.stringify({
fields: [
{ key: "current-condition", type: "select", value: condition },
{ key: "last-inspected-at", type: "date", value: inspectedAt },
],
}),
});
await fetch(`${itemUrl}/publish`, {
method: "POST",
headers: cmsHeaders(config),
});
```
実際のハンドラーには、これらの呼び出しのまわりに検証とエラー処理が加わっています。完全なコードは [`backend/src/routes/reports.ts`](https://github.com/eukarya-biz/infrastructure-inspection-tutorial/blob/main/backend/src/routes/reports.ts) と [`backend/src/routes/assets.ts`](https://github.com/eukarya-biz/infrastructure-inspection-tutorial/blob/main/backend/src/routes/assets.ts) を参照してください。
## ステップ4 — フロントエンドを動かす
[Section titled “ステップ4 — フロントエンドを動かす”](#ステップ4--フロントエンドを動かす)
```bash
cd ../frontend
npm install
npm run dev
```
`http://localhost:5173` を開きます。フロントエンドはインテグレーションAPI を直接呼びだすことはなく、バックエンド自身のルート（`/api/assets`・`/api/reports` など）だけを呼び出します。それを Vite の開発サーバーがポート 3000 のバックエンドにプロキシします。トークンは終始バックエンド側にとどまります。
地図上の資産をクリックしてポップアップを開き、**Start inspection** をクリックしてレポートのフォームを開きます。
 
フォームに入力し、**Submit report** をクリックします。すると、ステップ3 のバックエンドのルートが順番に呼び出されます — 写真のアップロード、レポートの作成、公開、資産の更新の順です。成功すると、地図のステータス欄に「Report submitted and `` updated」と表示されます。**View report history** ボタンから、これまで送信されたレポート（添付した写真を含む）を一覧できます。
## ステップ5（任意） — Re:Earth Visualizer と連携する
[Section titled “ステップ5（任意） — Re:Earth Visualizer と連携する”](#ステップ5任意--reearth-visualizer-と連携する)
このステップは任意です。アプリ本体の上に乗せるおまけであり、これ以降の内容が前提とするものではありません。
2つの CMS モデルは、パブリックAPI を使えばバックエンドを介さずブラウザから直接読み取ることもできます。
1. 各モデルの [パブリックAPI](/ja/developer/cms/getting-started/public-api-quickstart-read/) 設定で **読み取り** タブを開き、モデルを有効にして **変更を保存** をクリックします
2. 各モデルの `.geojson` エンドポイントを確認します：`https://api.cms.reearth.io/api/p///.geojson`
続いて、Re:Earth Visualizer で次の操作をします。
1. 新規プロジェクトを作成します
2. 各モデルについて、**＋新規レイヤー → リソースからレイヤーを追加** をクリックし、**GeoJSON** タブを選び、**ソースタイプ** をデフォルトの **アセットから** ではなく **Web から** に設定して、モデルの `.geojson` エンドポイントを **リソースURL** に貼り付け、**レイヤーに追加** をクリックします
3. **公開** タブを開き、**公開** をクリックします
公開した URL を知っている人は誰でも、Visualizer の地図上でバックエンドが書き込んでいるのと同じインフラ資産と点検レポートを見られるようになります。
## トラブルシューティング
[Section titled “トラブルシューティング”](#トラブルシューティング)
**レポートの作成で `invalid value` が返る**
選択肢フィールドに送った値が、モデルで定義した選択肢のいずれとも一致していません。`issue-category`・`severity` など、他の選択肢フィールドの値をステップ1 のスキーマと照らし合わせてください。
**地図に資産が1件も表示されない**
バックエンドの `.env` が正しいワークスペース・プロジェクト・モデルキーを指しているか、`infrastructure-assets` に1件以上アイテムが存在するかを確認してください。
**Visualizer でマーカーをクリックしても詳細が表示されない**
このステップは CMS のデータをそのまま GeoJSON レイヤとして読み込んでいるだけで、クリック時に情報を表示する設定（インフォボックス）をしていないため、地図上にマーカーは表示されても、クリックすると写真などのフィールド値は表示されません。これは想定どおりの動作です。このステップはパブリックAPI での読み取りを示すためのもので、フルインタラクティブな地図表示を目的としたものではありません。実現するには、レイヤにインフォボックスを設定する Visualizer のプラグインを書く必要があり、このチュートリアルの範囲を超えます。
## 完了チェックリスト
[Section titled “完了チェックリスト”](#完了チェックリスト)
* [ ] ステップ1 で作成したインフラ資産が地図に表示される
* [ ] 点検レポートを送信すると `inspection-reports` にアイテムが作成・公開される
* [ ] レポート送信後、対象資産の状態と最終点検日が更新される
* [ ] レポート履歴に送信済みのレポートがすべて表示される
* [ ] （任意）Re:Earth Visualizer でも同じデータがパブリックAPI 経由で表示される
# React と TypeScript で ISS Tracker プラグインを作成する
> ISS の現在位置を取得して追跡する Visualizer ウィジェットを作成し、テスト、パッケージ化、インストールします。
Re:Earth Visualizer の React・TypeScript プラグインテンプレートから始めます。ISS Tracker ウィジェットを設定し、ISS の現在位置データと接続して、Visualizer のカメラを操作します。最後に、プラグインをパッケージ化してプロジェクトにインストールします。各ステップで画面の結果を確認しながら進められます。
## 作るもの
[Section titled “作るもの”](#作るもの)
完成した **ISS Tracker プラグイン**には、ISS の現在の経度、緯度、高度が表示されます。**Update** は最新の位置を取得し、**Jump** は表示中の位置へカメラを移動します。**Follow** は5秒ごとに ISS の位置を取得し、カメラを移動します。完成したプラグインを ZIP ファイルにパッケージ化し、Visualizer プロジェクトにウィジェットとしてインストールします。
作業中のプロジェクトは、[完成版の ISS Tracker ソースコード](https://github.com/reearth-plugins/reearth-visualizer-plugin-iss-tracker)と比較できます。
## 前提条件
[Section titled “前提条件”](#前提条件)
* Node.js 20.11.0 以降
* Yarn 4.5.1
* Git
* Visual Studio Code などのコードエディター
* React と TypeScript の基本的な知識
* 開発用プラグインを動かすローカルの Re:Earth Visualizer フロントエンド
ノート
開発用プラグインを動かすには、Re:Earth Visualizer フロントエンドをローカルで起動する必要があります。`REEARTH_WEB_DEV_PLUGIN_URLS` を設定しても、ホストされている Visualizer には反映されません。
## ステップ1・開発環境を準備する
[Section titled “ステップ1・開発環境を準備する”](#ステップ1開発環境を準備する)
### プラグインテンプレートをインストールする
[Section titled “プラグインテンプレートをインストールする”](#プラグインテンプレートをインストールする)
ターミナルを開き、次のコマンドを実行してください。`` は、プロジェクトを作成するディレクトリに置き換えます。
```shell
cd
git clone https://github.com/reearth-plugins/reearth-visualizer-plugin-shadcn-template.git
cd reearth-visualizer-plugin-shadcn-template
corepack enable
yarn install
```
テンプレートは、`package.json` で指定されたバージョンの Yarn を使います。Corepack を有効にすると、互換性のないグローバル版ではなく、指定されたバージョンを使えます。
### ローカルの Visualizer フロントエンドを設定する
[Section titled “ローカルの Visualizer フロントエンドを設定する”](#ローカルの-visualizer-フロントエンドを設定する)
ローカル開発では、`http://localhost:5005` のプレビューサーバーからプラグインを読み込みます。
1. ローカルの Re:Earth Visualizer リポジトリで `web/.env` を開きます
2. 次の環境変数を追加します
```dotenv
REEARTH_WEB_DEV_PLUGIN_URLS='["http://localhost:5005"]'
```
3. ファイルを保存して、ローカルの Visualizer 開発サーバーを再起動します
### プラグインマニフェストを設定する
[Section titled “プラグインマニフェストを設定する”](#プラグインマニフェストを設定する)
プラグインプロジェクトで `public/reearth.yml` を開き、ファイル全体を次の内容に置き換えてください。
```yaml
id: iss-tracker-plugin
name: ISS Tracker Plugin
version: 1.0.0
extensions:
- id: iss_tracker
type: widget
name: ISS Tracker
```
拡張 ID、拡張ディレクトリ、エントリーファイル名、ビルドスクリプト名には、すべて `iss_tracker` を使います。
### ビルドスクリプトを設定する
[Section titled “ビルドスクリプトを設定する”](#ビルドスクリプトを設定する)
プラグインプロジェクトで `package.json` を開き、既存の `scripts` オブジェクトだけを次の内容に置き換えてください。
```json
"scripts": {
"dev:iss_tracker:main": "cross-env EXTENSION_NAME=iss_tracker UI_NAME=main vite -c configs/ui.ts",
"build:iss_tracker:main": "cross-env EXTENSION_NAME=iss_tracker UI_NAME=main vite build -c configs/ui.ts",
"build:iss_tracker:extension": "cross-env EXTENSION_NAME=iss_tracker vite build -c configs/extension.ts",
"build:iss_tracker": "run-s build:iss_tracker:main build:iss_tracker:extension",
"build": "run-s build:iss_tracker zip",
"preview": "vite preview --port 5005 --strict-port",
"zip": "node ./scripts/zip.mjs",
"manage": "node ./scripts/manage.mjs",
"type": "tsc -b",
"lint": "eslint .",
"fix": "eslint --fix .",
"format": "prettier --write .",
"dev-build": "concurrently 'yarn dev:iss_tracker:main' 'yarn build:iss_tracker:main --watch' 'yarn build:iss_tracker:extension --watch' 'vite preview --port 5005 --strict-port'"
}
```
`package.json` のほかの部分は置き換えないでください。
### 拡張ファイルの名前を変更する
[Section titled “拡張ファイルの名前を変更する”](#拡張ファイルの名前を変更する)
プラグインプロジェクトのルートで、テンプレートの拡張ディレクトリとエントリーファイルの名前を変更します。
```shell
mv src/extensions/demo src/extensions/iss_tracker
mv src/extensions/iss_tracker/demo.ts src/extensions/iss_tracker/iss_tracker.ts
```
`src/extensions/iss_tracker/iss_tracker.ts` を開き、HTML の import を次のように変更してください。
```typescript
import html from "@distui/iss_tracker/main/index.html?raw";
```
関連するソースファイルが次の構成になっていることを確認してください。
```text
src/extensions/iss_tracker/
├── iss_tracker.ts
└── main/
├── App.tsx
├── app.css
├── hooks.ts
├── index.html
└── main.tsx
```
### 開発用プラグインを起動してインストールする
[Section titled “開発用プラグインを起動してインストールする”](#開発用プラグインを起動してインストールする)
必要な出力を作るためにプラグインを一度ビルドしてから、開発プロセスを起動します。
```shell
yarn build
yarn dev-build
```
1. `http://localhost:3000/` を開き、ローカルの Visualizer でプロジェクトを選択します
2. エディターのヘッダーで **Install Dev Plugins** と **Reload Dev Plugin Extensions** を確認します
3. **Install Dev Plugins** を選択します。初めてプラグインをインストールするときと、`reearth.yml` を変更したあとに使います
4. 拡張または UI のコードを変更したら、**Reload Dev Plugin Extensions** を選択して最新のビルドを読み込みます
5. 開発用プラグインがインストールされたことを確認します
6. **Widgets** タブを開き、シーンに **ISS Tracker** を追加します
変更前のテンプレートウィジェットには、サンプルの UI が表示されます。次のステップでこの UI を置き換えます。
## ステップ2・ISS Tracker を作成する
[Section titled “ステップ2・ISS Tracker を作成する”](#ステップ2iss-tracker-を作成する)
完成したウィジェットには、次の3つの操作があります。
* **Update** は ISS の現在位置を取得します
* **Jump** は表示中の ISS の位置へ Visualizer のカメラを移動します
* **Follow** は5秒ごとに位置を取得してカメラを移動します
### プロジェクト構成を確認する
[Section titled “プロジェクト構成を確認する”](#プロジェクト構成を確認する)
主に `src` ディレクトリ内のファイルを編集します。
```text
iss-tracker-plugin/
├── node_modules/
├── public/
│ └── reearth.yml # Plugin definition
├── src/
│ ├── extensions/
│ │ └── iss_tracker/ # Extension directory named after its ID
│ │ ├── main/ # UI project for the main view
│ │ └── iss_tracker.ts # Extension script
│ └── shared/
│ ├── components/ # Shared shadcn/ui components
│ ├── lib/ # Shared shadcn/ui utilities
│ ├── reearthTypes/ # Visualizer Plugin API types
│ ├── global.css # Shared Tailwind CSS
│ └── utils.ts
├── dist/ # Plugin build output
├── dist-ui/ # UI build output
├── package/ # Installable ZIP output
├── configs/ # Vite configurations
├── scripts/
├── package.json
└── README.md
```
### テンプレートの UI を変更する
[Section titled “テンプレートの UI を変更する”](#テンプレートの-ui-を変更する)
`src/extensions/iss_tracker/main/App.tsx` を開きます。
既存の `CardHeader` を次の内容に置き換えてください。
```tsx
ISS Tracker
View, move, and update the current location of the ISS
```
テーブル本体で、行ラベルを `Mouse` から `ISS` に変更します。
```tsx
ISS
```
既存の `CardFooter` 全体を、次の3つの仮の操作に置き換えてください。
```tsx
```
この時点では、すべてのボタンが動作するわけではありません。新しい動作を実装する間も既存のハンドラーが参照されるように、`handleFlyToTokyo` を一時的に **Update** に設定します。
Visualizer で **Reload Dev Plugin Extensions** を選択します。UI 開発サーバーの起動中に `http://localhost:5173/` を開くと、UI の変更がホットリロードされます。
### Update を実装する
[Section titled “Update を実装する”](#update-を実装する)
ISS 位置情報 API について
このチュートリアルでは、ボランティアが提供する [Where the ISS at? REST API](https://wheretheiss.at/w/developer) を学習目的で使用します。リクエストは1秒あたり約1回に制限されています。過度なアクセスは避けてください。
`src/extensions/iss_tracker/main/hooks.ts` を開き、ファイル全体を次の内容に置き換えてください。
```typescript
import { useState } from "react";
type IssPosition = {
lat: number;
lon: number;
height: number;
};
export default () => {
const [issPosition, setIssPosition] = useState(null);
const handleUpdate = async () => {
const position = await fetchIssLocation();
setIssPosition(position);
};
return { issPosition, handleUpdate };
};
const fetchIssLocation = async (): Promise => {
try {
const response = await fetch(
"https://api.wheretheiss.at/v1/satellites/25544",
);
if (!response.ok) {
throw new Error(`HTTP error! Status: ${response.status}`);
}
const data = await response.json();
return {
lat: data.latitude,
lon: data.longitude,
height: data.altitude * 1000,
};
} catch {
return null;
}
};
```
このフックは、ISS の位置または `null` を保持します。`fetchIssLocation()` は現在の座標を取得し、高度を km から m に変換します。`handleUpdate()` は結果を React の状態に保存します。
次に `src/extensions/iss_tracker/main/App.tsx` を開き、既存の `useHooks()` 呼びだしを次の内容に置き換えてください。
```tsx
const { issPosition, handleUpdate } = useHooks();
```
**Update** が新しいハンドラーを呼びだすように、`CardFooter` 全体を次の内容に置き換えてください。
```tsx
```
テーブル行の3つの座標セルを次の内容に置き換えてください。
```tsx
```
プラグインを再読み込みして、**Update** を選択します。ウィジェットに現在の経度、緯度、高度が表示されることを確認してください。
### Jump を実装する
[Section titled “Jump を実装する”](#jump-を実装する)
`src/extensions/iss_tracker/main/hooks.ts` を開き、ファイル全体を次の内容に置き換えてください。
```typescript
import { useState } from "react";
import { postMsg } from "@/shared/utils";
type IssPosition = {
lat: number;
lon: number;
height: number;
};
export default () => {
const [issPosition, setIssPosition] = useState(null);
const handleUpdate = async () => {
const position = await fetchIssLocation();
setIssPosition(position);
};
const handleJump = () => {
flyTo(issPosition);
};
return { issPosition, handleUpdate, handleJump };
};
const fetchIssLocation = async (): Promise => {
try {
const response = await fetch(
"https://api.wheretheiss.at/v1/satellites/25544",
);
if (!response.ok) {
throw new Error(`HTTP error! Status: ${response.status}`);
}
const data = await response.json();
return {
lat: data.latitude,
lon: data.longitude,
height: data.altitude * 1000,
};
} catch {
return null;
}
};
const flyTo = (position: IssPosition | null): void => {
if (!position) {
console.warn("No position available to fly to.");
return;
}
postMsg("flyTo", position);
};
```
`flyTo()` は位置があることを確認し、`postMsg()` を使ってウィジェットの iframe から拡張へ位置を送ります。
`src/extensions/iss_tracker/iss_tracker.ts` を開き、ファイル全体を次の内容に置き換えてください。
```typescript
import html from "@distui/iss_tracker/main/index.html?raw";
import { GlobalThis } from "@/shared/reearthTypes";
type IssPosition = {
lat: number;
lon: number;
height: number;
};
type FlyToMessage = {
action: "flyTo";
payload: IssPosition;
};
const isFlyToMessage = (message: unknown): message is FlyToMessage => {
if (!message || typeof message !== "object") return false;
const candidate = message as Partial;
const position = candidate.payload;
return (
candidate.action === "flyTo" &&
!!position &&
Number.isFinite(position.lat) &&
Number.isFinite(position.lon) &&
Number.isFinite(position.height)
);
};
const reearth = (globalThis as unknown as GlobalThis).reearth;
reearth.ui.show(html);
reearth.extension.on("message", (message: unknown) => {
if (!isFlyToMessage(message)) return;
reearth.camera.flyTo(
{
lat: message.payload.lat,
lng: message.payload.lon,
height: message.payload.height,
},
{ duration: 1 },
);
});
```
拡張はメッセージを検証し、`reearth.camera.flyTo()` を呼びだします。ウィジェットでは `lon` を使いますが、カメラ API では `lng` が必要です。
最後に `src/extensions/iss_tracker/main/App.tsx` を開き、フックの呼びだしに `handleJump` を含めてください。
```tsx
const { issPosition, handleUpdate, handleJump } = useHooks();
```
`CardFooter` 全体を次の内容に置き換えてください。
```tsx
```
プラグインを再読み込みし、**Update**、**Jump** の順に選択します。表示中の ISS の位置へカメラが移動することを確認してください。
### Follow を実装する
[Section titled “Follow を実装する”](#follow-を実装する)
`src/extensions/iss_tracker/main/hooks.ts` を開き、ファイル全体を次の完成版フックに置き換えてください。
```typescript
import { useCallback, useEffect, useRef, useState } from "react";
import { postMsg } from "@/shared/utils";
type IssPosition = {
lat: number;
lon: number;
height: number;
};
const ISS_API_URL = "https://api.wheretheiss.at/v1/satellites/25544";
const isIssApiResponse = (
value: unknown,
): value is { latitude: number; longitude: number; altitude: number } => {
if (!value || typeof value !== "object") return false;
const data = value as Record;
return (
Number.isFinite(data.latitude) &&
Number.isFinite(data.longitude) &&
Number.isFinite(data.altitude)
);
};
const fetchIssLocation = async (signal: AbortSignal): Promise => {
const response = await fetch(ISS_API_URL, { signal });
if (!response.ok) {
throw new Error(`ISS API request failed (${response.status}).`);
}
const data: unknown = await response.json();
if (!isIssApiResponse(data)) {
throw new Error("The ISS API returned an unexpected response.");
}
return {
lat: data.latitude,
lon: data.longitude,
height: data.altitude * 1000,
};
};
const flyTo = (position: IssPosition) => {
postMsg("flyTo", position);
};
export default () => {
const [issPosition, setIssPosition] = useState(null);
const [isFollowing, setIsFollowing] = useState(false);
const [error, setError] = useState(null);
const activeRequest = useRef(null);
const loadPosition = useCallback(async (): Promise => {
activeRequest.current?.abort();
const controller = new AbortController();
activeRequest.current = controller;
setError(null);
try {
const position = await fetchIssLocation(controller.signal);
setIssPosition(position);
return position;
} catch (error) {
if (error instanceof DOMException && error.name === "AbortError") {
return null;
}
setError(
error instanceof Error
? error.message
: "Unable to load the ISS position.",
);
return null;
} finally {
if (activeRequest.current === controller) activeRequest.current = null;
}
}, []);
const handleUpdate = useCallback(() => {
void loadPosition();
}, [loadPosition]);
const handleJump = useCallback(() => {
if (issPosition) flyTo(issPosition);
}, [issPosition]);
useEffect(() => {
if (!isFollowing) return;
let stopped = false;
let timeoutId: ReturnType | undefined;
const follow = async () => {
const position = await loadPosition();
if (position) flyTo(position);
if (!stopped) timeoutId = setTimeout(follow, 5000);
};
void follow();
return () => {
stopped = true;
if (timeoutId) clearTimeout(timeoutId);
activeRequest.current?.abort();
};
}, [isFollowing, loadPosition]);
const toggleFollow = useCallback(() => {
setIsFollowing((current) => !current);
}, []);
return {
issPosition,
isFollowing,
error,
handleUpdate,
handleJump,
toggleFollow,
};
};
```
完成版のフックは API のレスポンスを検証します。新しいリクエストが失敗しても、最後に取得できた位置を表示したままにします。また、リクエストの重複を防ぎ、追跡モードの停止時にタイマーと実行中のリクエストを取り消します。
`src/extensions/iss_tracker/main/App.tsx` を開き、ファイル全体を次の完成版 UI に置き換えてください。
```tsx
import useHooks from "./hooks";
import { Button } from "@/shared/components/ui/button";
import {
Card,
CardContent,
CardDescription,
CardFooter,
CardHeader,
CardTitle,
} from "@/shared/components/ui/card";
import { Input } from "@/shared/components/ui/input";
import { Label } from "@/shared/components/ui/label";
import {
Table,
TableBody,
TableCell,
TableHead,
TableHeader,
TableRow,
} from "@/shared/components/ui/table";
function App() {
const {
issPosition,
isFollowing,
error,
handleUpdate,
handleJump,
toggleFollow,
} = useHooks();
return (
ISS Tracker
View, move, and update the current location of the ISS
{error && (
{error}
)}
);
}
export default App;
```
プラグインを再読み込みして、**Follow** を選択します。ボタンが **Unfollow** に変わり、5秒ごとに ISS の最新位置へカメラが移動することを確認してください。
注意
不要な API リクエストを避けるため、動作確認が終わったら **Unfollow** を選択してください。
## ステップ3・プラグインをパッケージ化してインストールする
[Section titled “ステップ3・プラグインをパッケージ化してインストールする”](#ステップ3プラグインをパッケージ化してインストールする)
### プラグインを検証してビルドする
[Section titled “プラグインを検証してビルドする”](#プラグインを検証してビルドする)
プラグインプロジェクトのルートで、次のコマンドを実行してください。
```shell
yarn type
yarn lint
yarn build
```
最後のコマンドは現在のソースをビルドし、`package/iss-tracker-plugin-1.0.0.zip` を作成します。
ZIP ファイルを開き、`reearth.yml` や `iss_tracker.js` などのインストール用ファイルが別のディレクトリ内ではなく、ZIP のルートにあることを確認してください。
### ローカル開発モードを終了する
[Section titled “ローカル開発モードを終了する”](#ローカル開発モードを終了する)
ローカルの Re:Earth Visualizer リポジトリで `web/.env` を開きます。`REEARTH_WEB_DEV_PLUGIN_URLS` を削除するか、次のようにコメントアウトしてください。
```dotenv
# REEARTH_WEB_DEV_PLUGIN_URLS='["http://localhost:5005"]'
```
環境ファイルを変更したら、Visualizer 開発サーバーを再起動してください。
### ZIP ファイルをインストールする
[Section titled “ZIP ファイルをインストールする”](#zip-ファイルをインストールする)
1. Visualizer プロジェクトを作成するか、既存のプロジェクトを開きます
2. プロジェクト名を選択し、**Plugins** を選択します
3. **Personally Installed** を開き、**Upload ZIP File from PC** を選択します
4. プラグインプロジェクトの `package` ディレクトリから `iss-tracker-plugin-1.0.0.zip` をアップロードします
5. インストール済みのプラグインに **ISS Tracker Plugin** が表示されることを確認します
6. エディターに戻ります
7. **Widgets** タブを開き、シーンに **ISS Tracker** を追加します
## 完成したプラグインを確認する
[Section titled “完成したプラグインを確認する”](#完成したプラグインを確認する)
次の項目をすべて確認できたら、プラグインは完成です。
* インストール済みのプラグインに **ISS Tracker Plugin** が表示される
* **Widgets** タブから **ISS Tracker** ウィジェットを追加できる
* **Update** を選択すると、ISS の最新の座標が表示される
* **Jump** を選択すると、表示中の位置へカメラが移動する
* **Follow** が **Unfollow** に変わり、ISS の位置が更新されるたびにカメラが移動する
# パブリックAPI で、1つのモデルからグラフと地図を作る
> Re:Earth CMS にモデルとスキーマを作り、パブリックAPI で配信して、表計算ソフトのグラフと Re:Earth Visualizer の地図で扱うまでを実践します。
このチュートリアルでは、ヘッドレス CMS である Re:Earth CMS の機能を使って、データを配信します。その仕組みは [Re:Earth CMS とはなにか](/ja/cms/concepts/what-is-reearth-cms/) で説明しているので、先に読むことをおすすめします。
Re:Earth CMS にモデルを作り、パブリックAPI を通じて2つの配信先で利用するまでを、次の手順で実践します。
* データの構造を決めて Re:Earth CMS に登録する。
* 登録したデータをパブリックAPI から配信する。
* 同じデータを、表計算ソフト（Microsoft Excel）のグラフと Re:Earth Visualizer の地図でそれぞれ利用する。
モデルに入れるのは、このチュートリアル用に用意した観光施設のデータです。来場者数は実際の数値ではなく、このチュートリアル用の値です。
手順はすべて画面の操作なので、コードエディタを使う場面はありません。
## 事前に準備するもの
[Section titled “事前に準備するもの”](#事前に準備するもの)
* Re:Earth のアカウント
* Microsoft Excel。表計算ソフトとして使います。
Excel を用意できないときは、Google スプレッドシートで代用できます。データの取り込みの手順は本文に書いています。グラフの作成は Excel の画面で書いているので、Google スプレッドシートの操作に読み替えてください。
## プロジェクトを作る
[Section titled “プロジェクトを作る”](#プロジェクトを作る)
Re:Earth CMS に、観光施設のデータを置く場所として、プロジェクトを1つ作りましょう。
1. [Re:Earth CMS](https://cms.reearth.io/) のワークスペースのホームで **新規プロジェクト** をクリックしてください。
2. **プロジェクト名** に `Tourist Spots` と入力してください。半角英数字なので、**プロジェクトエイリアス** に `tourist-spots` が自動で入ります。
3. **プロジェクトの公開範囲** で **公開** を選んでください。プランによっては **非公開** も選べます。
4. **プロジェクト概要** の入力は任意です。ここでは入力せずに進みます。
5. **プロジェクトのライセンス** で **Creative Commons Attribution 4.0 International** を選んでください。
6. **OK** をクリックしてください。
ワークスペースのホームのプロジェクト一覧に、作ったプロジェクトが表示されます。
手順3で選んだ **公開** は、プロジェクトをオープンデータとして公開する設定です。詳しくは [プロジェクトの「公開範囲」](/ja/cms/reference/publish-permissions/project/#%E5%85%AC%E9%96%8B%E7%AF%84%E5%9B%B2) を参照してください。
手順5で選んだ Creative Commons Attribution 4.0 International は、公開したデータを他者が利用・共有してよい条件を伝えるものです。作成者と著作権の表示、ライセンスへの参照を残し、改変したときはその旨を示すことを条件に、改変・再配布・商用利用のいずれも認めます。自分のデータを配信するときは、利用条件に合うライセンスを選びましょう。
## 施設のモデルを作る
[Section titled “施設のモデルを作る”](#施設のモデルを作る)
観光施設のデータを入れるモデルを、プロジェクトの中に作りましょう。
1. ワークスペースのホームのプロジェクト一覧で `Tourist Spots` を開いてください。
2. **モデル** 画面で **新規モデル** をクリックしてください。
3. **モデル名** に `Facility` と入力してください。**モデルキー** に `facility` が自動で入ります。
4. **モデル概要** は空のまま、**OK** をクリックしてください。
`Facility` モデルの **スキーマ** 画面が開きます。この画面で、モデルに入るアイテムの値を定義するスキーマを設定します。
## フィールドを追加する
[Section titled “フィールドを追加する”](#フィールドを追加する)
実際のデータを登録する前に、施設の何を記録するかをフィールドとして決めます。フィールドやスキーマという言葉や、データの登録より先にフィールドを決める理由が分からない場合は、[モデルの構造を先に決める](/ja/cms/concepts/model-structure-first/) を先に読むことをおすすめします。
次の4つのフィールドを、上から順に追加しましょう。
| 表示名 | フィールドキー | フィールド |
| ---------- | ---------- | --------- |
| `Name` | `name` | テキスト |
| `Address` | `address` | テキスト |
| `Location` | `location` | ジオメトリエディタ |
| `Visitors` | `visitors` | 整数型 |
1つ目の `Name` を追加します。
1. **フィールド** タブで **フィールドを追加** を開き、**テキスト** をクリックしてください。
2. **設定** タブの **表示名** に `Name` と入力してください。**フィールドキー** に `name` が自動で入ります。
3. この値をアイテムの見出しに使うので、**タイトルとして使用** をオンにしてください。
4. **検証** タブで **このフィールドを必須項目にする** をオンにしてください。
5. **OK** をクリックしてください。
2つ目の `Address` を追加します。
1. **フィールドを追加** を開き、**テキスト** をクリックしてください。
2. **表示名** に `Address` と入力してください。
3. **検証** タブで **このフィールドを必須項目にする** をオンにしてください。
4. **OK** をクリックしてください。
3つ目の `Location` を追加します。
1. **フィールドを追加** を開き、**ジオメトリエディタ** をクリックしてください。
2. **表示名** に `Location` と入力してください。
3. **対応タイプ** で **Point** を選んでください。
4. **検証** タブで **このフィールドを必須項目にする** をオンにしてください。
5. **OK** をクリックしてください。
4つ目の `Visitors` を追加します。
1. **フィールドを追加** を開き、**整数型** をクリックしてください。
2. **表示名** に `Visitors` と入力してください。
3. **検証** タブで **このフィールドを必須項目にする** をオンにしてください。
4. **OK** をクリックしてください。
**フィールド** タブの一覧に、追加した4つのフィールドが並びます。必須にしたフィールドには `*` が、タイトルに設定した `Name` には **タイトル** が付きます。
これで、`Facility` モデルのスキーマができました。このスキーマで定めたフィールドに沿って、アイテムを登録します。
## アイテムを登録する
[Section titled “アイテムを登録する”](#アイテムを登録する)
スキーマで定めたフィールドに沿って、施設を1件ずつアイテムとして登録しましょう。登録するのは次の4件です。
| `Name` | `Address` | `Location` | `Visitors` |
| ------- | -------------- | --------------- | ---------- |
| 国立西洋美術館 | 東京都台東区上野公園7-7 | 画面上の地図のエディタから入力 | `100000` |
| 浅草寺 | 東京都台東区浅草2-3-1 | 画面上の地図のエディタから入力 | `300000` |
| 恩賜上野動物園 | 東京都台東区上野公園9-83 | 画面上の地図のエディタから入力 | `200000` |
| 国立科学博物館 | 東京都台東区上野公園7-20 | 画面上の地図のエディタから入力 | `150000` |
`Name` と `Address` に選んだ **テキスト** は、文字を自由に入力する欄です。`Location` に選んだ **ジオメトリエディタ** は、画面上の地図に点を置いて値を入れる欄です。`Visitors` に選んだ **整数型** は、小数を含まない数値を入れる欄です。
1件目を登録しましょう。
1. **コンテンツ** の **モデル** からモデル名 `Facility` を選んでください。
2. **新規アイテム** をクリックしてください。
3. 各フィールドに値を入れてください。
1. `Name` に `国立西洋美術館` と入力してください。
2. `Address` に `東京都台東区上野公園7-7` と入力してください。
3. `Location` の地図にある検索バーに `国立西洋美術館` と入力して検索してください。地図がその施設の周辺に移動します。
4. 地図の右上にあるマップピンのアイコンをクリックしてください。
5. 地図上で施設の位置をクリックしてください。点が置かれ、`Location` の欄に座標が入ります。
6. `Visitors` に `100000` と入力してください。
4. **保存** をクリックしてください。
保存すると、アイテムのステータスに **ドラフト** が付きます。
同じ手順で、残り3件を登録しましょう。フィールドはモデルの中で固定されているので、2件目以降も同じ4つの欄に値を入れて登録できます。
これで、配信するデータの登録が完了しました。
Re:Earth CMS が行うのは、データの管理と配信までです。配信したデータをどう扱うかは配信先で決まり、このチュートリアルでは表計算ソフトと Re:Earth Visualizer の2つを使います。次のステップでは、配信するための設定を Re:Earth CMS で行います。
## アイテムを公開する
[Section titled “アイテムを公開する”](#アイテムを公開する)
Re:Earth CMS は、API を通じてデータを配信します。このチュートリアルでは、認証なしで公開データを読み取れるパブリックAPI を使います。詳しくは [パブリックAPI設定](/ja/cms/reference/publish-permissions/public-api-settings/) を参照してください。
パブリックAPI が配信するのは、ステータスが **公開済み** のアイテムだけです。登録した4件のうち、3件を **公開済み** にしましょう。
1. **コンテンツ** 画面の一覧で、`国立西洋美術館`・`浅草寺`・`恩賜上野動物園` の3件の行のチェックボックスにチェックを入れてください。
2. **公開** をクリックしてください。
3. **アイテムの公開** の確認で **はい** をクリックしてください。
3件のステータスが **公開済み** に変わります。`国立科学博物館` は **ドラフト** のままです。これから配信されるのは、いま **公開済み** にした3件です。
## エンドポイントを取得する
[Section titled “エンドポイントを取得する”](#エンドポイントを取得する)
パブリックAPI は、配信するモデルごとに URL を持ちます。この URL を **エンドポイント** と呼びます。配信先は、エンドポイントからそのモデルのアイテムを取得します。
`Facility` モデルのエンドポイントを取得しましょう。
1. 左メニューの **パブリックAPI** を開いてください。
2. **読み取り** タブを開いてください。
3. モデル名 `Facility` の行の **エンドポイント** の URL をコピーしてください。
有料プランのワークスペースで、プロジェクトの公開範囲を **非公開** にしている場合は、手順3の前に `Facility` の行の **有効** をオンにして、**変更を保存** をクリックしてください。
パブリックAPI は、アイテムを JSON・CSV・GeoJSON のいずれかの形式で配信できます。
次のステップでは、Excel や Re:Earth Visualizer を使って、Re:Earth CMS で作成したモデルの配信や再利用を実践してみましょう。
## 表計算ソフトで表示する
[Section titled “表計算ソフトで表示する”](#表計算ソフトで表示する)
Re:Earth CMS で取得したエンドポイントの URL を Excel に取り込んで、配信されているデータを表示してみましょう。
1. Excel で空白のブックを作成してください。
2. **データ** タブの **データの取得** から、**その他のデータソースから** の **Web から** をクリックしてください。
3. **URL** に、「エンドポイントを取得する」の手順3でコピーした URL を貼り付けてください。
4. 貼り付けた URL の末尾に `.csv` を入力してください。
5. **OK** をクリックしてください。
6. **Web コンテンツへのアクセス** が表示されます。**匿名** での接続であることを確認し、レベルを変えずに **接続** をクリックしてください。
7. **読み込み** をクリックしてください。
Google スプレッドシートで進めるときは、手順1から7の代わりに次の操作をしてください。
1. Google スプレッドシートで空白のスプレッドシートを作成してください。
2. セル `A1` に `=IMPORTDATA("")` と入力してください。
3. `"` と `"` の間に、「エンドポイントを取得する」の手順3でコピーした URL を貼り付けてください。
4. 貼り付けた URL の末尾に `.csv` を入力してください。
5. Enter キーを押してください。
新しいシートに、配信されているデータがテーブルとして表示されます。手順4でエンドポイントの URL の末尾に `.csv` を付けたので、Re:Earth CMS から Excel へ CSV の形式で配信されます。
テーブルの1行目は、「フィールドを追加する」で定義したフィールドキーが入力されています。 `id` は、アイテムごとに Re:Earth CMS が自動で付ける識別子です。CSV の形式では、ジオメトリエディタのフィールドが配信されないため、`Location` のフィールドは表示されません。
2行目から下は、「アイテムを登録する」で登録し、「アイテムを公開する」で **公開済み** にした3件のアイテムが入力されています。 `国立科学博物館` のアイテムは **ドラフト** のままのため配信されていません。
このように、パブリックAPI のエンドポイントを利用すると、`Facility` モデルで定義したフィールドキーと、公開したアイテムが、表計算ソフトで扱える構造で配信されます。
## 表計算ソフトでグラフを作る
[Section titled “表計算ソフトでグラフを作る”](#表計算ソフトでグラフを作る)
APIで配信された Re:Earth CMS のデータは、受け取ったツールのなかで再利用できます。テーブルの `visitors` の列から、施設ごとの来場者数を比べるグラフを作りましょう。
1. `name` の `B1` から `B4` までを選択してください。
2. Ctrl キーを押しながら、`visitors` の `D1` から `D4` までを選択してください。
3. **挿入** タブの **縦棒/横棒グラフの挿入** から **集合縦棒** をクリックしてください。
「アイテムを登録する」で `Visitors` に入力した値が、施設名ごとの縦棒グラフとして表示されます。
このグラフは、配信された `visitors` の列から作ったものです。グラフの種類も、どの列を軸と棒に使うかも、手順1から手順3で Excel の側で指定しました。
Re:Earth CMS には、グラフの設定はひとつもありません。どのフィールドを使って何を作るかは、配信先で決めています。
次のステップでは、Re:Earth Visualizer の画面で操作します。
## Re:Earth Visualizerで地図に表示する
[Section titled “Re:Earth Visualizerで地図に表示する”](#reearth-visualizerで地図に表示する)
Excel に取り込んだものと同じエンドポイントの URL を Re:Earth Visualizer に入力して、施設を地図に表示しましょう。
はじめに、プロジェクトを Re:Earth Visualizer に作ります。
1. [Re:Earth Visualizer](https://visualizer.reearth.io/) のダッシュボードで **＋新規プロジェクト** をクリックしてください。
2. **プロジェクト名** に `Tourist Spots Map` と入力してください。
3. **プロジェクト別名** に `tourist-spots-map` と入力してください。
4. **プロジェクトの公開範囲** で **公開** を選んでください。プランによっては **非公開** も選べます。
5. **説明** の入力は任意です。ここでは入力せずに進みます。
6. **Choose a license** で **Creative Commons Attribution 4.0 International** を選んでください。
7. **適用** をクリックしてください。
8. ダッシュボードに追加されたプロジェクトのカードをダブルクリックしてください。
作ったプロジェクトに、Re:Earth CMS のデータをレイヤとして追加しましょう。
1. 左パネルの **＋新しいレイヤー** をクリックしてください。
2. **リソースからレイヤーを追加** を選んでください。
3. データソースマネージャーの **GeoJSON** タブで、ソースタイプを **ウェブから** にしてください。
4. **リソースURL** に、「エンドポイントを取得する」の手順3でコピーした URL を入力してください。
5. 入力した URL の末尾に `.geojson` を付けてください。
6. **レイヤーに追加** をクリックしてください。
7. レイヤの一覧に追加されたレイヤの **移動** をクリックしてください。
地図が施設の周辺に移動し、「アイテムを公開する」で **公開済み** にした3件がピンで表示されます。レイヤを追加する手順5で末尾に `.geojson` を付けたことで、地図で扱うための GeoJSON の形式で配信されました。
「表計算ソフトで表示する」では列に出てこなかった `Location` の座標が、GeoJSON では配信されています。ピンの位置は、「アイテムを登録する」の手順3で地図上に置いた点の座標です。
エンドポイントの末尾を変えると、表計算ソフトではテーブルとして受け取ったデータを、Re:Earth Visualizer では地理空間データとして扱えます。地図のピン1つが、アイテム1件に対応しています。
GeoJSON形式のデータでも、`Location` フィールドのほかに、`Name`・`Address`・`Visitors` フィールドも配信されています。Re:Earth Visualizer のインフォボックスを使って、3つのフィールドの値が配信されていることを確かめましょう。
1. 地図に表示された施設のどれかをクリックしてください。
2. **インスペクター** パネルの **インフォボックス** タブを開いてください。
3. **有効** スイッチをオンにしてください。
インフォボックスが表示されます。この中に、フィールドごとのブロックを追加します。
1. `Name` フィールドのブロックを追加してください。
1. インフォボックスの左上にある **＋** をクリックし、**テキスト** を選んでください。
2. 追加されたブロックをクリックしてください。
3. ブロックの右上に表示される鉛筆のアイコンをクリックしてください。
4. **コンテンツ** の入力欄の右にある ****をクリックし、一覧から `name` を選んでください。
5. **\[→** をクリックしてください。
2. `Address` フィールドのブロックを追加してください。
1. **＋** をクリックし、**テキスト** を選んでください。
2. 追加されたブロックをクリックしてください。
3. ブロックの右上に表示される鉛筆のアイコンをクリックしてください。
4. **コンテンツ** の入力欄の右にある ****をクリックし、一覧から `address` を選んでください。
5. **\[→** をクリックしてください。
3. `Visitors` フィールドのブロックを追加してください。
1. **＋** をクリックし、**テキスト** を選んでください。
2. 追加されたブロックをクリックしてください。
3. ブロックの右上に表示される鉛筆のアイコンをクリックしてください。
4. **コンテンツ** の入力欄の右にある ****をクリックし、一覧から `visitors` を選んでください。
5. **\[→** をクリックしてください。
地図上の施設をクリックすると、インフォボックスにそのアイテムの `Name`・`Address`・`Visitors` フィールドの値が表示されます。3つのピンを順にクリックして、それぞれの施設の値が表示されることを確かめましょう。
ブロックを追加する手順で ****の一覧に並んでいた `name`・`address`・`visitors` は、「表計算ソフトで表示する」で1行目に並んでいた列見出しと同じです。
「表計算ソフトでグラフを作る」では施設どうしを比べる列として使った `visitors` を、ここでは1件ずつの値として表示しています。
## 未公開のアイテムを配信する
[Section titled “未公開のアイテムを配信する”](#未公開のアイテムを配信する)
「アイテムを公開する」でチェックを入れなかった `国立科学博物館` は、まだ **ドラフト** のままです。これを公開して、2つの配信先が両方とも変わることを確かめましょう。
はじめに、Re:Earth CMS に戻ります。
1. **コンテンツ** の **モデル** から `Facility` を選んでください。
2. `国立科学博物館` の行のチェックボックスにチェックを入れてください。
3. **公開** をクリックしてください。
4. **アイテムの公開** の確認で **はい** をクリックしてください。
`国立科学博物館` のステータスが **公開済み** に変わり、パブリックAPI が配信するアイテムは4件になります。
続いて、Excel で配信されるデータがどう変わったのかを確かめましょう。
1. テーブルの中のセルをクリックしてください。
2. **テーブル デザイン** タブの **更新** をクリックしてください。
Google スプレッドシートには **更新** に当たるボタンがありません。Google スプレッドシートで進めているときは、手順1と手順2の代わりに、セル `A1` の数式を数式バーからコピーし、セルの内容を消してから貼り付けてください。数式を入れ直すと、表が更新されます。
表に `国立科学博物館` の行が増えます。グラフに加えるには、「表計算ソフトでグラフを作る」の手順1と手順2で選んだ `B1:B4` と `D1:D4` を、`B1:B5` と `D1:D5` に広げます。
続いて、Re:Earth Visualizer で配信されるデータがどう変わったのかを確かめましょう。
1. 「Re:Earth Visualizerで地図に表示する」で利用したRe:Earth Visualizer のプロジェクトを開き、ブラウザの再読み込みをしてください。
2. デフォルトのカメラ位置（北米上空）に戻ってしまった場合には、レイヤの **移動** ボタンを押して該当のレイヤまでカメラを移動させてください。
地図のピンが4件に増えていることが確認できます。
## 振り返り
[Section titled “振り返り”](#振り返り)
表計算ソフトや地図に出ている値は、`Facility` モデルのスキーマで決めたフィールドの値です。Re:Earth CMS で行ったのは、「フィールドを追加する」で構造を決め、「アイテムを登録する」で構造に沿って値を入れ、「アイテムを公開する」で配信の対象にすることまでです。
Excel と Re:Earth Visualizer は、その配信先です。どちらも同じ1つのエンドポイントから、それぞれ適切な形式（拡張子）のデータで受け取りました。
受け取ったデータから何を作るかは、配信先の画面で決めました。Excel では `name` と `visitors` を選んで縦棒グラフにし、Re:Earth Visualizer では `Location` をもとに地図に表示されたピンに `Name`・`Address`・`Visitors` のインフォボックスを足して可視化しました。
Re:Earth CMS のモデルは、こうしてデータベースとして運用できます。配信先はここで使った2つに限らず、エンドポイントの URL さえあれば、別のサービスからも自分で作るフロントエンドからも、同じデータを同じ構造で扱えます。
## 実践したことを確かめる
[Section titled “実践したことを確かめる”](#実践したことを確かめる)
ここまでで実践したことをもとに、次の4つを考えてみましょう。
1. Re:Earth CMS で管理している座標を持つデータを地図のアプリで使いたいとき、パブリックAPI からどの形式でエンドポイントの URL を取得するとよいでしょうか。
2. Re:Earth Visualizer のインフォボックスのフォントサイズを変えたいとき、編集するのは Re:Earth Visualizer と Re:Earth CMS のどちらでしょうか。また、インフォボックスに出ている施設名と住所を変えたいときは、どちらを編集するでしょうか。
3. Re:Earth CMS を自分で使うとしたら、どんなことに使ってみたいでしょうか。その用途のために、モデルにはどんなフィールドが必要でしょうか。
4. 3で検討したモデルのデータを、パブリックAPI のどの形式のエンドポイントを使って、どんなフロントエンドで使えそうでしょうか。
# パブリックAPI で作る フィードバック収集・閲覧アプリ
> バックエンド不要で、ブラウザから直接 Re:Earth CMS にデータを投稿・表示する 1 ページのフィードバックアプリを作る。
Re:Earth CMS のパブリックAPI を使い、バックエンド不要のシンプルな 1 ページのフィードバックアプリを作ります。ブラウザから直接 CMS にデータを投稿し、公開済みのフィードバックを一覧表示します。
## 作成するもの
[Section titled “作成するもの”](#作成するもの)
ブラウザから Re:Earth CMS のパブリックAPI に直接アクセスする、バックエンド不要の 1 ページアプリです。Submit タブでフィードバックを投稿し、All Feedback タブで公開済みのフィードバックを一覧表示します。投稿されたデータは CMS に下書き状態で保存され、管理画面またはインテグレーションAPI で公開するとブラウザの一覧に反映されます。
Submit タブは、名前・製品・カテゴリ・コメントを入力してフィードバックを送信するフォームです。
All Feedback タブは、公開済みのフィードバックをカード形式で一覧表示します。
 
## 事前準備
[Section titled “事前準備”](#事前準備)
* Re:Earth CMS のアカウントとプロジェクトがあること
* テキストエディタとブラウザアプリケーションがあること
* Node.js がインストールされていること（Vite を使う場合）
## ステップ1・CMS でモデルを作る
[Section titled “ステップ1・CMS でモデルを作る”](#ステップ1cms-でモデルを作る)
Re:Earth CMS の管理画面で、以下のフィールドを持つモデルを作成します。
| フィールドキー | フィールド型 | 選択肢 | 必須 |
| ---------- | ------- | --------------------------------------------------- | -- |
| `name` | テキスト | — | ❌ |
| `product` | オプション | `visualizer` / `cms` / `flow` | ✅ |
| `category` | オプション | `bug` / `improvement` / `feature_request` / `other` | ✅ |
| `comment` | テキストエリア | — | ✅ |
モデルを作成したら、パブリックAPIを設定します。
1. プロジェクトが非公開の場合は、読み取りから、対象のモデルの **パブリックAPI を有効**にし、**変更を保存**をクリックする（公開プロジェクトでは不要です）
2. 書き込みから、許可するオリジンを `http://localhost:5500/` に設定する
3. 書き込みから、対象のモデルの **パブリックAPI を有効**にする
4. 書き込みから、**変更を保存**をクリックする
注意
読み取りと書き込みには、それぞれ独立した **変更を保存** ボタンがあります。どちらのタブも、このボタンを押すまで変更は保存されません。保存せずにページを離れると書き込みが無効のままになり、ステップ2の POST リクエストが失敗します。
設定が完了すると、Public API ページの Posting タブは以下のような状態になります。
パブリックAPI のセットアップ方法は [読み取り](/ja/developer/cms/getting-started/public-api-quickstart-read/) と [書き込み](/ja/developer/cms/getting-started/public-api-quickstart-write/) のページを参照してください。
## ステップ2・curl で API の動作を確認する
[Section titled “ステップ2・curl で API の動作を確認する”](#ステップ2curl-で-api-の動作を確認する)
コードを書く前に、curl を使って API が正しく動作するか確認しましょう。 ``・``・`` を実際の値に置き換えて実行してください。
### GET — 公開済みアイテムの一覧を取得する
[Section titled “GET — 公開済みアイテムの一覧を取得する”](#get--公開済みアイテムの一覧を取得する)
パブリックAPI はブラウザや curl から認証なしで呼び出せます。コマンドラインツールから以下のコマンドを実行して、レスポンスが返ってくることを確認します。
```bash
curl 'https://api.cms.reearth.io/api/p///'
```
まだアイテムを公開していない場合は、`results` が空の JSON が返ります。
```json
{ "results": [], "totalCount": 0 }
```
パブリックAPI の読み取りから、エンドポイントの URL をクリックすることで同様に取得できます。
### POST — フィードバックを投稿する
[Section titled “POST — フィードバックを投稿する”](#post--フィードバックを投稿する)
次に、フィードバックを 1 件投稿してみます。`fields` のキーと値が CMS のモデル定義と一致している必要があります。
```bash
curl -X POST \
'https://api.cms.reearth.io/api/p////items' \
-H 'Content-Type: application/json' \
-H 'Origin: http://localhost:5500' \
-d '{
"fields": {
"name": "Test",
"product": "cms",
"category": "improvement",
"comment": "I would like the documentation to be more comprehensive."
}
}'
```
パブリックAPI の書き込みから、エンドポイントの隣の Copy をクリックすると、curl リクエストをコピーできます。
成功すると、作成されたアイテムの JSON が返ります。
```json
{
"id": "01m098...",
"$createdAt": "2026-08-19T00:00:00.000Z",
"fields": {
"name": "Test",
"product": "cms",
"category": "improvement",
"comment": "I would like the documentation to be more comprehensive."
}
}
```
投稿は **下書き状態** のため、GET で取得しても一覧には表示されません。CMS の管理画面でアイテムを公開すると、パブリックAPI の GET で取得できるようになります。
## ステップ3・作業ディレクトリを作る
[Section titled “ステップ3・作業ディレクトリを作る”](#ステップ3作業ディレクトリを作る)
作業用のディレクトリを作成し、移動します。
```bash
mkdir feedback-app
cd feedback-app
```
このディレクトリの中に `index.html`・`style.css`・`app.js` の 3 ファイルを作成していきます。
## ステップ4・アプリを作る
[Section titled “ステップ4・アプリを作る”](#ステップ4アプリを作る)
API の動作が確認できたら、フロントエンドアプリを作ります。`index.html`・`style.css`・`app.js` の 3 ファイルで構成します。
注意
ここで扱うコードは学習用のサンプルです。本番環境で利用する場合は、入力値のバリデーションを追加し、認証・アクセス制御などのセキュリティ対策も検討してください。
### index.html
[Section titled “index.html”](#indexhtml)
HTML の構造を定義します。タブの切り替えや投稿フォーム、一覧表示エリアを配置しています。
```html
Re:Earth Feedback
Re:Earth
Feedback
```
### style.css
[Section titled “style.css”](#stylecss)
スタイルを定義します。
```css
*,
*::before,
*::after {
box-sizing: border-box;
margin: 0;
padding: 0;
}
body {
font-family: "Inter", system-ui, sans-serif;
background: #f8f9fb;
min-height: 100vh;
display: flex;
align-items: flex-start;
justify-content: center;
padding: 40px 16px;
}
.card {
background: #fff;
border-radius: 16px;
padding: 40px;
width: 100%;
max-width: 520px;
box-shadow: 0 4px 24px rgba(0, 0, 0, 0.07);
}
.logo {
font-size: 0.75rem;
font-weight: 700;
letter-spacing: 0.1em;
color: #6b7280;
margin-bottom: 20px;
}
h1 {
font-size: 1.5rem;
font-weight: 700;
color: #111827;
margin-bottom: 24px;
}
.tabs {
display: flex;
gap: 4px;
background: #f3f4f6;
border-radius: 10px;
padding: 4px;
margin-bottom: 32px;
}
.tab {
flex: 1;
padding: 8px;
border: none;
border-radius: 7px;
font-size: 0.875rem;
font-weight: 600;
cursor: pointer;
background: transparent;
color: #6b7280;
transition: all 0.15s;
}
.tab.active {
background: #fff;
color: #111827;
box-shadow: 0 1px 4px rgba(0, 0, 0, 0.1);
}
.field {
margin-bottom: 20px;
}
label {
display: block;
font-size: 0.8rem;
font-weight: 600;
color: #374151;
margin-bottom: 6px;
}
input,
select,
textarea {
width: 100%;
padding: 10px 14px;
border: 1.5px solid #e5e7eb;
border-radius: 8px;
font-size: 0.9rem;
color: #111827;
background: #fff;
transition: border-color 0.15s;
outline: none;
appearance: none;
}
input:focus,
select:focus,
textarea:focus {
border-color: #2563eb;
}
textarea {
resize: vertical;
min-height: 100px;
}
.btn {
width: 100%;
margin-top: 8px;
padding: 12px;
background: #2563eb;
color: #fff;
border: none;
border-radius: 8px;
font-size: 0.95rem;
font-weight: 600;
cursor: pointer;
transition: background 0.15s;
}
.btn:hover {
background: #1d4ed8;
}
.btn:disabled {
background: #93c5fd;
cursor: not-allowed;
}
#message {
margin-top: 16px;
font-size: 0.85rem;
text-align: center;
color: #6b7280;
}
#message.success {
color: #16a34a;
}
#message.error {
color: #dc2626;
}
.feedback-item {
border: 1px solid #e5e7eb;
border-radius: 10px;
padding: 16px;
margin-bottom: 12px;
}
.feedback-meta {
display: flex;
align-items: center;
gap: 8px;
margin-bottom: 8px;
flex-wrap: wrap;
}
.tag {
font-size: 0.75rem;
font-weight: 700;
padding: 2px 10px;
border-radius: 99px;
}
.tag-bug { background: #fee2e2; color: #dc2626; }
.tag-improvement { background: #e0f2fe; color: #0284c7; }
.tag-feature_request { background: #fef9c3; color: #ca8a04; }
.tag-other { background: #f3f4f6; color: #6b7280; }
.feedback-product {
font-size: 0.8rem;
color: #6b7280;
}
.feedback-name {
font-size: 0.8rem;
color: #9ca3af;
margin-left: auto;
}
.feedback-comment {
font-size: 0.9rem;
color: #374151;
line-height: 1.6;
}
.empty,
.loading {
text-align: center;
color: #9ca3af;
font-size: 0.9rem;
padding: 40px 0;
}
.section {
display: none;
}
.section.active {
display: block;
}
```
### app.js
[Section titled “app.js”](#appjs)
アプリのロジックを担います。タブの切り替え・一覧の取得・フォームの送信の 3 つの処理を実装します。
``・``・`` を実際の値に置き換えてください。
```js
const WORKSPACE = "";
const PROJECT = "";
const MODEL = "";
const BASE = `https://api.cms.reearth.io/api/p/${WORKSPACE}/${PROJECT}/${MODEL}`;
const PRODUCT_LABEL = {
visualizer: "Re:Earth Visualizer",
cms: "Re:Earth CMS",
flow: "Re:Earth Flow",
};
const CATEGORY_LABEL = {
bug: "🐛 Bug Report",
improvement: "✨ Improvement",
feature_request: "💡 Feature Request",
other: "💬 Other",
};
// タブ切り替え
document.querySelectorAll(".tab").forEach((tab) => {
tab.addEventListener("click", () => {
document
.querySelectorAll(".tab")
.forEach((t) => t.classList.remove("active"));
document
.querySelectorAll(".section")
.forEach((s) => s.classList.remove("active"));
tab.classList.add("active");
document
.getElementById(`${tab.dataset.tab}-section`)
.classList.add("active");
if (tab.dataset.tab === "list") {
loadList();
}
});
});
// 一覧取得
async function loadList() {
const content = document.getElementById("list-content");
try {
const resp = await fetch(BASE);
if (!resp.ok) {
throw new Error(`Request failed (${resp.status})`);
}
const data = await resp.json();
if (!data.results || data.results.length === 0) {
content.className = "empty";
content.textContent = "No feedback yet.";
return;
}
content.className = "";
content.innerHTML = "";
for (const item of data.results) {
const el = document.createElement("div");
el.className = "feedback-item";
const meta = document.createElement("div");
meta.className = "feedback-meta";
const tag = document.createElement("span");
tag.className = `tag tag-${item.category}`;
tag.textContent = CATEGORY_LABEL[item.category] ?? item.category;
const product = document.createElement("span");
product.className = "feedback-product";
product.textContent = PRODUCT_LABEL[item.product] ?? item.product;
const name = document.createElement("span");
name.className = "feedback-name";
name.textContent = item.name ?? "Anonymous";
meta.append(tag, product, name);
const comment = document.createElement("p");
comment.className = "feedback-comment";
comment.textContent = item.comment;
el.append(meta, comment);
content.appendChild(el);
}
} catch (err) {
content.className = "empty";
content.textContent = "Failed to load feedback.";
console.error(err);
}
}
// 投稿
const message = document.getElementById("message");
const btn = document.getElementById("submit-btn");
document
.getElementById("feedback-form")
.addEventListener("submit", async (e) => {
e.preventDefault();
btn.disabled = true;
message.className = "";
message.textContent = "Submitting...";
const formData = new FormData(e.target);
const body = {
fields: {
name: formData.get("name") || undefined,
product: formData.get("product"),
category: formData.get("category"),
comment: formData.get("comment"),
},
};
try {
const resp = await fetch(`${BASE}/items`, {
method: "POST",
headers: {
"Content-Type": "application/json",
Accept: "application/json",
},
body: JSON.stringify(body),
});
btn.disabled = false;
if (!resp.ok) {
const data = await resp.json().catch(() => ({}));
message.className = "error";
message.textContent = `Error: ${data.message ?? `Request failed (${resp.status})`}`;
return;
}
message.className = "success";
message.textContent =
"Submitted! It will appear in the list once published in CMS.";
e.target.reset();
} catch (err) {
btn.disabled = false;
message.className = "error";
message.textContent = "Failed to submit. ";
console.error(err);
}
});
```
一覧取得（GET）の処理について
`loadList()` 関数でパブリックAPI にアクセスし、公開済みのフィードバックを取得します。`await fetch(BASE)` で GET リクエストを送り、`resp.ok` を確認して HTTP エラーを空の一覧と取り違えないようにしたうえで、レスポンスの `results` 配列をループして DOM にカードを追加しています。一覧タブを開くたびに実行するため、一覧には常に現在の公開状態が表示されます。
投稿（POST）の処理について
フォームの送信イベントを受け取り、`fetch()` の `method: "POST"` で投稿します。フォームの値を `fields` オブジェクトにまとめてリクエストボディに渡します。`name` フィールドは任意項目のため、空の場合は `undefined` にして送信から除外しています。送信中はボタンを `disabled` にして二重送信を防いでいます。
## ステップ5・開発サーバーを起動する
[Section titled “ステップ5・開発サーバーを起動する”](#ステップ5開発サーバーを起動する)
3 ファイルが揃ったら、ローカルサーバーを起動してブラウザで確認します。
```bash
npx vite --port 5500
```
起動後、`http://localhost:5500` をブラウザで開きます。
Submit タブは以下のように表示されます。
All Feedback タブは、まだフィードバックを投稿していないため次のように表示されます。
補足
`index.html` をブラウザで直接開く（`file://`）と、セキュリティ制限により `fetch` が動作しない場合があります。必ずローカルサーバー経由でアクセスしてください。VS Code を使っている場合は、Live Server 拡張機能でも同様に確認できます。
## ステップ6・動作確認
[Section titled “ステップ6・動作確認”](#ステップ6動作確認)
サーバーが起動したら、実際に動作を確認してみましょう。
1. ブラウザでアプリを開き、**Submit タブ**からフィードバックを入力して送信する
2. Re:Earth CMS の管理画面を開き、作成したモデルのアイテム一覧を確認する — 投稿したフィードバックが **下書き状態**で登録されていることを確認する
3. アイテムを選択し、**Publish** をクリックして公開する
4. アプリに戻り、**All Feedback タブ**を開く — 公開したフィードバックが一覧に表示されることを確認する
下書き状態について
パブリックAPI で投稿されたアイテムは **下書き状態**で保存されます。パブリックAPI の読み取りでは公開済みのアイテムのみ取得できるため、下書き状態のアイテムは一覧に表示されません。
下書き状態のアイテムを公開するには、以下のいずれかの方法を使います。
* CMS の管理画面からアイテムを公開する
* インテグレーションAPI の `/publish` エンドポイントを使って公開する
## トラブルシューティング
[Section titled “トラブルシューティング”](#トラブルシューティング)
**送信したフィードバックが一覧に表示されない**
投稿されたフィードバックはデフォルトで **下書き状態**で保存されます。CMS の管理画面でアイテムを公開すると一覧に反映されます。
**送信時に `400 Bad Request` が返る**
`product` と `category` フィールドの値が、CMS のモデルで定義した選択肢と完全に一致しているか確認してください（例： `Visualizer` ではなく `visualizer`）。
**`429 Too Many Requests` が返る**
パブリックAPI にはレートリミットがあります。短時間に大量のリクエストを送信すると発生します。しばらく待ってから再試行してください。
**一覧に「Failed to load feedback」と表示される**
プロジェクトのパブリックAPI が有効になっているか、URL のモデルキーが正しいかを確認してください。
## 完了チェックリスト
[Section titled “完了チェックリスト”](#完了チェックリスト)
* [ ] Submit タブからフィードバックを送信できる
* [ ] CMS の Content 画面で、送信したフィードバックが下書き状態のアイテムとして確認できる
* [ ] CMS の管理画面からアイテムを公開できる
* [ ] All Feedback タブに、公開したフィードバックが一覧表示される
# 経路検索プラグインを作成する
> レイヤAPI・カメラAPI・外部の経路検索サービスを使って、2 地点間の経路を検索し地球儀上に描画するウィジェットを作成します。
[プラグインプレイグラウンド](https://visualizer.reearth.io/plugin-playground?plugin-id=my-plugin)を使って、2 地点間の経路を検索して地球儀上に描画するプラグインを作成します。ブラウザ上で完結するため、ローカル環境を用意する必要はありません。
## 作るもの
[Section titled “作るもの”](#作るもの)
経路検索ウィジェットは、2 地点間の経路を地球儀上に描画します。開始地点と終了地点は、座標を直接入力するか地図をクリックして指定します。徒歩・自転車・車のいずれかの移動手段を選ぶと、ウィジェットは外部の経路検索サービスを呼び出して経路を取得します。取得した経路は、クリックすると距離と所要時間を表示するクリック可能な線として描画されます。両端点にはマーカーが表示され、ボタンひとつですべてをクリアできます。
このウィジェットは、プラグインAPI の次の 4 つの部分を使用します。
* **UI と Visualizer 間の通信** — [`reearth.ui`](/ja/developer/plugin/api-reference/ui/) と [`reearth.extension`](/ja/developer/plugin/api-reference/extension/) を通じて、ウィジェットの iframe とプラグインロジックの間で双方向にデータをやり取りします
* **外部 API との連携** — `fetch` で経路検索サービスを呼び出し、レスポンスを GeoJSON に変換します
* **[レイヤAPI](/ja/developer/plugin/api-reference/layers/)** — 実行時にレイヤを追加・更新・検索・削除します
* **[カメラAPI](/ja/developer/plugin/api-reference/camera/)** — シーンの初期表示位置を設定します
## 前提条件
[Section titled “前提条件”](#前提条件)
* Re:Earth Visualizer のプロジェクト
* ブラウザのタブで開いた[プラグインプレイグラウンド](https://visualizer.reearth.io/plugin-playground?plugin-id=my-plugin)
* HTML・CSS・JavaScript の基礎知識。このガイドは、一般的な Web 開発ではなく Re:Earth プラグイン API について説明します。
はじめてプラグインを作成する場合は、先に「[プラグインプレイグラウンドで動かす](/ja/developer/plugin/get-started/run-in-plugin-playground/)」「[UI を表示する](/ja/developer/plugin/guides/display-ui/)」「[プラグインと Re:Earth の間で通信する](/ja/developer/plugin/guides/communicate-between-a-plugin-and-reearth/)」に取り組んでください。これらのガイドでは、プレイグラウンドの画面構成、`reearth.yml` マニフェスト、エクスポートとインストールの手順、そしてこのガイドでも使うメッセージのやり取りの方法を扱います。
## ステップ 1 — プラグインのファイルを開く
[Section titled “ステップ 1 — プラグインのファイルを開く”](#ステップ-1--プラグインのファイルを開く)
プレイグラウンドのファイルツリーの **Custom** セクションで、**My Plugin** を選択します。すでに `reearth.yml` マニフェストと `demo-widget` ファイルが含まれており、この 2 つのファイルを編集します。
## ステップ 2 — マニフェストを編集する
[Section titled “ステップ 2 — マニフェストを編集する”](#ステップ-2--マニフェストを編集する)
`reearth.yml` を開き、内容を 1 つのウィジェット拡張に置き換えます。
```yaml
id: route-search-plugin
name: Route Search
version: 1.0.0
extensions:
- id: demo-widget
type: widget
name: Route Search
description: Search and draw a route between two points
widgetLayout:
defaultLocation:
zone: outer
section: left
area: top
```
拡張の `id` は `demo-widget` のまま、既存の `demo-widget` ファイルと一致させます。拡張の id とファイル名は一致していなければなりません。プラグインの `id` には英小文字・数字・`_`・`-` を使用でき、スペースは使用できず、`reearth` は指定できません。同じ id のプラグインがすでにプロジェクトにあると、後のインストールが失敗するため、他と重複しない id を選んでください。
## ステップ 3 — ウィジェットの UI を作成する
[Section titled “ステップ 3 — ウィジェットの UI を作成する”](#ステップ-3--ウィジェットの-ui-を作成する)
`demo-widget` を選択し、内容を次のコードに置き換えます。`reearth.ui.show` は HTML 文字列を受け取り、iframe 内にウィジェットとして描画します。
```javascript
reearth.ui.show(`
`);
```
入力欄のプレースホルダーに表示されている `lng,lat` は経度・緯度を指します。以降も、コードに合わせて経度・緯度を `lng,lat` と表記します。
ウィジェットの動作は、この後の手順で `
```
iframe 内では、メッセージは `window.addEventListener("message", ...)` を通じて届きます。ピックモードが有効な間、座標は開始地点または終了地点の入力欄に書き込まれます。座標の順序は `lng,lat` で、これは経路検索サービスが想定する順序です。
📍 アイコンをクリックしてから地図をクリックすると、クリックした地点の座標が入力欄に表示されます。
## ステップ 6 — 選択した地点にマーカーを表示する
[Section titled “ステップ 6 — 選択した地点にマーカーを表示する”](#ステップ-6--選択した地点にマーカーを表示する)
選択した各地点のマーカーは、レイヤAPI で表示します。
### ウィジェットからマーカーをリクエストする
[Section titled “ウィジェットからマーカーをリクエストする”](#ウィジェットからマーカーをリクエストする)
`
`);
// ---------- プラグインロジック（Visualizer コンテキストで実行される） ----------
reearth.viewer.overrideProperty({
tiles: [
{
id: "osm",
type: "open_street_map",
},
],
});
reearth.viewer.on("click", (event) => {
const { lat, lng } = event;
if (lat === undefined || lng === undefined) return; // 空や何もない場所をクリックした場合
reearth.ui.postMessage({ type: "position", lat, lng });
});
let startMarkerId = null;
let endMarkerId = null;
let routeLayerId = null;
reearth.extension.on("message", (msg) => {
if (msg.action === "addMarkerLayer") {
const value = {
type: "FeatureCollection",
features: [
{ type: "Feature", properties: {}, geometry: { type: "Point", coordinates: [msg.lng, msg.lat] } },
],
};
const markerId = msg.pointName === "start" ? startMarkerId : endMarkerId;
if (markerId) {
reearth.layers.override(markerId, { data: { type: "geojson", value } });
} else {
const newId = reearth.layers.add({
type: "simple",
title: msg.pointName,
data: { type: "geojson", value },
marker: { pointColor: "blue", pointSize: 12, style: "point" },
});
if (msg.pointName === "start") startMarkerId = newId;
else endMarkerId = newId;
}
} else if (msg.action === "addRouteLayer") {
// 検索するたびに経路が積み重ならないよう、直前の経路を削除する
if (routeLayerId) reearth.layers.delete(routeLayerId);
routeLayerId = reearth.layers.add({
type: "simple",
title: "route",
data: { type: "geojson", value: msg.geojson },
infobox: {
blocks: [{ pluginId: "reearth", extensionId: "propertyInfoboxBetaBlock" }],
},
polyline: { strokeColor: "blue", strokeWidth: 2 },
});
} else if (msg.action === "deleteRouteAndMarkerLayer") {
if (routeLayerId) {
reearth.layers.delete(routeLayerId);
routeLayerId = null;
}
if (startMarkerId) {
reearth.layers.delete(startMarkerId);
startMarkerId = null;
}
if (endMarkerId) {
reearth.layers.delete(endMarkerId);
endMarkerId = null;
}
}
});
reearth.camera.setView({
lat: 35.68426,
lng: 139.71043,
height: 2000,
heading: 0,
pitch: -0.785,
roll: 0,
});
```
# シンプルな UI プラグインを作成してインストールする
> プラグインプレイグラウンドで Welcome ウィジェットを作成し、ZIP としてエクスポートし、Re:Earth Visualizer にインストールして、シーンに追加します。
プラグインプレイグラウンドにあらかじめ用意されたファイルを使って、Welcome ウィジェットを作成し、ビューアで実行し、ボタンでカメラを東京に移動させます。その後、同じウィジェットを ZIP ファイルとしてエクスポートし、Re:Earth Visualizer にインストールして、シーンに追加します。ローカルのセットアップは不要です。
## 作るもの
[Section titled “作るもの”](#作るもの)
完成した Welcome ウィジェットには短いメッセージと「Fly to Tokyo」ボタンが含まれます。ボタンをクリックすると、プラグインにメッセージが送信され、カメラが東京に移動してウィジェットのステータスメッセージが更新されます。完成したプラグインは ZIP ファイルとしてエクスポートされ、Visualizer プロジェクトにインストールされます。
## 前提条件
[Section titled “前提条件”](#前提条件)
* Re:Earth Visualizer のアカウントと、少なくとも 1 つの Visualizer プロジェクト
* モダンなデスクトップブラウザ
* HTML と JavaScript の基本的な知識
* ローカルの開発ツールは不要です
## ステップ 1 — プラグインプレイグラウンドを開く
[Section titled “ステップ 1 — プラグインプレイグラウンドを開く”](#ステップ-1--プラグインプレイグラウンドを開く)
[プラグインプレイグラウンド](https://visualizer.reearth.io/plugin-playground?plugin-id=my-plugin)は、Re:Earth Visualizer に組み込まれたブラウザベースのエディタです。ローカルに何もインストールせずに、プラグインを書いて、プレビューし、エクスポートできます。
1. Re:Earth Visualizer を開いてサインインします。
2. 左サイドバーの **エディター** → **プラグイン** に移動します。
3. **プラグインプレイグラウンド** をクリックしてエディターを開きます。
4. ファイルツリーの **Custom** セクションで **My Plugin** を選択します。すでに `reearth.yml` マニフェストとサンプルエクステンションファイルが含まれています。既存のマニフェストとウィジェットファイルを編集します。
## ステップ 2 — プラグインマニフェストを編集する
[Section titled “ステップ 2 — プラグインマニフェストを編集する”](#ステップ-2--プラグインマニフェストを編集する)
`reearth.yml` をクリックし、内容を以下に置き換えます：
```yaml
id: welcome-widget-plugin
name: Welcome Widget
version: 1.0.0
extensions:
- id: demo-widget
type: widget
name: Welcome
description: A simple welcome widget
widgetLayout:
defaultLocation:
zone: outer
section: left
area: top
```
Re:Earth プラグインには 1 つ以上のエクステンションを含めることができます。このチュートリアルでは、**ウィジェットエクステンション** — Visualizer のメインビューに表示されるユーザーインターフェースコンポーネント — を作成します。その位置はウィジェットアラインシステムで調整できます。マニフェストがエクステンションを宣言し、対応する JavaScript ファイルがその UI と動作を提供します。ここでは、エクステンション ID `demo-widget` が `demo-widget.js` に対応します。この名前は正確に一致させてください。
[プラグインの構造](/ja/developer/plugin/overview/plugin-structure/)と[エクステンションタイプの違い](/ja/developer/plugin/overview/extension-types/)について詳しく学ぶ。
マニフェストに **Welcome** という名前のウィジェットが宣言されました。エクステンション ID `demo-widget` は既存のファイル `demo-widget.js` と一致しています。ウィジェットが正しく動作するよう、これらの名前は正確に一致させてください。
## ステップ 3 — ウィジェットのコードを編集する
[Section titled “ステップ 3 — ウィジェットのコードを編集する”](#ステップ-3--ウィジェットのコードを編集する)
`demo-widget.js` を選択してコードパネルで開きます。JavaScript エディターでコードを編集してください。ライブプレイグラウンドでは、このファイルの **HTML エディター** コントロールが無効になっています。
その内容を以下に置き換えます：
```javascript
const html = `
👋 Welcome
Click the button to fly to Tokyo.