README

安装此扩展的首选方式是通过composer。

运行

composer require dfware/spreadsheet

或添加

"dfware/spreadsheet": "*"

到您的composer.json文件的require部分。

使用方法

此扩展提供了将数据导出到电子表格（例如Excel，LibreOffice等）的功能。它由phpoffice/phpspreadsheet库提供支持。导出通过\yii2tech\spreadsheet\Spreadsheet实例执行，该实例提供了类似于\yii\grid\GridView小部件的接口。

示例

<?php

use yii2tech\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');

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

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

<?php

use yii2tech\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');
    }
}

多个工作表文件

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

<?php

use yii2tech\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文件：“显示器”，“鼠标”和“键盘”。

使用\yii2tech\spreadsheet\Spreadsheet::configure()，您可以重置任何电子表格参数，包括columns。因此，您可以将几个完全不同的表格组合成单个文件。

大数据处理

\yii2tech\spreadsheet\Spreadsheet允许导出\yii\data\DataProviderInterface和\yii\db\QueryInterface实例。导出通过批量执行，这允许在不溢出内存的情况下处理大量数据。

在\yii\data\DataProviderInterface的使用情况下，数据将使用分页机制分割到批中。因此，您应该设置分页以设置批次大小，以便控制批次大小。

<?php

use yii2tech\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()方法。如果不存在batch()方法，则将自动创建yii\data\ActiveDataProvider实例来包围给定的查询。您可以通过\yii2tech\spreadsheet\Spreadsheet::$batchSize控制批次大小。

<?php

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

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

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

复杂的标题

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

<?php

use yii2tech\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() 方法之前，您能够编辑生成的电子表格，对其进行一些最终的调整。存在几种方法来简化此过程

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

您可以在通过 \yii2tech\spreadsheet\Spreadsheet::render() 组装好文档后使用这些方法来覆盖或添加一些内容。例如

<?php

use yii2tech\spreadsheet\Spreadsheet;
use yii2tech\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');

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

dfware / spreadsheet

维护者

详细信息