Справочник команд скриптов

Здесь собраны все команды скриптов Coverse. Подробные объяснения и примеры — в тематических статьях, ссылки на них даны в каждом разделе. Тот же справочник с поиском открывается во вкладке «Справка» редактора.

Строки и столбцы нумеруются с 1. Адреса пишутся как в таблице: "A1", "A2:C10", "A:A", "A2:G" (со второй строки до конца листа).

Объекты верхнего уровня

Объект	Для чего
Coverse.table	таблица, в которой лежит скрипт
Coverse.tables	другие таблицы с вкладки «Таблицы»
event	данные события, которые получает функция триггера
Http	запросы к внешним сервисам
Telegram	сообщения в Telegram
Mail	письма
Secrets	ключи и токены с вкладки «Секреты»
Properties	«Память» скрипта и таблицы
CoverseAI	запросы к ИИ
Library	подключение библиотек
Utilities	даты, числа, CSV, кодирование и подписи
console	журнал запуска

Таблица: Coverse.table

Подробнее: Работа с данными таблицы.

Команда	Что делает
getSheets()	все листы таблицы по порядку
getSheet(name)	лист по названию; если листа нет, скрипт останавливается с ошибкой
getSheetByName(name)	лист по названию или null
insertSheet(name)	создаёт лист в конце таблицы и возвращает его; без названия имя подбирается само; если лист с таким названием есть, будет ошибка
copySheet(sheet, name)	копия листа в этой таблице: данные, формулы, оформление, объединения, списки, подсветка и фильтр; защита, комментарии, режимы фильтра и связь с формой не копируются
moveSheet(sheet, position)	ставит лист на позицию среди ярлыков, позиции с 1 вместе со скрытыми листами
deleteSheet(sheet)	удаляет лист по названию или объекту, отменить нельзя; последний лист удалить нельзя
insertPivotTable(options)	создаёт сводную таблицу на отдельном листе и возвращает этот лист, см. Сводная таблица
getActiveSheet()	лист, открытый у того, кто запустил скрипт из таблицы, иначе null
getActiveRange()	выделенный диапазон у того, кто запустил скрипт из таблицы, иначе null
getActiveCell()	ячейка с курсором у того, кто запустил скрипт из таблицы, иначе null
getRangeByName(name)	диапазон по имени, заданному в таблице, или null; регистр не важен
getNamedRanges()	все именованные диапазоны с полями name, sheet, range
flush()	сразу отправляет в таблицу накопленные изменения

Выделение есть только при запуске кнопкой «Запустить», из меню «Макросы», кнопкой на листе или сочетанием клавиш. Выделить диапазон за пользователя скрипт не может.

Лист

Лист возвращают getSheet, getSheetByName, getSheets, insertSheet, copySheet и range.getSheet().

Данные

Команда	Что делает
getName()	название листа
setName(name)	переименовывает лист, до 100 знаков, без символов [ ] : ? ! * / ' "; формулы со старым названием на других листах не обновляются
getRange("A1:C10")	диапазон по адресу, без названия листа
getRange(row, column, rows, columns)	диапазон по номерам: первая строка, первый столбец, число строк, число столбцов; последние два можно не указывать
getDataRange()	диапазон всех заполненных ячеек листа
getLastRow()	номер последней строки с данными
getLastColumn()	номер последнего столбца с данными
appendRow(values)	добавляет строку в конец листа
appendRows(rows)	добавляет несколько строк за один вызов

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

Команда	Что делает
insertRowsBefore(row, count), insertRows(row, count)	вставляет пустые строки перед указанной
insertRowsAfter(row, count)	вставляет строки после указанной
insertRowBefore(row), insertRowAfter(row)	вставляет одну строку
insertColumnsBefore(column, count), insertColumns(column, count)	вставляет столбцы перед указанным
insertColumnsAfter(column, count)	вставляет столбцы после указанного
insertColumnBefore(column), insertColumnAfter(column)	вставляет один столбец
deleteRow(row), deleteRows(row, count)	удаляет строки вместе с данными
deleteColumn(column), deleteColumns(column, count)	удаляет столбцы вместе с данными
moveRows(row, count, before)	переносит строки целиком перед строкой before
moveColumns(column, count, before)	переносит столбцы целиком перед столбцом before
hideRows(row, count), showRows(row, count)	скрывает и показывает строки; данные остаются доступны скрипту
hideColumns(column, count), showColumns(column, count)	скрывает и показывает столбцы
setRowHeight(row, height)	высота строки в пикселях, от 5 до 1000
setRowHeights(row, count, height)	высота нескольких строк подряд
setColumnWidth(column, width)	ширина столбца в пикселях, от 5 до 2000
setColumnWidths(column, count, width)	ширина нескольких столбцов подряд
setFrozenRows(count), setFrozenColumns(count)	закрепляет первые строки или столбцы, 0 снимает закрепление
getFrozenRows(), getFrozenColumns()	сколько строк или столбцов закреплено

