メインコンテンツまでスキップ

日付の操作

TypeScript には、日付を操作するためのオブジェクトやメソッドが用意されているため、オフィススクリプトでも同様に取り扱うことができます。

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

日付を取得する​

標準で用意されている Date オブジェクトを呼び出すことで、日付を取得することができます。

引数を指定しなかった場合は、現在の日付が返却されます。

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

now.toLocaleDateString(); // 2024/1/1

/** 現在の日付 */
const now = new Date();

now.toLocaleDateString(); // 2022/3/16(現在の日付)

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

日付の加算・減算​

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 日から経過したミリ秒を受け取ることができます。

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

日付の差を求める
/** 現在の日付 */
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 オブジェクトが渡す前と同じである保証はありません。

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 オブジェクトを別の関数に渡す場合は、変更が加えられていないか注意する必要があります。