Руководство пользователя AutoExcel (версия 2.0.0)

Ссылка на сайт

GitHub
English
блог

Зачем использовать AutoExcel?

Импорт и экспорт в Excel очень распространены в разработке программного обеспечения, и если вы занимаетесь разработкой, вы обязательно столкнетесь с этим. Я полагаю, что многие люди, как и я, решат использовать Apache POI для выполнения этой работы.Ощутив силу POI, моя команда также столкнулась со следующими проблемами:

Непосредственное использование POI для работы с Excel создаст много жесткого кода, вы будете писать индекс мертвой строки и индекс столбца в кодировании.
Большое количество одноразовых кодов управления форматом, таких как цвет фона, выравнивание, стиль ячейки и т. д.
Консультант по внедрению четко предоставляет готовый шаблон, но его нужно разрабатывать и внедрять заново с кодом, а эффективность разработки низкая
Ресурсы разработки должны использоваться при корректировке шаблонов
Простой экспорт также требует написания специального кода.

AutoExcelОн решает вышеуказанные проблемы, он очень прост и требует лишь небольшого количества кода для выполнения сложного импорта и экспорта; при его использовании программисты не имеют смысла импорта и экспорта, то есть им не нужно напрямую управлять POI; в то же время внедрить Excel, предоставленный консультантом То есть импортировать и экспортировать шаблоны.Если не будут добавлены новые источники данных или поля, обновления шаблона не требуют ресурсов разработки.

AutoExcelВместо того, чтобы чрезмерно инкапсулировать POI, он в полной мере использует функции самого Excel - диспетчера имен, с помощью некоторых приемов для сопоставления ячеек и источников данных, чтобы отделить программистов от POI и избежать создания жесткого кода, чтобы сделать импорт и экспорт приятным вместо скучного.

Выходные данные

Текущая версия: v2.0.0

Поддерживаемый формат Excel: 2007

Функции

Экспорт шаблона
- Поддержка нескольких листов
- Поддержка базовых объектов и табличных данных
- Один лист поддерживает несколько источников данных переменной длины.
- Поддержка горизонтального заполнения данных
- Автоматически применять стили ячеек
- Автозаполнение номеров строк
- Формулы автозаполнения
- Автоматический итог
прямой экспорт
- Поддержка нескольких листов
- Экспорт с базовыми стилями
- Автоматическая ширина столбца
импорт
- Поддержка нескольких листов
- Автоматическое преобразование типа данных
Поддерживает импорт и экспорт миллионов данных за секунды

Предварительный просмотр функции

перед экспортом	после экспорта

Для реализации всего вышеперечисленного экспорта требуется только написать следующий небольшой объем кода (вам нужен дополнительный код для подготовки источника данных, например, выборки из базы данных. Демонстрационные данные генерируются с использованием DataGenerator в примере)

// 设置导出参数，如数据源名称、数据源等
List<TemplateExportPara> paras = new ArrayList<>();
paras.add(new TemplateExportPara("BusinessUnit", DataGenerator.genBusinessUnit()));
paras.add(new TemplateExportPara("Contract", DataGenerator.genContracts()));
paras.add(new TemplateExportPara("Project", DataGenerator.genProjects(1)));

List<Product> products = DataGenerator.genProducts(1);
TemplateExportPara para3 = new TemplateExportPara("Product", products);
// 单个sheet有多个数据源时，上方数据源应设置为插入
para3.setInserted(true);
paras.add(para3);

TemplateExportPara para5 = new TemplateExportPara("Product2", products);
// 横向填充
para5.setDataDirection(DataDirection.Right);
paras.add(para5);

//（可选操作）移除不需要的sheet
ExcelSetting excelSetting = new ExcelSetting();
excelSetting.setRemovedSheets(Arrays.asList("will be removed"));

AutoExcel.save(this.getClass().getResource("/template/Export.xlsx").getPath(),
               this.getClass().getResource("/").getPath() + "AutoExcel.xlsx",
               paras,
               excelSetting);

Maven

<dependency>
  <groupId>net.fenghaitao</groupId>
  <artifactId>auto-excel</artifactId>
  <version>2.0.0</version>
</dependency>

Распознайте шаблон

