コンテンツにスキップ

日付の操作

JavaScript(TypeScript)には、日付を操作するためのDateオブジェクトが標準で用意されており、オフィススクリプトでも同様に取り扱うことができます。

今回はオフィススクリプトを使って、日付の体系的な操作方法について、サンプルコードと併せて解説します。

new Date()で Date オブジェクトを作成することで、日付を取得することができます。

引数を指定しなかった場合は、現在の日時を表す Date オブジェクトが作成されます。

Dateオブジェクトの定義
/** 年・月・日を指定した日付 */
const date = new Date(2024, 0, 1);
date.toLocaleDateString(); // 2024/1/1
/** 現在の日付 */
const now = new Date();
now.toLocaleDateString(); // 2022/3/16(現在の日付)

月の範囲は 1 ~ 12 ではなく、0 ~ 11 であることに注意してください(0 が 1 月、11 が 12 月)。

なお、toLocaleDateStringの出力形式は実行環境のロケール(言語・地域の設定)によって異なります。サンプルのコメントは日本語環境での例です。

Date オブジェクトには、年月日、時分秒それぞれについて設定するメソッドが用意されています。

日付の加算・減算
/** 現在の日付 */
const now = new Date();
// 年の変更
now.setFullYear(now.getFullYear() + 1);
// 月の変更
now.setMonth(now.getMonth() + 1);
// 日の変更
now.setDate(now.getDate() - 1);
// 時間の変更
now.setHours(now.getHours() + 1);
// 分の変更
now.setMinutes(now.getMinutes() - 1);
// 秒の変更
now.setSeconds(now.getSeconds() - 1);

ここでもし繰り上がりが発生した場合は、自動的に上の単位に繰り上げて処理されます。

例えば、計算後の時間が 30 になった場合、自動的に翌日の 6 時として処理されます。

setMonthなどのメソッドは、指定した値で日付を組み立て、その日付が存在しない場合は繰り上げ(繰り下げ)た日付になります。日付や加える数を変えて、どのように日付が変わるかを確かめてみましょう。

date.setMonth(date.getMonth() + 1)

  1. 元の日付2024131
  2. setMonth(1) で指定した日付2024231存在しない日付
  3. 実際の日付202432
  • 月は 0 から数えるため、0 は 1 月を表します。
  • 2024 年 2 月は 29 日までのため、超えた 2 日分が翌月に繰り越されます。

日付や加える数を変えて、繰り上げのしかたを確かめてみましょう。

VBA のDateAdd関数のように、存在しない日付になる場合は月の末日に合わせる方法は、以下の記事で解説しています。

2 つの Date オブジェクトの差を求める

Section titled “2 つの Date オブジェクトの差を求める”

Date.getTimeメソッドを使用すると、1970 年 1 月 1 日 0 時 0 分 0 秒(UTC)から経過したミリ秒を受け取ることができます。

これを利用して、ミリ秒から日付の差を算出する方法が一般的です。

日付の差を求める
/** 現在の日付 */
const now = new Date();
/** 元旦 */
const gantan = new Date(now.getFullYear(), 0, 1);
/** 日付の差(ミリ秒) */
const difference = now.getTime() - gantan.getTime();
/** 日付の差(日) */
const differenceDays = Math.floor(difference / 1000 / 60 / 60 / 24);
console.log(`元旦から${differenceDays}日経過しました`);

Date オブジェクトは可変(ミュータブル)なオブジェクトです。

例えば、特定の関数に対して Date オブジェクトを引数として渡したとします。

その場合、関数の処理が完了した後、渡した Date オブジェクトが渡す前と同じである保証はありません。

Dateオブジェクトの可変性
function main(workbook: ExcelScript.Workbook) {
const now = new Date();
console.log(now.toLocaleDateString()); // 2022/3/16
changeMonth(now);
console.log(now.toLocaleDateString()); // 2022/1/16
}
function changeMonth(date: Date) {
date.setMonth(0);
}

上記のコードの場合、changeMonth 関数の実行前と後で、変数 now の値が変わっていることが分かります。

コードがシンプルなので、now がどこで変更されたのかすぐに特定できますが、プログラム全体が肥大化するにつれて、この特定が難しくなっていきます。

Date オブジェクトを別の関数に渡す場合は、変更が加えられていないか注意する必要があります。元の値を変更されたくない場合は、new Date(now.getTime())のように複製してから渡すと安全です。