Google Apps Script中Google表格日期格式化指南

引言

在Google Apps Script中处理Google表格时，日期格式化是一个常见且重要的操作。由于Google表格存储日期的方式与常规字符串不同，开发者经常需要在脚本中对日期进行格式化，以满足报表生成、数据导出或用户界面显示的需求。本文将详细介绍如何使用Google Apps Script对Google表格中的日期进行格式化，包括核心方法、模式说明以及实际案例。

理解Google表格中的日期数据

Google表格中的日期实际上是以序列号形式存储的，即一个整数代表自1900年1月1日以来的天数（注意：Google表格使用1900年日期系统，包含一个错误的1900年2月29日）。当您通过脚本读取单元格值时，会得到一个JavaScript的Date对象，或者直接是一个数字。为了在输出时展现为可读的日期字符串，必须进行格式化。

例如，读取一个单元格：

var sheet = SpreadsheetApp.getActiveSheet();
var cell = sheet.getRange("A1");
var value = cell.getValue();  // 可能是一个Date对象或数字

使用Utilities.formatDate()方法

Google Apps Script提供了内置的Utilities.formatDate()方法来格式化日期。该方法是处理日期格式化的首选方式。

基本语法

var formattedDate = Utilities.formatDate(date, timeZone, format);

• date : 要格式化的Date对象。

• timeZone : 时区字符串，例如 "GMT"、"America/New_York"、"Asia/Shanghai"。推荐使用Session.getScriptTimeZone()获取当前脚本的时区。

• format : 格式化模式字符串，遵循Java SimpleDateFormat规范（因为Apps Script底层基于Java的SimpleDateFormat）。

格式化模式说明

常用模式字符（部分）：

注意：模式区分大小写，例如MM表示数字月份，mm表示分钟。

示例：将当前日期格式化为"2024-02-05"格式：

var now = new Date();
var timeZone = Session.getScriptTimeZone();
var formatted = Utilities.formatDate(now, timeZone, "yyyy-MM-dd");
Logger.log(formatted); // 输出类似 "2024-02-05"

设置单元格格式为日期文本

除了格式化输出到日志或字符串，有时您需要将格式化后的日期写回到Google表格单元格中。请注意，如果您直接写入格式化字符串（如"2024-02-05"），该单元格将变为文本类型，而非日期类型。这意味着无法再进行日期计算或排序。若希望保持日期类型但显示特定格式，应使用单元格数字格式（NumberFormat），而不是写入格式化字符串。

设置单元格数字格式的方法：

var range = sheet.getRange("B1");
range.setValue(new Date()); // 写入当前日期
range.setNumberFormat("yyyy-MM-dd"); // 设置显示格式

这样，单元格值为日期类型，显示为"2024-02-05"，但底层仍是序列号，可用于计算。

将字符串解析为日期

当您从外部源（如CSV文件或用户输入）获取日期字符串时，需要将其解析为Date对象后再处理。Google Apps Script没有直接的日期解析函数，但可以利用new Date()构造函数或手动拆分字符串。

示例：将"2024-02-05"字符串转换为Date对象：

var dateStr = "2024-02-05";
var parts = dateStr.split("-");
var dateObj = new Date(parts[0], parts[1] - 1, parts[2]); // 月份从0开始
Logger.log(dateObj); // Tue Feb 05 2024 00:00:00 GMT+...

更稳健的方法推荐使用Utilities.parseDate()（如果环境支持，但官方推荐手动解析或使用Moment.js库的等效方法，不过Apps Script中建议使用本地方法）。

实战案例：根据日期动态生成报表标题

假设您有一个每日销售报表，需要将标题更新为“销售报表 - 2024年2月5日”。通过以下脚本可以自动生成：

function updateReportTitle() {
  var sheet = SpreadsheetApp.getActiveSheet();
  var today = new Date();
  var timeZone = Session.getScriptTimeZone();
  var formattedDate = Utilities.formatDate(today, timeZone, "yyyy年M月d日");
  var title = "销售报表 - " + formattedDate;
  sheet.getRange("A1").setValue(title);
}

此脚本每次运行时（例如通过触发器），都会将A1单元格（假设为标题区域）更新为当前日期的中文格式标题。

总结

在Google Apps Script中格式化日期主要依靠Utilities.formatDate()方法，结合时区与Java风格的格式化模式。需要根据需求选择是输出字符串还是设置单元格的数字格式。解析字符串为Date对象时，应手动处理以确保正确性。掌握这些技巧可以帮助您高效处理日期数据，使脚本更加健壮和可读。

GoogleAppsScript 日期格式化 Google表格 Utilities.formatDate 时间格式化