日付の操作

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

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

日付を取得する

new 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 時として処理されます。

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())のように複製してから渡すと安全です。