OSCHINA-MIRROR/chimmhuang-chimm.excel

Чимм.Эксель — настройка шаблона, заполнение данных, и всё готово!

码云 | GitHub

1. Введение в проект

1.1 Описание

Chimm.Excel — это программа на Java для создания Excel, основанная на шаблонах и простая в использовании.

1.2 Особенности

Способ организации данных отличается от других программ.

В отличие от некоторых открытых программ, этот инструмент основан на шаблоне Excel и требует заполнения переменных в шаблоне.
Почему не используется подход с аннотациями?

Некоторые открытые программы на основе аннотаций могут создавать только простые таблицы стилей. Этот инструмент использует шаблон Excel, что позволяет создавать более сложные таблицы.
Antlr4

Antlr (ANother Tool for Language Recognition) — мощный межъязыковой синтаксический анализатор, который можно использовать для чтения, обработки, выполнения или перевода структурированных текстовых или двоичных файлов. Он широко используется для создания языков, инструментов и фреймворков. Antlr может генерировать парсер из грамматики. Поскольку эта программа разработана с использованием Antlr4, переменные определяются гибко, позволяя определять коллекции переменных и даже формулы в переменных. Каждая таблица соответствует объекту данных, и разработчику нужно только запросить данные и собрать их.
Как создать шаблон Excel? Шаблоны создаются просто: при определении переменной используйте форму $ + скобки. Например: ${school.name}.
Краткое описание функций Chimm.Excel
- Экспорт файла Excel в двоичном формате
  - Поддержка нескольких листов (v1.4.1)
- Заполнение значениями на основе шаблона
- Поддержка формул
  - Поддерживает формулы с переменными, например: SUM(A1,A2,${demo.value})
- Операции с таблицами: добавление и удаление строк
  - ⭐️ Добавление строки автоматически обновляет формулу
- Объединение ячеек (поддержка пакетного объединения)
- Изменение стиля границ ячеек (жирный, пунктирный и т. д.)
- Поддержка установки гиперссылок (v1.2.0)

2. Демонстрация функций

Предоставлен тестовый класс demo.
Расположение шаблона: src/test/resources/demo.xlsx
Расположение тестового класса: src/test/java/../demo/Demo.java

Файл шаблона:

Обработанный файл:

3. Структура проекта

.com.github.chimmhuang
└── excel
    ├── ExcelHelper.java    Основной объект программы
    ├── exception           Исключения
    ├── parser              Antlr4 парсер
    └── tablemodel          Классы, связанные с таблицами

3.1 ExcelHelper — объект обработки таблиц

Этот объект является основным входом в программу Chimm.Excel и предоставляет функции для создания рабочей книги Excel, получения таблиц листов, заполнения шаблонов данными и экспорта двоичного файла. Ниже приводится подробное описание основных методов.

createWorkbook(byte[] bytes)
Создаёт рабочую книгу Excel: метод преобразует двоичный файл шаблона в объект ExcelWorkbook и возвращает его.
getSheetTable(byte[] bytes, int sheetIndex)
getSheetTable(byte[] bytes, String sheetName)
Получает таблицу указанного листа: метод получает таблицу листа из двоичного файла шаблона.
fillInData(SheetTable table, Object data)
Заполняет переменные в таблице: метод заполняет объект данных в таблицу шаблона.
convert2Byte(SheetTable table)
Преобразует таблицу в двоичный файл Excel

3.2 ExcelWorkbook — объект Excel

Этот объект представляет всю книгу Excel и содержит таблицы всех листов. На данном этапе этот объект имеет ограниченное применение, поэтому предоставляется меньше методов.

getSheet(int index)
getSheet(String sheetName)
Получение объекта листа по индексу или имени.
getXssfWorkbook()
Метод возвращает оригинальный объект Apache poi xssfWorkbook, предоставляя разработчикам возможность выполнять оригинальные операции poi.

3.3 SheetTable — объект таблицы

Этот объект соответствует таблице листа. Предоставляет методы для управления стилем таблицы.

getRow(int rowNum)
Получить строку по номеру.
removeRowGE(int rowNum)
Удалить строки с номером больше или равным указанному.
appendRow(Row srcRow)
Добавить строку в конец таблицы.
mergeCell(int firstRowNum, int lastRowNum, String firstColName, String lastColName)
mergeCellBatch(List<MergedRegion> mergedRegionList) Объединить ячейки.
setBorderStyle(int firstRowNum, int lastRowNum, String firstColName, String lastColName, BorderStyle borderStyle, BorderPositionEnum borderPositionEnum)
Установить стиль границы для указанного диапазона, включая жирный, пунктирный и другие стили.
setSheetName(String sheetName) Установить имя листа.

3.4 Row — объект строки

Этот объект соответствует строке Excel. Предоставляет методы для работы со строками.

getCell(String cellName)
Получить ячейку по имени столбца.
copy()
Копировать объект (глубокое клонирование).
setBorderStyle(BorderPositionEnum positionEnum, BorderStyle borderStyle)
Установить стиль границы строки, включая жирный, пунктирный и другие стили. Cell — объект ячейки

Данный объект соответствует ячейке Excel. Предоставляет некоторые методы для работы с ячейкой:

