Google Apps Script: Как получить лист в Google Sheets?

11.09.2025
51478

5 мин
130

Что такое Google Apps Script и зачем он нужен?

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

Основные понятия: Spreadsheets, Sheets, и их идентификаторы

Spreadsheet (таблица) — это основной документ Google Sheets, содержащий один или несколько листов (Sheets).

Sheet (лист) — это отдельная страница в таблице, содержащая ячейки для хранения данных.

Каждая таблица имеет уникальный ID, который можно найти в URL таблицы. Каждый лист также имеет свой ID, который может быть получен программно.

Предварительные шаги: открытие редактора скриптов и подключение к таблице

Чтобы начать работу с Google Apps Script, откройте Google Sheets, выберите Инструменты > Редактор скриптов. В редакторе скриптов вы можете писать и запускать код, взаимодействующий с вашей таблицей. Перед началом работы с листами, необходимо получить ссылку на таблицу:

/**
 * Получает активную таблицу Google Sheets.
 *
 * @returns {Spreadsheet} Активная таблица.
 */
function getActiveSpreadsheet(): GoogleAppsScript.Spreadsheet.Spreadsheet {
  return SpreadsheetApp.getActiveSpreadsheet();
}

// Пример использования:
const ss: GoogleAppsScript.Spreadsheet.Spreadsheet = getActiveSpreadsheet();

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

Метод `getSheetByName(name)`: синтаксис и примеры использования

Метод getSheetByName(name) позволяет получить лист по его имени. Он возвращает объект Sheet, представляющий лист с указанным именем, или null, если лист с таким именем не найден.

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

// Пример использования:
const sheetName: string = "Отчет за январь";
const sheet: GoogleAppsScript.Spreadsheet.Sheet | null = getSheetByName(sheetName);

if (sheet) {
  console.log(`Лист ${sheetName} найден.`);
} else {
  console.log(`Лист ${sheetName} не найден.`);
}

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

Важно проверять, возвращает ли getSheetByName(name) значение null, чтобы избежать ошибок при дальнейшей работе с листом. Можно использовать условные операторы или обработку исключений:

function safelyGetSheetByName(sheetName: string): GoogleAppsScript.Spreadsheet.Sheet {
    const ss: GoogleAppsScript.Spreadsheet.Spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
    const sheet: GoogleAppsScript.Spreadsheet.Sheet | null = ss.getSheetByName(sheetName);

    if (!sheet) {
        throw new Error(`Лист с именем '${sheetName}' не найден.`);
    }

    return sheet;
}

try {
    const sheet: GoogleAppsScript.Spreadsheet.Sheet = safelyGetSheetByName("Несуществующий лист");
    // Дальнейшая работа с листом
} catch (e) {
    console.error(e.message);
}

Практический пример: функция для получения листа по имени

/**
 * Получает лист по имени и записывает значение в ячейку A1.
 *
 * @param {string} sheetName Имя листа.
 * @param {any} value Значение для записи в ячейку A1.
 * @returns {void}
 */
function setCellValueToSheet(sheetName: string, value: any): void {
  const sheet: GoogleAppsScript.Spreadsheet.Sheet | null = getSheetByName(sheetName);

  if (sheet) {
    sheet.getRange("A1").setValue(value);
    console.log(`Значение '${value}' записано в ячейку A1 листа '${sheetName}'.`);
  } else {
    console.log(`Лист '${sheetName}' не найден.`);
  }
}

// Пример использования:
setCellValueToSheet("Лист1", "Привет, мир!");

Получение активного листа

Метод `getActiveSheet()`: получение текущего активного листа

Метод getActiveSheet() возвращает активный лист в текущей открытой таблице. Активный лист — это лист, который в данный момент отображается у пользователя.

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

// Пример использования:
const activeSheet: GoogleAppsScript.Spreadsheet.Sheet = getActiveSheet();
console.log(`Активный лист: ${activeSheet.getName()}`);

Пример использования `getActiveSheet()` для работы с данными активного листа

/**
 * Получает имя активного листа и записывает его в ячейку B1.
 *
 * @returns {void}
 */
function writeActiveSheetNameToCell(): void {
  const activeSheet: GoogleAppsScript.Spreadsheet.Sheet = getActiveSheet();
  const sheetName: string = activeSheet.getName();
  activeSheet.getRange("B1").setValue(sheetName);
  console.log(`Имя активного листа '${sheetName}' записано в ячейку B1.`);
}

Разница между `getActiveSheet()` и `getActiveSheet()`

Тут опечатка в заголовке, поправьте. Должно быть, Разница между getActiveSheet() и getSheetByName(). Метод getActiveSheet() получает лист, который в данный момент открыт у пользователя. Метод getSheetByName() получает лист по его имени, независимо от того, открыт ли он в данный момент или нет.

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

