README

为Yii2提供的电子表格数据导出扩展

本扩展提供了将数据导出到电子表格的功能，例如Excel、LibreOffice等。

有关许可证信息，请查看LICENSE文件。

用法

本扩展提供了将数据导出到电子表格的功能，例如Excel、LibreOffice等。它由phpoffice/phpspreadsheet库提供支持。导出是通过\jstudioo\spreadsheet\Spreadsheet实例执行的，它提供了类似于\yii\grid\GridView小部件的界面。

示例

<?php

use jstudioo\spreadsheet\Spreadsheet;
use yii\data\ArrayDataProvider;

$exporter = new Spreadsheet([
    'dataProvider' => new ArrayDataProvider([
        'allModels' => [
            [
                'name' => 'some name',
                'price' => '9879',
            ],
            [
                'name' => 'name 2',
                'price' => '79',
            ],
        ],
    ]),
    'columns' => [
        [
            'attribute' => 'name',
            'contentOptions' => [
                'alignment' => [
                    'horizontal' => 'center',
                    'vertical' => 'center',
                ],
            ],
        ],
        [
            'attribute' => 'price',
        ],
    ],
]);
$exporter->save('/path/to/file.xls');

请参考\jstudioo\spreadsheet\Column类以获取有关列属性和配置规范的信息。

在运行Web应用程序时，您可以使用\jstudioo\spreadsheet\Spreadsheet::send()方法通过下载对话框将结果文件发送到浏览器。

<?php

use jstudioo\spreadsheet\Spreadsheet;
use yii\data\ActiveDataProvider;
use yii\web\Controller;

class ItemController extends Controller
{
    public function actionExport()
    {
        $exporter = new Spreadsheet([
            'dataProvider' => new ActiveDataProvider([
                'query' => Item::find(),
            ]),
        ]);
        return $exporter->send('items.xls');
    }
}

多工作表文件

您可以创建包含多个工作表（标签）的输出文件。例如：您可能希望导出有关办公室使用的设备的资料，将显示器、鼠标、键盘等分别列出，但都在同一个文件中。为此，您需要在创建最终文件之前手动调用具有不同配置的\jstudioo\spreadsheet\Spreadsheet::render()方法。例如

<?php

use jstudioo\spreadsheet\Spreadsheet;
use yii\data\ActiveDataProvider;
use app\models\Equipment;

$exporter = (new Spreadsheet([
    'title' => 'Monitors',
    'dataProvider' => new ActiveDataProvider([
        'query' => Equipment::find()->andWhere(['group' => 'monitor']),
    ]),
    'columns' => [
        [
            'attribute' => 'name',
        ],
        [
            'attribute' => 'price',
        ],
    ],
]))->render(); // call `render()` to create a single worksheet

$exporter->configure([ // update spreadsheet configuration
    'title' => 'Mouses',
    'dataProvider' => new ActiveDataProvider([
        'query' => Equipment::find()->andWhere(['group' => 'mouse']),
    ]),
])->render(); // call `render()` to create a single worksheet

$exporter->configure([ // update spreadsheet configuration
    'title' => 'Keyboards',
    'dataProvider' => new ActiveDataProvider([
        'query' => Equipment::find()->andWhere(['group' => 'keyboard']),
    ]),
])->render(); // call `render()` to create a single worksheet

$exporter->save('/path/to/file.xls');

结果您将获得一个包含3个工作表（标签）的单个*.xls文件：“显示器”、“鼠标”和“键盘”。

使用\jstudioo\spreadsheet\Spreadsheet::configure()，您可以重置任何电子表格参数，包括columns。因此，您可以将多个完全不同的工作表合并到单个文件中。

大数据处理

\jstudioo\spreadsheet\Spreadsheet允许导出\yii\data\DataProviderInterface和\yii\db\QueryInterface实例。导出是通过批量处理的，这允许处理大量数据而不会出现内存溢出。

在\yii\data\DataProviderInterface的使用中，数据将使用分页机制分割成批量。因此，您应该设置分页，并设置页面大小以控制批量大小。

<?php

use jstudioo\spreadsheet\Spreadsheet;
use yii\data\ActiveDataProvider;

$exporter = new Spreadsheet([
    'dataProvider' => new ActiveDataProvider([
        'query' => Item::find(),
        'pagination' => [
            'pageSize' => 100, // export batch size
        ],
    ]),
]);
$exporter->save('/path/to/file.xls');

注意：如果您在数据提供程序中禁用了分页，则不会执行批量处理。

