Google Apps Script: Как работать с датами в Google Sheets?

28.09.2025
55211

5 мин
299

Google Apps Script предоставляет мощные инструменты для автоматизации работы с Google Sheets, и работа с датами – одна из ключевых задач. Правильная обработка дат позволяет автоматизировать отчетность, планирование и анализ данных.

Основные понятия: Date object в JavaScript и его представление в Google Sheets

В основе работы с датами лежит объект Date в JavaScript. Google Sheets, в свою очередь, хранит даты как числа, представляющие количество дней, прошедших с 30 декабря 1899 года. При чтении даты из ячейки Google Sheets Apps Script возвращает именно объект Date (или Number, если ячейка не отформатирована как дата).

Почему важно правильно работать с датами: распространенные ошибки и как их избежать

Неправильная обработка дат может привести к серьезным ошибкам в ваших скриптах. Наиболее распространенные проблемы включают:

Некорректное форматирование дат: Разные страны используют разные форматы (например, ДД/ММ/ГГГГ против ММ/ДД/ГГГГ). Важно учитывать региональные настройки.

Неправильное преобразование типов: Попытки математических операций над строками, представляющими даты, приведут к непредсказуемым результатам. Необходимо преобразовывать строки в объекты Date.

Проблемы с часовыми поясами: При работе с датами из разных источников учитывайте разницу в часовых поясах.

Получение и запись дат в Google Sheets с использованием Apps Script

Чтение значений ячеек с датами: особенности формата даты Google Sheets

При чтении даты из ячейки, отформатированной как дата, вы получите объект Date. Если же ячейка имеет текстовый формат, то вернется строка. Для чтения данных используется метод getValue():

/**
 * Чтение даты из ячейки.
 * @param {string} sheetName Название листа.
 * @param {string} cell Адрес ячейки (например, "A1").
 * @return {Date|string} Объект Date или строка, если ячейка не отформатирована как дата.
 */
function getDateFromSheet(sheetName, cell) {
  const ss = SpreadsheetApp.getActiveSpreadsheet();
  const sheet = ss.getSheetByName(sheetName);
  const dateValue = sheet.getRange(cell).getValue();
  return dateValue;
}

// Пример использования:
const myDate = getDateFromSheet("Sheet1", "A1");
Logger.log(typeof myDate); // Выведет "object" или "string"

Преобразование строковых представлений даты в объекты Date

Если дата хранится в ячейке в виде строки, ее необходимо преобразовать в объект Date. Для этого можно использовать конструктор new Date() или Utilities.parseDate():

/**
 * Преобразование строки в дату.
 * @param {string} dateString Строка с датой.
 * @param {string} timeZone Временная зона (например, "GMT+3").
 * @param {string} format Формат даты (например, "yyyy-MM-dd").
 * @return {Date} Объект Date.
 */
function parseDateString(dateString, timeZone, format) {
  try {
     return Utilities.parseDate(dateString, timeZone, format);
  } catch (e) {
    Logger.log("Error parsing date: " + e);
    return null;
  }
}

//Пример использования:
const dateString = "2024-01-01";
const parsedDate = parseDateString(dateString, "GMT+3", "yyyy-MM-dd");
Logger.log(parsedDate);

Запись объектов Date в ячейки Google Sheets: форматирование даты

Для записи даты в ячейку используйте метод setValue(). Важно, чтобы ячейка была отформатирована как дата. Для этого можно использовать setNumberFormat():

/**
 * Запись даты в ячейку и форматирование.
 * @param {string} sheetName Название листа.
 * @param {string} cell Адрес ячейки (например, "A1").
 * @param {Date} date Объект Date.
 * @param {string} format Формат даты (например, "yyyy-MM-dd").
 */
function setDateToSheet(sheetName, cell, date, format) {
  const ss = SpreadsheetApp.getActiveSpreadsheet();
  const sheet = ss.getSheetByName(sheetName);
  sheet.getRange(cell).setValue(date).setNumberFormat(format);
}

// Пример использования:
const today = new Date();
setDateToSheet("Sheet1", "B1", today, "yyyy-MM-dd");

Манипуляции с датами в Google Apps Script

Основные операции: добавление и вычитание дней, месяцев, лет

