README

filament-excel

通过批量操作或页面操作轻松配置Filament中的Excel导出。

安装

通过Composer安装。这将下载包并安装Laravel Excel。

composer require pxlrbt/filament-excel

Laravel > 9

如果因为simple-cache依赖项而导致Composer require在Laravel 9或更高版本上失败，您需要在composer.json中将psr/simple-cache版本指定为^2.0以满足PhpSpreadsheet依赖项。您可以同时安装这两个包：

composer require psr/simple-cache:^2.0 pxlrbt/filament-excel

快速入门

从v0.2版本开始，Filament Excel应与filament/filament和filament/tables包一起工作。最简单的用法是将ExportBulkAction添加到您的批量操作中。

管理员包示例

<?php

namespace App\Filament\Resources;

use pxlrbt\FilamentExcel\Actions\Tables\ExportBulkAction;

class UserResource extends Resource
{  
    public static function table(Table $table): Table
    {
        return $table
            ->columns([
                //   
            ])
            ->bulkActions([
                ExportBulkAction::make()
            ]);
    }
}

分离的表包示例

<?php

namespace App\Filament\Resources;

use pxlrbt\FilamentExcel\Actions\Tables\ExportBulkAction;

public function getTableBulkActions()
{
    return  [
        ExportBulkAction::make()
    ];
}

用法

Filament Excel提供了三个您可以使用的操作

• Actions\Tables\ExportBulkAction 用于表格批量操作
• Actions\Tables\ExportAction 用于表格标题操作
• Actions\Pages\ExportAction 用于记录页面

在不进行进一步配置的情况下，它们将尝试从表格或表单定义中解析字段并输出Excel文件。

多个导出类

您可以覆盖默认的导出类，也可以配置具有不同设置的多个导出。用户将看到一个模态对话框，以便选择他想要使用的导出类。

use pxlrbt\FilamentExcel\Actions\Tables\ExportAction;
use pxlrbt\FilamentExcel\Exports\ExcelExport;

ExportAction::make()->exports([
    ExcelExport::make('table')->fromTable(),
    ExcelExport::make('form')->fromForm(),
])

闭包自定义

许多用于自定义导出类的函数接受一个闭包，该闭包传递动态数据

use pxlrbt\FilamentExcel\Actions\Tables\ExportAction;
use pxlrbt\FilamentExcel\Exports\ExcelExport;

ExportAction::make()->exports([
    ExcelExport::make('table')->withFilename(fn ($resource) => $resource::getLabel()),
])

以下参数可用

• $livewire: Livewire组件（对于排队导出不可用）
• $livewireClass: Livewire组件类
• $resource: 资源类
• $model: 模型类
• $recordIds: 选择记录的ID（批量操作）
• $query: 构建器实例

文件名

文件名通过 ->withFilename() 设置

use pxlrbt\FilamentExcel\Actions\Tables\ExportAction;
use pxlrbt\FilamentExcel\Exports\ExcelExport;

ExportAction::make()->exports([
    // Pass a string
    ExcelExport::make()->withFilename(date('Y-m-d') . ' - export'),
    
    // Or pass a Closure
    ExcelExport::make()->withFilename(fn ($resource) => $resource::getLabel())
])

导出类型

您可以通过 ->withWriterType() 设置文件类型

use pxlrbt\FilamentExcel\Actions\Tables\ExportAction;
use pxlrbt\FilamentExcel\Exports\ExcelExport;

ExportAction::make()->exports([
    ExcelExport::make()->withWriterType(\Maatwebsite\Excel\Excel::XLSX),
])

定义列

当使用 ->fromForm()/->fromTable()/->fromModel() 时，列是从您的表格或表单定义中解析出来的。您也可以手动提供列，追加列或覆盖生成的列。

use pxlrbt\FilamentExcel\Actions\Tables\ExportAction;
use pxlrbt\FilamentExcel\Exports\ExcelExport;
use pxlrbt\FilamentExcel\Columns\Column;

ExportAction::make()->exports([
    ExcelExport::make()->withColumns([
        Column::make('name'),
        Column::make('created_at'),
        Column::make('deleted_at'),
    ]),
])