在\yii\db\QueryInterface的使用中，如果查询类（例如在\yii\db\Query或\yii\db\ActiveQuery的使用中）中存在batch()方法，则Spreadsheet将尝试使用该方法。如果不存在batch()方法，则将自动创建一个包含给定查询的yii\data\ActiveDataProvider实例。您可以通过\jstudioo\spreadsheet\Spreadsheet::$batchSize控制批量大小。

<?php

use jstudioo\spreadsheet\Spreadsheet;
use yii\data\ActiveDataProvider;

$exporter = new Spreadsheet([
    'query' => Item::find(),
    'batchSize' => 200, // export batch size
]);
$exporter->save('/path/to/file.xls');

注意：尽管批量数据处理减少了生成电子表格文件所需的资源量，但您的程序仍然可能会在处理大量数据时遇到PHP内存限制错误。这是因为创建的文档复杂度很大，在整个过程中存储在内存中。如果您需要导出大量数据集，请考虑使用jstudioo/csv-grid扩展通过简单的CSV数据格式进行操作。

复杂的表头

您可以将工作表标题中的某些列合并成组。例如：您可能有2个不同的数据列：'计划收入'和'实际收入'。在这种情况下，您可能希望将它们显示为单个列'Revenue'，分为2个子列：'计划'和'实际'。这可以通过使用\jstudioo\spreadsheet\Spreadsheet::$headerColumnUnions实现。其每个条目应指定'offset'，它决定了要跳过的列数，以及'length'，它决定了要合并的列数。合并的其他选项与常规列相同。例如

<?php

use jstudioo\spreadsheet\Spreadsheet;
use yii\data\ArrayDataProvider;

$exporter = new Spreadsheet([
    'dataProvider' => new ArrayDataProvider([
        'allModels' => [
            [
                'column1' => '1.1',
                'column2' => '1.2',
                'column3' => '1.3',
                'column4' => '1.4',
                'column5' => '1.5',
                'column6' => '1.6',
                'column7' => '1.7',
            ],
            [
                'column1' => '2.1',
                'column2' => '2.2',
                'column3' => '2.3',
                'column4' => '2.4',
                'column5' => '2.5',
                'column6' => '2.6',
                'column7' => '2.7',
            ],
        ],
    ]),
    'headerColumnUnions' => [
        [
            'header' => 'Skip 1 column and group 2 next',
            'offset' => 1,
            'length' => 2,
        ],
        [
            'header' => 'Skip 2 columns and group 2 next',
            'offset' => 2,
            'length' => 2,
        ],
    ],
]);
$exporter->save('/path/to/file.xls');

注意：仅支持单级标题列合并。更复杂的情况您需要自行处理。

自定义单元格渲染

在调用save()或send()方法之前，您可以编辑生成的电子表格，对其进行一些最后的调整。存在几种方法来简化此过程

\jstudioo\spreadsheet\Spreadsheet::renderCell() - 使用给定的内容和样式渲染指定的单元格。
\jstudioo\spreadsheet\Spreadsheet::applyCellStyle() - 将指定的样式应用于单元格。
\jstudioo\spreadsheet\Spreadsheet::mergeCells() - 将单元格范围合并为一个单元格。

在通过\jstudioo\spreadsheet\Spreadsheet::render()生成文档后，您可以使用这些方法覆盖或添加一些内容。例如

<?php

use jstudioo\spreadsheet\Spreadsheet;
use jstudioo\spreadsheet\SerialColumn;
use yii\data\ArrayDataProvider;

$exporter = new Spreadsheet([
    'dataProvider' => new ArrayDataProvider([
        'allModels' => [
            [
                'id' => 1,
                'name' => 'first',
            ],
            [
                'id' => 2,
                'name' => 'second',
            ],
        ],
    ]),
    'columns' => [
        [
            'class' => SerialColumn::class,
        ],
        [
            'attribute' => 'id',
        ],
        [
            'attribute' => 'name',
        ],
    ],
])->render(); // render the document

// override serial column header :
$exporter->renderCell('A1', 'Overridden serial column header');

// add custom footer :
$exporter->renderCell('A4', 'Custom A4', [
    'font' => [
        'color' => [
            'rgb' => '#FF0000',
        ],
    ],
]);

// merge footer cells :
$exporter->mergeCells('A4:B4');

$exporter->save('/path/to/file.xls');

提示：您可以使用\jstudioo\spreadsheet\Spreadsheet::$rowIndex获取紧接最后渲染的行的行号。

jstudioo / spreadsheet

维护者

详细信息