Перейти к основному содержимому

Чтение и запись данных таблицы

Скрипт работает со своей таблицей через объект Coverse.table. Полный список команд с примерами — во вкладке «Справка» редактора скрипта. Здесь собраны основные.

Листы​

const sheets = Coverse.table.getSheets();               // все листы по порядку
const orders = Coverse.table.getSheet("Заказы");        // лист по названию, ошибка если нет
const archive = Coverse.table.getSheetByName("Архив");  // лист или null

Создать лист, только если его ещё нет:

const sheet = Coverse.table.getSheetByName("Октябрь") || Coverse.table.insertSheet("Октябрь");
КомандаЧто делает
Coverse.table.insertSheet("Имя")создаёт лист в конце таблицы; лист с таким именем уже есть — ошибка
Coverse.table.copySheet("Шаблон", "Октябрь")копия листа с данными, формулами, оформлением, списками, подсветкой и фильтром
Coverse.table.moveSheet(лист, 1)ставит лист на позицию среди ярлыков, нумерация с 1
Coverse.table.deleteSheet("Черновик")удаляет лист с данными без возможности отмены
sheet.setName("Архив 2026")переименовывает лист; формулы на других листах со старым именем не обновляются
sheet.hideSheet(), sheet.showSheet()скрывает и показывает лист
sheet.setTabColor("#ffcc00")цвет ярлыка, null убирает цвет

Диапазоны​

const range = sheet.getRange("A1:C10");     // по адресу
const same = sheet.getRange(1, 1, 10, 3);   // строка, столбец, число строк, число столбцов
const all = sheet.getDataRange();           // все заполненные ячейки
const lastRow = sheet.getLastRow();         // номер последней строки с данными

Строки и столбцы нумеруются с 1. У диапазона есть getRow(), getColumn(), getLastRow(), getLastColumn(), getNumRows(), getNumColumns(), getA1Notation() и getSheet().

Чтение​

const rows = sheet.getDataRange().getValues();  // массив строк, строка — массив ячеек
const header = rows[0];
const first = sheet.getRange("B2").getValue();  // одна ячейка
const shown = sheet.getRange("D2:D10").getDisplayValues(); // как показано в ячейках
const formulas = sheet.getRange("E2:E10").getFormulas();

Типы значений в getValues():

  • число приходит числом, даже если в таблице оно записано с запятой: 12,5 → 12.5;
  • дата приходит объектом Date;
  • всё остальное приходит текстом; пустая ячейка — пустая строка;
  • флажок приходит true или false.

Искать столбец лучше по заголовку, а не по номеру: так скрипт не сломается, если столбцы переставят.

const rows = sheet.getDataRange().getValues();
const col = rows[0].indexOf("Сумма");
if (col === -1) throw new Error("Нет столбца «Сумма»");

Запись​

sheet.getRange("A1").setValue("Готово");
sheet.getRange("A2:B3").setValues([[1, 2], [3, 4]]);   // размер массива = размер диапазона
sheet.appendRow([new Date(), "Чай", 120]);               // строка в конец листа
sheet.appendRows([["Кофе", 300], ["Сахар", 80]]);         // несколько строк за раз
sheet.getRange("A2:C100").clear();                       // очистить значения
  • Числа передавайте числами: 12.5 станет числом в формате ячейки, а строка "12.5" останется текстом.
  • Объект Date записывается датой.
  • Значение, которое начинается с =, считается формулой.
Пишите большими блоками

Одна запись setValues на весь диапазон работает быстрее, чем setValue в цикле по каждой ячейке. Соберите данные в массив и запишите его одной командой.

Формулы​

sheet.getRange("D11").setFormula("=SUM(D2:D10)");
sheet.getRange("E2:E3").setFormulas([["=C2*D2"], ["=C3*D3"]]);

Правила записи формул в скрипте:

  • названия функций по-английски: SUM, IF, VLOOKUP;
  • аргументы через точку с запятой: =IF(A2>0;"да";"нет");
  • дробная часть через точку: =A2*1.2;
  • ссылка на другой лист: ='Заказы'!A1.

После записи формулы скрипт сразу читает её результат.

Строки и столбцы​

КомандаЧто делает
sheet.insertRowsBefore(2, 3)три пустые строки перед второй; также insertRowsAfter, insertRowBefore, insertRowAfter, insertRows
sheet.insertColumnsAfter(3, 1)столбец после третьего; также insertColumnsBefore, insertColumnBefore, insertColumnAfter, insertColumns
sheet.deleteRows(5, 3)удаляет три строки начиная с пятой; deleteRow(5) — одну
sheet.deleteColumn(2), deleteColumns(2, 3)удаляет столбцы
sheet.moveRows(5, 2, 2)переносит две строки начиная с пятой перед второй; moveColumns — столбцы
sheet.hideRows(5, 2), showRows(5, 2)скрывает и показывает строки; hideColumns, showColumns — столбцы
range.copyTo(sheet.getRange("H2"))копирует диапазон со значениями, формулами, оформлением и примечаниями

Удаляете строки по одной в цикле — идите снизу вверх, иначе номера остальных строк сдвинутся:

const rows = sheet.getDataRange().getValues();
for (let i = rows.length - 1; i >= 1; i--) {
  if (rows[i][4] === "Отменён") sheet.deleteRow(i + 1);
}

Ограничения: за запуск не больше 15 вставок, удалений и переносов строк и столбцов, одна команда — до 1000 строк или 100 столбцов. На листе с диаграммами, сводной таблицей, импортом из другой таблицы, защищёнными или именованными диапазонами, ответами формы такие команды не работают, скрипт остановится и назовёт причину. Удалить много строк по условию проще так: прочитать данные, отфильтровать в массиве, очистить лист и записать результат одной командой setValues.

Выделение пользователя​

Если скрипт запустили вручную, кнопкой или сочетанием клавиш, он видит, что выделено у пользователя:

const range = Coverse.table.getActiveRange();
if (!range) throw new Error("Выделите ячейки и запустите скрипт из таблицы");
range.setBackground("#ffeb9c");

getActiveSheet() возвращает открытый лист, getActiveCell() — ячейку с курсором. При запуске по расписанию, событию или вебхуку выделения нет, все три команды возвращают null.

Именованные диапазоны​

const rate = Coverse.table.getRangeByName("Ставка").getValue();
const names = Coverse.table.getNamedRanges(); // [{ name, sheet, range }]

Имена задаются в таблице. Скрипт их читает, но не создаёт и не меняет.

Что дальше​