getValue();
setValue(Object value) — получение/установка значения ячейки;
setFormula(String formula) — установка формулы в ячейке;
setBorderStyle(BorderPositionEnum positionEnum, BorderStyle borderStyle) — установка стиля границы ячейки. Можно изменить стиль границы, например, на жирную или пунктирную линию.

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

4.1. Конфигурация шаблона

Шаблон конфигурации использует знак доллара и фигурные скобки для определения переменных, например: ${demo.value}. В этом проекте я использую шаблон функции demo, который удовлетворяет большинству сценариев: src/test/resources/demo.xlsx.

4.2. Импорт координат

<dependency>
    <groupId>com.github.chimmhuang</groupId>
    <artifactId>chimm.excel</artifactId>
    <version>1.4.1</version>
</dependency>

4.3. Функциональное описание

4.3.1. Импорт шаблона, экспорт результатов таблицы

Здесь показан импорт шаблона. Пропущено заполнение таблицы данными, но необходимо сопоставить переменные таблицы с именами переменных шаблона. Здесь показано заполнение данных и создание окончательного объекта байтов, который является ожидаемой таблицей результатов. Разработчик может работать с этим объектом для экспорта или загрузки файла.

public void testFillInTable() throws Exception {
    // Получение двоичного файла
    File file = new File("src/test/resources/demo.xlsx");
    byte[] bytes = FileUtils.readFileToByteArray(file);

    // Создание объекта книги Excel с помощью ExcelHelper
    ExcelWorkbook excelWorkbook = ExcelHelper.createWorkbook(bytes);

    // Получение указанной страницы листа (этот объект является настроенной таблицей)
    SheetTable table = excelWorkbook.getSheet(0);

    // Установка имени указанного листа
    table.setSheetName("Результаты");

    // Упаковка объекта данных таблицы
    SchoolReportData tableData = new SchoolReportData();

    // ... заполнение данных ...
    tableData.setTitle("Отчет о школе xx");
    // ... пропущено добавление данных ...
    // ... опущено динамическое задание стиля таблицы ...

    // Добавление упакованного объекта таблицы в Excel
    ExcelHelper.fillInData(table, tableData);

    // Преобразование объекта таблицы в двоичный файл, resultBytes — это окончательный результат
    byte[] resultBytes = ExcelHelper.convert2Byte(table);
}

4.3.2. Установка формулы

public void testFillInTable() throws Exception {
    /*
        Получение двоичного файла
        Создание объекта книги Excel с помощью ExcelHelper
        ...
     */

    // Получение указанного листа (этот объект является настроенной таблицей)
    SheetTable table = excelWorkbook.getSheet(0);

    // Установка формулы для строки 13 столбца A
    Row row13 = table.getRow(13).getCell("A").setFormula("SUM(A1,A2,${demo.value})");
}

4.3.3. Добавление строк / уменьшение строк

public void testFillInTable() throws Exception {
    /*
        Получение двоичного файла
        Создание объекта книги Excel с помощью ExcelHelper
        ...
     */

    // Получение указанного листа (этот объект является настроенной таблицей)
    SheetTable table = excelWorkbook.getSheet(0);

    // Получение строки 13
    Row row13 = table.getRow(13);

    // Удаление всех строк больше 13 для динамического добавления таблицы
    table.removeRowGE(13);

    // Копирование строки
    Row copy1 = row13.copy();
    Row copy2 = row13.copy();

    // Установление новых значений
    copy1.getCell("A").setValue("copy1");
    copy2.getCell("A").setValue("copy2");

    // После установки добавление в таблицу
    table.appendRow(copy1);
    table.appendRow(copy2);
}

4.3.4. Объединение ячеек

public void testFillInTable() throws Exception {
    /*
        Получение двоичного файла
        Создание объекта книги Excel с помощью ExcelHelper
        ...
     */

    // Получение указанного листа (этот объект является настроенной таблицей)
    SheetTable table = excelWorkbook.getSheet(0);

    // Объединение ячеек (здесь показаны только функциональные возможности, рекомендуется динамический расчёт объединяемых номеров строк)
    table.mergeCell(13, 15, "A", "A");
    table.mergeCell(16, 19, "A", "A");
}

4.3.5. Утолщение границ ячеек

public void testFillInTable() throws Exception {
    /*
        Получение двоичного файла
        Создание объекта книги Excel с помощью ExcelHelper
        ...
     */

    // Получение указанного листа (этот объект является настроенной таблицей)
    SheetTable table = excelWorkbook.getSheet(0);

    // Настройка стиля строки для указанных ячеек (здесь показана только функция: утолщение, рекомендуется динамический расчет номера строки)
    table.getRow(19).setBorderStyle(BorderPositionEnum.BOTTOM, BorderStyle.MEDIUM);
}

4.3.6. Установка гиперссылки

public void testFillInTable() throws Exception {
    /*
        Получение двоичного файла
        Создание объекта книги Excel с помощью ExcelHelper
        ...
     */

    // Получение указанного листа (этот объект является настроенной таблицей)
    SheetTable table = excelWorkbook.getSheet(0);

    // Установка гиперссылки
    table.getRow(2).getCell("A").setHyperlinkURL("https://www.baidu.com");
}

5. Участие в проекте

Мы будем рады вашему участию! Создайте новую задачу или отправьте запрос на вытягивание.

6. Связаться с автором

QQ & WeChat: 905369866 email: chimmhuang@163.com