您还可以仅包含列的子集（->only()）或排除某些列（->except()）

use pxlrbt\FilamentExcel\Actions\Tables\ExportAction;
use pxlrbt\FilamentExcel\Exports\ExcelExport;

ExportAction::make()->exports([
    ExcelExport::make()->fromTable()->except([
        'created_at', 'updated_at', 'deleted_at',
    ]),
    
    ExcelExport::make()->fromTable()->only([
        'id', 'name', 'title',
    ]),
])

当您既不传递 ->only() 也不传递 ->except() 时，导出也将尊重模型的 $hidden 属性，例如用户模型上的 password。您可以通过传递一个空数组 ->except([]) 来禁用此功能。

标题

当使用 ->fromForm()/->fromTable()/->fromModel() 时，标题是从您的表格或表单定义中解析出来的。您也可以覆盖标题

use pxlrbt\FilamentExcel\Actions\Tables\ExportAction;
use pxlrbt\FilamentExcel\Exports\ExcelExport;
use pxlrbt\FilamentExcel\Columns\Column;

ExportAction::make()->exports([
    ExcelExport::make()->withColumns([
        Column::make('name')->heading('User name'),
        Column::make('email')->heading('Email address'),
        Column::make('created_at')->heading('Creation date'),
    ]),
])

如果您想使用列名而不喜欢自动生成的标题，可以使用 ->withNamesAsHeadings()。要完全禁用标题，可以添加 ->withoutHeadings()

格式化

每个列都可以通过提供一个闭包来格式化。除了默认参数外，您还可以访问 $state 和 $record。

use pxlrbt\FilamentExcel\Actions\Tables\ExportAction;
use pxlrbt\FilamentExcel\Exports\ExcelExport;
use pxlrbt\FilamentExcel\Columns\Column;

