Box/Spout 文档深度解析：Excel/CSV处理库的高级配置指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_01071/article/details/148527606

Box/Spout 文档深度解析：Excel/CSV处理库的高级配置指南

spout Read and write spreadsheet files (CSV, XLSX and ODS), in a fast and scalable way 项目地址: https://gitcode.com/gh_mirrors/sp/spout

前言

Box/Spout 是一个强大的 PHP 库，专门用于高效处理电子表格文件（XLSX、ODS、CSV）。本文将深入解析其核心功能与高级配置选项，帮助开发者充分利用这个工具。

CSV 文件配置详解

基础配置

CSV 文件的读写支持多种自定义配置：

use Box\Spout\Reader\Common\Creator\ReaderEntityFactory;

$reader = ReaderEntityFactory::createReaderFromFile('/path/to/file.csv');
// 必须在打开reader前设置
$reader->setFieldDelimiter('|');  // 设置字段分隔符
$reader->setFieldEnclosure('@');  // 设置字段包围符

编码处理

对于非 UTF-8 编码的文件，可以指定编码格式：

$reader->setEncoding('UTF-16LE');  // 处理UTF-16小端编码文件

BOM 控制

默认情况下，CSV 写入器会生成带 BOM 的 UTF-8 文件，但可以禁用：

use Box\Spout\Writer\Common\Creator\WriterEntityFactory;

$writer = WriterEntityFactory::createWriterFromFile('/path/to/file.csv');
$writer->setShouldAddBOM(false);  // 禁用BOM头

XLSX/ODS 文件高级配置

工作表自动创建

当达到单工作表行数上限（1,048,576）时，可以控制是否自动创建新工作表：

use Box\Spout\Writer\Common\Creator\WriterEntityFactory;

$writer = WriterEntityFactory::createODSWriter();
$writer->setShouldCreateNewSheetsAutomatically(true);  // 默认行为
$writer->setShouldCreateNewSheetsAutomatically(false); // 达到限制后停止写入

临时文件夹设置

处理大型文件时，可以指定自定义临时文件夹：

$writer = WriterEntityFactory::createXLSXWriter();
$writer->setTempFolder('/custom/temp/path');  // 提升I/O性能

字符串存储策略

XLSX 提供两种字符串存储方式：

$writer = WriterEntityFactory::createXLSXWriter();
$writer->setShouldUseInlineStrings(true);  // 默认方式，性能更好
$writer->setShouldUseInlineStrings(false); // 共享字符串模式，文件更小

兼容性提示：Apple Numbers 和 iOS 预览器不支持内联字符串，如需兼容这些平台必须使用共享字符串模式。

日期时间处理

读取时可以控制日期格式返回方式：

$reader = ReaderEntityFactory::createXLSXReader();
$reader->setShouldFormatDates(true);  // 返回格式化字符串
$reader->setShouldFormatDates(false); // 返回DateTime对象(默认)

空行处理策略

默认跳过空行，但可以保留：

$reader = ReaderEntityFactory::createReaderFromFile('/path/to/file.ext');
$reader->setShouldPreserveEmptyRows(true);  // 保留所有空行

样式系统详解

样式属性总览

Box/Spout 支持丰富的样式设置：

| 类别 | 属性 | 示例代码 | |------------|----------------|------------------------------------------| | 字体 | 加粗 | StyleBuilder::setFontBold() | | | 斜体 | StyleBuilder::setFontItalic() | | | 下划线 | StyleBuilder::setFontUnderline() | | | 删除线 | StyleBuilder::setFontStrikethrough() | | | 字体名称 | StyleBuilder::setFontName('Arial') | | | 字体大小 | StyleBuilder::setFontSize(14) | | | 字体颜色 | StyleBuilder::setFontColor(Color::BLUE)| | 对齐 | 单元格对齐 | setCellAlignment(CellAlignment::CENTER)| | | 自动换行 | setShouldWrapText(true) | | 格式(XLSX) | 数字格式 | setFormat('0.000') | | | 日期格式 | setFormat('m/d/yy h:mm') |

行样式应用

use Box\Spout\Common\Entity\Style\Color;
use Box\Spout\Common\Entity\Style\CellAlignment;

$style = (new StyleBuilder())
    ->setFontBold()
    ->setFontColor(Color::BLUE)
    ->setCellAlignment(CellAlignment::RIGHT)
    ->setBackgroundColor(Color::YELLOW)
    ->build();

$row = WriterEntityFactory::createRowFromArray(['数据1', '数据2'], $style);

单元格边框设置

$border = (new BorderBuilder())
    ->setBorderBottom(Color::GREEN, Border::WIDTH_THIN, Border::STYLE_DASHED)
    ->build();

$style = (new StyleBuilder())->setBorder($border)->build();

样式继承机制

单元格样式继承自行样式，行样式继承自默认样式，形成三级样式体系：

$defaultStyle = (new StyleBuilder())->setFontSize(8)->build();
$writer->setDefaultRowStyle($defaultStyle);

$rowStyle = (new StyleBuilder())->setFontBold()->build();
$cellStyle = (new StyleBuilder())->setFontColor(Color::RED)->build();

$cells = [
    WriterEntityFactory::createCell('普通文本'),
    WriterEntityFactory::createCell('红色文本', $cellStyle)
];
$row = WriterEntityFactory::createRow($cells, $rowStyle);

工作表管理技巧

多工作表操作

// 获取当前工作表
$firstSheet = $writer->getCurrentSheet();

// 创建并切换到新工作表
$newSheet = $writer->addNewSheetAndMakeItCurrent();

// 切换回之前的工作表
$writer->setCurrentSheet($firstSheet);

// 获取所有工作表
$allSheets = $writer->getSheets();

工作表属性设置

$sheet = $writer->getCurrentSheet();
$sheet->setName('销售数据');  // 设置工作表名称

// 读取时获取工作表属性
foreach ($reader->getSheetIterator() as $sheet) {
    $name = $sheet->getName();
    $isVisible = $sheet->isVisible();
}

命名规范提示：Excel 对工作表名称有严格限制（长度≤31字符，不能包含特殊字符等），开发者需自行确保合规。

流畅接口实践

Box/Spout 支持流畅的链式调用：

WriterEntityFactory::createWriterFromFile('data.xlsx')
    ->setTempFolder('/temp')
    ->openToFile('output.xlsx')
    ->addRow($header)
    ->addRows($dataRows)
    ->close();