К содержимому
Akmelo

Документация

JavaScript SDK: Worksheet: листы и ячейки

document.sheet(0) возвращает первый лист; выбор листа начинается с нуля, номера строк и столбцов — с единицы. Методы листа работают локально.

Примеры — отдельные фрагменты тела async function run(ctx). Используйте await только для методов с Promise в сигнатуре.

Как получить объект

const document = await ctx.documents().fromBytes('sku,price\nA-1,1250', 'report.csv');
const sheet = document.sheet(0);

Методы

name

sheet.name() → string

Имя листа в исходном файле.

const result = sheet.name();

rows

sheet.rows() → Array<Array<unknown>>

Все строки без предположений о заголовках. Пустые строки и промежутки сохраняются. Строки и столбцы массива индексируются с нуля.

const result = sheet.rows();

rowCount

sheet.rowCount() → number

Количество извлечённых строк, включая пустые. Это не число записей: у файла могут быть заголовки, итоги и несколько секций.

const result = sheet.rowCount();

columnCount

sheet.columnCount() → number

Ширина самой длинной извлечённой строки. У неполных строк недостающие ячейки остаются пустыми.

const result = sheet.columnCount();

cell

sheet.cell(address, resolveMerged) → string|number|boolean|null

Читает ячейку по адресу вроде B2. При resolveMerged=true берёт значение верхней левой ячейки объединённой области. Используйте относительный адрес без знаков $.

const result = sheet.cell('B2');

row

sheet.row(number) → Array<unknown>

Строка по номеру с единицы. За пределами листа возвращает пустой массив; нулевой и отрицательный номер вызывают ошибку.

const result = sheet.row(2);

column

sheet.column(column, startRow, endRow) → Array<unknown>

Столбец по буквам или номеру с единицы. startRow и endRow включительны. Пропущенные значения сохраняются как null.

const result = sheet.column('B');

range

sheet.range(range, resolveMerged) → Array<Array<unknown>>

Прямоугольная матрица A1:C10, включая пустоты. До 50 000 ячеек. resolveMerged=true размножает значение якоря объединения только в возвращаемом массиве. Обратные и неверные диапазоны вызывают ошибку.

const result = sheet.range('A1:B5');

nonEmptyRows

sheet.nonEmptyRows() → object

Непустые строки с исходными номерами в ключах с единицы. Значения 0 и false считаются данными, а не пустотой.

const result = sheet.nonEmptyRows();

find

sheet.find(text, exact, limit) → Array<{ address: string, value: unknown }>

Поиск по значениям без учёта регистра. exact=true требует полного совпадения. Возвращает address и value, максимум limit совпадений (1–1000). Формулы не исполняются и не участвуют в поиске вместо значений.

const result = sheet.find('A-1');

findHeader

sheet.findHeader(labels, maxRows) → number | null

Находит первую строку, в которой есть все перечисленные подписи. Сравнение без учёта регистра и пробелов по краям. По умолчанию проверяет первые 50 строк; maxRows от 1 до 5000. Если шапка не найдена, возвращает null. Для многоуровневой шапки используйте явные диапазоны.

const result = sheet.findHeader(['Артикул', 'Цена']);

merged

sheet.merged() → Array<unknown>

Список объединений XLSX/XLS вида A1:C1. Значения остальных ячеек по умолчанию не дублируются. В CSV объединений нет.

const result = sheet.merged();

formula

sheet.formula(address) → string | null

Исходный текст формулы XLSX с ведущим = или null. Расчётное значение читается через cell(), исходное выражение через formula(). Общие формулы зависимых ячеек могут не содержать полный текст: ориентируйтесь на сохранённое значение.

const result = sheet.formula('B2');

error

sheet.error(address) → string | null

Сохранённая ошибка XLSX, например #DIV/0!, либо null. Не подменяет ошибку нулём.

const result = sheet.error('B2');

records

sheet.records(headerRow, startRow, endRow) → Array<object>

Превращает выбранную секцию в записи. headerRow задаёт шапку с единицы, startRow/endRow задают включительный диапазон данных. headerRow=0 использует буквенные ключи A, B, C. Пустые строки пропускаются. Пустые подписи заменяются буквами, дубликаты получают суффиксы _2, _3 без потери полей. Итоги и примечания не распознаются автоматически: ограничьте диапазон явно.

const result = sheet.records(1);

structure

sheet.structure() → object

Обезличенная структура для AI-плана: rows, columns, merged и sample первых 24×16 ячеек. sample содержит только e (пусто), s (строка), n (число), b (логическое). Имена листов, заголовки, значения, ссылки и формулы отсутствуют. Сам метод не вызывает модель.

const result = sheet.structure();

calculation

sheet.calculation(address) → string

Статус пересчёта XLSX: calculated, unsupported, external_reference, circular_reference, error или limit. not_calculated означает, что формула есть, но пересчёт не проводился; not_formula означает обычную ячейку. Неподдерживаемые формулы дают явную ошибку, не ноль и не скрытую подмену старым значением.

const result = sheet.calculation('B2');

cachedValue

sheet.cachedValue(address) → string|number|boolean|null

Значение, которое автор XLSX сохранил в файле до пересчёта. Оно может отсутствовать или устареть. Для обычной ячейки совпадает с cell(). Используйте только как явно выбранный резерв: по умолчанию SDK возвращает пересчитанные значения.

const result = sheet.cachedValue('B2');