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

EasyExcel 3.x 实战：告别丑陋报表，实现表头自适应与智能换行

每次看到导出的Excel报表里，表头文字被截断、内容挤成一团，是不是都觉得特别影响专业形象？尤其是在需要向客户或领导展示数据的时候，一个排版精美的报表，往往能无声地传递出开发者的严谨与细致。对于使用EasyExcel 3.x的Java开发者来说，实现表头宽度根据内容自动调整，以及单元格内容的智能换行，早已不是难题，但如何优雅、高效且可复用地集成到项目中，却有不少门道。这篇文章，我就结合自己最近在几个数据中台项目中的实践，抛开那些官方文档里干巴巴的说明，直接聊聊怎么用最少的代码，打造出既美观又实用的Excel导出功能。无论你是要生成复杂的业务报表，还是简单的数据导出，下面的思路和代码都能让你直接“抄作业”。

1. 理解核心：为什么需要自定义样式策略？

在深入代码之前，我们得先搞清楚EasyExcel处理样式的机制。EasyExcel通过WriteHandler接口提供了强大的扩展能力，允许我们在写入Excel的不同生命周期（如创建单元格、结束Sheet等）插入自定义逻辑。对于单元格宽度和样式，主要依靠两个核心策略类：

• AbstractColumnWidthStyleStrategy：这是一个抽象类，专门用于控制列宽。我们需要继承它，并重写setColumnWidth方法。这个方法会在每个单元格被写入时调用，无论是表头还是数据单元格，我们都可以在这里计算当前内容的“宽度”，并与该列已记录的最大宽度进行比较和更新。
• HorizontalCellStyleStrategy：这是一个具体的策略实现类，用于统一设置单元格的样式，比如边框、对齐方式、字体，以及我们关心的自动换行（setWrapped(true)）。

注意：EasyExcel的样式策略是叠加的。你可以注册多个WriteHandler，它们会按注册顺序生效。这意味着我们可以将列宽策略和单元格样式策略分开编写、独立注册，保持代码的清晰和可维护性。

很多朋友直接复制网上的代码后，发现宽度计算不准或者换行没生效，问题往往出在对POI底层模型和策略执行时机的理解偏差上。下面，我们就来逐一拆解。

1.1 列宽自适应策略的深度定制

网上常见的宽度计算是基于字符串的字节长度，这简单但粗糙。在实际项目中，中英文混排、数字格式、甚至包含换行符的内容，都需要更精细的处理。直接使用getBytes().length会因为编码问题（如UTF-8下一个中文占3字节）导致宽度严重偏离。

这里我分享一个经过改良的CustomColumnWidthStyleStrategy类，它更关注字符的视觉宽度，而非单纯的存储字节数。

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;

/**
 * 增强型列宽自适应策略
 * 特点：基于字符数进行更合理的宽度估算，并支持宽度上限配置。
 */
public class CustomColumnWidthStyleStrategy extends AbstractColumnWidthStyleStrategy {

    // 缓存结构：Sheet编号 -> (列索引 -> 该列最大宽度)
    private final Map<Integer, Map<Integer, Integer>> cache = new HashMap<>();
    // 可配置的列宽上限（字符数），Excel最大支持255个字符宽度
    private static final int MAX_COLUMN_WIDTH = 50;
    // 一个中文字符大致相当于英文字符宽度的倍数
    private static final double CHINESE_CHAR_WIDTH_RATIO = 1.8;

    @Override
    protected void setColumnWidth(WriteSheetHolder writeSheetHolder,
                                  List<WriteCellData<?>> cellDataList,
                                  Cell cell,
                                  Head head,
                                  Integer relativeRowIndex,
                                  Boolean isHead) {
        // 只有表头或有数据内容的单元格才需要计算宽度
        if (!isHead && CollectionUtils.isEmpty(cellDataList)) {
            return;
        }

        int sheetNo = writeSheetHolder.getSheetNo();
        Map<Integer, Integer> maxWidthMap = cache.computeIfAbsent(sheetNo, k -> new HashMap<>());

        int columnIndex = cell.getColumnIndex();
        int contentWidth = calculateContentWidth(cellDataList, cell, isHead);

        if (contentWidth > 0) {
            // 应用宽度上限，防止过宽
            contentWidth = Math.min(contentWidth, MAX_COLUMN_WIDTH);
            Integer currentMaxWidth = maxWidthMap.get(columnIndex);

            // 如果当前计算宽度大于该列已记录的最大宽度，则更新
            if (currentMaxWidth == null || contentWidth > currentMaxWidth) {