Сеанс и соглашения F1

Имена полей в F1 записываются слитно, со строчной первой буквы: subsetId, sheetKey, expectedRevision, requestId. Это отличается от A4, где слова разделены подчёркиванием — document_id, paragraph_index. Если вы встраиваете оба продукта, поле из одного в другом не найдётся.

Размеры листа приходят в единицах Excel, и они разные. Ширина колонки — в символьных единицах: одна единица равна ширине цифры в шрифте по умолчанию, и колонка обычной ширины — это 8.43, а не восемь пикселей. Высота строки — в пунктах, то есть в семьдесят вторых долях дюйма: обычная строка — 15. Пикселей в контракте нет ни там, ни там.

У самих операций стиля два, и это не опечатка: почти все записаны через подчёркивание — apply_cell_edits, save_workbook_subset, — а девятнадцать через дефис. Это семнадцать операций Power Query с приставкой pq- и две операции внешних диапазонов, external-range-properties-apply и external-range-properties-inventory. Имя операции передаётся буква в букву: приводить его к одному виду нельзя — ядро такой операции не знает.

Строки и столбцы считаются с нуля: первая строка — 0. Так же считаются границы видимой области. Диапазон описывается полями sheetKey, rowStart, rowEnd, colStart, colEnd.

Открытие книги — операциями open_workbook_subset или open_workbook_subset_from_bytes — возвращает subsetId. Все последующие операции над этой книгой передают его обратно: по нему ядро узнаёт, о каком открытом сеансе речь.

Поле expectedRevision — защита от гонки. Если оно передано и книга с тех пор изменилась, запрос отклоняется до правки, а не применяется поверх чужой. Поле необязательное: без него правка идёт безусловно.

Запросы видимой области и диапазона должны оставаться ограниченными: контракт не обещает развернуть книгу в память целиком, и запрос «отдай всё» рассчитывать не на что.

Успешный ответ может прийти с именем другой операции — той, к которой запрос свёлся внутри ядра:

• open_workbook_subset_from_bytes отвечает как open_workbook_subset;
• move_clipboard_range отвечает как paste_range;
• paste_conditional_formatting_rules отвечает как apply_conditional_formatting_rules.

Обработчик, который сверяет имя операции в ответе с отправленным, эти три случая не узнает. Связывать запрос с ответом нужно по идентификатору, а не по имени.

Поля, которые приходят почти всегда

Поле	Что означает
previewCells	Ячейки запрошенного участка: адрес, показанное значение, вид значения и исходная формула, если она есть. Это то, что рисуют на экране.
recalcNeeded	true, если в книге остались формулы, ждущие пересчёта. Значения в previewCells при этом уже показаны — но могут быть не окончательными.
supportedSubset	Строкой описано, какое подмножество формул ядро понимает в этом сеансе. Полезно показывать в диагностике, а не разбирать в коде.
dirtyCellCount	Сколько ячеек изменено с открытия книги. По нему удобно показывать признак несохранённого.
layoutMetrics	Раскладка листа: высоты строк, ширины столбцов, скрытые строки и столбцы, объединения. Приходит не в каждом ответе — только там, где нужна для отрисовки.