Вставка, удаление и перенос не работают на листе с диаграммами, импортом из другой таблицы, сводной таблицей, защищёнными или именованными диапазонами, формулой, которая заполняет несколько ячеек, ответами формы или сохранёнными режимами фильтра, а также в закреплённых строках и столбцах. Перенос не работает и на листе с фильтром. Лимиты — в статье Лимиты.

Вид листа

Команда	Что делает
setTabColor(color)	цвет ярлыка "#rrggbb", null убирает цвет
hideSheet(), showSheet()	скрывает и показывает лист; данные остаются доступны скрипту и формулам; последний видимый лист скрыть нельзя
isSheetHidden()	скрыт ли лист

Подсветка, проверка данных, фильтр, защита, диаграммы, сводные

Команда	Что делает
getConditionalFormats()	правила подсветки листа с полями id, range, condition, format
clearConditionalFormats()	удаляет все правила подсветки листа и возвращает их число
getDataValidations()	все правила проверки данных листа
getFilter()	фильтр листа или null
protect(options)	защищает лист, { except: ["B2:B50"] } оставляет ячейки открытыми, name задаёт название
unprotect()	снимает защиту листа
getProtections()	защиты листа с полями type, name, range, except, editors
insertChart(options)	добавляет диаграмму, см. Диаграмма
getCharts()	диаграммы листа
getPivotTables()	описания сводных таблиц листа

Подробнее: Оформление и структура.

Диапазон

Диапазон возвращают sheet.getRange, sheet.getDataRange, Coverse.table.getActiveRange и getRangeByName.

Адрес и размер

Команда	Что делает
getA1Notation()	адрес текстом, например "A2:C10"
getSheet()	лист диапазона
getRow(), getColumn()	номер первой строки и первого столбца
getLastRow(), getLastColumn()	номер последней строки и последнего столбца
getNumRows(), getNumColumns()	число строк и столбцов

Для диапазонов без последней строки или столбца, например "A:A" или "A2:A", команды getLastRow, getLastColumn, getNumRows и getNumColumns дают ошибку.

Значения и формулы

Команда	Что делает
getValues()	значения: массив строк, каждая строка — массив ячеек; дата приходит как Date, число числом, флажок как true или false, остальное текстом
getValue()	значение левой верхней ячейки
getDisplayValues(), getDisplayValue()	значения так, как они показаны в ячейках
getFormulas(), getFormula()	формулы диапазона или левой верхней ячейки
setValues(rows)	записывает значения; размер массива должен совпадать с диапазоном
setValue(value)	записывает значение в ячейку
setFormulas(rows)	своя формула в каждую ячейку; пустая строка очищает ячейку
setFormula(formula)	записывает формулу в одну ячейку
clear()	очищает значения диапазона

Числа передавайте числами: 12.5 станет числом, а "12.5" останется текстом. Значение, которое начинается с =, считается формулой. Функции в формулах пишутся по-английски (SUM, IF, VLOOKUP), аргументы через точку с запятой, дробная часть через точку.

Оформление

Команды оформления возвращают тот же диапазон, их можно писать цепочкой: range.setBackground("#fff2cc").setFontWeight("bold").

Команда	Что делает
setBackground(color)	заливка, null убирает
setFontColor(color)	цвет текста
setFontWeight("bold")	"bold" или "normal"
setFontStyle("italic")	"italic" или "normal"
setFontLine("underline")	"underline", "line-through" или "none"
setFontSize(size)	размер от 1 до 400
setFontFamily(name)	шрифт: Arial, Roboto, Open Sans, Noto Sans, Times New Roman, PT Sans, PT Serif, PT Astra Sans, PT Astra Serif, PT Root UI, PT Mono
setHorizontalAlignment(value)	"left", "center", "right" или "normal"
setVerticalAlignment(value)	"top", "middle" или "bottom"
setWrap(true)	перенос текста по словам, false отключает
setNumberFormat(format)	числовой формат: "#,##0.00", "0%", "#,##0.00 ₽", "dd.mm.yyyy", "@" (текст)
setBorder(top, left, bottom, right, vertical, horizontal, color, style)	границы: true рисует, false убирает, null не трогает; стиль "solid", "dotted", "dashed", "solid_medium", "solid_thick"
copyFormatTo(range)	копирует оформление и числовой формат на другие ячейки, значения не меняются

