Google Apps Script: Как Работать с Классом Sheet?

05.09.2025
49273

7 мин
142

Что такое Класс Sheet и его назначение

Класс Sheet в Google Apps Script представляет собой интерфейс для взаимодействия с отдельными листами в Google Таблицах. Он предоставляет методы для чтения, записи, форматирования и управления данными на листе. Фактически, класс Sheet является центральным элементом при автоматизации задач, связанных с обработкой табличных данных. Этот класс позволяет решать широкий спектр задач, от простых, вроде автоматической генерации отчетов, до сложных, например, интеграции данных из различных источников.

Получение доступа к листу (Sheet) в Google Таблицах

Прежде чем начать работу с листом, необходимо получить к нему доступ. Это можно сделать несколькими способами. Наиболее распространенный способ – получение активного листа или листа по его имени. Рассмотрим примеры:

/**
 * Получает активный лист в текущей таблице.
 * @return {GoogleAppsScript.Spreadsheet.Sheet} Активный лист.
 */
function getActiveSheet(): GoogleAppsScript.Spreadsheet.Sheet {
  const spreadsheet: GoogleAppsScript.Spreadsheet.Spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
  const sheet: GoogleAppsScript.Spreadsheet.Sheet = spreadsheet.getActiveSheet();
  return sheet;
}

/**
 * Получает лист по его имени.
 * @param {string} sheetName Имя листа.
 * @return {GoogleAppsScript.Spreadsheet.Sheet | null} Лист, если найден, иначе null.
 */
function getSheetByName(sheetName: string): GoogleAppsScript.Spreadsheet.Sheet | null {
  const spreadsheet: GoogleAppsScript.Spreadsheet.Spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
  const sheet: GoogleAppsScript.Spreadsheet.Sheet | null = spreadsheet.getSheetByName(sheetName);
  return sheet;
}

Основные методы и свойства класса Sheet

Класс Sheet предоставляет множество методов и свойств, позволяющих выполнять различные операции с листом. Вот некоторые из наиболее важных:

getDataRange(): Возвращает объект Range, представляющий весь диапазон данных на листе.

getRange(row, column, numRows, numColumns): Возвращает объект Range, представляющий указанный диапазон ячеек.

getLastRow(): Возвращает номер последней строки, содержащей данные.

getLastColumn(): Возвращает номер последнего столбца, содержащего данные.

getName(): Возвращает имя листа.

setName(name): Устанавливает имя листа.

insertRowBefore(beforePosition): Вставляет строку перед указанной позицией.

deleteRow(rowPosition): Удаляет строку.

Работа с Данными в Классе Sheet

Чтение данных из ячеек, строк и столбцов

Для чтения данных из листа используются методы getRange() и getValue() (для одной ячейки) или getValues() (для диапазона ячеек). Пример:

/**
 * Читает значение из указанной ячейки.
 * @param {number} row Номер строки (начиная с 1).
 * @param {number} column Номер столбца (начиная с 1).
 * @return {any} Значение ячейки.
 */
function readCellValue(row: number, column: number): any {
  const sheet: GoogleAppsScript.Spreadsheet.Sheet = getActiveSheet();
  const cellValue: any = sheet.getRange(row, column).getValue();
  return cellValue;
}

/**
 * Читает данные из диапазона ячеек.
 * @param {number} startRow Номер начальной строки (начиная с 1).
 * @param {number} startColumn Номер начального столбца (начиная с 1).
 * @param {number} numRows Количество строк.
 * @param {number} numColumns Количество столбцов.
 * @return {any[][]} Двумерный массив значений.
 */
function readRangeValues(startRow: number, startColumn: number, numRows: number, numColumns: number): any[][] {
  const sheet: GoogleAppsScript.Spreadsheet.Sheet = getActiveSheet();
  const rangeValues: any[][] = sheet.getRange(startRow, startColumn, numRows, numColumns).getValues();
  return rangeValues;
}

Запись данных в ячейки, строки и столбцы

Для записи данных используются методы getRange() и setValue() (для одной ячейки) или setValues() (для диапазона ячеек). Пример:

/**
 * Записывает значение в указанную ячейку.
 * @param {number} row Номер строки (начиная с 1).
 * @param {number} column Номер столбца (начиная с 1).
 * @param {any} value Значение для записи.
 */
function writeCellValue(row: number, column: number, value: any): void {
  const sheet: GoogleAppsScript.Spreadsheet.Sheet = getActiveSheet();
  sheet.getRange(row, column).setValue(value);
}

