導入
JavaScriptで日付を扱う際、サーバーとの通信やタイムゾーンを考慮した処理で「時刻がずれる」という経験はありませんか?多くの場合、その原因はブラウザのローカル時刻に基づいたメソッドを使用していることにあります。今回解説する Date.prototype.setUTCHours は、協定世界時(UTC)を基準に時間を設定するためのメソッドです。これを使うことで、タイムゾーンに依存しない、正確で予測可能な時刻計算が可能になります。
基礎知識
JavaScriptの Date オブジェクトには、大きく分けて「ローカル時間(実行環境のタイムゾーン)」と「UTC(世界標準時)」を操作する2系統のメソッドが存在します。
例えば、`setHours()` を使うとPCのローカル時刻で変更されますが、`setUTCHours()` を使うと、PCの設定に関わらず「UTC基準」で時間が更新されます。API連携などで「常にグリニッジ標準時でデータを扱いたい」という場面において、このメソッドは非常に重要です。
実装/解決策
setUTCHours メソッドは、第1引数に「時」を指定し、オプションで「分」「秒」「ミリ秒」を続けて指定できます。
構文:`dateObj.setUTCHours(hoursValue[, minutesValue[, secondsValue[, msValue]]])`
このメソッドを実行すると、対象の Date オブジェクトの内部値が変更されると同時に、その変更後のタイムスタンプ(ミリ秒単位の数値)が戻り値として返されます。これにより、メソッドチェーンや計算結果の即時利用が可能です。
サンプルプログラム
以下のコードは、ある特定のUTC時刻を作成し、そこから時間を設定し直す一例です。
// 現在の時刻をUTCで取得
const date = new Date();
// UTC基準で「15時30分0秒」に設定する
// 第1引数:時, 第2引数:分, 第3引数:秒
date.setUTCHours(15, 30, 0);
// 結果を表示(ブラウザのローカル環境に合わせて変換された文字列が出力されます)
console.log("設定後のUTC時間:", date.toUTCString());
// 応用: 既存の時刻から「+5時間」する処理
const currentHours = date.getUTCHours();
date.setUTCHours(currentHours + 5);
console.log("5時間追加後のUTC時間:", date.toUTCString());
応用・注意点
注意点1:ミュータブルな挙動
Date オブジェクトはミュータブル(変更可能)です。`setUTCHours` を実行すると、元のオブジェクト自体が書き換わります。もし元の値を保持したい場合は、一度 `new Date(originalDate.getTime())` のようにコピーを作成してから操作するようにしてください。
注意点2:日付の繰り越し
`setUTCHours` は非常に賢く設計されています。例えば、23時の状態で「+2時間」を設定すると、自動的に日付が翌日に繰り上がります。この仕様は便利ですが、カレンダーアプリなどで意図せず日付が変わってしまうバグになりやすいため、境界値のテストは必ず行うようにしましょう。
フロントエンド開発において、UTCを正しく制御することは、グローバルなユーザー体験を守るための第一歩です。ぜひ活用してください。