Google Apps Script: Как работать с новой датой?

01.10.2025
55290

6 мин
125

Google Apps Script, основанный на JavaScript, предоставляет широкие возможности для работы с датами. Правильная обработка дат критически важна для автоматизации задач, создания отчетов, планирования и многих других сценариев, особенно в контексте Google Workspace (Sheets, Docs, Calendar и т.д.). Эта статья посвящена эффективным методам работы с датами, ориентированным на опытных разработчиков.

Почему важна правильная обработка дат?

Некорректная обработка дат может привести к серьезным ошибкам в логике ваших скриптов. Например, неправильное вычисление сроков рекламных кампаний в Google Ads, неверное формирование отчетов о расходах, или сбои в автоматической рассылке уведомлений. Точность и надежность в работе с датами – залог стабильности и эффективности ваших решений.

Обзор основных объектов Date в JavaScript (и Google Apps Script)

В основе работы с датами лежит объект Date. Он представляет собой момент времени, выраженный в миллисекундах, прошедших с начала эпохи Unix (1 января 1970 года, 00:00:00 UTC). Важно понимать, что объект Date хранит дату и время в UTC, а при выводе может быть преобразован в локальное время пользователя или в заданный часовой пояс.

Создание новых объектов Date

Создание объекта Date с текущей датой и временем

Самый простой способ создать объект Date – использовать конструктор без аргументов. Это создаст объект, представляющий текущую дату и время.

/**
 *  Возвращает объект Date, представляющий текущую дату и время.
 *  @return {Date} Объект Date.
 */
function getCurrentDate(): Date {
  return new Date();
}

Создание объекта Date с указанием конкретной даты и времени

Можно создать объект Date, указав год, месяц, день, часы, минуты и секунды. Важно: месяц отсчитывается с 0 (0 – январь, 11 – декабрь).

/**
 *  Создает объект Date с указанной датой и временем.
 *  @param {number} year Год.
 *  @param {number} month Месяц (0-11).
 *  @param {number} day День месяца.
 *  @param {number} hours Часы (0-23).
 *  @param {number} minutes Минуты (0-59).
 *  @param {number} seconds Секунды (0-59).
 *  @return {Date} Объект Date.
 */
function createSpecificDate(year: number, month: number, day: number, hours: number, minutes: number, seconds: number): Date {
  return new Date(year, month, day, hours, minutes, seconds);
}

//Пример:
const newYear: Date = createSpecificDate(2024, 0, 1, 0, 0, 0); // 1 января 2024, 00:00:00

Создание объекта Date из строки

Объект Date можно создать из строки, представляющей дату и время. Формат строки должен быть понятен JavaScript.

/**
 *  Создает объект Date из строки.
 *  @param {string} dateString Строка, представляющая дату и время.
 *  @return {Date} Объект Date.
 */
function createDateFromString(dateString: string): Date {
  return new Date(dateString);
}

//Примеры:
const date1: Date = createDateFromString("2023-12-25");
const date2: Date = createDateFromString("December 25, 2023 10:00:00");

Получение даты из Spreadsheet ячейки и преобразование в объект Date

При работе с Google Sheets, дата часто хранится в ячейке. getValue() возвращает дату в виде объекта Date.

/**
 *  Получает дату из ячейки Spreadsheet и возвращает объект Date.
 *  @param {string} sheetName Название листа.
 *  @param {number} row Номер строки.
 *  @param {number} column Номер столбца.
 *  @return {Date} Объект Date.
 */
function getDateFromSheet(sheetName: string, row: number, column: number): Date {
  const ss = SpreadsheetApp.getActiveSpreadsheet();
  const sheet = ss.getSheetByName(sheetName);
  if (!sheet) {
    throw new Error(`Sheet with name '${sheetName}' not found.`);
  }
  const dateValue = sheet.getRange(row, column).getValue();

  if (!(dateValue instanceof Date)) {
    throw new Error("The cell does not contain a date value.");
  }

  return dateValue;
}

// Пример
// const myDate: Date = getDateFromSheet("Sheet1", 2, 3);

Форматирование дат

Использование Utilities.formatDate() для форматирования даты в нужный формат

Utilities.formatDate() – основной инструмент для преобразования объекта Date в строку заданного формата. Требует указания часового пояса и формата даты.

/**
 *  Форматирует дату в заданный формат.
 *  @param {Date} date Объект Date.
 *  @param {string} timeZone Часовой пояс (например, "GMT+3").
 *  @param {string} format Формат даты (например, "yyyy-MM-dd HH:mm:ss").
 *  @return {string} Отформатированная строка даты.
 */
function formatDate(date: Date, timeZone: string, format: string): string {
  return Utilities.formatDate(date, timeZone, format);
}

//Пример:
const now: Date = new Date();
const formattedDate: string = formatDate(now, "GMT+3", "yyyy-MM-dd HH:mm:ss");
Logger.log(formattedDate); // Вывод: 2023-10-27 15:30:00 (пример)

Примеры различных форматов дат (год, месяц, день, время, часовой пояс)

yyyy: год (4 цифры)

yy: год (2 цифры)

MMMM: название месяца (полное)