Цвет задаётся как "#rrggbb", "#rgb", "rgb(255, 242, 204)" или английским названием ("red", "lightgray"). Оформление работает только в своей таблице.

Примечания

Команда	Что делает
setNote(text)	одно примечание всем ячейкам диапазона, пустой текст удаляет
setNotes(rows)	своё примечание каждой ячейке
getNote()	примечание левой верхней ячейки
getNotes()	примечания диапазона массивом
clearNote()	удаляет примечания диапазона

Объединение, сортировка, копирование

Команда	Что делает
merge()	объединяет ячейки, остаётся значение первой непустой
mergeAcross()	объединяет отдельно в каждой строке
mergeVertically()	объединяет отдельно в каждом столбце
breakApart()	снимает объединения, которые задевает диапазон
getMergedRanges()	объединённые диапазоны
isPartOfMerge()	есть ли в диапазоне объединения
sort(column)	сортирует строки по столбцу листа
sort({ column, ascending })	сортировка по убыванию: ascending: false
sort([{ column: 3 }, { column: 2, ascending: false }])	сортировка по нескольким столбцам
copyTo(range)	копирует значения, формулы, оформление, примечания и ссылки; место назначения задаётся левой верхней ячейкой

Подсветка

Команда	Что делает
setConditionalFormat(condition, format)	правило подсветки; повторный вызов с теми же параметрами второе правило не создаёт
clearConditionalFormats()	удаляет правила, которые целиком лежат внутри диапазона, и возвращает их число

Условия: greaterThan, greaterThanOrEqual, lessThan, lessThanOrEqual, equalTo, notEqualTo, between: [от, до], textContains, textEquals, duplicates: true, unique: true, formula. Оформление: background, color, bold, italic, strike.

sheet.getRange("A2:G").setConditionalFormat({ formula: '=$E2="Не оплачен"' }, { background: "#ffc7ce" });

Выпадающие списки и флажки

Команда	Что делает
setDataValidation({ list: [...] })	выпадающий список; colors: [...] задаёт цвета вариантов
setDataValidation({ listFromRange: range })	список из ячеек, можно с другого листа
setDataValidation({ checkbox: true })	флажки
getDataValidation()	правило левой верхней ячейки или null
clearDataValidations()	удаляет правила диапазона

Фильтр и защита

Команда	Что делает
createFilter()	включает фильтр на диапазоне, первая строка — заголовки; возвращает фильтр
protect(options)	закрывает диапазон для всех, кроме владельца таблицы; name задаёт название
unprotect()	снимает защиту диапазонов внутри указанного

Менять защиту может только скрипт владельца таблицы. Как скрипты подчиняются защите: Права и безопасность.

Фильтр

Фильтр возвращают range.createFilter() и sheet.getFilter().

Команда	Что делает
setColumnFilter(column, condition)	оставляет строки, подходящие под условие; столбец — номер на листе
getColumnFilter(column)	условие столбца
removeColumnFilter(column)	снимает условие столбца
getRange()	диапазон фильтра
remove()	удаляет фильтр и показывает все строки

Условия: values: [...], hideValues: [...], greaterThan, greaterThanOrEqual, lessThan, lessThanOrEqual, equalTo, notEqualTo, between: [от, до], notBetween, textContains, textNotContains, textStartsWith, textEndsWith, textEquals, empty: true, notEmpty: true. Текст сравнивается с учётом регистра. Фильтр применяется один раз и не распространяется на строки, которые появятся позже.

Диаграмма

sheet.insertChart(options) добавляет диаграмму и возвращает её, sheet.getCharts() возвращает все диаграммы листа.

Параметр	Что задаёт
type	"column", "bar", "line", "area", "pie"
range	данные: первая строка — названия рядов, первый столбец — подписи
title	заголовок
position	ячейка левого верхнего угла, по умолчанию справа от данных
width, height	размер в пикселях
stacked: true	накопление для column, bar, area
smooth: true	сглаженная линия
donut: true	кольцо вместо круга

Команда	Что делает
getId(), getType(), getTitle(), getRange(), getOptions()	свойства диаграммы
update(options)	меняет параметры
refresh()	обновляет снимок данных после записи значений
remove()	удаляет диаграмму

Сводная таблица

