reearth.timeline

更新日2026年8月4日

reearth.timeline 名前空間は、reearth 環境でタイムライン機能を管理・操作するためのメソッドとプロパティを提供します。時間ベースのデータやアニメーションを制御・監視・同期する必要があるシナリオ向けに設計されています。

プロパティ

startTime

startTime プロパティは、reearth 環境におけるタイムラインの開始点を表します。タイムラインが開始する時刻を定義するオプションの Date オブジェクトです。このプロパティは、プラグインが時間固有のデータやアニメーションを扱う必要がある場合に便利です。

構文

reearth.timeline.startTime?: Date;

`Date`

タイムラインの開始時刻を表す JavaScript Date オブジェクトです。startTime が定義されていない場合、タイムラインの開始時刻は関係ないか、動的に決定されます。

使用例

// 使用例: タイムラインの開始時刻を確認してログに出力する
if (reearth.timeline.startTime) {
  console.log("Timeline Start Time:", reearth.timeline.startTime.toISOString());
} else {
  console.log("Timeline Start Time is not set.");
}

stopTime

stopTime プロパティは、reearth 環境におけるタイムラインの終了点を表します。タイムラインが停止する時刻を定義するオプションの Date オブジェクトです。このプロパティは、プラグイン内で時間制限のあるデータやアニメーションを管理する際に便利です。

構文

reearth.timeline.stopTime?: Date;

`Date`

タイムラインの停止時刻を表す JavaScript Date オブジェクトです。stopTime が定義されていない場合、タイムラインに固定の終了点がないか、動的に決定されることを示している場合があります。

使用例

// 使用例: タイムラインの停止時刻を確認してログに出力する
if (reearth.timeline.stopTime) {
  console.log("Timeline Stop Time:", reearth.timeline.stopTime.toISOString());
} else {
  console.log("Timeline Stop Time is not set.");
}

currentTime

currentTime プロパティは、reearth 環境におけるタイムライン上の現在時刻を表します。タイムラインが進行するにつれて更新されるオプションの Date オブジェクトです。このプロパティは、プラグインのイベントやデータビジュアライゼーションをタイムラインの現在位置と同期させる際に便利です。

構文

reearth.timeline.currentTime?: Date;

`Date`

タイムライン上の現在時刻を表す JavaScript Date オブジェクトです。currentTime が定義されていない場合、タイムラインが初期化されていないか、現在非アクティブであることを示している場合があります。

使用例

// 使用例: タイムラインの現在時刻を確認してログに出力する
if (reearth.timeline.currentTime) {
  console.log(
    "Current Timeline Time:",
    reearth.timeline.currentTime.toISOString()
  );
} else {
  console.log("Current Timeline Time is not set.");
}

isPlaying

このプロパティは、タイムラインが現在再生中かどうかを示します。タイムラインの再生状態を反映するブール値です。このプロパティは、タイムラインのアニメーションやイベントを制御・監視する際に便利です。

構文

reearth.timeline.isPlaying?: boolean;

型 boolean

true：タイムラインは現在再生中です。
false：タイムラインは一時停止中です。

isPlaying が定義されていない場合、タイムラインが初期化されていないことを示している場合があります。

使用例

// 使用例 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

speed プロパティは、reearth 環境におけるタイムラインの再生速度を表します。タイムラインがリアルタイムに対してどれだけ速く進行するかを決定する数値です。このプロパティは、タイムラインに紐づいたアニメーションやデータ更新のペースを制御する際に便利です。

構文

reearth.timeline.speed?: number;

型 number

タイムラインの再生速度を表す数値です。例：1.0：リアルタイム再生、>1.0：リアルタイムより速い、<1.0：リアルタイムより遅い。speed が定義されていない場合、タイムラインの再生速度が設定または初期化されていないことを示している場合があります。

使用例

// 使用例 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

このプロパティは、タイムラインが時間を進行させるステップの種類を定義します。タイムラインが可変レート（時間に比例）で進むか、固定間隔で進むかを決定します。タイムラインに紐づいたデータやアニメーションの更新方法を制御する際に便利です。

構文

