Google Apps Script: Как получить значение листа?

Что такое Google Apps Script и для чего он нужен?

Google Apps Script (GAS) — это облачный скриптовый язык, основанный на JavaScript, позволяющий автоматизировать задачи и расширять функциональность сервисов Google Workspace (Sheets, Docs, Forms, Gmail и др.). Он позволяет интегрировать эти сервисы между собой и с внешними API, создавая мощные инструменты автоматизации для бизнеса и личного использования. GAS особенно полезен для задач, связанных с обработкой данных, созданием отчетов, автоматизацией email-рассылок и интеграцией с другими веб-сервисами.

Обзор объекта Spreadsheet и листа (Sheet)

В Google Apps Script объект Spreadsheet представляет собой файл электронной таблицы. Объект Sheet представляет собой отдельный лист внутри этой таблицы. Для работы с данными на листе необходимо получить доступ к соответствующему объекту Sheet. Spreadsheet является контейнером для Sheet. Мы работаем с Spreadsheet, чтобы получить доступ к Sheet, а затем работаем с Sheet, чтобы получить доступ к ячейкам и диапазонам.

Основные методы для работы с листами в Google Apps Script

Основные методы для работы с листами включают получение доступа к листу по имени или индексу, чтение и запись данных, а также управление диапазонами ячеек. Мы будем рассматривать методы getSheetByName(), getSheet(), getValue(), getValues(), getDataRange() и getRange(). Важно понимать, как правильно использовать эти методы для эффективной работы с данными.

Получение доступа к листу в Google Apps Script

Получение активной таблицы (Spreadsheet)

Чтобы начать работу с листом, сначала нужно получить доступ к активной таблице. Это можно сделать с помощью метода SpreadsheetApp.getActiveSpreadsheet():

/**
 * @return {Spreadsheet} Возвращает активную таблицу.
 */
function getActiveSpreadsheet(): Spreadsheet {
  const ss: Spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
  return ss;
}

Получение листа по имени (getSheetByName)

Для получения листа по его имени используется метод getSheetByName(name). Этот метод возвращает объект Sheet с указанным именем.

/**
 * @param {string} sheetName Имя листа.
 * @return {Sheet | null} Возвращает лист по имени или null, если лист не найден.
 */
function getSheetByName(sheetName: string): Sheet | null {
  const ss: Spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
  const sheet: Sheet | null = ss.getSheetByName(sheetName);
  return sheet;
}

Получение листа по индексу (getSheet)

Можно получить лист по его индексу (порядковому номеру) с помощью метода getSheet(index). Важно: Индексация начинается с 1.

/**
 * @param {number} index Индекс листа (начиная с 1).
 * @return {Sheet | null} Возвращает лист по индексу или null, если индекс некорректен.
 */
function getSheetByIndex(index: number): Sheet | null {
  const ss: Spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
  try {
    const sheet: Sheet = ss.getSheets()[index - 1];
    return sheet;
  } catch (e) {
    return null; // Обработка ошибки, если индекс вне диапазона
  }
}

Обработка ошибок: что делать, если лист не найден?

При попытке получить лист по имени или индексу важно предусмотреть обработку ошибок. Если лист не найден, методы могут возвращать null или вызывать исключение. Необходимо проверять возвращаемое значение и обрабатывать возможные ошибки, чтобы избежать сбоев в работе скрипта. Например, можно использовать try...catch блоки для перехвата исключений или проверять значение на null перед дальнейшей работой.

Чтение данных из листа: основные методы

Метод `getValue()`: получение значения одной ячейки

Метод getValue() позволяет получить значение одной конкретной ячейки. Для его использования необходимо сначала получить объект Range, представляющий собой ячейку, а затем вызвать метод getValue().

/**
 * @param {string} sheetName Имя листа.
 * @param {number} row Номер строки (начиная с 1).
 * @param {number} column Номер столбца (начиная с 1).
 * @return {any} Значение ячейки.
 */
function getCellValue(sheetName: string, row: number, column: number): any {
  const sheet: Sheet | null = getSheetByName(sheetName);
  if (!sheet) {
    return null; // Обработка случая, когда лист не найден
  }
  const cell: Range = sheet.getRange(row, column);
  return cell.getValue();
}

Метод `getValues()`: получение диапазона значений (двумерный массив)

Метод getValues() позволяет получить значения из диапазона ячеек в виде двумерного массива. Это удобно для обработки больших объемов данных.

/**
 * @param {string} sheetName Имя листа.
 * @param {number} startRow Номер начальной строки (начиная с 1).
 * @param {number} startColumn Номер начального столбца (начиная с 1).
 * @param {number} numRows Количество строк.
 * @param {number} numColumns Количество столбцов.
 * @return {any[][]} Двумерный массив значений.
 */
function getRangeValues(sheetName: string, startRow: number, startColumn: number, numRows: number, numColumns: number): any[][] {
  const sheet: Sheet | null = getSheetByName(sheetName);
  if (!sheet) {
    return [[]]; // Обработка случая, когда лист не найден
  }
  const range: Range = sheet.getRange(startRow, startColumn, numRows, numColumns);
  return range.getValues();
}

Метод `getDataRange()`: получение всего диапазона данных на листе

Метод getDataRange() возвращает объект Range, представляющий собой диапазон, содержащий все данные на листе. Это удобно для получения всего содержимого листа.

/**
 * @param {string} sheetName Имя листа.
 * @return {Range | null} Объект Range, представляющий весь диапазон данных.
 */
function getDataRange(sheetName: string): Range | null {
  const sheet: Sheet | null = getSheetByName(sheetName);
  if (!sheet) {
    return null; // Обработка случая, когда лист не найден
  }
  return sheet.getDataRange();
}

Использование `getRange()` для указания конкретного диапазона

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

/**
 * @param {string} sheetName Имя листа.
 * @param {string} rangeNotation A1-нотация диапазона (например,