Coverse.table.insertPivotTable(options) создаёт сводную на отдельном листе и возвращает лист. Результат можно сразу прочитать через getDataRange().getValues().

Параметр	Что задаёт
source	диапазон со строкой заголовков или адрес "Заказы!A1:G500"
rows, columns	названия столбцов или { field, group, order, total, name }; group: "month" группирует даты по месяцам, group: { every: 1000 } числа по интервалам
values	показатели { field, summarize, showAs }
filters	{ field, hide: [...] } или { field, show: [...] }
name	название листа
replace: true	пересчитать сводную с тем же названием на её листе

summarize: sum, count, counta, countunique, average, max, min, median, product, stdev, stdevp, var, varp. showAs: percentOfTotal, percentOfColumn, percentOfRow, runningTotal, rank, difference. Вычисляемое поле: { name: "Средний чек", formula: "=Сумма / Штук" }.

Другие таблицы: Coverse.tables

Подробнее: Другие таблицы.

Команда	Что делает
Coverse.tables.open(idOrLink)	открывает таблицу с вкладки «Таблицы» по идентификатору или ссылке
Coverse.tables.list()	таблицы, которые скрипт может открыть, с полями id, name

У открытой таблицы есть getId(), getName(), getSheets(), getSheet(name), getSheetByName(name) и flush().

У её листа: getName, getRange, getDataRange, getLastRow, getLastColumn, appendRow, appendRows.

У диапазона: команды адреса и размера, getValues, getValue, getDisplayValues, getDisplayValue, getFormulas, getFormula, setValues, setValue, setFormulas, setFormula, clear. Остальные команды листа и диапазона в другой таблице недоступны.

События триггеров

Функция, которую вызывает триггер, получает событие первым параметром. Поле event.type указывает вид события: "edit", "form_submit", "open" или "webhook". При ручном запуске кнопкой «Запустить» события нет. Подробнее: Триггеры и Вебхуки.

При изменении

Поле	Что содержит
event.changes	изменённые ячейки: sheet, cell, row, column, value, displayValue, formula
event.authors	кто внёс изменения: id, name
event.source	"user", "api" или "mixed"
event.sheet, event.range, event.value	лист, адрес текстом и значение первой изменённой ячейки
event.cellCount	сколько ячеек изменилось всего
event.truncated	true, если пришли не все ячейки или длинные значения обрезаны

При отправке формы

Поле	Что содержит
event.answers	ответы: question, answer
event.namedValues	ответы по тексту вопроса, у каждого вопроса массив: event.namedValues["Имя"][0]
event.values	ответы списком в порядке вопросов
event.form	id и title формы
event.sheet, event.row	лист и строка, куда записан ответ
event.submittedAt	время отправки
event.respondent	кто отправил, если ответ дал вошедший пользователь, иначе null

При открытии

Поле	Что содержит
event.openedAt	время открытия
event.authors	кто открыл: id, name

По вебхуку

Поле	Что содержит
event.json	тело запроса, разобранное из JSON, или null
event.form	поля формы для application/x-www-form-urlencoded
event.body	тело запроса текстом
event.query	параметры адреса
event.headers	заголовки запроса
event.method	метод запроса
event.contentType	тип содержимого
event.ip	адрес отправителя
event.receivedAt	время получения

Http

Подробнее: Внешние сервисы.

Команда	Что делает
Http.fetch(url, options)	запрос к внешнему сервису
Http.get(url, options)	запрос GET
Http.post(url, body, options)	запрос POST

Параметры options:

Параметр	Что задаёт
method	GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
headers	заголовки запроса
query	параметры адреса объектом
body	строка или объект; объект отправляется как JSON
timeout	ожидание ответа в миллисекундах, не больше 15 секунд
redirect	"follow" (по умолчанию) или "manual"

Ответ:

Поле или команда	Что возвращает
response.status	код ответа
response.ok	true для кодов 200–299
response.url	адрес, с которого пришёл ответ
response.headers	заголовки ответа объектом, названия в нижнем регистре
response.header(name)	заголовок ответа или null
response.text()	ответ текстом
response.json()	ответ, разобранный из JSON

Telegram

Подробнее: Внешние сервисы.

Команда	Что делает
Telegram.send(chat, text, options)	отправляет сообщение; chat — числовой идентификатор чата или "@канал"; возвращает { messageId, parts }

Параметр	Что задаёт
parseMode	"HTML", "Markdown" или "MarkdownV2"
silent: true	без звука
disablePreview: true	без предпросмотра ссылок
threadId	номер темы в группе с темами
secret	название секрета с токеном бота вместо TELEGRAM_BOT_TOKEN
token	токен бота прямо в вызове; надёжнее хранить его в секрете

