getCellRange

await crafttechApi.getCellRange(fileHandler, sheetName, cellRange, flag);

Описание

Возвращает значения диапазона ячеек.

Параметры

• fileHandler (number) — ссылка на файл; ссылку предоставляет метод openFile;
• sheetName (string) — название листа;
• cell (string) — диапазон ячеек в строковом формате, адреса ячеек разделяются двоеточием (например: A1:C2, либо 1,1:2,3; во втором случае сначала передаётся строка, а потом столбец);
• flag (string | null) — флаг, указывающий, какие данные необходимо получить;
  • по умолчанию null, возвращает стили, значения и адреса;
  • доступны следующие флаги:
    • style - возвращает стили. (см. editCells (для версии 3 и выше) или editCells Legacy)
    • formula - возвращает формулы. (ключ formula.formula содержит формулу)
    • sizes - возвращает размеры ячеек. (sizes: {width: 9.14, height: 14.25})
    • shared-formula - возвращает “протянутые” формулы. (ключ formula.formula содержит “протянутую” формулу)
    • merge - возвращает диапазон мерджа, в который входит ячейка. (merge: 'A1:B10' | None)
    • hidden - возвращает поле hidden с булевым значением, в зависимости от видимости ячейки.
    • rich-text - флаг для версии API 3 и выше. возвращает структуру Rich-текста, если в ячейке присутствует разное форматирование текста, в поле value будет возвращен массив с текстами, а в поле style - массив с объектами форматирования (для форматирования см. editCells (для версии 3 и выше)).
• Флаги необходимо указывать через запятую. Например, если вы хотите получить стили и формулы, необходимо написать style, formula.

Возвращает

• cellRange (object[][]) — двумерный массив значений диапазона ячеек; данные ячеек представляют собой объект, в котором строковое или числовое значение ячейки хранится под ключом value, стиль ячейки со всеми полями хранится под ключом style, а также объект с ключом address, в котором хранятся три поля:

  • cell (string) — строковое представление адреса;
  • col (number) — числовое значение колонки;
  • row (number) — числовое значение ряда.

  Помимо этого, при передаче флага sizes, вы получаете в объекте ячейки поле size, в котором хранятся два ключа:

  • height (number) — высота строки ячейки в пунктах;
  • width (number) — ширина столбца ячейки в символах;

Пример

const fileHandler = await crafttechApi.openFile("book.xlsx");
const range = await crafttechApi.getCellRange(fileHandler, "Лист1", "A1:C3");
console.log("Содержимое ячеек A1:C3: ", range);

Вывод:

[
  [
    {
      value: "Word",
      style: { font: { bold: true } },
      address: { cell: "A1", col: 1, row: 1 },
    },
    { value: "Time", style: {}, address: { cell: "B1", col: 2, row: 1 } },
    { value: "Number", style: {}, address: { cell: "C1", col: 3, row: 1 } },
  ],
  [
    { value: "Water", style: {}, address: { cell: "A2", col: 1, row: 2 } },
    { value: "Day", style: {}, address: { cell: "B2", col: 2, row: 2 } },
    { value: "Part", style: {}, address: { cell: "C2", col: 3, row: 2 } },
  ],
  [
    { value: "Place", style: {}, address: { cell: "A3", col: 1, row: 3 } },
    { value: 4444, style: {}, address: { cell: "B3", col: 2, row: 3 } },
    { value: "Back", style: {}, address: { cell: "C3", col: 3, row: 3 } },
  ],
];

В данном случае массив содержит в себе данные трёх рядов из заданного диапазона на листе «Лист1». Порядок рядов хранится сверху-вниз. Данные ячеек хранятся слева-направо: первое значение — это самый левый ряд.