EasyExcel中CellData如何设置单元格为只读？

Question

在使用 EasyExcel 进行 Excel 导出时，开发者常误以为可通过 `CellData` 对象直接设置单元格为“只读”（如禁用编辑、加锁保护等）。但需明确：**`CellData` 仅用于封装单元格的值、类型、样式等数据，本身不提供权限控制能力，也无法影响 Excel 的编辑行为**。Excel 的“只读”或“单元格锁定”功能属于工作表保护（Worksheet Protection）范畴，需通过 Apache POI 底层 API 在 `Workbook` 或 `Sheet` 级别启用保护并配合单元格锁定状态（`CellStyle.setLocked(true)`）实现；而 EasyExcel 默认导出时不启用 sheet 保护，且 `CellData` 不暴露 `locked` 属性或保护相关配置。因此，单纯操作 `CellData` 无法实现单元格只读——这是开发者高频误解点。正确方案是：导出后通过 `EasyExcel` 的 `WriteHandler`（如 `SheetWriteHandler`）获取 `Sheet` 对象，调用 POI API 设置锁定与保护密码。

Answer 1

```html

一、现象层：开发者高频误操作——“CellData.setLocked(true)” 的幻觉

大量使用 EasyExcel 的中高级开发者（尤其3–8年经验者）在实现导出模板时，习惯性地尝试通过 CellData 对象的构造或反射方式注入 locked 属性，例如：
cellData.setExtData(Map.of("locked", true)) 或自定义 CellWriteHandler 中强行调用 cellData.setComment(...) 试图“模拟”保护逻辑。这类代码在编译和运行时均无报错，但导出的 Excel 文件在 Excel 客户端中完全无视该设置——单元格仍可自由编辑。这是典型的「API 表面理解陷阱」。

二、机制层：EasyExcel 与 Apache POI 的职责边界剖析

组件	核心职责	是否参与工作表保护	是否暴露锁定控制接口
CellData	轻量级数据载体：封装值、类型、格式字符串、样式索引、超链接等渲染元信息	❌ 完全不感知	❌ 无 setLocked() / isLocked() 方法
CellStyle（POI）	定义字体、边框、填充、对齐、锁定状态、隐藏状态等物理样式	✅ 是保护前提（需配合 Sheet.protectSheet()）	✅ setLocked(true/false) 有效

关键事实：EasyExcel 的 CellData 在写入阶段仅用于构建 Row.createCell().setCellValue() 及关联样式索引；真正的单元格属性（含锁定）由 CellStyle 绑定至 Cell 实例，而该实例仅在 SheetWriteHandler 或 WorkbookWriteHandler 的回调中才可安全访问。

三、原理层：Excel 工作表保护的双要素模型

graph LR
A[用户意图：禁止单元格编辑] --> B[要素1：单元格锁定状态]
A --> C[要素2：工作表启用保护]
B --> D[CellStyle.setLocked(true) // 默认为true，但需显式设置]
C --> E[Sheet.protectSheet(“password”) // 密码非空才生效]
D & E --> F[最终效果：锁定单元格不可编辑，未锁定单元格仍可编辑]
F --> G[⚠️ 注意：未调用 protectSheet() → 所有锁定设置均无效]

四、实践层：正确实现路径（含完整可运行代码）

以下为生产环境验证的最小可行方案，使用 SheetWriteHandler 注入 POI 原生能力：

public class LockedSheetWriteHandler implements SheetWriteHandler {
    @Override
    public void afterSheetCreate(WriteWorkbookHolder writeWorkbookHolder, WriteSheetHolder writeSheetHolder) {
        Sheet sheet = writeSheetHolder.getSheet();
        Workbook workbook = writeWorkbookHolder.getWorkbook();
        // 1. 创建可复用的锁定样式
        CellStyle lockedStyle = workbook.createCellStyle();
        lockedStyle.setLocked(true); // ⚠️ 关键：启用锁定
        // 2. 应用到指定列（如第0列：ID列只读）
        for (int rowNum = 0; rowNum <= sheet.getLastRowNum(); rowNum++) {
            Row row = sheet.getRow(rowNum);
            if (row != null) {
                Cell cell = row.getCell(0);
                if (cell != null) cell.setCellStyle(lockedStyle);
            }
        }
        // 3. 启用工作表保护（密码必须非空）
        sheet.protectSheet("Excel@2024");
    }
}

调用方式：EasyExcel.write(outputStream, Data.class).sheet().registerWriteHandler(new LockedSheetWriteHandler()).doWrite(dataList);

五、避坑层：5个被低估的实战细节

1. ✅ 锁定默认开启：POI 中 CellStyle 默认 locked=true，但 EasyExcel 自动创建的样式未显式继承此状态，必须手动 setLocked(true)；
2. ✅ 密码强度要求：Excel 2016+ 要求密码至少1字符，但建议使用 ASCII 字符集（避免 Unicode 导致兼容性问题）；
3. ✅ 样式复用必要性：每新建一个 CellStyle 都占用 POI 内部样式槽位（上限 64K），务必复用而非循环 new；
4. ✅ 保护 ≠ 只读文件：此方案仅锁定工作表，不阻止用户另存为、复制内容或取消保护（需密码）；如需真正只读，应结合文件系统权限或 PDF 导出；
5. ✅ 兼容性验证点：在 LibreOffice Calc 中保护功能部分失效，建议在 Microsoft Excel / WPS 表格中验收。

六、架构层：为什么 EasyExcel 故意屏蔽保护能力？

EasyExcel 的设计哲学是「专注数据流，解耦表现控制」。其作者明确指出：“工作表保护属于文档安全策略，与数据导出正交；若内置保护 API，将迫使所有用户承担密码管理、加解密、兼容性测试等非核心成本。” 这种分层抽象正是成熟开源项目的典型取舍——将底层能力（POI）保持开放，上层框架（EasyExcel）聚焦高价值场景（如大数据量、内存优化、模板引擎）。因此，CellData 不提供 locked 字段，不是缺陷，而是刻意为之的架构约束。

```