Excel读取工具 - ExcelReader

介绍

ExcelReader 是 Hutool 提供的用于读取 Excel 文件内容的工具类。通过构造 ExcelReader 对象，可以从指定的 Excel 文件、流或工作簿中读取内容，并将其转换为多种格式的数据，例如列表、Map 或自定义的 JavaBean 对象。

ExcelReader 支持读取 .xls 和 .xlsx 格式的文件，并且能够自动识别和处理不同的文件格式。

1. 读取 Excel 文件为二维列表

可以通过 ExcelReader.read() 方法将 Excel 文件的所有行和列读取为一个二维列表，每个列表元素表示 Excel 文件中的一行数据，每行的数据以列表形式表示。

示例代码

import cn.hutool.poi.excel.ExcelReader;
import cn.hutool.poi.excel.ExcelUtil;

import java.util.List;

public class ExcelReaderExample {
    public static void main(String[] args) {
        // 读取指定路径的 Excel 文件
        ExcelReader reader = ExcelUtil.getReader("d:/example.xlsx");

        // 将 Excel 中的所有行读取为二维列表
        List<List<Object>> readAll = reader.read();

        // 遍历并输出每一行的数据
        for (List<Object> row : readAll) {
            System.out.println(row);
        }

        // 关闭 ExcelReader，释放资源
        reader.close();
    }
}

参数说明

• ExcelUtil.getReader(String filePath)：从指定的文件路径中获取一个 ExcelReader 实例。
• read()：读取 Excel 文件中的所有行和列，并将其转换为一个二维列表。

实际场景

在处理简单数据或需要手动遍历 Excel 内容时，可以使用这种方式。比如在分析 Excel 中的原始数据或进行批量数据导入时。

2. 读取为 Map 列表（首行为标题行）

默认情况下，ExcelReader 会将 Excel 文件的第一行作为标题行，然后将数据从第二行开始读取。每一行数据会以 Map<String, Object> 形式存储，其中 key 为标题，value 为对应单元格的值。

示例代码

import cn.hutool.poi.excel.ExcelReader;
import cn.hutool.poi.excel.ExcelUtil;

import java.util.List;
import java.util.Map;

public class ExcelReaderExample {
    public static void main(String[] args) {
        // 读取指定路径的 Excel 文件
        ExcelReader reader = ExcelUtil.getReader("d:/example.xlsx");

        // 将 Excel 中的数据读取为 Map 列表，默认第一行为标题
        List<Map<String, Object>> readAll = reader.readAll();

        // 遍历并输出每一行的数据
        for (Map<String, Object> row : readAll) {
            System.out.println(row);
        }

        // 关闭 ExcelReader，释放资源
        reader.close();
    }
}

参数说明

• readAll()：将 Excel 文件中的数据读取为 Map 列表。每一个 Map 代表一行数据，Map 的 key 是标题，value 是对应单元格的值。

实际场景

在导入配置表、数据表时，通常使用这种方式。比如从 Excel 中批量导入用户信息或商品数据，可以直接将数据读取为 Map 列表，然后进行业务处理。

3. 读取为 JavaBean 列表

如果 Excel 中的数据结构与 JavaBean 对应，可以使用 readAll(Class<T> beanClass) 方法将数据直接映射为自定义的 JavaBean 列表。此方法会根据标题名称自动匹配 JavaBean 中的字段。

示例代码

import cn.hutool.poi.excel.ExcelReader;
import cn.hutool.poi.excel.ExcelUtil;

import java.util.List;

public class ExcelReaderExample {
    public static void main(String[] args) {
        // 读取指定路径的 Excel 文件
        ExcelReader reader = ExcelUtil.getReader("d:/example.xlsx");

        // 将 Excel 中的数据读取为 JavaBean 列表
        List<Person> personList = reader.readAll(Person.class);

        // 遍历并输出每一行的数据
        for (Person person : personList) {
            System.out.println(person);
        }

        // 关闭 ExcelReader，释放资源
        reader.close();
    }
}

JavaBean 示例

import cn.hutool.core.annotation.Alias;

public class Person {
    @Alias("姓名")
    private String name;
    @Alias("年龄")
    private int age;
    @Alias("性别")
    private String gender;

    // 省略 getter 和 setter 方法

    @Override
    public String toString() {
        return "Person{" +
                "name='" + name + '\'' +
                ", age=" + age +
                ", gender='" + gender + '\'' +
                '}';
    }
}

参数说明

• readAll(Class<T> beanClass)：将 Excel 文件中的数据读取为指定类型的 JavaBean 列表。

实际场景

在需要与业务模型直接对应的场景下，这种方法特别实用。比如导入用户信息、产品列表等，这些数据可以直接映射为对应的 JavaBean 进行业务逻辑处理。

4. 注意事项

1. 资源管理：在读取 Excel 文件后，一定要记得调用 close() 方法关闭 ExcelReader，以释放内存资源。
2. 数据映射：当使用 JavaBean 方式读取数据时，标题名称需要与 JavaBean 中的字段名称或 @Alias 注解一致。
3. 文件格式：ExcelReader 支持 .xls 和 .xlsx 文件格式，但在处理大数据量文件时建议使用 .xlsx 格式以提高性能。

5. 其他功能

• 指定读取的 Sheet：可以通过指定 Sheet 编号或名称来读取特定 Sheet 的内容。
• 大数据量读取：对于超大文件可以使用 readBySax 方法按行读取，避免一次性加载到内存中导致的内存溢出。