LoginSignup
4
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

More than 1 year has passed since last update.

@access3151fq(ayame 113)

Temporal入門その1 ～ Temporalクラスの使い分けと相互変換について

Last updated at Posted at 2023-07-10

Temporalとは

Temporalとは、JavaScriptに導入が予定されている(2023年時点)、Date型に代わる新しい日付処理APIです。
https://tc39.es/proposal-temporal/docs/index.html

現在TC39のStage 3で、仕様策定に関する議論が行われています。 https://github.com/tc39/proposal-temporal

従来のDate型の問題点を解消しており、タイムゾーンやサマータイムに関する処理も行うことができるようになっています。

Temporalのクラス

従来のDate型は、new Date()のようにDate型のインスタンスを作成して使用していました。
Temporalには以下の11個のクラスがあり、それぞれ用途によって使い分ける必要があります。

  • Temporal.Now
  • Temporal.Instant
  • Temporal.ZonedDateTime
  • Temporal.PlainDate
  • Temporal.PlainTime
  • Temporal.PlainDateTime
  • Temporal.PlainYearMonth
  • Temporal.PlainMonthDay
  • Temporal.Duration
  • Temporal.TimeZone
  • Temporal.Calendar

時刻を表すクラス

Temporalで時刻を表すには、以下の3タイプのクラスを利用します。

クラス名 役割
Temporal.Instant Unix Timeに相当する。カレンダー情報やタイムゾーン情報を持たない、ただの時刻。(Exact Timeと呼ばれる)
単純な時刻の足し算や引き算に使う。
Temporal.PlainDateTime(年月日時分秒)
Temporal.PlainDate(年月日のみ)
Temporal.PlainTime(時分秒のみ)
Temporal.PlainYearMonth(年月のみ)
Temporal.PlainMonthDay(月日のみ)		 カレンダー情報を扱うことができるクラス。曜日やうるう年を考慮した日付処理を行うことができる。(Wall-clock timeと呼ばれる)
Temporal.ZonedDateTime カレンダー情報とタイムゾーン情報を持っている時刻。サマータイムを考慮した処理ができる。

これらのクラスを使用するには、それぞれ以下のようにfrom()メソッドでインスタンスを生成します。

// Temporal.Instant型
const instant = Temporal.Instant.from('2019-03-30T00:45Z');
// or
const instant = Temporal.Instant.fromEpochSeconds(1553906700); // unix time(秒)からの変換
// or
const instant = Temporal.Instant.fromEpochMilliseconds(1553906700 * 1000); // unix time(ミリ秒)からの変換

// Temporal.PlainDateTime型
//   (その他のTemporal.PlainXXX型も同様)
const plainDateTime = Temporal.PlainDateTime.from('1995-12-07T03:24:30');
// or
const plainDateTime = Temporal.PlainDateTime.from({
  year: 1995,
  month: 12,
  day: 7,
  hour: 3,
  minute: 24,
  second: 30,
  millisecond: 0,
  microsecond: 3,
  nanosecond: 500
});

// Temporal.ZonedDateTime型
const zonedDateTime = Temporal.ZonedDateTime.from("2020-08-05T20:06:13+09:00[Asia/Tokyo][u-ca=japanese]");
// or
const zonedDateTime = Temporal.ZonedDateTime.from({
  timeZone: "Asia/Tokyo",
  year: 2023,
  month: 4,
  day: 8,
  hour: 22,
  minute: 34,
  second: 18,
  millisecond: 4,
  microsecond: 2,
  nanosecond: 1,
});

Temporal.ZonedDateTimeは一番保持できる情報量が多く、他の型への変換も可能な便利なクラスです。
ただし、日付を扱う上で、全ての処理でタイムゾーンの情報が得られるわけではありません。また、そもそも処理にタイムゾーン情報が必要ない場合もあるでしょう。

どのクラスを使うべきかは、おそらく以下のような手順で判断すればいいと思います。

  1. Unix Timeで表せるような単純な日付時刻（例：「2005年6月12日14時26分」）の和や差を求めたいだけの場合、Temporal.Instantを使う
  2. 「翌月の日付」や「先週の同じ曜日の日付」など、カレンダーに基づいた処理を行いたい場合、Temporal.PlainXXXを使う
  3. サマータイムや、別のタイムゾーンとの比較など、より詳細な情報が必要な場合はTemporal.ZonedDateTimeを使う

また、Temporal.Instantは、従来使われていたDate型との間で相互に変換することもできます。

// Date型からTemporal.Instant型に変換
const date = new Date();
date.toTemporalInstant(); //=> Temporal.Instant型

// Temporal.Instant型からDate型に変換
const instant = Temporal.Now.instant();
new Date(instant.epochMilliseconds); // Date型

Temporalのそれぞれのクラスは相互に変換することができます。
どのクラスがどのクラスに変換できるかを示したのが、以下の図です。

この図を載せたかっただけです。

その他のクラス

現在時刻を取得するTemporal.Now

Temporal.Nowには現在時刻を取得するためのメソッドが含まれています。

Temporal.Now.timeZoneId(); // 現在のシステム設定のタイムゾーン (例："Asia/Tokyo")
Temporal.Now.instant(); // 現在時刻が入ったTemporal.Instant型
Temporal.Now.plainDateTimeISO(); // 現在時刻が入ったTemporal.PlainDateTime型
Temporal.Now.plainDateISO(); // 現在時刻が入ったTemporal.PlainDate型
Temporal.Now.plainTimeISO(); // 現在時刻が入ったTemporal.PlainTime型
Temporal.Now.zonedDateTimeISO(); // 現在時刻が入ったTemporal.ZonedDateTime型
「時間」を表すTemporal.Duration

Temporal.Durationは、時刻ではなく時間を表します。

// 1年と1日という「期間」を表す
const duration = Temporal.Duration.from({ years: 1, days: 1 });

// 符号を反転する（この場合はマイナス1年とマイナス1日になる）
duration.negated();
// 符号(-1なら負、0なら0時間0分0秒、1なら正)
duration.sign;
// 絶対値を取る
duration.abs();
// Temporal.Duration同士の足し算
duration.add(Temporal.Duration.from({ days: 1 }));
// Temporal.Duration同士の引き算
duration.subtract(Temporal.Duration.from({ days: 1 }));
// 1日は24時間
Temporal.Duration.from({ days: 1 }).total({ unit: 'hour' }); //=> 24

単体で使われることはあまりありませんが、時刻の足し算や引き算で使用されます。

Temporal.TimeZone / Temporal.Calendar

タイムゾーン情報やカレンダー情報を扱いたい時に使用します。
通常は使用することは無いでしょう。

まとめ

  • Temporal APIには用途別に11個のクラスが存在する
  • 日付や時刻を表すには主に3種類のクラスを使い分ける
    • Temporal.Instant：Unix Timeのような、単なる日時を表す
    • Temporal.PlainXXX系：カレンダー上の日付を表す。1週間後の日付や1か月前の日付を求めたり、カレンダーを作成するなど曜日情報が欲しいときに使う
    • Temporal.ZonedDateTime：タイムゾーン情報が必要な時に使う
  • その他の補助的なクラス
    • Temporal.Now：現在時刻を取得するのに使う
    • Temporal.Duration：時間を表す
    • Temporal.TimeZone / Temporal.Calendar：タイムゾーン情報やカレンダー情報

以上、Temporal APIではどのようなクラスが使用できるのかの紹介でした。

次の記事では実際にTemporalオブジェクトを操作して日付処理を行ってみます。

また、Temporalオブジェクトと文字列の間の変換方法についても紹介しています。

4
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
4
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?