EasyExcel 3.x实战：如何让表头宽度智能适应内容并自动换行（附完整代码）

EasyExcel 3.x实战：告别手动调列宽，实现表头与内容的智能自适应与优雅换行

每次导出Excel报表，最头疼的莫过于调整列宽。要么是表头文字被截断，要么是长文本内容挤成一团，用户还得手动拖动列宽才能看清。对于追求交付质量和用户体验的中高级Java开发者来说，这不仅是细节问题，更是专业度的体现。EasyExcel作为阿里开源的优秀工具，其3.x版本在性能和扩展性上都有了显著提升，但要让它“聪明”地自动适应内容宽度，并让超长文本优雅换行，还需要我们进行一些策略性的定制。这篇文章，我将带你深入实战，从原理到代码，一步步构建一个既能自适应宽度、又能自动换行的健壮解决方案，让你导出的每一份报表都赏心悦目。

1. 理解核心：EasyExcel的样式策略与列宽控制机制

在动手编码之前，我们得先搞清楚EasyExcel是如何处理单元格样式和列宽的。这能帮你避开很多“知其然不知其所以然”的坑。

EasyExcel 3.x 的写入过程高度可定制化，其核心扩展点之一是 WriteHandler。对于样式和列宽，它提供了更细粒度的策略类：

• AbstractColumnWidthStyleStrategy：这是控制列宽的抽象基类。它的工作方式是，在写入每个单元格时，都会回调 setColumnWidth 方法。关键在于，它允许我们根据当前单元格的内容（无论是表头还是数据）来动态计算并设置该列的最佳宽度。这里有一个常见的误解：很多人以为这个策略只在表头写入时生效一次。实际上，它会遍历所有行，这为我们实现“根据整列数据中最宽的内容来设定列宽”提供了可能。
• HorizontalCellStyleStrategy 或 AbstractVerticalCellStyleStrategy：这些是控制单元格样式的策略，比如字体、颜色、对齐方式，以及我们关心的 自动换行（Wrapped Text）。通过设置 WriteCellStyle 的 setWrapped(true)，就能让单元格内文本在超过列宽时自动折行显示。

一个关键挑战在于，自适应宽度和自动换行这两个功能，在实现上存在一定的“矛盾”。自适应宽度希望列宽足够容纳内容，避免换行；而自动换行则是当内容过长时，允许其折行显示，可能不需要无限拉宽列。我们的目标是在两者间找到平衡：先为列设定一个合理的最大宽度（基于内容），然后对于仍然超出这个宽度的超长内容，启用换行来优雅展示，而不是被截断。

提示：EasyExcel 3.x 的 API 相对于 2.x 有部分调整，例如包路径和部分类名。确保你的项目依赖是正确的版本（如 com.alibaba:easyexcel:3.3.2 或更高），否则示例代码可能无法直接运行。

2. 构建智能列宽自适应策略

直接使用默认设置，列宽是固定的。我们需要继承 AbstractColumnWidthStyleStrategy 来实现自己的逻辑。核心思路是：在写入过程中，缓存每个工作表（Sheet）中每一列遇到的最大内容宽度，并在最终确定该列宽度时，应用这个最大值。

下面是一个增强版的 CustomWidthStyleStrategy。我不仅实现了基础功能，还增加了对中文字符的更好支持，以及可配置的最大宽度限制。

import com.alibaba.excel.enums.CellDataTypeEnum;
import com.alibaba.excel.metadata.Head;
import com.alibaba.excel.metadata.data.WriteCellData;
import com.alibaba.excel.write.metadata.holder.WriteSheetHolder;
import com.alibaba.excel.write.style.column.AbstractColumnWidthStyleStrategy;
import org.apache.poi.ss.usermodel.Cell;
import org.springframework.util.CollectionUtils;

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

/**
 * 智能列宽自适应策略
 * 1. 遍历所有行（表头和数据），记录每列的最大内容宽度。
 * 2. 对中英文字符进行差异化宽度估算（一个中文通常占2个英文字符宽度）。
 * 3. 支持设置最大列宽上限，防止单个超长单元格导致列宽过宽。
 */
public class SmartColumnWidthStyleStrategy extends AbstractColumnWidthStyleStrategy {

    // 缓存结构：Map<Sheet序号, Map<列索引, 该列最大宽度>>
    private final Map<Integer, Map<Integer, Integer>> sheetColumnWidthCache = new HashMap<>();
    
    // 最大允许的列宽（单位：字符数）。Excel最大列宽为255个字符。
    private static final int MAX_COLUMN_WIDTH = 100;
    // 是否启用最大宽度限制
    private final boolean enableMaxWidthLimit;

    public SmartColumnWidthStyleStrategy() {
        this(true);
    }

    public SmartColumnWidthStyleStrategy(boolean enableMaxWidthLimit) {
        this.enableMaxWidthLimit = enableMaxWidthLimit;
    }

    @Override
    protected void setColumnWidth(WriteSheetHolder writeSheetHolder, List<WriteCellData<?>> cellDataList,
                                  Cell cell, Head head, Integer relativeRowIndex, Boolean isHead) {
        // 只有需要设置宽度的情况（有内容）才进行处理
        boolean hasContent = isHead || !CollectionUtils.isEmpty(cellDataList);
        if (!hasContent) {
            return;
        }

        int sheetNo = writeSheetHolder.getSheetNo();
        int columnIndex = cell.getColumnIndex();
        
        // 获取或创建当前Sheet的列宽缓存Map
        Map<Integer, Integer>