Для манипуляций с датами используйте методы объекта Date. Важно помнить, что методы setDate(), setMonth() и setFullYear() изменяют исходный объект Date.

/**
 * Добавление дней к дате.
 * @param {Date} date Исходная дата.
 * @param {number} days Количество дней для добавления.
 * @return {Date} Новая дата.
 */
function addDays(date, days) {
  const newDate = new Date(date);
  newDate.setDate(date.getDate() + days);
  return newDate;
}

// Пример использования:
const tomorrow = addDays(new Date(), 1);
Logger.log(tomorrow);

Аналогично можно добавлять и вычитать месяцы и годы, используя setMonth() и setFullYear().

Получение информации о дате: день недели, месяц, год

Для получения информации о дате используйте методы getDay(), getMonth(), getFullYear() и т.д. Обратите внимание, что getMonth() возвращает номер месяца, начиная с 0 (0 – январь, 11 – декабрь).

const date = new Date();
const dayOfWeek = date.getDay(); // 0 - воскресенье, 6 - суббота
const month = date.getMonth(); // 0 - январь, 11 - декабрь
const year = date.getFullYear();

Logger.log("Сегодня: " + dayOfWeek + ", " + month + ", " + year);

Сравнение дат: определение, какая дата раньше или позже

Для сравнения дат используйте операторы сравнения (<, >, <=, >=). Важно помнить, что даты сравниваются как числа, представляющие количество миллисекунд с 1 января 1970 года.

const date1 = new Date("2023-01-01");
const date2 = new Date("2024-01-01");

if (date1 < date2) {
  Logger.log("date1 раньше date2");
}

Форматирование дат в Google Sheets через Apps Script

Использование `Utilities.formatDate()` для преобразования даты в строку

Функция Utilities.formatDate() позволяет преобразовать объект Date в строку в соответствии с заданным форматом.

Настройка формата даты: примеры различных шаблонов

Шаблоны формата определяют, как дата будет представлена в виде строки. Некоторые полезные символы:

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

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

dd: День (2 цифры)

HH: Час (2 цифры, 24-часовой формат)

mm: Минуты (2 цифры)

ss: Секунды (2 цифры)

const date = new Date();
const formattedDate = Utilities.formatDate(date, "GMT+3", "yyyy-MM-dd HH:mm:ss");
Logger.log(formattedDate);

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

Utilities.formatDate() позволяет форматировать дату в соответствии с языковыми стандартами. Влияет временная зона, указанная вторым аргументом.

Практические примеры работы с датами в Google Sheets

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

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

function onEdit(e) {
  const sheet = e.range.getSheet();
  // Проверяем, что изменение произошло на нужном листе
  if (sheet.getName() == "DataSheet") {
    const row = e.range.getRow();
    const column = e.range.getColumn();

    // Проверяем, что изменение произошло в нужном столбце
    if (column == 2) { // столбец B
      // Записываем текущую дату и время в столбец C той же строки
      sheet.getRange(row, 3).setValue(new Date());
    }
  }
}

Расчет разницы между двумя датами (в днях, месяцах, годах)

/**
 * Расчет разницы в днях между двумя датами.
 * @param {Date} date1 Первая дата.
 * @param {Date} date2 Вторая дата.
 * @return {number} Количество дней между датами.
 */
function daysBetween(date1, date2) {
  const diff = Math.abs(date1.getTime() - date2.getTime());
  return Math.ceil(diff / (1000 * 3600 * 24));
}

// Пример использования:
const startDate = new Date("2023-01-01");
const endDate = new Date("2023-01-10");
const dayDifference = daysBetween(startDate, endDate);
Logger.log("Разница в днях: " + dayDifference);

Создание календаря событий на основе данных из Google Sheets

Этот пример предполагает, что в Google Sheets есть таблица с событиями, где указаны дата начала, дата окончания и название события. Скрипт читает эти данные и создает события в Google Calendar.

(Реализация этого примера выходит за рамки данного документа, но принцип заключается в чтении данных из Sheets, преобразовании дат в объекты Date и использовании Calendar API для создания событий).

В заключение, умение работать с датами в Google Apps Script открывает широкие возможности для автоматизации различных задач в Google Sheets. Правильное форматирование и обработка дат – залог корректной работы ваших скриптов.