reearth.timeline.stepType?: "rate" | "fixed";

型 rate

タイムラインは可変レートで進行します。タイムラインは継続的に進み、進行速度は speed プロパティによって決定されます。

型 fixed

タイムラインは固定時間間隔（例：毎秒、毎分、毎時）で進行します。この種類は、離散的なステップや均等間隔の更新を持つタイムラインに最適です。

stepType が定義されていない場合、デフォルトのステップ種類はプラグインの設定または Reearth 環境によって異なる場合があります。

使用例

// 使用例 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

rangeType プロパティは、タイムラインが時間進行の範囲をどのように扱うかを定義します。タイムラインが定義された startTime と stopTime を超えて拡張できるか、特定の範囲内に制限されるかを決定します。このプロパティは、タイムラインに紐づいたアニメーションやイベントの動作を制御するために重要です。

構文

reearth.timeline.rangeType?: "unbounded" | "clamped" | "bounced";

型 unbounded

タイムラインは定義された startTime と stopTime を超えて拡張できます。境界を超えても無制限に進行できます。この種類は、継続的なアニメーションやデータ更新に便利です。

型 clamped

タイムラインは startTime と stopTime の範囲内に制限されます。開始時刻より前や停止時刻より後には進行できません。この種類は、時間制限のあるアニメーションやイベントに便利です。

型 bounced

タイムラインは startTime と stopTime の間で「バウンス」し、ループのような効果を生み出します。タイムラインが終端に達すると方向を逆転させ、開始点に向かって戻ります。この種類は、継続的なアニメーションやサイクルを作成する際に便利です。

rangeType が定義されていない場合、動作はタイムラインの設定にデフォルトするか、制限なしのままになる場合があります。

使用例

// 使用例 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'.");

メソッド

tick

tick メソッドは、タイムラインの現在のティック値を Date オブジェクトとして取得します。このメソッドは、アニメーションやプラグイン固有のイベントをタイムラインの進行と同期させる際に便利です。

構文

reearth.timeline.tick?: () => Date | undefined;

戻り値:

型 Date | undefined

"Date"：タイムライン上の現在のティック値を Date オブジェクトとして表します。
"undefined"：タイムラインが初期化されていないか非アクティブの場合、メソッドは undefined を返します。

使用例

// 使用例: 現在のティック値を取得してログに出力する
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

play メソッドは、タイムラインの再生を開始します。タイムラインが現在の状態から範囲を進行し始めるようにトリガーするために使用します。このメソッドは、アニメーション、時間ベースのデータビジュアライゼーション、またはユーザーによるタイムライン操作のシナリオに便利です。

構文

reearth.timeline.play?: () => void;

戻り値:

なし (void)。このメソッドは値を返さずに操作を実行します。

使用例

// 使用例: タイムラインを再生する
if (reearth.timeline.play) {
  reearth.timeline.play();
  console.log("Timeline playback started.");
} else {
  console.log("The play method is not available.");
}

pause

pause メソッドは、現在位置をリセットせずにタイムラインの再生を停止します。このメソッドは、タイムラインに紐づいたアニメーションや時間ベースの処理を一時的に停止し、後で同じ位置から再開できるようにする際に便利です。

構文

reearth.timeline.pause?: () => void;

戻り値:

なし (void)。このメソッドは値を返さずに操作を実行します。

使用例

// 使用例: タイムラインを一時停止する
if (reearth.timeline.pause) {
  reearth.timeline.pause();
  console.log("Timeline playback paused.");
} else {
  console.log("The pause method is not available.");
}

setTime

このメソッドを使用すると、タイムラインの開始・停止・現在時刻を設定できます。このメソッドは、アニメーションの同期や時間ベースのデータビジュアライゼーションの調整など、タイムラインの範囲と位置を動的に制御する際に便利です。

構文

reearth.timeline.setTime?: (time: Options) => void;

パラメータ

`time`

setTime メソッドの time オブジェクトを使用すると、タイムラインの3つの重要なポイントを定義できます。

型:

type Options = {
  start: Date | string;
  stop: Date | string;
  current: Date | string;
};

