laravel-excel文档翻译笔记详细
laravel-excel文档翻译笔记
转自这位前辈的总结文档
1.安装
1>composer 安装 "maatwebsite/excel": "~2.1.0"
2>app/config/app.php，添加服务
Maatwebsite\Excel\ExcelServiceProvider::class
设置Facade：
'Excel' => Maatwebsite\Excel\Facades\Excel::class,
这样，就将 'excel' 绑定到了laravel的ioc容器
$excel = App::make('excel');
3>生成配置文件
php artisan vendor:publish --provider="Maatwebsite\Excel\ExcelServiceProvider"
将会在 'app/config/' 添加 'excel.php' 文件
4>依赖
php > 5.3.7
laravel >= 4.1
PHPOffice PHPExcel >= 1.8.0
php_zip(如果需要处理 .xlsx, .ods, .gnumeric 文件，需要此扩展)
php_xml
php_gd2(如果需要精确的自动计算列宽，需要此扩展)
2.导入
1>导入文件
Excel::load('file.xls');
Excel::load('file.xls', function($reader){
})
回调函数可选
2>ExcelFile injections(注入)
应该是参照Laravel5.0的FormRequest注入，Excel提供了ExcelFile注入
1)ExcelFile类
class UserListImport extends \Maatwebsite\Excel\Files\ExcelFile
{
public function getFile()
{
return storage_path('exports') . '/file.csv';
}
public function getFilters()
{
return [
'chunk'
];
}
}
getFile() - 返回要导入的excel的文件名及路径。
getFilters() - 可以启用各种 'filter'(过滤器)
getFile()如果想动态获取用户上传的文件，可以参考下方：
public function getFile()
{
// Import a user provided file
$file = Input::file('report'); // 文件上传
$filename = $this->doSomethingLikeUpload($file); // 执行上传，得到上传后路径
// Return it's location
return $filename; // 返回上传后路径
}
2)使用
定义好了ExcelFile注入类，可以注入到 构造方法或其他方法
Class TestController extends Controller()
{
// 从这里就很明显知道是个什么意思了
// public function __construct(Request $request)
// 我们经常使用Request请求
public function __construct(UserListImport $import)
{
// 获取结果
$results = $import->get();
}
}
3)CSV配置
可以定义一些可选的CSV设置项，用类的 'protected' 属性来定义
protected $delimiter = ',';
protected $enclosure = '"';
protected $lineEnding = '\r\n';
4)导入处理
为了完全将Excel导入代码与控制器解耦，可以使用导入处理
public function importUserList(UserListImport $import)
{
$import->handleImport(); // 导入处理
}
上面的 'handleImport()' 方法，将会动态调用一个 '类名'.'Handler' 的处理类(以我们定义的 'UserListImport' 为例，就应该是 'UserListImportHandler')，所以我们还得定义 '处理类'
class UserListImportHandler implements \Maatwebsite\Excel\Files\ImportHandler {
public function handle(UserListImport $import)
{
// 获取结果
$results = $import->get();
}
}
提示：
就是将处理结果的方法，又抽离到另一个类中(算是公共方法，而不是仅这个控制器可用)
3>处理导入结果
1)获取所有工作表和每个工作表内的所有行
2种处理方式，都可以：
1.Excel::load('file.xls', function($reader){})->get();
2.Excel::load('file.xls', function($reader){
// 获取所有结果
$results = $reader->get();
// all()方法，是对 get()方法的一个包装，工作一致
$results = $reader->all();
});
get()和all()，会返回一个 '工作表集合' 或者 '单个工作表内所有行的集合'(发现只有1张工作表时)
提示：
我们可以通过配置：excel.php -> force_sheets_collection = true，强制，即使单个表，也返回 '工作表集合'
2)表标题
默认，工作表的第一行为表标题
$row->firstname;
注意：
默认情况下，这些属性会被转换为 'slug'。可以通过配置import.heading来改变默认行为。可选值有：
true | false | slugged | ascii | numberic | hashed | trans | original
true 和 slugged 也会被转换为 'ascii'，等同于设置了 'ascii'
3)集合
工作表(sheets)、行(rows)、单元格(cells)都是集合，只要是通过 'get()' 方法获取后，我们都可以调用 'laravel' 的集合方法
$reader->get()->groupBy();
4)获取第一张工作表 或 第一行
$reader->first();
注意：
上面也提到了 'force_sheets_collection' 配置，根据这一配置，excel只有单个工作表时，这个获取的可能是 '第一张工作表' 或 '第一行'
5)工作簿(excel文件)和工作表(sheets)标题
$reader->getTitle(); // excel文件名
foreach($reader as $sheet)
{
$sheetTitle = $sheet->getTitle(); // 工作表名
}
6)限制文件读取
1.获取行
$reader->takeRows(10);
$reader->limitRows(10);
2.跳过行(偏移)
$reader->skipRows(10); // 跳过10行
$reader->limitRows(false, 10); // 跳过10行，但不进行行限制，读取剩余所有行
$reader->skipRows(10)->takeRows(10); // 跳过10行，并读取10行
3.获取列
$reader->takeColumns(10);
$reader->limitColumns(10);
4.跳过列(偏移)
$reader->skipColumns(10); // 跳过10列
$reader->limitColumns(false, 10); // 跳过10列，但不进行列限制，读取剩余所有列
$reader->skipColumns(10)->takeColumns(10); // 跳过10列，并读取10列
7)结果转换
默认获取的是一个集合
1)转换为数组
$reader->toArray();
2)转换为对象
$reader->toObject();
8)打印结果
$reader->dump(); // 打印结果
$reader->dd(); // 打印结果，并退出
9)迭代结果
$reader->each(function($sheet){ // 循环所有工作表
$sheet->each(function($row){ // 循环单个工作表，所有行
});
});
提示：
也可使用 foreach() 来循环结果集
4>选择工作表和列
1)选择指定的工作表
Excel::selectSheets('sheet1')->load();
2)选择多个工作表
Excel::selectSheets('sheet1', 'sheet2')->load(); // 也可以传递一个数组 ['sheet1', 'sheet2']
3)通过下标选择工作表(index 从 0 开始)
Excel::selectSheetsByIndex(0)->load();
Excel::selectSheetsByIndex(0, 1)->load();
4)选择列
1.$reader->select(['firstname', 'lastname'])->get();
2.$reader->get(['firstname', 'lastname']);
注意：
所有的获取结果方法(例如：all(), first(), dump(), toArray(), ...)，都接收一个 '列数组' 参数
5>日期
默认情况下，日期将被解析为一个 'Carbon' 对象(这个可以了解下，是composer的一个日期处理包).
可配置 dates.enabled = false，禁用日期格式(对整个项目生效)
1)单个导入，开启/禁用日期格式化，使用 '->formatDates($boolean, $format)'
$reader->formatDates(true); // 启用
$reader->formatDates(false); // 禁用
$reader->formatDates(true, 'Y-m-d'); // 启用，并设置日期格式
2)日期格式
默认，日期并未格式化，但是返回一个 'Carbon' 对象，我们有2种方式，来格式化日期：
1.先用过 'get()' 等方法获取结果后，再格式化
$rows->each(function($row){
$created_at = $row->created_at->format('Y-m-d'); // 获取到的$row->created_at，已经是一个 'Carbon' 对象
});
2.设置一个默认的日期格式
1>在 excel.php 配置文件中，设置日期格式，则不会再返回 'Carbon' 对象
2>或者，我们仅在本次导入设置日期格式，$reader->setDateFormat('Y-m-d');
3)设置自定义日期列
不是Excel格式日期的单元格不会被解析为日期。我们可以设置哪些字段，来手动格式化为日期格式。
$reader->setDateColumns(['created_at', 'updated_at'])->get();
6>计算公式
默认情况下，文件内的公式会被计算，并返回结果。
可配置 import.calculate 来改变默认行为。
1)import.calculate = false
2)仅在单次导入时，设置
$reader->calculate([fals]); // 禁用
$reader->calculate(true); // 启用
7>自定义单元格值(例如：统一添加前缀，替换敏感词为 '*'等，处理单元格的值)
看文档
8>缓存和单元格缓存
1)单元格缓存
在 excel.php 中，配置 '单元格缓存'。默认开启缓存，并使用 '内存缓存'
2)缓存excel文件结果集
记录结果集，可使用 remember($minutes) 方法。下次载入同样文件时(如果它还在缓存中)，将返回缓存的结果
$results = $reader->remember(10)->get(); // 缓存10分钟
9>分块导入
1)当导入大文件时，最好的解决方法是 '分块导入'。可通过 filter('chunk') 来开启；并且使用 'chunk($size, $callback)' 来代替 'get()' 获取结果集。
Excel::filter('chunk')->load('file.csv')->chunk(250, function($results)
{
// 处理结果集
foreach($results as $row){
}
});
2)ExcelFile 注入实例：
class UserListImport extends \Maatwebsite\Excel\Files\ExcelFile
{
public function getFile()
{
return storage_path('exports') . '/file.csv';
}
public function getFilters()
{
return [
'chunk' // 使用 'chunk' 过滤器
];
}
}
public function importUserList(UserListImport $import) // 注入 ExcelFile
{
$import->chunk(250, function($results)
{
});
}
3)分块导入，队列
如果我们在配置文件中，启用了队列驱动，会自动将每个分块放入队列
如果不想使用该功能，设置第3个参数为false
chunk($size, $callback, false)
如果想使用 '非默认工作队列'，设置第3个参数为 '指定的工作队列名'
chunk($size, $callback, $shouldQueue)
10>批量导入
1)导入目录下的所有文件，仅 '.xls, .xlsx, .csv' 后缀的文件
Excel::batch('app/storage/uploads', function($row, $file){
// 处理目录下的导入文件的每一行
$rows->each(function($row){
dd($row->firstname);
});
});
2)导入多个文件
$files = ['1.xls', '2.xls'];
Excel::batch($files, function($row, $file){
})
3)导入目录|多个文件，每个文件包含多个工作表
Excel::batch('app/storage/uploads', function($sheets, $file){
$sheets->each(function($sheet){
});
});
11>设置导入配置
当使用高级Excel文件（例如：没有任何标题列）时，导入这些文件可能很复杂。使用 byConfig() 来处理这类问题
关联 excel.php 配置文件的 import.sheets 配置
Excel::load('file.xls')->byConfig('excel::import.sheets', function($sheet){
// 获取excel.php的import.sheets配置项的 'firstname' 配置
$firstname = $sheet->firstname;
});
注意：
如果正在使用多张工作表，byConfig() 将会作用于每张表。如果只存在于一张表中，可以使用 'selectSheets()' 来选取指定的工作表
13>编辑现有的文件
通过加载现有的Excel文件，修改后再导出，来编辑现有的文件。
Excel::load('file.csv', function($file){
// 修改
})->export('csv');
14>转换
通过 'convert()' 转换文件类型
Excel::load('file.csv', function($file){
// 修改
})->convert('xls');
15>其他
1)禁止使用第一行作为集合属性
默认情况下，我们将使用文件的第一行作为表标题(也作为集合的属性名)。
可以修改 excel.php 的配置项 import.heading，来改变默认行为。
$reader->noHeading(); // 仅在本次改变默认行为
2)设置单元格名字分隔符
默认情况下，集合属性名为第一行。空格将被转换为 '_'。例如：Created at --> created_at
可以修改 excel.php 的配置项 import.separator，来改变默认行为。
$reader->setSeparator('-''); // 仅在本次改变默认行为
3)忽略空单元
默认空单元不会被忽略，在单元格集合中显示为null
可以修改 excel.php 的配置项 import.ignoreEmpty，来改变默认行为。
$reader->ignoreEmpty(); // 仅在本次改变默认行为
4)输入编码
默认是 UTF-8
Excel::load('1.csv', function($reader){ // 使用闭包
}, 'UTF-8');
Excel::load('1.csv', 'UTF-8'); // 不使用闭包
5)CSV设置
查看 excel.php csv等配置
3.导出
1>简单的Excel导出
1)基本
Excel::create('文件名');
Excel::create('文件名', function($excel){ // 使用闭包
// 调用 写方法
});
2)改变属性
可以在闭包内，改变一些属性。它们中的大多数是默认设置。可查看默认配置：
app/config/packages/maatwebsite/excel/config.php
Excel::create('文件名', function($excel){ // LaravelExcelWriter
$excel->setTitle('聘学兼优会员表'); // 设置标题
$excel->setCreator('xxx')
->setCompany('yyy'); // 链式调用
$excel->setDescription('描述'); // 单个调用，设置描述
});
2>导出
下载创建的excel文件，使用 'export($ext)' 或 'download($ext)'
1)导出为 Excel5(xls)
Excel::create('文件名', function($excel){
})->export('xls'); // 或 ->download('xls');
2)导出为 Excel2007(xlsx)
export('xlsx');
3)导出为 CSV
export('csv');
注意：
还可以在配置文件内设置默认的 'enclosure' 和 'delimiter'
4)导出为 PDF
为了支持导出为pdf格式，composer需要安装任意一种
"dompdf/dompdf": "~0.6.1"
"mpdf/mpdf": "~6.1"
"tecnick.com/tcpdf": "~6.0.0"
并且配置文件中，配置 pdf.driver
3>NewExcelFile injections(注入)
1)NewExcelFile 类
class UserListExport extends \Maatwebsite\Excel\Files\NewExcelFile {
public function getFilename()
{
return 'filename'; // 定义想要的文件名
}
}
2)使用
定义好了NewExcelFile注入类，可以注入到 构造方法或其他方法
class ExampleController extends Controller {
public function exportUserList(UserListExport $export) // 注入
{
// work on the export
return $export->sheet('sheetName', function($sheet)
{
})->export('xls');
}
}
3)导出处理
为了完全将Excel导出代码与控制器解耦，可以使用导出处理
class ExampleController extends Controller {
public function exportUserList(UserListExport $export)
{
// 处理导出
$export->handleExport();
}
}
上面的 'handleExport()' 方法，将会动态调用一个 '类名'.'Handler' 的处理类(以我们定义的 'exportUserList' 为例，就应该是 'exportUserListHandler')，所以我们还得定义 '处理类'
class exportUserListHandler implements \Maatwebsite\Excel\Files\ExportHandler {
public function handle(UserListExport $export)
{
return $export->sheet('表单名', function($sheet){
})->export('xls');
}
}
4>存储到服务器
将创建的excel文件，保存到服务器，使用 'store($ext, $path = false, $returnInfo = false)' 或 'save()'
1)导出到默认路径，默认是 'storage/exports' 目录。可修改 excel.php 的 export.store.path
Excel::create('文件名', function($excel){
})->store('xls');
2)导出到指定路径
->store('xls', storage_path('excel/exports'));
3)存储并导出
->store('xls')->export('xls');
4)存储并返回存储信息
->store('xls', false, true); // 设置第3个参数为 true
也可在 excel.php 设置 export.store.returnInfo，进行全局默认配置
返回的信息有：
full - 文件全路径
path - 路径，不含文件名
file - 文件名
title - 文件标题
ext - 文件后缀
注意：
确保目录有写权限！
5>工作表
1)创建一个工作表
Excel::create('文件名', function($excel){
$excel->sheet('工作表名', function($sheet){
});
})->export('xls');
2)创建多个工作表
Excel::create('文件名', function($excel){
$excel->sheet('表1', function($sheet){
});
$excel->sheet('表2', function($sheet){
});
})->export('xls');
3)改变属性
可以在闭包内，改变一些属性。它们中的大多数是默认设置。可查看默认配置：
app/config/packages/maatwebsite/excel/config.php
Excel::create('文件名', function($excel){
$excel->sheet('工作表名', function($sheet){
$sheet->setOrientation('landscape'); // 设置横向属性
});
})->export('xls');
4)默认页边距
excel.php 设置 export.sheets.page_margin 来设置页边距，可选值有：false | 单个值 | 数组
也可使用 setPageMargin()，仅在本次导出设置
$sheet->setPageMargin([0.25, 0.30, 0.25, 0.30]); // 上、右、下、左
$sheet->setPageMargin(0.25);
5)设置工作表密码
// 默认保护
$sheet->protect('密码');
// 高级保护
$sheet->protect('密码', function(\PHPExcel_Worksheet_Protection $protection){
$protection->setSort(true);
});
6>从数组中创建工作表
1)数组
1.使用 fromArray()
Excel::create('Filename', function($excel) {
$excel->sheet('Sheetname', function($sheet) {
$sheet->fromArray(array(
array('data1', 'data2'),
array('data3', 'data4')
));
});
})->export('xls');
2.也可使用 with() 替代 fromArray()
$sheet->with();
3.在closure(闭包)内，调用，使用 'use()'
$data = [
['xxx', 'yyy'],
['111', '222'],
];
/*
注意：
闭包想要使用外部的变量，必须使用 'use()' 来引入
*/
Excel::create('Filename', function($excel) use($data){
$excel->sheet('Sheetname', function($sheet) use($data){
$sheet->fromArray($data);
});
})->export('xls');
2)空比较
默认情况下，0显示为空单元格。设置第4个参数为true，来改变默认行为
全局修改：export.sheets.strictNullComparison
单次修改：$sheet->fromArray($data, null, 'A1', true); // 0显示0，而非空
3)Eloquent模型
使用 fromModel($model)
4)自动生成标题
默认情况下，导出将使用数组的键(或模型属性名)作为第一行(标题列)
全局修改：excel.php 的export.generate_heading_by_indices
单次修改：$sheet->fromArray($data, null, 'A1', false, false); // 设置第5个参数
7>行操作
1)操作单个行
1.改变单元格值
$sheet->row(1, ['11', '22']); // 操作第一行
$sheet->row(2, ['33', '44']); // 操作第二行
2.操作行单元格样式
$sheet->row(1, function($row){
$row->setBackground('#000'); // 设置单元格北京
});
2)追加行
$sheet->appendRow(2, [55, 66]); // 第二行后，追加新行
$sheet->appendRow([55, 66]); // 追加新行到最后一行
3)前追加行
$sheet->prependRow(2, [55, 66]); // 第二行前，追加新行
$sheet->prependRow([55, 66]); // 追加新行到第一行
4)追加多行
$sheet->rows([
[77, 88],
[99, 1010],
]);
8>单元格操作
1)设置单元格的值
$sheet->cell('A1', function($cell){
$cell->setValue('1111');
});
$sheet->cell('A1:A5', function($cells){
// 设置该范围内单元格
});
2)设置单元格背景
$cells->setBackground('#000');
3)设置单元格字体
$cells->setFontColor('#fff'); // 颜色
$cells->setFontFamily('Calibri'); // 字体
$cells->setFontSize(16); // 大小
$cells->setFontWeight('bold'); // 粗体
$cells->setFont([ // 一次性设置
'family' => 'Calibri',
'size' => 16,
'bold' => true,
]);
4)设置边框，上、右、下、左
$cells->setBorder('solid', 'none', 'none', 'solid');
$cells->setBorder([
'top' => [
'style' => 'solid',
],
]);
5)设置水平居中
$cells->setAligment('center');
6)设置垂直居中
$cells->setValigment('center');
9>工作表样式
1)一般样式
$sheet->setStyle([
'font' => [
'name' => 'Calibri',
'size' => 15,
'bold' => true,
];
]);
2)字体
1.批量设置
$sheet->setFont([
'name' => 'Calibri',
'size' => 15,
'bold' => true,
]);
2.分开设置
$sheet->setFontFamily('Calibri');
$sheet->setFontSize(15);
$sheet->setFontBold(true);
3)边框
1.设置所有边框
$sheet->setAllBorders('thin');
2.设置某个单元格的边框
$sheet->setBorder('A1', 'thin');
3.设置某个范围内单元格的边框
$sheet->setBorder('A1:F10', 'thin');
注意:
参考文档，查看可用的边框样式
10>冻结行、列、单元格
$sheet->freezeFirstRow(); // 冻结第一行
$sheet->freezeFirstColumn(); // 冻结第一列
$sheet->freezeFirstRowAndColumn(); // 冻结第一行和第一列
$sheet->setFreeze('A2'); // 冻结A2单元格
11>自动过滤器
开启自动过滤器，使用 setAutoFilter($range = false)
$sheet->setAutoFilter(); // 作用整张工作表
$sheet->setAutoFilter('A1:E10'); // 作用某个范围的单元格
12>单元格尺寸
1)设置列宽
$sheet->setWidth('A', 5); // 设置单个列
$sheet->setWidth([ // 设置多个列
'A' => 5,
'B' => 10,
]);
2)设置行高
$sheet->setHeight(1, 50); // 设置单个行
$sheet->setHeight([ // 设置多个行
1 => 50,
2 => 25,
]);
3)设置单元格尺寸
$sheet->stSize('A1', 500, 50); // 设置单个单元格
$sheet->setHeight([ // 设置多个单元格
'A1 => [
'width' => 50,
'height' => 500,
],
'B2' => [
'width' => 20,
'height' => 200,
],
]);
13>自动调整大小
默认情况下导出的文件自动调整大小。若要更改此行为，可以更改配置 或 使用设置程序
$sheet->setAutoSize(true); // 启用
$sheet->setAutoSize(false); // 禁用
$sheet->setAutoSize([ // 禁用 'A、C' 列
'A', 'C'
]);
全部配置：excel.php 的 autosize 和 autosize-method
14>合并列
1)合并某个范围的单元格
$sheet->mergeCells('A1:E1');
2)合并行和列
$sheet->setMergeColumn([
'columns' => ['A', 'B', 'C', 'D'],
'rows' => [
[2, 3],
[4, 5],
],
]);
15>列格式化
可以使用 'setColumnFormat($array)'，告诉Excel应该如何解释某些列
$sheet->setColumnFormat([ // 百分比展示
'C' => '0%'
]);
$sheet->setColumnFormat([ // 前导0展示
'A2:K2' => '0000'
]);
$sheet->setColumnFormat([ // 其他格式展示
'B' => '0',
'D' => '0.00',
'F' => '@',
'F' => 'yyyy-mm-dd',
]);
注意:
参考文档，查看可用的格式
16>调用 PHPExcel 的原生方法
可以在 $excel 和 $sheet 对象上，调用 'PHPExcel' 的原生方法
1)调用 'excel文件' 方法
$excel->getDefaultStyle();
2)调用 '工作表' 方法
$sheet->protectCells('A1', $password);
可以到 PHPOffice 获取等多原生方法
https://github.com/PHPOffice/PHPExcel
4.利用laravel的 blade 模板引擎，来进行Excel导出，每个工作表加载一个视图，在视图中创建一个HTML表格，设置基本的样式。意思就是：我们写一个表格的模板，然后将这个模板直接载入到Excel进行处理
1>一个工作表，加载一个视图
Excel::create('文件名', function($excel) {
$excel->sheet('工作表名', function($sheet) {
$sheet->loadView('folder.view'); // 载入视图
});
});
2>不同的工作表，使用不同视图
Excel::create('文件名', function($excel) {
$excel->sheet('工作表1', function($sheet) {
$sheet->loadView('view1'); // 载入视图
});
$excel->sheet('工作表2', function($sheet) {
$sheet->loadView('view2'); // 载入视图
});
});
3>所有工作表，共享一个视图
Excel::shareView('view')->create();
4>当我们使用共享视图时，在当前工作表中，不想使用视图，使用 'unsetView()' 来取消
$sheet->unsetView();
5>给视图传参
1)作为第二个参数传递
$view_data = [
'name' => 'dongxuemin',
'age' => 30,
];
$sheet->loadView('view', $view_data);
2)使用 with() 方法
$sheet->loadView('view')->with('name', 'dongxuemin')
->with('age', 30);
3)使用 '动态with()' 方法
$sheet->loadView('view')->withName('dongxuemin')
->withAge(30);
强调！！！
这其实就是laravel模板传参的3种方法！
6>设置工作表样式
1)参照excel导出的设置样式的方法
2)使用PHPExcel设置样式的方法
$sheet->getStyle('A1')->applyFromArray([
'fill' => [
'type' => PHPExcel_Style_Fill::FILL_SOLID,
'color' => ['rgb' => 'FF0000'],
],
]);
3)使用HTML标签
laravel-excel 扩展，定义了很多html标签的解析，以及标签的默认样式，我们可以在配置文件中修改
excel.php 的 views.styles 配置项
4)使用HTML属性，支持一些基本属性
Big title
Bold cell
Bold cell
Italic cell
Cell with width of 100
Cell with height of 100
5)使用内联样式
Cell
6)使用外部样式表
excel.css:
.cell {
color: #fff;
}
tr td {
color: #f00;
}
view:
{{ HTML::style('excel.css') }} // 引入外部css文件
Cell
注意：
建议包含 ，解决编码问题
5.参考指南
可用的文件属性
可用的工作表属性
可用的CSS样式
可用的边框样式
可用的列格式
闭包
http://www.maatwebsite.nl/laravel-excel/docs/reference-guide