laravel-excel maatwebsite/excel 新版中文文檔php
原文https://blog.csdn.net/chenqiang088/article/details/88827179laravel
項目從 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.擴展
有點複雜，不總結了，看文檔git