Как устроены диапазоны (A1-нотация)

Диапазон — это адрес ячейки или прямоугольной области в A1-нотации, как в привычных электронных таблицах.

Формы записи

Запись	Что означает
A1	одна ячейка
A1:C10	прямоугольник от A1 до C10
Лист1!A1:C10	тот же диапазон на конкретном листе
'Мой лист'!B2	лист с пробелом или спецсимволами — имя в одинарных кавычках

Открытые диапазоны

Запись	Что означает
A:A	весь столбец A
A:C	столбцы A–C целиком
1:1	вся строка 1
A1:A	от A1 и до конца данных столбца

Сервер разворачивает открытый диапазон по фактическому размеру данных и возвращает в ответе поле range с конкретными границами.

URL-кодирование

Если диапазон в пути содержит имя листа (!) или двоеточие (:), закодируйте его: Лист1!A1:C10 → Лист1%21A1%3AC10.

Что приходит в ответе

Значения — сетка по строкам (majorDimension: ROWS по умолчанию). Каждая ячейка — { v, m, f? }: v — исходное значение, m — как видит пользователь, f — формула (если есть). Пустая ячейка — null. Большие диапазоны разбиваются на страницы (pagination с hasMore и nextOffset).

Чтобы получить сетку по столбцам, добавьте ?majorDimension=COLUMNS — внутренние массивы cells станут столбцами. Пагинация при этом остаётся построчной.

Запись: привязка и ориентация

При записи (PUT .../values/{range}, append, batchUpdate) от диапазона в пути используется только верхняя-левая ячейка — как точка привязки. Какие ячейки реально запишутся, определяет форма матрицы values, а не размер диапазона; «хвост» диапазона игнорируется. Указывать многоячейковый диапазон необязательно — можно передать одну ячейку (A1).

Например, A1:A3 с телом {"values": [[10, 2, 5]]} запишет строку A1:C1 (матрица 1×3 от привязки A1), а не столбец A1:A3.

Чтобы записать столбец, есть два пути:

• передать матрицу столбцом: {"values": [[10],[2],[5]]};
• либо оставить строку и указать ориентацию: {"values": [[10,2,5]], "majorDimension": "COLUMNS"}.

В ответе на запись приходит updatedRange — фактический записанный диапазон с именем листа (например Лист 1!A1:C1), а также updatedRows, updatedColumns, updatedCells. Это удобно, чтобы точно видеть, куда легли данные.

Числа, даты, формулы

• v типизировано: числа — JSON-числа (1234.5), логические — true/false, текст — строка. Тип одинаков для всего столбца независимо от того, введено значение вручную или посчитано формулой. m — всегда строка по локали документа (1 234,50).
• Даты: в v — серийный номер (число дней от эпохи, например 46037), в m — готовая отформатированная строка. Конвертируйте serial у себя либо используйте m.
• Формулы пишите английскими именами с ; между аргументами: =SUM(A1;B1).

Полный список методов чтения и записи — в Справочнике API.