Чтобы добиться вышеуказанного экспорта, сначала необходимо завершить изготовление шаблона. Для некоторых средств отчетности, таких как Microsoft RDL, вы создадите модель экспорта в RDL, а затем объедините код для экспорта данных в Excel. В этом процессе RDL играет только посредническую роль, а это означает, что каждый раз, когда возникает новая задача экспорта, сначала должна быть создана модель экспорта. В AutoExcel Excel является шаблоном. Если ваш источник Excel является консультантом по внедрению, весьма вероятно, что этот Excel уже установил формат данных, стиль ячейки и т. д. и ждет, пока вы заполните данные. случае, почему бы не поставить этот Excel в качестве нашего шаблона экспорта, все, что нам нужно сделать, это добавить в него наш материал.

имя менеджера

Диспетчер имен в Excel, функция, которую большинство людей игнорирует, стала связующим звеном между источниками данных и ячейками в AutoExcel. Вы можете щелкнуть менюФормула -> Диспетчер именЧтобы открыть диспетчер имен, каждое имя соответствует определенному местоположению в Excel, которое может быть диапазоном или ячейкой.Конечно, здесь все имена, которые мы определяем, указывают на ячейки. Таким образом, можно понять, что менеджер имен используется для именования ячеек. Именно потому, что у ячеек есть имена, мы можем автоматически присваивать значения ячейкам без необходимости персонализированного кода.

После определения имени для ячейки, когда вы снова щелкнете по ячейке, вы обнаружите, что имя, которое вы только что определили, отображается в верхнем левом углу.

Помимо добавления новых имен в Диспетчер имен, есть еще один способ, более интуитивно понятный и быстрый. Щелкните ячейку, которую вы хотите назвать, затем введите имя непосредственно в верхнем левом углу и, наконец, нажмите клавишу Enter. Это рекомендуемый способ создания имен.

правила имени

Поскольку имена ячеек определяют, какие данные заполняются и как, они должны называться в соответствии со следующими правилами:

Имя источника данных.Имя поля [.Тип агрегата], используемое для заполнения общих полей или суммарных значений общих полей, например: product.SaleArea.sum
Имя источника данных.Formula.xxxx, используемое для заполнения формул, например: product.Formula.1
Имя источника данных.RowNo, используемое для заполнения номера строки, например: product.RowNo

Все имена нечувствительны к регистру, следующее будет введено в соответствии с конкретными сценариями

экспорт

базовый объект

Как показано на рисунке, имя каждой ячейки указано в комментарии, согласно数据源名称.字段名称написание правил

String templatePath = this.getClass().getResource("/template/Export.xlsx").getPath();
String outputPath = this.getClass().getResource("/").getPath() + "AutoExcel.xlsx";
//DataGenerator.genBusinessUnit()用于生成demo数据
TemplateExportPara para = new TemplateExportPara("BusinessUnit", DataGenerator.genBusinessUnit());
AutoExcel.save(templatePath, outputPath, para);

один стол

Если вы хотите экспортировать список данных, вам просто нужно назвать его в соответствии с правилами написания базового объекта. Конечно, экспорт данных списка часто бывает сложнее, чем базовый объект, например, вам может понадобиться столбец с номерами строк, и вы не хотите делать специальную обработку в коде, в этом случае вы можете использовать数据源名称.RowNo, передайте работу AutoExcel для обработки. Уведомление,RowNoявляется встроенным полем, если источник данных содержит это поле, оно будет перезаписано.

Также очень распространена ситуация, когда у вас есть ячейка с формулой в таблице, например:=E6+F6, вы хотите, чтобы ячейке в следующей строке было присвоено значение=E7+F7, то вы должны использовать数据源名称.Formula.xxxx, вы можете использовать любую формулу, которая вам нравится, и AutoExcel автоматически заполнит ее в конце.xxxxВы можете написать что угодно, лишь бы имя было уникальным.FormulaТакже встроенные поля.

String templatePath = this.getClass().getResource("/template/Export.xlsx").getPath();
String outputPath = this.getClass().getResource("/").getPath() + "AutoExcel.xlsx";
//DataGenerator.genContracts()用于生成demo数据
TemplateExportPara para = new TemplateExportPara("Contract", DataGenerator.genContracts());
AutoExcel.save(templatePath, outputPath, para);

Если вы запустили приведенный выше код, вы обнаружите, что AutoExcel автоматически применяет стили ячеек для вас.Любой стиль, который вы хотите применить к экспортируемым данным, можно сделать, установив начальную строку данных в шаблоне (то есть, где ячейка вы назвали находится) линия) стиль для управления.