ExportAction::make()->exports([
    ExcelExport::make()->withColumns([
        Column::make('email')
            ->formatStateUsing(fn ($state) => str_replace('@', '[at]', $state)),
            
        Column::make('name')
            ->formatStateUsing(fn ($record) => $record->locations->pluck('name')->join(','),
    ]),
])

列会自动缩放以适应内容。如果您想使用自定义列宽覆盖它，可以这样做

use pxlrbt\FilamentExcel\Actions\Tables\ExportAction;
use pxlrbt\FilamentExcel\Exports\ExcelExport;
use pxlrbt\FilamentExcel\Columns\Column;

ExportAction::make()->exports([
    ExcelExport::make()->withColumns([
        Column::make('email')->width(10)
    ]),
])

底层包 PhpSpreadsheet 提供了各种 Excel 列格式化选项。检查 NumberFormat 列表以获取完整列表。

use pxlrbt\FilamentExcel\Actions\Tables\ExportAction;
use pxlrbt\FilamentExcel\Exports\ExcelExport;
use pxlrbt\FilamentExcel\Columns\Column;
use PhpOffice\PhpSpreadsheet\Style\NumberFormat;

ExportAction::make()->exports([
    ExcelExport::make()->withColumns([
        Column::make('currency')->format(NumberFormat::FORMAT_CURRENCY_EUR_INTEGER)
    ]),
])

忽略格式

当使用 ->fromForm()/->fromTable() 时，格式将从您的表或表单定义中解析。如果您不想覆盖每个列的 ->formatStateUsing() 方法，您可以使用 ->ignoreFormatting() 忽略格式或特定列的格式。

use pxlrbt\FilamentExcel\Actions\Tables\ExportAction;
use pxlrbt\FilamentExcel\Exports\ExcelExport;
use pxlrbt\FilamentExcel\Columns\Column;

ExportAction::make()->exports([
    // Ignore all formatting
    ExcelExport::make()->fromTable()->ignoreFormatting()
    
    // Ignore specific columns
    ExcelExport::make()->fromTable()->ignoreFormatting([
        'created_at', 'updated_at',
    ]),
    
    // Ignore columns based on Closure
    ExcelExport::make()->fromTable()->ignoreFormatting(
        fn (Column $column) => Str::startsWith($column->getName(), 'customer_')
    ),
])

格式化器

当列的状态不是字符串时，即使您使用 ->ignoreFormatting() 来确保它在 Excel 中的正确格式，也会运行格式化器。

目前有 3 种格式化器：ArrayFormatter、EnumFormatter 和 ObjectFormatter。您可以通过 Laravel 的服务容器替换任何实现，例如，为了使用不同的分隔符来使用 ArrayFormatter。

use pxlrbt\FilamentExcel\Exports\Formatters\ArrayFormatter;

class AppServiceProvider extends ServiceProvider
{
    public function register()
    {
        App::bind(ArrayFormatter::class, function () {
            return new ArrayFormatter(';');
        });
    }

用户输入

您可以使用 ->askForFilename() 和 ->askForWriterType() 让用户选择文件名和写入类型。

use pxlrbt\FilamentExcel\Actions\Tables\ExportAction;
use pxlrbt\FilamentExcel\Exports\ExcelExport;

ExportAction::make()->exports([
    ExcelExport::make()
        ->askForFilename()
        ->askForWriterType()
])

您还可以在闭包中使用用户的输入。

use pxlrbt\FilamentExcel\Actions\Tables\ExportAction;
use pxlrbt\FilamentExcel\Exports\ExcelExport;

ExportAction::make()->exports([
    ExcelExport::make()
        ->askForFilename()
        ->withFilename(fn ($filename) => 'prefix-' . $filename)
])

修改查询

您可以使用 ->modifyQueryUsing() 来修改用于检索模型所使用的查询。

use pxlrbt\FilamentExcel\Actions\Tables\ExportAction;
use pxlrbt\FilamentExcel\Exports\ExcelExport;

ExportAction::make()->exports([
    ExcelExport::make()
        ->fromTable()
        ->modifyQueryUsing(fn ($query) => $query->where('exportable', true))
])

排队导出

具有许多条目的资源导出可能需要一些时间，因此可以使用 ->queue() 排队。它们将在后台作业中处理，并在下次页面加载时（或 Livewire 轮询时）通知用户。

临时文件将在第一次下载后被删除。未下载的文件将在 24 小时后由计划任务删除。

use pxlrbt\FilamentExcel\Actions\Tables\ExportAction;
use pxlrbt\FilamentExcel\Exports\ExcelExport;

ExportAction::make()->exports([
    ExcelExport::make()->queue()
])

可以通过使用 ->withChunkSize() 来调整每个作业导出记录的大小。

se pxlrbt\FilamentExcel\Actions\Tables\ExportAction;
use pxlrbt\FilamentExcel\Exports\ExcelExport;

ExportAction::make()->exports([
    ExcelExport::make()->queue()->withChunkSize(100)
])

自定义导出

如果您需要更多自定义或想要通过分离导出代码来清理资源，您可以扩展 ExcelExport 类并使用 setUp() 进行配置。

use pxlrbt\FilamentExcel\Actions\Tables\ExportAction;
use pxlrbt\FilamentExcel\Exports\ExcelExport;
use pxlrbt\FilamentExcel\Columns\Column;

class CustomExport extends ExcelExport
{
    
    public function setUp()
    {
        $this->withFilename('custom_export');
        $this->withColumns([
            Column::make('name'),
            Column::make('email'),
        ]);
    }
}

贡献

如果您想为此包做出贡献，您可能希望在一个真实的 Filament 项目中对其进行测试。

• 将此存储库分叉到您的 GitHub 账户。
• 在本地创建一个 Filament 应用。
• 将您的分叉克隆到 Filament 应用根目录。
• 在 /filament-excel 目录中，为您的修复创建一个分支，例如 fix/error-message。

在您的应用的 composer.json 中安装包。

"require": {
    "pxlrbt/filament-excel": "dev-fix/error-message as main-dev",
},
"repositories": [
    {
        "type": "path",
        "url": "filament-excel"
    }
]

现在，运行 composer update。

鸣谢

此包基于由 SpartnerNL 开发的优秀的 Laravel Nova Excel Package，并已移植到 Filament。