README

xlsx-reader 是 spreadsheet-reader 的一部分，是一个针对 XLSX 的电子表格读取器的扩展。

它提供读取指定 XLSX 文件中数据的函数。

该库的焦点是提供 XLSX 电子表格单元格中的数据，而不是文档的样式。因此，该库不支持严格来说不是实现此目标所必需的 XLSX 功能。仅支持基本的单元格值格式化和共享字符串功能。

要求

• PHP 7.1.0 或更高版本，至少启用以下可选功能
  • Zip（见 https://php.ac.cn/manual/en/zip.installation.php）
  • XMLReader（见 https://php.ac.cn/manual/en/xmlreader.installation.php）

使用 Composer 安装

该包可在 Packagist 上找到。您可以使用 Composer 安装它。

composer require aspera/xlsx-reader

使用方法

所有数据都是顺序地从文件中读取的，每一行都作为列的数组返回。

<?php
use Aspera\Spreadsheet\XLSX\Reader;

$reader = new Reader();
$reader->open('example.xlsx');

foreach ($reader as $row) {
    print_r($row);
}

$reader->close();

也支持具有多个工作表的 XLSX 文件。getSheets() 方法返回一个数组，其中以工作表索引为键，以 Worksheet 对象为值。changeSheet($index) 方法用于在读取之间切换工作表。

<?php
use Aspera\Spreadsheet\XLSX\Reader;

$reader = new Reader();
$reader->open('example.xlsx');

$sheets = $reader->getSheets();
foreach ($sheets as $index => $sheet_data) {
    $reader->changeSheet($index);
    echo 'Sheet #' . $index . ': ' . $sheet_data->getName();

    // Note: Any call to changeSheet() resets the current read position to the beginning of the selected sheet.
    foreach ($reader as $row_number => $row) {
        echo 'Row #' . $row_number . ': ' . print_r($row, true);
    }
}

$reader->close();

可以通过 ReaderConfiguration 实例指定调整读取器行为和输出的选项。

有关支持的选项及其效果的完整列表，请参阅 ReaderConfiguration 的代码文档。

<?php
use Aspera\Spreadsheet\XLSX\Reader;
use Aspera\Spreadsheet\XLSX\ReaderConfiguration;
use Aspera\Spreadsheet\XLSX\ReaderSkipConfiguration;

$reader_configuration = (new ReaderConfiguration())
  ->setTempDir('C:/Temp/')
  ->setSkipEmptyCells(ReaderSkipConfiguration::SKIP_EMPTY)
  ->setReturnDateTimeObjects(true)
  ->setCustomFormats(array(20 => 'hh:mm'));
// For a full list of supported options and their effects, consult the in-code documentation of ReaderConfiguration.

$spreadsheet = new Reader($reader_configuration);

有关库性能的注意事项

XLSX 文件使用所谓的“共享字符串”来优化文件大小，以便在相同的字符串多次重复的情况下。对于较大的文档，这个共享字符串列表可能会变得相当大，这会导致解析文档时出现性能瓶颈或高内存消耗。

为了解决这个问题，读取器选择合理的默认最大 RAM 消耗。一旦超出这个内存限制，就会使用文件系统进行进一步的优化策略。

要详细配置此行为，例如增加读取器可用的内存量，可以将 SharedStringsConfiguration 实例附加到提供给读取器构造函数的 ReaderConfiguration 实例。

有关支持的选项及其效果的完整列表，请参阅 SharedStringsConfiguration 的代码文档。

<?php
use Aspera\Spreadsheet\XLSX\Reader;
use Aspera\Spreadsheet\XLSX\ReaderConfiguration;
use Aspera\Spreadsheet\XLSX\SharedStringsConfiguration;

$shared_strings_configuration = (new SharedStringsConfiguration())
    ->setCacheSizeKilobyte(16 * 1024)
    ->setUseOptimizedFiles(false);
// For a full list of supported options and their effects, consult the in-code documentation of SharedStringsConfiguration.

$reader_configuration = (new ReaderConfiguration())
  ->setSharedStringsConfiguration($shared_strings_configuration);

$spreadsheet = new Reader($reader_configuration);

有关不受支持的功能的注意事项

此读取器的目的是允许从 XLSX 文档中读取基本数据（文本、数字、日期...）。因此，没有计划扩展支持以包括 XLSX 文件中所有可用的功能。仅支持 XLSX 功能的最小子集。

特别是，以下关于不受支持的功能应该注意

• 忽略显示单元格宽度。因此，在流行 xlsx 编辑器会使用科学记数法或 "#####"-占位符缩短值的情况下，读取器将返回未缩短的值。
• 不支持具有多个内部共享字符串文件的文件。
• 不支持具有多个内部样式定义文件的文件。
• 分数支持不完整。读取器输出的结果可能与原始输入略有出入。

许可

本库中的所有代码均采用MIT许可，许可信息包含在LICENSE.md文件中。