Несколько таблиц

Экспортировать несколько таблиц в один лист.Если у вас есть такое требование, установите параметр экспорта таблицы, которая не находится внизу в коде, на:setInserted(true), как показано на рисунке выше, параметр экспорта, соответствующий продуктам, должен быть установлен следующим образом:para.setInserted(true). Вы знаете, AutoExcel не заботится о том, достаточно ли места в экспортируемых данных, он будет только выводить их непрерывно, поэтому, когда места в вашем шаблоне недостаточно, вам нужно сообщить об этом AutoExcel, и тогда AutoExcel выделит достаточно места для его размещения. перед экспортом ваших данных.

Здесь вводятся новые соглашения об именах:数据源名称.字段名称.合计类型, используемый для агрегирования указанного поля, в настоящее время поддерживает два типа агрегирования: Sum и Avg.

String templatePath = this.getClass().getResource("/template/Export.xlsx").getPath();
String outputPath = this.getClass().getResource("/").getPath() + "AutoExcel.xlsx";
List<TemplateExportPara> paras = new ArrayList<>();
//DataGenerator.genProjects()用于生成demo数据
paras.add(new TemplateExportPara("Project", DataGenerator.genProjects()));

//DataGenerator.genProducts()用于生成demo数据
TemplateExportPara para = new TemplateExportPara("Product", DataGenerator.genProducts());
para.setInserted(true);  //导出空间不够时需设置
paras.add(para);

AutoExcel.save(templatePath, outputPath, paras);

Горизонтальное заполнение

Если вам нужно заполнить данные справа, а не вниз, вам просто нужно использоватьsetDataDirection(DataDirection.Right)Вот и все.

String templatePath = this.getClass().getResource("/template/Export.xlsx").getPath();
String outputPath = this.getClass().getResource("/").getPath() + "AutoExcel.xlsx";
TemplateExportPara para = new TemplateExportPara("Product2", DataGenerator.genProducts());
para.setDataDirection(DataDirection.Right);  //向右填充
AutoExcel.save(templatePath, outputPath, para);

прямой экспорт

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

String outputPath = this.getClass().getResource("/").getPath() + "Export Directly.xlsx";
DirectExportPara para = new DirectExportPara(DataGenerator.genProjects(1));
AutoExcel.save(outputPath, para);

Эффект:

Как видите, экспорт поставляется с базовыми стилями и автоматически настраивает ширину столбцов.

Конечно, вам не понравится такой заголовок и порядок заголовков, поэтому вам нужно использовать FieldSetting, чтобы ваши заголовки читались и отображались в том порядке, который вам нравится.

List<FieldSetting> fieldSettings = new ArrayList<FieldSetting>() {{
    add(new FieldSetting("projName", "Project Name"));
    add(new FieldSetting("projInfo", "Project Info."));
    add(new FieldSetting("saleStartDate", "Sales Start Date"));
    add(new FieldSetting("availablePrice", "Available Price"));
    add(new FieldSetting("availableAmount", "Available Amount"));
}};
String outputPath = this.getClass().getResource("/").getPath() + "Export Directly.xlsx";
DirectExportPara para = new DirectExportPara(DataGenerator.genProjects(), "Projects", fieldSettings);
AutoExcel.save(outputPath, para);

окончательный эффект:

Кроме того, вы можете экспортировать сразу несколько листов.

String outputPath = this.getClass().getResource("/").getPath() + "Export Directly.xlsx";
List<DirectExportPara> paras = new ArrayList<>();
paras.add(new DirectExportPara(DataGenerator.genProjects(200), "Projects",
        DataGenerator.genProjectFieldSettings()));
paras.add(new DirectExportPara(DataGenerator.genContracts()));
AutoExcel.save(outputPath, paras);

пользовательское действие

AutoExcel предназначен для обработки распространенных сценариев импорта и экспорта, если у вас есть индивидуальные потребности, вы должны вернуть его обратно.Workbookуправление, персонализированное в соответствии с вашими потребностями. Метод сохранения обеспечивает дваConsumer,вactionAheadбудет вызываться перед началом операции экспорта,actionBehindбудет вызываться после завершения экспорта, вы можете передать эти дваConsumerчтобы добавить желаемую функциональность.

