laravel-excel maatwebsite/excel 新版中文文档

原文https://blog.csdn.net/chenqiang088/article/details/88827179

项目从 5.2 升级到了 5.7，Excel 的导入导出，使用的 maatwebsite/excel laravel-excel 依赖包，也从 2.* 升级到了 3.*，发明不能用了，打开文档一看，这尼玛窜改也太大了吧，完全不能使用的节奏啊！
 
先分享几个链接：
    github 地点：
        https://github.com/Maatwebsite/Laravel-Excel
 
    官网地点：
        https://laravel-excel.maatwebsite.nl
 
    看文档的升级指南，可以发明官方保举了个链接，有人从 2.x 升级到 3.x，项目里进行的代码改削
        https://github.com/Maatwebsite/Laravel-Excel/issues/1799
PS：
    想搜下新版的中文文档，打开 google 搜索，输入 ‘maatwebsite/excel 中文文档‘，发明第 3 条居然是我之前写的博客，打开一看，吓我一跳，我尼玛压根没有一点印象，之前居然总结过旧版文档，而且写了 700 多行，有点受惊，我以前居然这么有耐心~
 
好了，闲话少数，开始新版文档学习之旅~
    依赖：
        PHP: ^7.0
        Laravel: ^5.5
        PhpSpreadsheet: ^1.4
        php_zip
        php_xml
        php_gd2
 
    安置：
        composer require maatwebsite/excel
 
    配置：
        Maatwebsite\Excel\ExcelServiceProvider 默认是自动发明并注册，我们也可以手动添加：
            config/app.php
                ‘providers‘ => [
                    /*
                     * Package Service Providers...
                     */
                    Maatwebsite\Excel\ExcelServiceProvider::class,
                ]
 
        Excel 门面(Facade)也是自动发明，也可以手动添加:
            config/app.php
                ‘aliases‘ => [
                    ...
                    ‘Excel‘ => Maatwebsite\Excel\Facades\Excel::class,
                ]
 
        颁布配置文件：
            php artisan vendor:publish
            会创建 config/excel.php
 
    导出：
        1.5分钟快速入门：
            在 App/Exports 下创建导出类
                php artisan make:export UsersExport --model=User
 
            UserExport.php 内容：
                <?php
 
                    namespace App\Exports;
 
                    use App\User;
                    use Maatwebsite\Excel\Concerns\FromCollection;
 
                    class UsersExport implements FromCollection
                    {
                        public function collection()
                        {
                            return User::all();
                        }
                    }
 
            控制器里挪用导出：
                use App\Exports\UsersExport;
                use Maatwebsite\Excel\Facades\Excel;
                use App\Http\Controllers\Controller;
 
                class UsersController extends Controller 
                {
                    public function export() 
                    {
                        return Excel::download(new UsersExport, ‘users.xlsx‘);
                    }
                }
 
            这样就导出了个 ‘users.xlsx‘ 文件
 
        2.导出调集
            导出的最简单方法是，创建一个自界说的导出类。就是使用之前的命令，在 App/Exports 下创建一个导出类
                php artisan make:export UsersExport --model=User
 
            1>常用要领
                控制器里下载：
                    public function export() 
                    {
                        return Excel::download(new InvoicesExport, ‘invoices.xlsx‘);
                    }
 
                控制器里生存到硬盘：
                    public function storeExcel() 
                    {
                        return Excel::store(new InvoicesExport, ‘invoices.xlsx‘, ‘s3‘);
                    }
 
            2>依赖注入：
                另一种写法，看文档
 
            3>调集宏：
                Laravel-Excel 为 Laravel 的导出调集类，供给了一些宏，更便利的下载和存储调集。
 
                下载：
                    (new Collection([
                        [1, ‘dongxuemin‘, 30], 
                        [2, ‘yangyaping‘, 30])
                    )->downloadExcel($filePath, $writerType = null, $headings = false);
 
                生存：
                    (new Collection([
                        [1, ‘dongxuemin‘, 30], 
                        [2, ‘yangyaping‘, 30])
                    )->storeExcel($filePath, $disk = null, $writerType = null, $headings = false);
 
                总结：
                    我们可以本身操作 new Collection 来结构调集，进行下载和存储
 
        3.在硬盘上存储导出数据：
            导出可以很容易地被存储到 Laravel 所撑持的任意文件系统。
 
            1>不通报参数，默认文件系统
                Excel::store(new InvoicesExport(2018), ‘invoices.xlsx‘);
 
            2>存储到 ‘s3‘ 文件系统
                Excel::store(new InvoicesExport(2018), ‘invoices.xlsx‘, ‘s3‘);
 
            3>存储到 ‘s3‘ 文件系统，并指定 ‘writer‘ 类型
                Excel::store(new InvoicesExport(2018), ‘invoices.xlsx‘, ‘s3‘, Excel::XLSX);
 
        4.导格外式：
            默认情况下，导格外式由导出文件的后缀决定，例如：‘user.xlsx‘，导格外式就是：\Maatwebsite\Excel\Excel::XLSX。我们也可以通报第二个参数，显式地指定导格外式。
                (new InvoicesExport)->download(‘invoices.xlsx‘, \Maatwebsite\Excel\Excel::XLSX);
 
            撑持的格局有：
                XLSX
                CSV
                TSV
                ODS
                XLS
                SLK
                XML
                GNUMERIC
                HTML
                MPDF
                DOMPDF
                TCPDF
 
        5.可导出的
            之前的要领中，我们使用 Excel::download 门面(Facade) 来导出。
            例如：在控制器中使用 Excel::download(new InvoicesExport(2018));
 
            Laravel Excel 也供给了一个 ‘Maatwebsite\Excel\Concerns\Exportable‘ trait，使得我们创建的导出类，自己具有可导出的要领。
 
            示例：
                use Maatwebsite\Excel\Concerns\Exportable;
 
                class InvoicesExport implements FromCollection
                {
                    use Exportable;
 
                    public function collection()
                    {
                        return Invoice::all();
                    }
                }
 
            这样，InvoicesExport 类自己就具有可导出要领，不用再使用 Excel 门面(Facade)
 
            下载：
                return (new InvoicesExport)->download(‘invoices.xlsx‘);
 
            存储：
                return (new InvoicesExport)->store(‘invoices.xlsx‘, ‘s3‘);
 
            可响应：
                可以使用 ‘Responsable‘ 接口，进一步简化导出操纵。
 
                use Illuminate\Contracts\Support\Responsable;
                class InvoicesExport implements FromCollection, Responsable
                {
 
                    // 要求必需指定 ‘fileName‘ 属性(导出的文件名)
                    private $fileName = ‘invoices.xlsx‘;    
                }
 
                下载：
                    return new InvoicesExport();
 
        6.从盘问导出
            在之前的例子中，我们在导出类中进行盘问。对付小型导出，这个是一个非常好的解决方案，但是对付大型导出，会有很大的性能开销。
 
            通过使用 ‘FromQuery‘，我们可以为导出筹备一个盘问。在底层，‘FromQuery‘ 盘问使用了 chunks 盘问，以减少性能开销。
 
            普通盘问：
 
                示例：
                    use Maatwebsite\Excel\Concerns\FromQuery;        // 引入 ‘FromQuery‘
 
                    class InvoicesExport implements FromQuery        // 实现 ‘FromQuery‘
                    {
                        use Exportable;
 
                        public function query()
                        {
                            return Invoice::query();                // 确保不要使用 ‘get()‘ 要领
                        }
                    }
 
                下载：
                    return (new InvoicesExport)->download(‘invoices.xlsx‘);
 
            自界说盘问
 
                /*
                    这个应该是我们最经常使用的要领！！！
                    我们一般都是按照用户的各类筛选条件，然后进行 query 盘问，然后得到最终的功效列表，再进行导出。
                    但因为新版，导出的数据功效，都是通过外部的导出类来实现了，我们必需将 query 参数，通报到导出类中，来获取功效集。
                 */
 
                普通示例：
                    use Maatwebsite\Excel\Concerns\FromQuery;        // 引入 ‘FromQuery‘
 
                    class InvoicesExport implements FromQuery        // 实现 ‘FromQuery‘
                    {
                        use Exportable;
 
                        public function __construct(int $year)        // 导入外部盘问参数
                        {
                            $this->year = $year;
                        }
 
                        public function query()
                        {
                            return Invoice::query()->whereYear(‘created_at‘, $this->year);            // 使用 where 盘问
                        }
                    }
 
                    下载：
                        // 通报盘问参数
                        return (new InvoicesExport(2018))->download(‘invoices.xlsx‘);
 
                设置器示例(另一种写法)：
                    use Maatwebsite\Excel\Concerns\FromQuery;        // 引入 ‘FromQuery‘
 
                    class InvoicesExport implements FromQuery        // 实现 ‘FromQuery‘
                    {
                        use Exportable;
 
                        public function forYear(int $year)            // 界说 ‘设置器‘
                        {
                            $this->year = $year;
                            
                            return $this;
                        }
 
                        public function query()
                        {
                            return Invoice::query()->whereYear(‘created_at‘, $this->year);            // 使用 where 盘问
                        }
                    }
 
                    下载：
                        // 挪用 ‘设置器‘
                        return (new InvoicesExport)->forYear(2018)->download(‘invoices.xlsx‘);
 
        7.从模板中导出
            界说导出类，同时界说一个导出模板，Laravel Excel 会将界说的 HTML table 转换为一个 Excel 电子表单
 
            示例：
                use Illuminate\Contracts\View\View;
                use Maatwebsite\Excel\Concerns\FromView;
 
                class InvoicesExport implements FromView
                {
                    public function view(): View
                    {
                        return view(‘exports.invoices‘, [
                            ‘invoices‘ => Invoice::all()
                        ]);
                    }
                }
 
            Blade 模板，界说一个标准的 <table> 即可，<thead> - 表头 & <tbody> - 表内容
                <table>
                    <thead>
                    <tr>
                        <th>Name</th>
                        <th>Email</th>
                    </tr>
                    </thead>
                    <tbody>
                    @foreach($users as $user)
                        <tr>
                            <td>{{ $user->name }}</td>
                            <td>{{ $user->email }}</td>
                        </tr>
                    @endforeach
                    </tbody>
                </table>
 
        8.行列队伍
            如果措置惩罚惩罚大量的数据导出，保举使用行列队伍来进行导出。
 
            行列队伍导出，底层实现是：使用 chunk 盘问，多个 job 任务链接在一起(应该是按挨次链接)。这些 job 任务以插入行列队伍的先后挨次正确执行，只有当前面的任务执行告成，后面的才会执行。
 
            普通示例：
                导出类界说一致
 
                下载，直接挪用 ‘queue()‘ 要领
                    (new InvoicesExport)->queue(‘invoices.xlsx‘);
                    return back()->withSuccess(‘Export started!‘);
 
            显示界说导出到行列队伍
                use Maatwebsite\Excel\Concerns\FromQuery;
                use Illuminate\Contracts\Queue\ShouldQueue;            // 引入 ‘ShouldQueue‘
 
                class InvoicesExport implements FromQuery, ShouldQueue        // 实现 ‘ShouldQueue‘
                {
                    use Exportable;
 
                    public function query()
                    {
                        return Invoice::query();
                    }
                }
 
                下载，使用 ‘store()‘ 要领
                    (new InvoicesExport)->store(‘invoices.xlsx‘);
 
            追加行列队伍任务
                queue() 要领返回 Laravel 的 ‘PendingDispatch‘ 实例。意味着，我们可以在行列队伍尾部添加特别的 job 任务，新添加的导出任务，只有在之前的导出都正确后，才会执行。
 
                示例：
                    use Illuminate\Bus\Queueable;                    // 引入 ‘Queueable‘
                    use Illuminate\Contracts\Queue\ShouldQueue;
                    use Illuminate\Queue\SerializesModels;            // 引入 ‘SerializesModels‘
 
                    class NotifyUserOfCompletedExport implements ShouldQueue
                    {
                        use Queueable, SerializesModels;            // 使用 ‘Queueable‘ & ‘SerializesModels‘
                        
                        public $user;
                        
                        public function __construct(User $user)        // 通报参数
                        {
                            $this->user = $user;
                        }
 
                        public function handle()                    // 挪用了 ‘handle()‘ 要领
                        {
                            $this->user->notify(new ExportReady());
                        }
                    }
 
                追加：
                    (new InvoicesExport)->queue(‘invoices.xlsx‘)->chain([
                        new NotifyUserOfCompletedExport(request()->user()),        // 通报参数
                    ]);
 
            自界说行列队伍：
                由于返回了 ‘PendingDispatch‘，我们也可以变动使用的行列队伍。(有时间可看下 PendingDispatch 源码)
 
                (new InvoicesExport)->queue(‘invoices.xlsx‘)->allOnQueue(‘exports‘);
 
        9.多个表单
            多表单的导出，需要使用 ‘WithMultipleSheets‘。然后在导出类中，实现 ‘sheets()‘ 要领，sheets() 要领，返回一个由 ‘单个表单东西‘ 构成的数组。
 
            多表单的导出，需要2个类：
                1>导出类
                2>单个表单类
 
            示例：
                1>导出类
                    use Maatwebsite\Excel\Concerns\WithMultipleSheets;
 
                    class InvoicesExport implements WithMultipleSheets
                    {
 
                        // 实现 sheets() 要领，返回一个由 ‘单个表单东西‘ 构成的数组。
                        public function sheets(): array
                        {
                            $sheets = [];
 
                            for ($month = 1; $month <= 12; $month++) {
                                $sheets[] = new InvoicesPerMonthSheet($this->year, $month);
                            }
 
                            return $sheets;
                        }
                    }
 
                2>单个表单类，可以实现 ‘FromQuery‘，‘FromCollection‘，...
                    use Maatwebsite\Excel\Concerns\FromQuery;        // 引入 ‘FromQuery‘
                    use Maatwebsite\Excel\Concerns\WithTitle;        // 引入 ‘WithTitle‘(可改削 excel 表单名)
 
                    class InvoicesPerMonthSheet implements FromQuery, WithTitle
                    {
 
                        // 盘问
                        public function query()
                        {
                            return Invoice
                                ::query()
                                ->whereYear(‘created_at‘, $this->year)
                                ->whereMonth(‘created_at‘, $this->month);
                        }
 
                        // Excel 电子表单名
                        public function title(): string
                        {
                            return ‘Month ‘ . $this->month;
                        }
                    }
 
        10.映射数据
            映射行
                添加 ‘WithMapping‘，我们可以界说一个 ‘map()‘ 要领，将盘问到的每条数据，颠末 map() 要领措置惩罚惩罚，返回我们需要的 ‘一整行‘。
 
                示例：
                    use Maatwebsite\Excel\Concerns\WithMapping;        // 引入 ‘WithMapping‘
 
                    class InvoicesExport implements FromQuery, WithMapping        // 实现 ‘WithMapping‘
                        
                        // 界说 ‘map()‘ 要领，参数是 ‘盘问出来的每行数据东西‘
                        public function map($invoice): array
                        {
                            return [
                                $invoice->invoice_number,
                                Date::dateTimeToExcel($invoice->created_at),
                            ];
                        }
                    }
 
            添加标题行
                添加 ‘WithHeadings‘，界说 ‘headings()‘ 要领，来添加标题行
 
                示例：
                    use Maatwebsite\Excel\Concerns\WithHeadings;        // 引入 ‘WithHeadings‘
 
                    class InvoicesExport implements FromQuery, WithHeadings        // 实现 ‘WithHeadings‘
                        
                        // 界说 ‘headings()‘ 要领
                        public function headings(): array
                        {
                            return [
                                ‘#‘,
                                ‘Date‘,
                            ];
                        }
                    }
 
        11.格局化列
            使用 ‘WithColumnFormatting‘，界说 ‘columnFormats()‘ 要领，我们可以轻松格局化整列数据。    
 
            如果想要更多自界说内容，建议使用 AfterSheet 事件直接与底层 Worksheet 类进行交互。
 
            示例：
                use PhpOffice\PhpSpreadsheet\Shared\Date;            // 日期措置惩罚惩罚
                use PhpOffice\PhpSpreadsheet\Style\NumberFormat;    // 数字格局化
                use Maatwebsite\Excel\Concerns\WithColumnFormatting;        // 引入 ‘列格局化‘
                use Maatwebsite\Excel\Concerns\WithMapping;
 
                class InvoicesExport implements WithColumnFormatting, WithMapping
                {
                    public function map($invoice): array
                    {
                        return [
                            $invoice->invoice_number,
                            Date::dateTimeToExcel($invoice->created_at),
                            $invoice->total
                        ];
                    }
                    
                    /**
                     * @return array
                     */
                    public function columnFormats(): array
                    {
                        return [
                            ‘B‘ => NumberFormat::FORMAT_DATE_DDMMYYYY,
                            ‘C‘ => NumberFormat::FORMAT_CURRENCY_EUR_SIMPLE,
                        ];
                    }
                }
 
            日期措置惩罚惩罚：
                保举在 map() 要领中使用 ‘\PhpOffice\PhpSpreadsheet\Shared\Date::dateTimeToExcel()‘
 
            自动调解尺寸：
                引入 ‘ShouldAutoSize‘，，让 Laravel Excel 自动调解单元格宽度
 
                use Maatwebsite\Excel\Concerns\ShouldAutoSize;
                Class InvoicesExport implements ShouldAutoSize
                {
 
                }
 
        12.供给的所有可用的 ‘Export concerns‘
            接口：
                Maatwebsite\Excel\Concerns\FromArray - 使用 array 来实现导出
                Maatwebsite\Excel\Concerns\FromCollection - 使用 Laravel collection 来实现导出
                Maatwebsite\Excel\Concerns\FromIterator - 使用 iterator(迭代器)来实现导出
                Maatwebsite\Excel\Concerns\FromQuery - 使用 Eloquent query 来实现导出
                Maatwebsite\Excel\Concerns\FromView - 使用 (Blade) 模板来实现导出
                Maatwebsite\Excel\Concerns\WithTitle - 设置事情簿或事情表标题
                Maatwebsite\Excel\Concerns\WithHeadings - 添加表头
                Maatwebsite\Excel\Concerns\WithMapping - 在写入文件前，格局化行
                Maatwebsite\Excel\Concerns\WithColumnFormatting - 格局化列
                Maatwebsite\Excel\Concerns\WithMultipleSheets - 开启多表单撑持
                Maatwebsite\Excel\Concerns\ShouldAutoSize - 在事情表中，自动调解列宽
                Maatwebsite\Excel\Concerns\WithStrictNullComparison - 在测试单元格的 null 时，使用严格对照
                Maatwebsite\Excel\Concerns\WithEvents - 注册事件，挂载到 ‘PhpSpreadsheet‘ 措置惩罚惩罚过程中
                Maatwebsite\Excel\Concerns\WithCustomQuerySize - 允许 ‘Exportable‘ 实现 ‘FromQuery‘，来供给它们本身的自界说盘问巨细。
                Maatwebsite\Excel\Concerns\WithCustomCsvSettings - 允许对指定的导出，运行自界说的 CSV 设置。
                Maatwebsite\Excel\Concerns\WithCharts - 允许运行一个或多个 PhpSpreadsheet Chart 实例
                Maatwebsite\Excel\Concerns\WithDrawings - 允许运行一个或多个 PhpSpreadsheet Drawing 实例
                Maatwebsite\Excel\Concerns\WithCustomStartCell - 允许指定一个自界说起始单元格。注意：仅撑持 ‘FromCollection‘ 导出
 
            Traits：
                Maatwebsite\Excel\Concerns\Exportable - 给导出类自身添加 ‘download()‘ 和 ‘store()‘ 要领
                Maatwebsite\Excel\Concerns\RegistersEventListeners
 
        13.扩展
            有点庞大，不总结了，看文档

laravel-excel maatwebsite/excel 新版中文文档