MMM: название месяца (сокращенное)

MM: месяц (2 цифры)

M: месяц (1 или 2 цифры)

dd: день месяца (2 цифры)

d: день месяца (1 или 2 цифры)

HH: часы (00-23)

hh: часы (01-12)

mm: минуты (00-59)

ss: секунды (00-59)

zzz: часовой пояс (например, GMT+03:00)

Локализация: форматирование дат для разных регионов

Укажите правильный часовой пояс для корректного отображения даты и времени в нужном регионе. Наиболее распространённые: "GMT+0", "GMT+3" (Москва), "America/Los_Angeles".

Операции с датами

Добавление и вычитание дней, месяцев, лет

Для добавления или вычитания дней, месяцев или лет, необходимо использовать методы объекта Date. Важно: эти методы изменяют исходный объект Date.

/**
 *  Добавляет дни к дате.
 *  @param {Date} date Объект Date.
 *  @param {number} days Количество дней для добавления.
 *  @return {Date} Измененный объект Date.
 */
function addDays(date: Date, days: number): Date {
  date.setDate(date.getDate() + days);
  return date;
}

/**
 *  Вычитает дни из даты.
 *  @param {Date} date Объект Date.
 *  @param {number} days Количество дней для вычитания.
 *  @return {Date} Измененный объект Date.
 */
function subtractDays(date: Date, days: number): Date {
  date.setDate(date.getDate() - days);
  return date;
}

// Пример:
let myDate: Date = new Date("2023-10-27");
addDays(myDate, 7); // Добавляем 7 дней
Logger.log(myDate);  // Вывод: Fri Nov 03 2023...

Аналогичные методы существуют для работы с месяцами (setMonth) и годами (setFullYear).

Получение разницы между двумя датами (в днях)

Разницу между двумя датами можно вычислить, получив их значения в миллисекундах (getTime()) и поделив на количество миллисекунд в дне.

/**
 *  Вычисляет разницу между двумя датами в днях.
 *  @param {Date} date1 Первая дата.
 *  @param {Date} date2 Вторая дата.
 *  @return {number} Разница в днях.
 */
function daysBetween(date1: Date, date2: Date): number {
  const oneDay: number = 24 * 60 * 60 * 1000; // milliseconds in a day
  return Math.round(Math.abs((date1.getTime() - date2.getTime()) / oneDay));
}

//Пример:
const date1: Date = new Date("2023-10-01");
const date2: Date = new Date("2023-10-27");
const diff: number = daysBetween(date1, date2);
Logger.log(diff); // Вывод: 26

Получение дня недели, месяца, года из объекта Date

Используйте методы getDay() (день недели, 0-6), getMonth() (месяц, 0-11), getFullYear() (год).

Определение високосного года

/**
 *  Определяет, является ли год високосным.
 *  @param {number} year Год.
 *  @return {boolean} True, если год високосный, иначе False.
 */
function isLeapYear(year: number): boolean {
  return (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
}

//Пример:
Logger.log(isLeapYear(2024)); // Вывод: true
Logger.log(isLeapYear(2023)); // Вывод: false

Решение распространенных задач с датами в Google Apps Script

Получение даты начала и окончания недели/месяца/года

Это часто требуется для формирования отчетов за определенный период.

/**
 *  Получает дату начала недели для заданной даты (воскресенье).
 *  @param {Date} date Дата.
 *  @return {Date} Дата начала недели.
 */
function getStartOfWeek(date: Date): Date {
  const dayOfWeek: number = date.getDay();
  const diff: number = date.getDate() - dayOfWeek + (dayOfWeek === 0 ? -6 : 1); // adjust when day is sunday

  return new Date(date.setDate(diff));
}

Аналогично можно реализовать функции для получения начала и конца месяца/года.

Проверка, попадает ли дата в определенный период

/**
 *  Проверяет, попадает ли дата в заданный период.
 *  @param {Date} date Дата для проверки.
 *  @param {Date} startDate Начало периода.
 *  @param {Date} endDate Конец периода.
 *  @return {boolean} True, если дата попадает в период, иначе False.
 */
function isDateWithinRange(date: Date, startDate: Date, endDate: Date): boolean {
  return date >= startDate && date <= endDate;
}

Автоматическое создание отчетов за определенный период времени

Пример: создание отчета за последний месяц.

/**
 *  Создает отчет за последний месяц (пример).  Необходимо доработать
 *  в зависимости от требований к отчету (например, интеграция с Google Analytics).
 */
function generateLastMonthReport() {
  const today: Date = new Date();
  const lastMonthStart: Date = new Date(today.getFullYear(), today.getMonth() - 1, 1);
  const lastMonthEnd: Date = new Date(today.getFullYear(), today.getMonth(), 0);

  Logger.log(`Отчет за период с ${lastMonthStart} по ${lastMonthEnd}`);
  // Здесь должен быть код для сбора данных и формирования отчета.
}

Помните, что это лишь базовые примеры. Работа с датами в Google Apps Script может быть намного сложнее, в зависимости от ваших конкретных задач. Не забывайте про unit-тестирование, чтобы убедиться в корректности ваших функций.