Mail

Подробнее: Внешние сервисы.

Команда	Что делает
Mail.send(to, subject, text, options)	отправляет письмо и возвращает число адресатов; to — адрес, массив или строка через запятую, до 10 адресатов
Mail.remaining()	скольким адресатам ещё можно отправить письма сегодня

Параметры: htmlBody — текст с разметкой (абзацы, жирный, курсив, ссылки, списки, таблицы), replyTo — адрес для ответа.

Secrets

Подробнее: Секреты.

Команда	Что делает
Secrets.get(name)	значение секрета или null
Secrets.has(name)	задан ли секрет

Properties

Подробнее: Память скрипта. Properties.script доступна только этому скрипту, Properties.table всем скриптам таблицы. Команды у них одинаковые.

Команда	Что делает
get(key)	значение строкой или null
set(key, value)	сохраняет строку, число или true/false; читаются обратно строкой
getJson(key)	объект или массив, сохранённый через setJson
setJson(key, value)	сохраняет объект или массив
has(key)	есть ли ключ
delete(key)	удаляет ключ
keys()	все ключи
getAll()	объект со всеми парами «ключ: значение»
clear()	удаляет все ключи хранилища

CoverseAI

Подробнее: ИИ в скриптах.

Команда	Что делает
CoverseAI.ask(prompt, options)	отправляет запрос ИИ и возвращает ответ текстом

Параметр	Что задаёт
system	указания: в каком виде отвечать, какую роль играть
data	данные таблицей, первая строка — заголовки
json: true	вернуть готовый объект или массив вместо текста

Library

Подробнее: Библиотеки.

Команда	Что делает
Library.use("name")	подключает библиотеку рабочего пространства и возвращает объект с её функциями; имя пишется строкой прямо в вызове

Utilities

Подробнее: Даты, числа и утилиты. Даты считаются в часовом поясе владельца скрипта.

Даты

Команда	Что делает
Utilities.timezone	часовой пояс владельца скрипта
Utilities.today()	начало сегодняшнего дня
Utilities.startOfDay(date)	начало дня
Utilities.startOfWeek(date)	понедельник недели
Utilities.startOfMonth(date)	первое число месяца
Utilities.addDays(date, days)	новая дата, сдвинутая на число дней
Utilities.daysBetween(from, to)	разница в днях
Utilities.dateParts(date)	year, month, day, hour, minute, second, weekday (1 — понедельник)
Utilities.toDate(value)	дата из значения ячейки или текста, иначе null
Utilities.parseDate(text, pattern, timezone)	текст в дату по шаблону
Utilities.formatDate(date, pattern, timezone)	дата текстом по шаблону: yyyy, MM, dd, HH, mm, ss, MMMM, LLLL, EEEE

Без параметра startOfDay, startOfWeek, startOfMonth и dateParts считают от текущего момента.

Числа и текст

Команда	Что делает
Utilities.formatNumber(number, options)	число с разделителями; decimals, currency: "RUB", percent: true, grouping: false
Utilities.formatString(template, ...values)	подстановка в шаблон: %s, %d, %.2f, %05d, %%
Utilities.parseCsv(text, delimiter)	CSV в массив строк; все ячейки текстом
Utilities.uuid()	новый уникальный идентификатор
Utilities.sleep(ms)	пауза, не больше 10 секунд за вызов

Кодирование и подписи

Команда	Что делает
Utilities.base64Encode(text), Utilities.base64Decode(text)	base64
Utilities.base64EncodeWebSafe(text), Utilities.base64DecodeWebSafe(text)	base64 для адресов
Utilities.hash(algorithm, text, output)	хеш: md5, sha1, sha256, sha384, sha512
Utilities.hmac(algorithm, text, key, output)	HMAC-подпись, алгоритмы те же
Utilities.rsaSign(algorithm, text, key, output)	подпись закрытым ключом RSA в формате PEM, до 4096 бит; sha1, sha256, sha384, sha512

output: "hex", "base64" или "base64url". По умолчанию hash и hmac возвращают hex, rsaSign — base64.

console

Команда	Что делает
console.log(...), console.info(...)	строка в журнал запуска
console.warn(...)	строка с пометкой предупреждения
console.error(...)	строка с пометкой ошибки
Logger.log(...)	то же, что console.log
throw new Error(text)	останавливает скрипт, запуск помечается как «Ошибка»
return value	значение, которое вернула функция, показывается в журнале