String templatePath = this.getClass().getResource("/template/Export.xlsx").getPath();
String outputPath = this.getClass().getResource("/").getPath() + "AutoExcel.xlsx";
List<TemplateExportPara> paras = new ArrayList<>();
paras.add(new TemplateExportPara("BusinessUnit", DataGenerator.genBusinessUnit()));
Consumer<Workbook> actionAhead = Workbook -> {
    //做任何你想做的事情
};        
Consumer<Workbook> actionBehind = workbook -> {
    //做任何你想做的事情
};
AutoExcel.save(templatePath, outputPath, paras, actionAhead, actionBehind);

импорт

Импорт в версии 2.0.0 больше не использует шаблоны, поэтому необходимо передатьFieldSettingУкажите сопоставление между именами столбцов и именами полей, которые могут храниться в вашей базе данных. Поддерживает одновременный импорт нескольких листов и может указывать индекс строки заголовка и индекс строки данных.

List<ImportPara> importParas = new ArrayList<ImportPara>() {{
    add(new ImportPara(0, DataGenerator.genProductFieldSettings()));
    add(new ImportPara(1, DataGenerator.genProjectFieldSettings(), 1, 5));
}};
String fileName = this.getClass().getResource("/template/Import.xlsx").getPath();
DataSet dataSet = AutoExcel.read(fileName, importParas);
// 方式一、获取原始数据，没有类型转换，可通过这种方式检验数据是否符合要求
List<Map<String, Object>> products = dataSet.get("Product");
List<Map<String, Object>> projects = dataSet.get("Project");
// 方式二、通过sheet索引获取指定类的数据，类型自动转换，转换失败将抛出异常
// List<Product> products = dataSet.get(0, Product.class);
// List<Project> projects= dataSet.get(1, Project.class);
// 方式三、通过sheet名称获取指定类的数据，类型自动转换，转换失败将抛出异常
// List<Product> products = dataSet.get("Product", Product.class);
// List<Project> projects = dataSet.get("Project", Project.class);

public static List<FieldSetting> genProjectFieldSettings() {
    List<FieldSetting> fieldSettings = new ArrayList<>();
    fieldSettings.add(new FieldSetting("projName", "Project Name"));
    fieldSettings.add(new FieldSetting("projInfo", "Project Info."));
    fieldSettings.add(new FieldSetting("basalArea", "Basal Area"));
    fieldSettings.add(new FieldSetting("availableArea", "Available Area"));
    fieldSettings.add(new FieldSetting("buildingArea", "Building Area"));
    fieldSettings.add(new FieldSetting("buildingsNumber", "Buildings Number"));
    fieldSettings.add(new FieldSetting("saleStartDate", "Sales Start Date"));
    fieldSettings.add(new FieldSetting("landAcquisitionTime", "Land Acquisition Time"));
    fieldSettings.add(new FieldSetting("availablePrice", "Available Price"));
    fieldSettings.add(new FieldSetting("availableAmount", "Available Amount"));
    fieldSettings.add(new FieldSetting("insideArea", "Inside Area"));
    return fieldSettings;
}

public static List<FieldSetting> genProductFieldSettings() {
    List<FieldSetting> fieldSettings = new ArrayList<FieldSetting>() {{
        add(new FieldSetting("projName", "Project Name"));
        add(new FieldSetting("basalArea", "Basal Area"));
        add(new FieldSetting("availableArea", "Available Area"));
        add(new FieldSetting("buildingArea", "Building Area"));
        add(new FieldSetting("buildingsNumber", "Buildings Number"));
    }};
    return fieldSettings;
}

Входные параметры конструктора ImportPara:

SheetIndex: требуется, индекс листа
fieldSettings: обязательно, имя столбца и настройки отображения имени поля
titleIndex: можно не указывать, начальный индекс строки заголовка, по умолчанию 0
dataStartIndex: можно не указывать, начальный индекс строки данных, по умолчанию 1

Зачем использовать FieldSetting вместо использования аннотаций для объявления имен столбцов?

Ненавязчивый, не влияет на исходный код

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

Миллионы данных, отнимающие много времени

Единица: миллисекунды

	10W строк и 10 столбцов данных	100 Вт строк и 10 столбцов данных
Экспорт шаблона	6,258	23,540
прямой экспорт	5,711	24,952
импорт	4,466	21,595
импорт + преобразование типа	4,823	26,279

Запустите пример кода

Полный пример кода см.здесьПроверить