start: Date | string;：タイムラインの開始点を定義します。
stop: Date | string;：タイムラインの終了点を定義します。
current: Date | string;：タイムライン上の現在の時点を定義します。

戻り値:

なし (void)。このメソッドは値を返さずに操作を実行します。

使用例

// 使用例: カスタムタイムライン時刻を設定する
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

このメソッドを使用すると、タイムラインの再生速度を動的に調整できます。このメソッドは、タイムラインが範囲をどれだけ速く進行するかを制御し、アニメーションや時間ベースのデータビジュアライゼーションに柔軟性を提供します。

構文

reearth.timeline.setSpeed?: (speed: number) => void;

パラメータ

`speed`

型: number

タイムラインの再生速度を表す数値です。1.0：リアルタイム再生、>1.0：リアルタイムより速い（例：2.0 で2倍速）、<1.0：リアルタイムより遅い（例：0.5 で半速）。

戻り値:

なし (void)。このメソッドは値を返さずに操作を実行します。

使用例

// 使用例 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

setStepType メソッドを使用すると、タイムラインのステップ動作を動的に調整できます。タイムラインが可変レート（rate）で進むか、固定間隔（fixed）で進むかを制御します。アニメーションやデータ更新など、タイムラインの時間進行処理をカスタマイズする際に便利です。

構文

reearth.timeline.setStepType?: (stepType: "rate" | "fixed") => void;

パラメータ

`stepType`

ステップ動作を指定します。

型: "rate" | "fixed"

rate：タイムラインは時間に比例した可変レートで進行し、通常は再生速度（speed プロパティ）の影響を受けます。
fixed：タイムラインは固定時間間隔（例：毎秒、毎分、毎時）で進行します。

戻り値:

なし (void)。このメソッドは値を返さずに操作を実行します。

使用例

// 使用例 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

setRangeType メソッドを使用すると、タイムラインが時間進行の範囲をどのように扱うかを動的に定義できます。このメソッドは、タイムラインが定義された startTime と stopTime を超えて拡張できるか、その範囲内に制限されるか、またはループ効果を生み出しながら開始・停止時刻の間で「バウンス」するかを決定します。

構文

reearth.timeline.setRangeType?: (
  rangeType: "unbounded" | "clamped" | "bounced"
) => void;

パラメータ

`rangeType`

範囲の動作を指定します。

型: "unbounded" | "clamped" | "bounced"

unbounded：タイムラインは startTime と stopTime を超えて無制限に拡張できます。
clamped：タイムラインは定義された startTime と stopTime の範囲内に制限されます。
bounced：タイムラインは startTime と stopTime の間で「バウンス」し、ループのような効果を生み出します。

戻り値:

なし (void)。このメソッドは値を返さずに操作を実行します。

使用例

// 使用例 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'.");
  }
}

イベント

tick

tick イベントは、タイムラインの現在時刻が更新されるたびに発火します。これは通常、タイムラインが進行するか、手動で調整されたときにトリガーされます。

構文

reearth.timeline.on("tick", (event: Date) => void): void;

パラメータ

event: Date

tick イベント中のタイムラインの現在時刻を表す JavaScript Date オブジェクトです。

使用例

// タイムラインの現在時刻の各ティックをログに出力する
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

commit イベントは、ウィジェット、プラグイン、またはその他のタイムラインブロックからの更新など、アクションによってタイムラインが変更されるたびに発火します。

構文

reearth.timeline.on("commit", (event: TimelineCommitter) => void): void;

パラメータ

event: TimelineCommitter

タイムライン変更のソースと追加のメタデータを記述するオブジェクトです。

type TimelineCommitter = {
  source:
    | "widgetContext" // ウィジェット操作によるタイムライン変更
    | "pluginAPI" // プラグイン API を通じた変更
    | "storyTimelineBlock" // ストーリー内のタイムラインブロックによる変更
    | "storyPage"; // ストーリーページナビゲーションによってトリガーされた変更
  id?: string;
};

source: string：コミットアクションの起点を指定します。
id?: string：コミットのソースに対するオプションの識別子です。

使用例

// タイムラインが変更されたときにコミットのソースと 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.");
  }
});