allorion-exporting-html-to-xlsx

v1.8.6

Published

4 months ago

NPM module for converting HTML content into formatted XLSX documents.

Downloads

0High
0Medium
0Low

allori

Allorion Exporting HTML to XLSX

npm license

📦 Описание

Этот модуль позволяет экспортировать HTML-разметку в формат (XLSX), учитывая кастомные dataset-атрибуты на HTML-элементах. Подходит для использования в любом JavaScript-фреймворке, а также в средах Node.js и Bun.

Полностью типизирован и написан на TypeScript.

🚀 Установка

npm install allorion-exporting-html-to-xlsx
# или
bun add allorion-exporting-html-to-xlsx

✅ Поддержка

✅ React, Vue, Angular, Svelte и любые другие JS-фреймворки
✅ Node.js, Bun
✅ TypeScript

🔑 Лицензирование

Для использования модуля необходимо приобрести лицензию. Для получения ключа лицензии и подписи обратитесь в Telegram @a11ori.

Пример инициализации модуля:

const license = {
  licenseKey: "licenseKey",
  signature: "signature",
};

export const exportHtmlToXlsx = await initializeModule(license);

🧩 Использование

📁 Пример вызова функции:

const exportToXlsx = async () => {
  const response = await exportingHtmlToXlsx({
    fileName: "test",
    divId: "tab-export",
  });
};

📝 HTML-разметка с поддержкой dataset (Пример использования)

<div
  id="tab-export"
  data-column-width="C:20; D:F:25; G:30"
  data-row-height="1:50; 3:6:40; 8:60"
>
  <h1 data-no-export>Заголовок первого уровня</h1>
  <h2>Заголовок второго уровня</h2>
  <h3>Заголовок третьего уровня</h3>

  <p>Обычный текст</p>
  <p data-text-bold>Жирный текст</p>
  <p data-text-underlined>Подчеркнутый текст</p>
  <p data-text-italic>Курсивный текст</p>
  <p data-cell-address="G1">Фиксированная ячейка G1</p>

  <p data-text-color="FFFF0000">Текст красного цвета</p>
  <p data-fill-color="FFFF0000">Красная заливка</p>

  <p data-cell-format="{...}">Форматированное значение</p>

  <p data-no-export>Этот текст не будет экспортирован</p>

  <p data-column-width="10">Ширина столбца в котором находится ячейка 10</p>

  <p data-row-height="50">Высота строки в которой находится ячейка 50</p>

  <p data-alignment-h="center">Текст ячейки по центру</p>

  <p data-alignment-v="top">Текст ячейки по центру</p>

  <p data-alignment-v="top" data-alignment-h="center">
    Текст ячейки сверху по центру
  </p>

  <p data-text-wrap>Текст переносится внутри ячейки</p>

  <br />

  <table>
    <thead>
      <tr>
        <th rowspan="2">Колонка 1</th>
        <th rowspan="2">Колонка 2</th>
        <th colspan="3">Колонка 3</th>
      </tr>
      <tr>
        <th>Подколонка 3.1</th>
        <th>Подколонка 3.2</th>
        <th>Подколонка 3.3</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>Ячейка 1</td>
        <td>Ячейка 2</td>
        <td>Ячейка 3.1</td>
        <td>Ячейка 3.2</td>
        <td>Ячейка 3.3</td>
      </tr>
    </tbody>
  </table>
</div>

⚙️ Поддерживаемые dataset-атрибуты

Общие:

data-no-export — исключает элемент из экспорта
data-cell-address — фиксирует позицию ячейки (например, G1)

Стили текста:

data-text-bold — жирный текст
data-text-underlined — подчеркнутый текст
data-text-italic — курсив
data-text-color — цвет текста в формате ARGB (например, FFFF0000 для красного)
data-fill-color — цвет заливки в формате ARGB

Формат ячеек:

data-cell-format — принимает строку с форматом для XLSX. Он позволяет задавать стандартные форматы с использованием numFmtId (которые можно найти в таблице ниже, например data-cell-format='{"numFmtId": 2}'), а также поддерживает добавление пользовательских форматов через объект formatCode содержащий поле code (например, { code: "#,##0" }), и type (например, data-cell-format='{ code: "D MMMM YYYY", type: "s" }'). Список доступных типов также приведён в таблице ниже.

Объединение ячеек (только для p и h):

data-merge-horizontal="N" — объединить ячейку по горизонтали на N колонок
data-merge-vertical="N" — объединить по вертикали на N строк
data-merge-all="NxM" — объединение по горизонтали и вертикали

Изменение ширины столбца:

data-column-width="width" — Указывает только числовое значение ширины (width). В этом случае номер столбца будет вычисляться автоматически.
data-column-width="column:width" — Указывает номер и ширину столбца (column - буквенное обозначение столбца, width - числовое значение ширины)
data-column-width="startColumn:endColumn:width" — Указывает диапазон столбцов и ширину столбца (startColumn - буквенное обозначение начального столбца, endColumn - буквенное обозначение конечного столбца, width - числовое значение ширины)

Изменение высоты строки:

data-row-height="height" — Указывает только числовое значение высоты (height). В этом случае номер строки будет вычисляться автоматически.
data-row-height="row:height" — Указывает номер и высоту строки (row - буквенное обозначение строки, height - числовое значение высоты)
data-row-height="startRow:endRow:height" — Указывает диапазон и высот строк (startRow - буквенное обозначение начальной строки, endRow - буквенное обозначение конечной строки, height - числовое значение высоты)

Выравнивание:

data-alignment-h="left" — Выравнивание по левому краю
data-alignment-h="center" — Выравнивание по центру
data-alignment-h="right" — Выравнивание по правому краю
data-alignment-v="top" — Выравнивание по верху
data-alignment-v="center" — Выравнивание по центру
data-alignment-v="bottom" — Выравнивание по низу

Перенос текста:

data-text-wrap — Перенос текста внутри ячейки

📌 Примечания

Все dataset, применимые к <p>, также работают на <h1>–<h6> и <span> (кроме объединения).
Таблицы поддерживают colSpan и rowSpan для объединения, а также все dataset, применимые к <p> (кроме объединения).
Структура сохраняется, включая вложенные span внутри p.

Таблица стандартных форматов ячеек (numFmtId)

| numFmtId | Описание | Формат-код | | ------------ | --------------------------------------------------- | -------------- | | 0 | Общий формат | s | | 1 | Целое число (0) | null | | 2 | Число (0.00) | null | | 3 | Число с разделителями (например, 1,000) | null | | 4 | Число с разделителями и двумя знаками после запятой | null | | 9 | Процент (0%) | null | | 10 | Процент с двумя знаками после запятой (0.00%) | null | | 11 | Экспоненциальный формат (0.00E+00) | null | | 14 | Дата (mm-dd-yy) | d | | 15 | Дата (d-mmm-yy) | d | | 16 | Дата (d-mmm) | d | | 17 | Дата (mmm-yy) | d | | 18 | Время (h:mm AM/PM) | d | | 19 | Время (h:mm:ss AM/PM) | d | | 20 | Время (h:mm) | d | | 21 | Время (h:mm:ss) | d | | 22 | Дата и время (m/d/yy h:mm) | d | | 49 | Текст (строка) | s |

Таблица типов ячеек