Метод `getSheet()`: синтаксис и примеры использования

Метод getSheet() возвращает лист по его индексу. Индексация листов начинается с 0. Внимание: Этот метод устарел и рекомендуется использовать getSheets() для получения массива всех листов, а затем обращаться к нужному листу по индексу в массиве. Однако, если требуется именно этот метод, вот пример:

/**
 * Получает лист по индексу (устаревший метод).
 *
 * @deprecated Рекомендуется использовать getSheets() и обращаться к листу по индексу в массиве.
 * @param {number} index Индекс листа (начиная с 0).
 * @returns {GoogleAppsScript.Spreadsheet.Sheet} Лист по указанному индексу.
 */
function getSheetByIndex(index: number): GoogleAppsScript.Spreadsheet.Sheet {
  const ss: GoogleAppsScript.Spreadsheet.Spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
  const sheets: GoogleAppsScript.Spreadsheet.Sheet[] = ss.getSheets();
  return sheets[index];
}

// Пример использования (не рекомендуется):
// const sheet: GoogleAppsScript.Spreadsheet.Sheet = getSheetByIndex(0);
// console.log(`Лист с индексом 0: ${sheet.getName()}`);

Важность проверки индекса: избегаем ошибок выхода за границы

При использовании getSheetByIndex() крайне важно проверять, не выходит ли индекс за границы массива листов, чтобы избежать ошибок. Лучше избегать данного метода, используя getSheets().

Практический пример: функция для получения листа по индексу

Этот пример демонстрирует, как получить лист по индексу, используя рекомендованный метод через getSheets():

/**
 * Получает лист по индексу (рекомендуемый метод).
 *
 * @param {number} index Индекс листа (начиная с 0).
 * @returns {GoogleAppsScript.Spreadsheet.Sheet | null} Лист по указанному индексу или null, если индекс недействителен.
 */
function getSheetByIndexSafe(index: number): GoogleAppsScript.Spreadsheet.Sheet | null {
    const ss: GoogleAppsScript.Spreadsheet.Spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
    const sheets: GoogleAppsScript.Spreadsheet.Sheet[] = ss.getSheets();

    if (index >= 0 && index < sheets.length) {
        return sheets[index];
    } else {
        console.warn(`Индекс ${index} выходит за границы массива листов.`);
        return null;
    }
}

// Пример использования:
const sheet: GoogleAppsScript.Spreadsheet.Sheet | null = getSheetByIndexSafe(0);
if (sheet) {
    console.log(`Лист с индексом 0: ${sheet.getName()}`);
} else {
    console.log("Лист с указанным индексом не найден.");
}

Получение всех листов в Google Sheets

Метод `getSheets()`: получение массива всех листов

Метод getSheets() возвращает массив, содержащий все листы в таблице. Это наиболее безопасный и рекомендуемый способ работы с листами по индексу или для перебора всех листов.

/**
 * Получает массив всех листов в таблице.
 *
 * @returns {GoogleAppsScript.Spreadsheet.Sheet[]} Массив всех листов.
 */
function getAllSheets(): GoogleAppsScript.Spreadsheet.Sheet[] {
  const ss: GoogleAppsScript.Spreadsheet.Spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
  return ss.getSheets();
}

// Пример использования:
const sheets: GoogleAppsScript.Spreadsheet.Sheet[] = getAllSheets();
console.log(`В таблице ${sheets.length} листов.`);

Перебор всех листов: примеры использования цикла `for` и `forEach`

Можно использовать цикл for или метод forEach для перебора всех листов в массиве, полученном с помощью getSheets():

// Использование цикла for:
function logAllSheetNamesUsingFor(): void {
    const sheets: GoogleAppsScript.Spreadsheet.Sheet[] = getAllSheets();
    for (let i = 0; i  {
        console.log(`Лист ${index + 1}: ${sheet.getName()}`);
    });
}

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

/**
 * Находит лист, имя которого содержит определенную подстроку.
 *
 * @param {string} searchString Подстрока для поиска в имени листа.
 * @returns {GoogleAppsScript.Spreadsheet.Sheet | null} Найденный лист или null, если ничего не найдено.
 */
function findSheetByNameContaining(searchString: string): GoogleAppsScript.Spreadsheet.Sheet | null {
    const sheets: GoogleAppsScript.Spreadsheet.Sheet[] = getAllSheets();
    for (const sheet of sheets) {
        if (sheet.getName().includes(searchString)) {
            return sheet;
        }
    }
    return null;
}

/**
 * Получает массив имен всех листов в таблице.
 *
 * @returns {string[]} Массив имен листов.
 */
function getAllSheetNames(): string[] {
    const sheets: GoogleAppsScript.Spreadsheet.Sheet[] = getAllSheets();
    return sheets.map(sheet => sheet.getName());
}