【Googleスプレッドシート】Apps Scriptで日付を「2025-03-15」形式にフォーマット!Utilities.formatDate

スプレッドシートで日付を扱う際、セルの書式設定では表現できない特定の形式に変換したいとお考えではありませんか。たとえば「2025-03-15」のようなISO形式の日付文字列が必要になることがあります。そんなときに役立つのが、Apps Scriptに組み込まれたUtilities.formatDate関数です。この記事では、同関数の基本的な使い方から応用テクニックまでをわかりやすく解説します。スクリプトの記述に不安がある方でも、コピー&ペーストで使えるサンプルコードを用意していますので、ご安心ください。

Utilities.formatDateの動作を理解する

Utilities.formatDateは、JavaScriptのDateオブジェクトを指定した書式の文字列に変換するGoogle Apps Scriptのユーティリティ関数です。第一引数に日付オブジェクト、第二引数にタイムゾーン(例:”JST”)、第三引数にフォーマットパターン(例:”yyyy-MM-dd”)を指定します。フォーマットパターンはJavaのSimpleDateFormatに準拠しており、主なパターン文字として「yyyy」が4桁の年、「MM」が2桁の月(01〜12)、「dd」が2桁の日(01〜31)、「HH」が24時間制の時(00〜23)、「mm」が分(00〜59)、「ss」が秒(00〜59)があります。タイムゾーンを正しく設定しないと、日付がずれる原因になりますので注意が必要です。

日付を「yyyy-MM-dd」形式に変換する手順

基本的なサンプルコードの実行

1. スクリプトエディタを起動する
   対象のスプレッドシートを開き、メニューバーから「拡張機能」→「Apps Script」を選択します。新しいタブでスクリプトエディタが開きます。
2. サンプルコードを記述する
   エディタに以下のコードを入力します。

   function formatDateAsISO() {
     var date = new Date();
     var formattedDate = Utilities.formatDate(date, 'JST', 'yyyy-MM-dd');
     Logger.log(formattedDate);
   }

   このコードは現在の日時を取得し、日本時間でyyyy-MM-dd形式の文字列に変換してログに出力します。

3. スクリプトを実行する
   ツールバーの実行ボタン(▶)をクリックして関数を実行します。初回は承認が必要な場合があります。表示されるダイアログに従って許可してください。
4. ログを確認する
   メニュー「表示」→「ログ」を開くと、変換された日付文字列が表示されます。期待した形式になっているか確認しましょう。

シート上の日付を一括変換する

1. アクティブシートの範囲を取得する
   以下のコードでは、A2:A10の範囲に日付が入っていると仮定します。getActiveSheet().getRange()で範囲を指定します。
2. 各セルの日付をフォーマットする
   ループ処理で各セルのDate値を取得し、Utilities.formatDateで変換します。変換後の文字列をB列に出力する例を示します。

   function formatDateRange() {
     var sheet = SpreadsheetApp.getActiveSheet();
     var range = sheet.getRange("A2:A10");
     var dates = range.getValues();
     var formatted = [];
     for (var i = 0; i < dates.length; i++) {
       var date = dates[i][0];
       if (date instanceof Date) {
         formatted.push([Utilities.formatDate(date, Session.getScriptTimeZone(), 'yyyy-MM-dd')]);
       } else {
         formatted.push(['']);
       }
     }
     sheet.getRange("B2:B10").setValues(formatted);
   }

   Session.getScriptTimeZone()はスプレッドシートのタイムゾーン設定を自動で取得するため、タイムゾーンの指定ミスを防げます。

3. 実行して結果を確認する
   関数を実行すると、B2:B10に変換された日付文字列が入力されます。

使用時の注意点とよくあるトラブル

タイムゾーンの指定を忘れると日付がずれる

Utilities.formatDateの第二引数にタイムゾーンを正しく指定しないと、スクリプトのサーバー時間(UTC)で計算されるため、日本時間と異なる日付になる可能性があります。常に"JST"またはSession.getScriptTimeZone()を使用することを推奨します。

フォーマットパターンの大文字小文字に注意する

パターン"yyyy"は年、"MM"は月、"dd"は日です。"mm"は分を意味するため、間違えないようにしましょう。例えば"yyyy-mm-dd"と書くと、月ではなく分が表示されてしまいます。

シート上の日付が文字列の場合の対処

シート上の日付が文字列として入力されている場合、new Date()で変換できないことがあります。その場合は、事前に文字列を日付オブジェクトに変換する処理が必要です。例:var date = new Date(cellValue); ただし、セルの書式が日付になっていれば自動的にDateオブジェクトとして取得できます。

日付が空欄の場合のエラーハンドリング

範囲内に空欄や数値など日付以外の値が含まれていると、Utilities.formatDateがエラーを起こします。サンプルコードではinstanceof Dateでチェックしていますが、さらにisNaN(date.getTime())などで妥当性を検証するとより安全です。

Utilities.formatDateとセルの書式設定の比較

まとめ

この記事では、Apps ScriptのUtilities.formatDate関数を使って日付を「yyyy-MM-dd」形式に変換する方法をご紹介しました。基本的な構文の理解と、シート上の日付を一括変換するサンプルコードを提供しました。タイムゾーンとフォーマットパターンに注意すれば、自由自在に日付文字列を生成できます。応用として、ファイル名やメール本文に日付を埋め込む処理にも活用できます。ぜひ実際のスクリプトに組み込んでみてください。