/**
 * Записывает данные в диапазон ячеек.
 * @param {number} startRow Номер начальной строки (начиная с 1).
 * @param {number} startColumn Номер начального столбца (начиная с 1).
 * @param {any[][]} values Двумерный массив значений для записи.
 */
function writeRangeValues(startRow: number, startColumn: number, values: any[][]): void {
  const sheet: GoogleAppsScript.Spreadsheet.Sheet = getActiveSheet();
  const numRows: number = values.length;
  const numColumns: number = values[0].length;
  sheet.getRange(startRow, startColumn, numRows, numColumns).setValues(values);
}

Очистка данных на листе

Метод clearContent() позволяет очистить данные в указанном диапазоне ячеек или на всем листе. Например:

/**
 * Очищает содержимое диапазона ячеек.
 * @param {number} startRow Номер начальной строки (начиная с 1).
 * @param {number} startColumn Номер начального столбца (начиная с 1).
 * @param {number} numRows Количество строк.
 * @param {number} numColumns Количество столбцов.
 */
function clearRangeContent(startRow: number, startColumn: number, numRows: number, numColumns: number): void {
  const sheet: GoogleAppsScript.Spreadsheet.Sheet = getActiveSheet();
  sheet.getRange(startRow, startColumn, numRows, numColumns).clearContent();
}

/**
 * Очищает содержимое всего листа.
 */
function clearSheetContent(): void {
  const sheet: GoogleAppsScript.Spreadsheet.Sheet = getActiveSheet();
  sheet.getDataRange().clearContent();
}

Получение диапазонов (Range) для работы с данными

Объект Range представляет собой группу смежных ячеек на листе. Получить Range можно с помощью метода getRange(). Range предоставляет методы для работы с данными, форматированием и стилем.

Форматирование и Стиль в Классе Sheet

Изменение шрифта, размера и цвета текста

Для изменения шрифта, размера и цвета текста используются методы объекта Range, такие как setFontFamily(), setFontSize() и setFontColor(). Пример:

/**
 * Устанавливает шрифт, размер и цвет текста для диапазона ячеек.
 * @param {number} startRow Номер начальной строки (начиная с 1).
 * @param {number} startColumn Номер начального столбца (начиная с 1).
 * @param {number} numRows Количество строк.
 * @param {number} numColumns Количество столбцов.
 * @param {string} fontFamily Название шрифта.
 * @param {number} fontSize Размер шрифта.
 * @param {string} fontColor Цвет шрифта (в формате hex).
 */
function formatText(startRow: number, startColumn: number, numRows: number, numColumns: number, fontFamily: string, fontSize: number, fontColor: string): void {
  const sheet: GoogleAppsScript.Spreadsheet.Sheet = getActiveSheet();
  const range: GoogleAppsScript.Spreadsheet.Range = sheet.getRange(startRow, startColumn, numRows, numColumns);
  range.setFontFamily(fontFamily);
  range.setFontSize(fontSize);
  range.setFontColor(fontColor);
}

Установка фонового цвета ячеек

Фоновый цвет ячеек устанавливается с помощью метода setBackground(). Пример:

/**
 * Устанавливает фоновый цвет для диапазона ячеек.
 * @param {number} startRow Номер начальной строки (начиная с 1).
 * @param {number} startColumn Номер начального столбца (начиная с 1).
 * @param {number} numRows Количество строк.
 * @param {number} numColumns Количество столбцов.
 * @param {string} backgroundColor Цвет фона (в формате hex).
 */
function setBackgroundColor(startRow: number, startColumn: number, numRows: number, numColumns: number, backgroundColor: string): void {
  const sheet: GoogleAppsScript.Spreadsheet.Sheet = getActiveSheet();
  const range: GoogleAppsScript.Spreadsheet.Range = sheet.getRange(startRow, startColumn, numRows, numColumns);
  range.setBackground(backgroundColor);
}

Работа с выравниванием текста

Для управления выравниванием текста используются методы setHorizontalAlignment() и setVerticalAlignment(). Пример:

/**
 * Устанавливает выравнивание текста по горизонтали для диапазона ячеек.
 * @param {number} startRow Номер начальной строки (начиная с 1).
 * @param {number} startColumn Номер начального столбца (начиная с 1).
 * @param {number} numRows Количество строк.
 * @param {number} numColumns Количество столбцов.
 * @param {string} alignment Выравнивание ('left', 'center', 'right').
 */