| Тип | Описание | | ----------- | ---------------------------------------------------------------- | | `s` | Строка (обычный текст) | | `b` | Булево (True или False) | | `d` | Дата (например, формат даты "mm-dd-yy" или "d-mmm-yy") | | `e` | Ошибка (например, #DIV/0!) | | `inlineStr` | Встроенная строка (строка, заключённая непосредственно в ячейке) | | `str` | Строка (аналогично `s`, но используется для других типов строк) | | `n` | Число (по умолчанию используется для числовых значений) | | `null` | Число (если не указано иное, то ячейка считается числовой) |

Руководство по пользовательским форматам чисел в Excel (Custom Number Formats)

Пользовательские форматы в Excel — это специальный синтаксис, который управляет отображением значения, не изменяя фактическое содержимое ячейки. Этот стандарт используется не только в Excel, но и в большинстве табличных редакторов и библиотек генерации файлов (например, SheetJS, ExcelJS).

Важно: В коде формата всегда используется американский стандарт:
Точка . — разделитель дробной части.
Запятая , — разделитель тысяч.
Excel автоматически заменит их на региональные символы при отображении (например, запятую и пробел для РФ).

1. Общая структура формата

Формат может состоять из одной или четырёх секций, разделённых точкой с запятой ;.

Синтаксис:

ПОЛОЖИТЕЛЬНЫЕ ; ОТРИЦАТЕЛЬНЫЕ ; НОЛЬ ; ТЕКСТ

Пример:

#,##0.00;[Red]-#,##0.00;"-";@

Расшифровка:

Положительные числа — #,##0.00 (разделители тысяч, 2 знака после запятой).
Отрицательные числа — [Red]-#,##0.00 (красный цвет и явный знак минус).
Ноль — "-" (вместо 0 выводится прочерк).
Текст — @ (отображается без изменений).

Если указана одна секция, она применяется ко всем значениям.

2. Форматирование чисел

Базовые символы для построения числовых форматов:

| Символ | Назначение | Пояснение | | ------- | ---------------------- | ----------------------------------------------------------------------------------------------------- | | 0 | Обязательная цифра | Всегда отображается. Если цифры нет — выводится 0. Полезно для фиксированной длины и дробной части. | | # | Необязательная цифра | Отображается только при наличии значащей цифры. Лишние нули скрываются. | | . | Десятичный разделитель | Отделяет целую часть от дробной. | | , | Разделитель тысяч | Включает группировку разрядов (обычно по 3 цифры). |

Примеры числовых форматов

| Исходное значение | Код | Результат | Комментарий | | ----------------- | ----------- | ------------- | ------------------------------------- | | 1234.567 | 0 | 1235 | Округление до целого. | | 1234.567 | 0.00 | 1234.57 | Ровно 2 знака после запятой. | | 5.1 | 0.00 | 5.10 | Добавляет недостающий ноль. | | 0.5 | #.## | .5 | Ведущий ноль скрыт. | | 1234567 | #,##0 | 1 234 567 | Группировка тысяч. | | 1231.213 | #,##0.000 | 1 231.213 | Тысячи + 3 знака дроби. | | 15 | 00000 | 00015 | Фиксированная длина (артикулы, коды). |

3. Даты и время

В Excel даты и время хранятся как числа, поэтому корректный формат критически важен для отображения.

| Категория | Код | Описание | Пример (5 янв 2025) | | --------- | ---------- | ------------------------ | ------------------- | | День | d | День без ведущего нуля | 5 | | | dd | День с нулём | 05 | | | ddd | День недели (кратко) | Вс | | | dddd | День недели (полностью) | Воскресенье | | Месяц | m | Месяц без нуля | 1 | | | mm | Месяц с нулём | 01 | | | mmm | Название месяца (кратко) | янв | | | mmmm | Полное название месяца | Январь | | | mmmmm | Первая буква месяца | Я | | Год | yy | Год (2 цифры) | 25 | | | yyyy | Год (4 цифры) | 2025 | | Время | h / hh | Часы (0–23) | 9 / 09 | | | m / mm | Минуты* | 05 | | | s / ss | Секунды | 30 |

Важно: m используется и для месяцев, и для минут. Excel различает их по контексту:
рядом с h или s — минуты;
в остальных случаях — месяц.

Примеры форматов дат

| Код | Отображение | | --------------- | ------------------ | | dd.mm.yyyy | 05.01.2025 | | d mmm yyyy | 5 янв 2025 | | mmmm yyyy | Январь 2025 | | dd/mm/yy h:mm | 05/01/25 15:30 | | hh:mm:ss | 15:30:45 |

4. Текст, единицы измерения и валюта

Для добавления текста к числу используются:

двойные кавычки "текст";
экранирование символов \.

| Формат | Значение | Результат | | ------------------- | -------- | -------------- | | 0 "шт." | 5 | 5 шт. | | 0 "руб." | 100 | 100 руб. | | #,##0.00 [$€-407] | 1500.5 | 1 500,50 € | | #,##0.00 [$₽-419] | 1500.5 | 1 500,50 ₽ | | "№" 000 | 25 | № 025 |

5. Проценты

Формат процента автоматически умножает значение на 100.

| Формат | Значение в ячейке | Результат | | ------- | ----------------- | ---------- | | 0% | 0.15 | 15% | | 0.00% | 0.1567 | 15.67% |

6. Цвета и условия

Цвет задаётся в квадратных скобках в начале секции.

Доступные базовые цвета: [Black], [Blue], [Cyan], [Green], [Magenta], [Red], [White], [Yellow].

Пример:

[Green]#,##0;[Red]-#,##0

Положительные значения — зелёные.
Отрицательные — красные.

7. Использование в HTML / JSON

При использовании форматов в HTML-атрибутах и JSON необходимо учитывать экранирование кавычек.

Общий шаблон

<td data-cell-format='{"formatCode":{"code":"ВАШ_КОД","type":"n"}}'>ЗНАЧЕНИЕ</td>

type: "n" — числовое значение.
type: "d" — дата.

Готовые примеры

1. Деньги (2 знака после запятой):

<p data-cell-format='{"formatCode":{"code":"#,##0.00","type":"n"}}'>12500.5</p>

2. Точное число (3 знака):

<p data-cell-format='{"formatCode":{"code":"#,##0.000","type":"n"}}'>1231.213</p>

3. Проценты:

<p data-cell-format='{"formatCode":{"code":"0.00%","type":"n"}}'>0.15</p>

Результат: 15.00%

4. Дата (ДД.ММ.ГГГГ):

<p data-cell-format='{"formatCode":{"code":"dd.mm.yyyy","type":"d"}}'>2025-01-05</p>

5. Единицы измерения:

<p data-cell-format='{"formatCode":{"code":"#,##0 \\\"кг\\\"","type":"n"}}'>5000</p>

Обратите внимание на двойное экранирование кавычек внутри JSON-строки.

Лицензия

См. файл LICENSE.