editCells

Данная статья предназначена для использования на версии API 3 и выше.

Для версии 2.0.2 и ниже используйте статью: editCells (legacy).

await crafttechApi.editCells(fileHandler, sheetName, data, replaceStyle=True);

Описание

Изменяет значение ячейки и применяет форматирование к ней.

Требует сохранения при помощи saveFile (для внешнего файла), либо applyActiveFileChanges (для активного файла).

С версии 1.0.3 указание всех RGB цветов доступно в привычном HEX-формате #FF12BC вместо FFFF12BC. Старый формат тоже обрабатывается.

Параметры

• fileHandler (number) — ссылка на файл; ссылку предоставляет метод openFile;
• sheetName (string) — название листа;
• data (object[]) — массив объектов; каждый из этих объектов содержит данные о конкретной ячейке, включая адрес, данные и стили (одна ячейка === один объект).

  • Для установки стиля передаётся объект с соответствующими полями и их значениями; в объекте должны быть только те стили, которые мы хотим задать. Например, чтобы изменить размер текста, достаточно передать в style { font: {fontSize: 13} }.

    • address (string) — передаётся адрес ячейки, которую хотим изменить;
    • value (string | number) — передаётся значение ячейки;
    • formula (object) — передается объект formula с полем formula, в котором хранится формула ячейки;
    • style (object) — конфигурация стилей ячейки.

    При этом остальные параметры стиля в ячейке вернутся к стандартным, так что при изменении или добавления параметра прописывайте все параметры которые были у ячейки!

• replaceStyle - Позволяет смешивать стили, если передать False , иначе перезапишет стиль ячейки полностью.

Доступные конфигурации стилей:

СТИЛЬ ТЕКСТА (font: {})

• bold (boolean) – полужирный шрифт;
• italic (boolean) – шрифт курсивом;
• underline (boolean) – нижнее подчёркивание;
• size (number) – размер шрифта (в pt);
• name (string) – название шрифта;
• color (object) – объект для указания цвета текста со следующими ключами:
  • rgb (string) – цвет текста (RGB);
  • indexed (number) – цвет текста (Индексированный);
  • theme (number) – цвет текста (Тема);
  • tint (number) – акцент белого с цветом темы от 0 до 1 (Применяется только в связке с theme).

ФОН (fill: {})

• patternType (string) - стиль паттерна, по умолчанию solid;
• fg (object) - объект с указанием параметров цвета переднего фона, ключи:
  • rgb (string) – цвет текста (RGB);
  • indexed (number) – цвет текста (Индексированный);
  • theme (number) – цвет текста (Тема);
  • tint (number) – акцент белого с цветом темы от 0 до 1 (Применяется только в связке с theme).
• bg (object) - объект с указанием параметров цвета заднего фона, ключи:
  • rgb (string) – цвет текста (RGB);
  • indexed (number) – цвет текста (Индексированный);
  • theme (number) – цвет текста (Тема);
  • tint (number) – акцент белого с цветом темы от 0 до 1 (Применяется только в связке с theme).

ГРАНИЦЫ (border)

• border: ‘string’ – быстрая настройка, позволяющая разом установить одни и те же стили для четырёх сторон ячейки (вверх, вниз, влево, вправо).

Таким способом можно изменить только style(например, thin), для более детального изменения нужно прописывать свойства для каждой границы, как показано ниже.

СВОЙСТВА ГРАНИЦ (border: {})

Далее идет определение полей объекта границ, если вам требуется более гибкая настройка. У границ есть направления(далее direction): left, right, top, bottom, diagonal. Описанные свойства применяются исключительно с прописыванием стороны, к которой применяется изменение. Например, для применения rgb цвета к левой стороне границы, необходимо написать:

{
  left: {
    color: {
      rgb: '#FF1133'
    }
  }
}

• {direction} (object) - объект для конкретного направления границы, например, left. у него есть следующие ключи:
  • style (str) - тип границы (например, thin);
  • color (object) - объект с указанием параметров цвета, ключи:
    • rgb (string) – цвет текста (RGB);
    • indexed (number) – цвет текста (Индексированный);
    • theme (number) – цвет текста (Тема);
    • tint (number) – акцент белого с цветом темы от 0 до 1 (Применяется только в связке с theme).

ВЫРАВНИВАНИЕ (alignment: {})

• alignment (object) - объект для указания выравнивания ячейки. Ключи:
  • horizontal (string) [“left”, “right”, “center”] – устанавливает горизонтальное выравнивание текста;
  • vertical (string) [“top”, “bottom”, “center”] – устанавливает вертикальное выравнивание текста;
  • wrapText (boolean) - указывает, будут ли слова в ячейке переноситься в соответствии с размером ячейки;
  • textRotation (number) - количество градусов, на которое необходимо повернуть текст.

Возвращает

• true | false (boolean) — возвращает логическую истину true в случае успешного изменения ячеек.

Пример

const editedCells = await crafttechApi.editCells(fileHandler, "Лист2", [
  {
    address: "A1",
    value: "hello",
    formula: { formula: "A13+A14" },
    style: {
      font: { bold: true, underline: true },
      border: { right: { style: "thin", color: {rgb: "#000000"} },
      fill: { bg: {rgb: "#2A8DD4"}, fg: {rgb: "#2A8DD4"} },
    },
  },
  {
    address: "B7",
    value: "planet",
    style: {
      border: "thin",
      font: { size: 13, italic: true, bold: true },
    },
  },
  {
    address: "C4",
    value: "dog",
  },
]);

console.log("Метод editCells вернул значение:", editedCells);

В данном случае:

• A1 – хранит значение “hello” с полужирным, подчёркнутым шрифтом и правая граница ячейки тонко окрашена, а также иметь заливку;
• B7 – хранит значение “planet” с полужирным шрифтом и курсивом, кегль 13pt, а границы ячейки тонко окрашены;
• C4 – хранит значение “dog” с прежними стилями (если они были);