function setHorizontalAlignment(startRow: number, startColumn: number, numRows: number, numColumns: number, alignment: string): void {
  const sheet: GoogleAppsScript.Spreadsheet.Sheet = getActiveSheet();
  const range: GoogleAppsScript.Spreadsheet.Range = sheet.getRange(startRow, startColumn, numRows, numColumns);
  range.setHorizontalAlignment(alignment);
}

Форматирование чисел и дат

Для форматирования чисел и дат используется метод setNumberFormat(). Пример:

/**
 * Устанавливает формат чисел для диапазона ячеек.
 * @param {number} startRow Номер начальной строки (начиная с 1).
 * @param {number} startColumn Номер начального столбца (начиная с 1).
 * @param {number} numRows Количество строк.
 * @param {number} numColumns Количество столбцов.
 * @param {string} numberFormat Формат чисел (например, '#,##0.00').
 */
function setNumberFormat(startRow: number, startColumn: number, numRows: number, numColumns: number, numberFormat: string): void {
  const sheet: GoogleAppsScript.Spreadsheet.Sheet = getActiveSheet();
  const range: GoogleAppsScript.Spreadsheet.Range = sheet.getRange(startRow, startColumn, numRows, numColumns);
  range.setNumberFormat(numberFormat);
}

Управление Листом (Sheet) в Google Apps Script

Переименование листа

Лист можно переименовать с помощью метода setName(). Пример:

/**
 * Переименовывает текущий лист.
 * @param {string} newName Новое имя листа.
 */
function renameSheet(newName: string): void {
  const sheet: GoogleAppsScript.Spreadsheet.Sheet = getActiveSheet();
  sheet.setName(newName);
}

Изменение размера строк и столбцов

Размер строк и столбцов можно изменить с помощью методов setRowHeight() и setColumnWidth(). Пример:

/**
 * Устанавливает высоту строки.
 * @param {number} row Номер строки (начиная с 1).
 * @param {number} height Высота строки в пикселях.
 */
function setRowHeight(row: number, height: number): void {
  const sheet: GoogleAppsScript.Spreadsheet.Sheet = getActiveSheet();
  sheet.setRowHeight(row, height);
}

/**
 * Устанавливает ширину столбца.
 * @param {number} column Номер столбца (начиная с 1).
 * @param {number} width Ширина столбца в пикселях.
 */
function setColumnWidth(column: number, width: number): void {
  const sheet: GoogleAppsScript.Spreadsheet.Sheet = getActiveSheet();
  sheet.setColumnWidth(column, width);
}

Скрытие и отображение строк и столбцов

Строки и столбцы можно скрыть и отобразить с помощью методов hideRow(), showRow(), hideColumn() и showColumn(). Пример:

/**
 * Скрывает строку.
 * @param {number} row Номер строки (начиная с 1).
 */
function hideRow(row: number): void {
  const sheet: GoogleAppsScript.Spreadsheet.Sheet = getActiveSheet();
  sheet.hideRow(sheet.getRange(row, 1));
}

/**
 * Отображает строку.
 * @param {number} row Номер строки (начиная с 1).
 */
function showRow(row: number): void {
  const sheet: GoogleAppsScript.Spreadsheet.Sheet = getActiveSheet();
  sheet.showRow(sheet.getRange(row, 1));
}

Защита листа от изменений

Для защиты листа от изменений можно использовать класс Protection. Пример:

/**
 * Защищает лист от редактирования всеми пользователями.
 */
function protectSheet(): void {
  const sheet: GoogleAppsScript.Spreadsheet.Sheet = getActiveSheet();
  const protection: GoogleAppsScript.Spreadsheet.Protection = sheet.protect();
  protection.removeEditors(protection.getEditors());
  protection.setWarningOnly(false);
}

Примеры Использования Класса Sheet

Автоматизация создания отчетов

Класс Sheet идеально подходит для автоматического создания отчетов. Можно считывать данные из различных источников (например, из CRM-системы или базы данных) и записывать их в таблицу в отформатированном виде.

Импорт и экспорт данных

Данные из внешних файлов (например, CSV или JSON) можно импортировать в таблицу, а данные из таблицы можно экспортировать в различные форматы.

Создание динамических таблиц

С помощью класса Sheet можно создавать динамические таблицы, которые автоматически обновляются при изменении исходных данных. Например, можно создать таблицу, которая отображает данные из Google Analytics и автоматически обновляется каждый час.