Get to know MDN better
このページはコミュニティーの尽力で英語から翻訳されました。MDN Web Docs コミュニティーについてもっと知り、仲間になるにはこちらから。
This feature is not Baseline because it does not work in some of the most widely-used browsers.
Experimental: これは実験的な機能です。
本番で使用する前にブラウザー互換性一覧表をチェックしてください。
Temporal オブジェクトは、組み込みのタイムゾーンおよび暦の表現、実時刻の変換、算術演算、書式化など、さまざまなシナリオで日付と時刻の管理を可能にします。これは、 Date オブジェクトを完全に置き換えるものとして設計されています。
ほとんどのグローバルオブジェクトとは異なり、 Temporal はコンストラクターではありません。 new 演算子と一緒に使用したり、 Temporal オブジェクトを関数として呼び出したりすることはできません。 Temporal のすべてのプロパティとメソッドは静的です（Math オブジェクトと同様）。
Temporal は複雑で強力な API を備えています。複数のクラスを通じて 200 以上のユーティリティメソッドを公開しているため、とても複雑に見えるかもしれません。これらの API が互いにどのように関連しているかを、概要で説明します。
JavaScript には、その誕生当初から日付と時刻を処理するための Date オブジェクトが存在していました。しかし、Date API は、設計が良くなく 2010 年代初頭に置き換えられた Java の java.util.Date クラスをベースにしています。ただ、JavaScript は下位互換性を重視しているため、Date はこの言語に残っています。
この紹介の冒頭で重要なことは、日付の処理は複雑であるということです。Date の問題のほとんどは、メソッドを追加することで解決できますが、根本的な設計上の欠陥は残っています。つまり、同じオブジェクトにあまりにも多くのメソッドが公開されているため、開発者はどれを使用すべきか迷うことが多く、予期せぬ問題が発生しやすいのです。よく設計された API は、より多くのことを行う必要があるだけでなく、各抽象化レベルで行うことを少なくする必要があります。なぜなら、誤用を防ぐことは、用途を拡大することと同じくらい重要だからです。
Date オブジェクトは 2 つの役割を同時に果たします。
タイムゾーンは、日付関連のバグの多くの根底にあります。「成分の組み合わせ」モデルで Date を操作する場合、時刻は UTC とローカル （端末） の 2 つのタイムゾーンしか指定できず、任意のタイムゾーンを指定する方法がありません。また、「タイムゾーンがない」という概念も持っていません。これは、カレンダーの日付 （日付の場合） または壁掛け時計の時刻 （時刻の場合） として知られており、「カレンダーや時計で読み取る」時刻です。例えば、毎日の目覚ましアラームを設定する場合、夏時間であるかどうか、別のタイムゾーンに移動しているかどうかに関係なく、「午前 8 時」に設定したいでしょう。
Date に欠けている 2 つ目の機能は、暦体系です。ほとんどの人は、西暦と紀元前という 2 つの時代があり、12 か月があり、各月の日数は異なり、4 年に 1 回は閏年がある、といったグレゴリオ暦に慣れているでしょう。しかし、ヘブライ暦、中国の旧暦、日本の旧暦など、別の暦体系を使用している場合、これらの概念の一部は適用されない場合があります。Date では、グレゴリオ暦のモデルしか使用できません。
Date には、すべてのセッターが変更可能である （これは多くの場合、望ましくない副作用を引き起こします）、日付と時刻の文字列形式を一貫した方法で解釈できない、など、他にも多くの望ましくない古い部分があります。結局、最善の解決策は、新しい API を一から構築することであり、それが Temporal です。
Temporal は Intl と同様に名前空間です。これには、日付および時刻の管理の特定の側面を処理するように設計された、いくつかのクラスおよび名前空間が含まれています。クラスは次のようにグループ化できます。
さらに、 Temporal.Now という別のユーティリティ名前空間もあり、さまざまな形式で現在の時刻を取得するメソッドを提供しています。
Temporal 名前空間には多数のクラスがいますが、これらのクラスは多くの似たメソッドを共有しています。次の表は、各クラスのすべてのメソッド（変換メソッドを除く）を一覧表示したものです。
次の表は、各クラスで利用できるプロパティをまとめたもので、各クラスが表す情報の意味を把握するのに役立ちます。
以下の表は、各クラスに存在するすべての変換メソッドをまとめたものです。
| 変換元 | ||||||||
| 変換先 | Instant/ | toInstant() | まず ZonedDateTime へ変換 | |||||
| toZonedDateTimeISO() | / | toZonedDateTime() | toZonedDateTime() | PlainDate#toZonedDateTime() （引数として渡す） | まず PlainDate へ変換 | |||
| まず ZonedDateTime へ変換 | toPlainDateTime() | / | toPlainDateTime() | PlainDate#toPlainDateTime() （引数として渡す） | ||||
| toPlainDate() | toPlainDate() | / | 情報に対応するものがない | toPlainDate() | toPlainDate() | |||
| toPlainTime() | toPlainTime() | 情報に対応するものがない | / | 情報に対応するものがない | ||||
| まず PlainDate へ変換 | toPlainYearMonth() | 情報に対応するものがない | / | まず PlainDate へ変換 | ||||
| toPlainMonthDay() | まず PlainDate へ変換 | / | ||||||
これらの表で、 Temporal API の基本的な考え方が理解できると思います。
暦は、通常、週、月、年、時代などの期間に日を整理する方法です。世界の大半はグレゴリオ暦を使用していますが、特に宗教的および文化的な文脈では、他にも多くの暦が使用されています。既定では、暦を認識するすべての Temporal オブジェクトは、グレゴリオ暦をベースとし、週の番号付けに関する追加の規則を定義する ISO 8601 暦体系を使用します。 Intl.supportedValuesOf() には、ブラウザーで対応している可能性の高い暦のほとんどが掲載されています。ここでは、暦体系がどのように構成されているかを簡単に説明し、暦同士で異なる成分を内部的に理解しやすくします。
地球上には 3 つの顕著な周期的なイベントがあります。それは、太陽の周りを回る回転（1 回転は 365.242 日）、月が地球の周りを回る回転（新月から新月まで 29.53 日）、そして自転（日の出から日の出まで 24 時間）です。すべての文化では、「1 日」は 24 時間という同じ単位で測定されます。夏時間などの一時的な変更は、暦には属しません。これらはタイムゾーンの情報の一部です。
Temporal では、1 つの暦体系におけるすべての日付は、year、month、day の 3 つの成分によって一意に識別されます。 year は通常、正の整数ですが、0 または負の値も取り、時間とともに単調に増加します。1 の年（または、存在する場合 0）は、暦の元期として知られており、暦ごとに任意に設定されます。month は 1 から始まり、date.monthsInYear で終わり、年が改まると 1 にリセットされる、1 回ごとに 1 ずつ増加する正の整数です。day も正の整数ですが、政治的な変更によって日がスキップされたり繰り返されたりする場合があるため、1 から開始したり、毎回 1 ずつ増加したりしない場合があります。しかし、一般的には、day は単調に増加し、月が改まるとリセットされます。
year に加えて、時代を使用する暦では、era と eraYear の組み合わせによって、年を固有に識別することもできます。例えば、グレゴリオ暦では "CE" (Common Era) と "BCE" (Before Common Era) という時代が使用されており、年 -1 は { era: "bce", eraYear: 2 } と同じです（なお、年 0 はすべての暦に存在します。グレゴリオ暦では、これは天文学的紀年法のため 1 BCE に対応します）。 era は小文字の文字列で、eraYear は 0 または負の任意の整数で、時点とともに減少する場合もあります （通常は最も古い時代の場合）。
メモ: era と eraYear は常にペアで使用してください。一方のプロパティだけを使用しないでください。また、競合を避けるため、年を指定する際に year と era/eraYear を組み合わせて使用しないでください。1 つの年表現を選択し、それを一貫して使用してください。
年に関する次の誤った仮定に注意してください。
month に加えて、1 年間の月は monthCode によって一意に識別することもできます。monthCode は通常、月の名前に割り当てられますが、month はそうではありません。例えば、太陰太陽暦の場合、同じ monthCode を持つ 2 つの月があり、一方は閏年に属し、もう一方は閏年に属さない場合、閏月の後に続く 2 つの月の month 値は、閏月の挿入により、異なる値になります。
メモ: 競合を避けるため、月を指定する際に month と monthCode を組み合わせないでください。 1 つの月を表す表記法を選び、それを一貫して使用してください。 month は、1 年間の月の順番が必要なとき（たとえば、月をループする場合など）に、 monthCode は、月の名前が必要なとき（たとえば、誕生日を格納する場合など）に、それぞれより有用です。
月に関する次の誤った仮定に注意してください。
day （月ベースのインデックス） に加えて、1 年の中の 1 日は dayOfYear によって一意に識別することもできます。dayOfYear は、1 から始まり、date.daysInYear で終わる、1 ずつ増加する正の値です。
「週」という概念は、天文学的なイベントとは関係なく、文化的に構築されたものです。最も一般的な長さは 7 日間ですが、週は 4、5、6、8 日、あるいはそれ以上、あるいは固定の日数がない場合もあります。ある日付のある週の具体的な日数を取得するには、その日付の daysInWeek を使用します。Temporal は、weekOfYear と yearOfWeek の組み合わせによって週を識別します。weekOfYear は、1 から始まり、年が進むごとに 1 ずつ増加する正の整数です。yearOfWeek は通常 year と同じですが、1 週間が 2 年にまたがる場合があり、yearOfWeek は暦の規則に基づいて 2 年のうちどちらか一方を選択するため、各年の開始または終了時に異なる場合があります。
メモ: weekOfYear と yearOfWeek は常にペアで使用してください。weekOfYear と year の組み合わせでは使用しないでください。
週に関する次の誤った仮定に注意してください。
すべての Temporal クラスは、 ISO 8601 / RFC 3339 に基づく RFC 9557 で指定されている書式を使用して、シリアル化およびデシリアル化することができます。この書式の完全な形式は次のとおりです（空白は読みやすさのためにのみ使用されており、実際の文字列には存在しません）。
YYYY-MM-DD T HH:mm:ss.sssssssss Z/±HH:mm [time_zone_id] [u-ca=calendar_id]クラスによって、各成分の存在に関する要件が異なるため、各クラスのドキュメント内に「RFC 9557 の書式化」という節があり、そのクラスが認識する書式化が指定されています。
これは、ISO 8601 にも基づいている Date で使用されている日付と時刻の文字列の書式とよく似ています。主な追加機能は、マイクロ秒およびナノ秒の成分を指定できることと、タイムゾーンおよび暦体系を指定できることです。
特定の暦の日付を表すすべての Temporal オブジェクトは、表現可能な日付の範囲に同様の制限を課します。この制限は、Unix 元期から ±108 日 （包括的） または -271821-04-20T00:00:00 から +275760-09-13T00:00:00 までの瞬間です。これは、有効な日時と同じ範囲です。より具体的には、次のとおりです。
Temporal オブジェクトは、この制限を超える日付/時刻を表すインスタンスの構築を拒否します。これには以下が含まれます。
2 つの時点間の差を表します。日付/時刻の演算で使用できます。基本的には、年、月、週、日、時、分、秒、ミリ秒、マイクロ秒、ナノ秒の値の組み合わせとして表されます。
Temporal.Instantナノ秒の精度で、固有の時点を表します。これは基本的に、タイムゾーンや暦体系を使用せずに、 Unix 元期（1970 年 1 月 1 日午前 0 時、UTC）からのナノ秒の数として表されます。
Temporal.Nowさまざまな書式で現在の時刻を取得するメソッドを提供します。
Temporal.PlainDate暦の日付（時刻やタイムゾーンを含まない日付）を表します。例えば、どのタイムゾーンで発生しても 1 日中続く暦上のイベントなどです。基本的には、年、月、日フィールドと関連付けられた暦体系を含む ISO 8601 暦日付として表されます。
Temporal.PlainDateTimeタイムゾーンのない日付（暦日）および時刻（壁時計の時間）を表します。基本的には、日付（関連付けられた暦体系付き）と時刻の組み合わせとして表されます。
Temporal.PlainMonthDay年やタイムゾーンを含まない、暦の日付の月と日を表します。例えば、毎年繰り返し、1 日中に現れる暦上のイベントなどです。これは基本的に、年、月、日フィールドと関連付けられた暦体系を含む ISO 8601 の暦の日付として表されます。年は、ISO 以外の暦体系で月と日を明確にするために使用されます。
Temporal.PlainTime日付やタイムゾーンを含まない時点を表します。例えば、毎日同じ時間に現れる繰り返しイベントなどです。基本的には、時、分、秒、ミリ秒、マイクロ秒、ナノ秒の値の組み合わせとして表されます。
Temporal.PlainYearMonth日やタイムゾーンを含まない、暦日の年と月を表します。例えば、1 か月間に現れる暦上のイベントなどです。基本的には、年、月、日フィールドと、関連付けられた暦体系を含む ISO 8601 暦日として表されます。日は、ISO 以外の暦体系で年と月を区別するために使用されます。
Temporal.ZonedDateTimeタイムゾーン付きの日付と時刻を表します。基本的には、瞬間、タイムゾーン、および暦体系の組み合わせとして表されます。
Temporal[Symbol.toStringTag][Symbol.toStringTag] プロパティの初期値は、文字列 "Temporal" です。このプロパティは、Object.prototype.toString() で使用されます。
| Temporal # sec-temporal-objects |
Enable JavaScript to view this browser compatibility table.
This page was last modified on 2026年4月23日 by MDN contributors.
Your blueprint for a better internet.
Visit Mozilla Corporation’s not-for-profit parent, the Mozilla Foundation.
Portions of this content are ©1998–2026 by individual mozilla.org contributors. Content available under a Creative Commons license.