【JavaScript ECMAScript】Date::Date.prototype.setUTCFullYearインスタンスメソッドの使い方

Date.prototype.setUTCFullYear()メソッドは、Dateオブジェクトの年を協定世界時（UTC）に基づいて設定するメソッドです。このメソッドを使用することで、既存のDateオブジェクトの年を、必要に応じて月や日も同時に指定して変更できます。

このメソッドは、最大で3つの引数を受け取ります。最初の引数であるyearValueは必須で、設定したい年を整数で指定します。例えば、2024年を設定する場合は2024と記述します。2番目の引数であるmonthValueは省略可能で、0から11の整数で月を指定します（0が1月、1が2月、…、11が12月）。この引数を省略した場合、Dateオブジェクトの現在の月は変更されません。3番目の引数であるdateValueも省略可能で、1から31の整数で日付を指定します。この引数を省略した場合、Dateオブジェクトの現在の日付は変更されません。

引数に範囲外の値を指定した場合、JavaScriptは自動的に日付を調整します。例えば、13月を指定すると翌年の1月として扱われます。このメソッドは、設定が成功したDateオブジェクトのタイムスタンプ（1970年1月1日00:00:00 UTCからの経過ミリ秒数）を数値として返します。

特に注意すべき点は、このメソッドが時間をUTC基準で操作するということです。ローカルタイムではなく、世界中で共通の標準時であるUTCに基づいて年を設定しますので、タイムゾーンによる影響を考慮する必要がありません。ウェブアプリケーションなどでサーバーとの時刻同期を行う際や、タイムゾーンに依存しない日付操作が必要な場合に非常に役立ちます。

Copy
1const dateObject = new Date();
2dateObject.setUTCFullYear(2024, 0, 1);

yearValue, monthValue = undefined, dayValue = undefined

• yearValue: number: UTCの年を指定する数値
• monthValue: number = undefined: UTCの月を指定する数値 (0から11、省略時は現在の月)
• dayValue: number = undefined: UTCの日を指定する数値 (1から31、省略時は現在の月の日)

number

Date.prototype.setUTCFullYear() メソッドは、指定したUTC（協定世界時）における日付の年を設定します。このメソッドの戻り値は、1970年1月1日 00:00:00 UTC から、設定された日付までの経過ミリ秒数（数値）です。