README

最近我在工作中相当忙碌，我目前正在寻找一名或多名共同维护者来帮助我维护和开发这个包。

当前路线图

PR 审查
Livewire 3 兼容性
Tailwind 3 兼容性

请通过 arthur[dot]lorent[at]gmail.com 联系我以申请。

节省时间，轻松地从 Eloquent 模型渲染视图中的表格。

以下 UI 框架下可以生成表格

Bootstrap 5
Bootstrap 4
TailwindCSS 3（即将推出功能）

觉得这个包有用？请考虑支持我的工作！

兼容性

升级指南

用法

使用以下命令创建您的表格

php artisan make:table UsersTable --model=App/Models/User

在 UsersTable 生成的类中配置您的表格，该类位于 app\Tables 目录中

namespace App\Tables;

use App\Models\User;
use Okipa\LaravelTable\Table;
use Okipa\LaravelTable\Column;
use Okipe\LaravelTable\Formatters\Date;
use Okipa\LaravelTable\Abstracts\AbstractTableConfiguration;

class UsersTable extends AbstractTableConfiguration
{
    protected function table(): Table
    {
        return Table::make()->model(User::class);
    }

    protected function columns(): array
    {
        return [
            Column::make('id')->sortable(),
            Column::make('name')->searchable()->sortable(),
            Column::make('email')->searchable()->sortable(),
            Column::make('created_at')
                ->format(new DateFormatter('d/m/Y H:i', 'Europe/Paris'))
                ->sortable(),
            Column::make('updated_at')
                ->format(new DateFormatter('d/m/Y H:i', 'Europe/Paris'))
                ->sortable()
                ->sortByDefault('desc'),
        ];
    }
}

然后在视图中显示它

<livewire:table :config="App\Tables\UsersTable::class"/>

安装

使用 composer 安装此包

composer require okipa/laravel-table

此包在底层使用 Livewire，其安装是必需的。

如果您的项目上尚未安装 Livewire，您必须遵循安装说明。

配置

可选：发布包配置

php artisan vendor:publish --tag=laravel-table:config

模板

可选：发布包模板

php artisan vendor:publish --tag=laravel-table:views

翻译

此包中使用的所有单词和句子均可翻译。

有关如何翻译它们的说明，请参阅 Laravel 官方文档：https://laravel.net.cn/docs/localization#using-translation-strings-as-keys。

以下是可供翻译的单词和句子列表

状态

正在加载...
未找到结果。
您可以使用拖放操作重新排列此列表中条目的顺序。
重置过滤器
是
否
通过以下方式搜索
重置搜索
每页行数
升序排序
降序排序
操作
批量操作
创建
添加
显示
编辑
删除
激活
停用
验证电子邮件
取消验证电子邮件
切换开
关闭
您确定要执行对第#:primary行的操作:action吗？
您确定要执行对第#:primary行字段:attribute的操作:action吗？
您确定要执行对所选的:count行执行操作:action吗？
第#:primary行不允许执行操作:action，将不受影响。
所选的:count行不允许执行操作:action，将不受影响。
操作:action已在第#:primary行执行。
操作:action已在第#:primary行的字段:attribute上执行。
操作:action已在所选的:count行上执行。
第#:primary行不允许执行操作:action，未受到影响。
所选的:count行不允许执行操作:action，未受到影响。
列表已重新排序。
显示结果 :start 到 :stop，共 :total 条

如何

创建表格配置

通过执行此命令生成表格配置: php artisan make:table UsersTable。

如果您想使用预定义的模型生成配置，只需在末尾添加此选项: --model=App/Models/User。

您可以在 app/Tables 目录中找到所有生成的表格配置。

在视图中显示表格

只需在视图中调用此Livewire组件，并通过 config 参数传入配置类名称。

<livewire:table :config="App\Tables\UsersTable::class"/>

将外部数据传递到您的表格中

如果您有特定的属性要传递给您的表格配置，应通过 configParams 参数传递它们。

这在您需要向表格传递外部信息时很有用。

<livewire:table :config="App\Tables\UsersTable::class" :configParams="['categoryId' => 1]"/>

然后，您应将传递的属性声明为表格配置的 public 属性。

namespace App\Tables;

use App\Models\User;
use Okipa\LaravelTable\Table;
use Okipa\LaravelTable\Abstracts\AbstractTableConfiguration;

class UsersTable extends AbstractTableConfiguration
{
    // You will now be able to use the provided `$this->categoryId` category ID in your table configuration.
    public int $categoryId;

    // ...
}

从 Eloquent 模型生成表格

要从Eloquent模型生成表格，只需在您的表格上调用 model 方法。

namespace App\Tables;

use App\Models\User;
use Okipa\LaravelTable\Table;
use Okipa\LaravelTable\Abstracts\AbstractTableConfiguration;

class UsersTable extends AbstractTableConfiguration
{
    protected function table(): Table
    {
        return Table::make()->model(User::class);
    }
}

覆盖您表格上的原生选择行为

您可能想覆盖您表格上原生HTML选择组件的行为。

您可以通过为 laravel-table.html_select_components_attributes 配置键定义一个HTML属性数组作为值，将数据属性添加到您表格上显示的所有HTML选择组件。

// `data-selector` HTML attribute will be appended to all tables HTML select components.
'html_select_components_attributes' => ['data-selector' => true],

在表格上添加查询指令

要向表格添加特定的查询指令，请使用可用的 query 方法。

您可以通过将闭包参数传递给表格上的 query 方法来设置特定的Eloquent指令。

此闭包将允许您操作 \Illuminate\Database\Eloquent\Builder $query 参数。

namespace App\Tables;

use App\Models\User;
use Okipa\LaravelTable\Table;
use Illuminate\Database\Eloquent\Builder;
use Okipa\LaravelTable\Abstracts\AbstractTableConfiguration;

class UsersTable extends AbstractTableConfiguration
{
    protected function table(): Table
    {
        return Table::make()
            ->model(User::class)
            ->query(fn(Builder $query) => $query->where('category_id', 1));
    }   
}

处理表格每页行数、分页和导航状态

您有两种方式允许或禁止用户选择每页显示的行数。

从全局配置 laravel-table.enable_number_of_rows_per_page_choice 的布尔值激活或停用。
通过在您的表格上执行 enableNumberOfRowsPerPageChoice() 方法覆盖全局激活状态。

namespace App\Tables;

use App\Models\User;
use Okipa\LaravelTable\Table;
use Okipa\LaravelTable\Abstracts\AbstractTableConfiguration;

class UsersTable extends AbstractTableConfiguration
{
    protected function table(): Table
    {
        return Table::make()
            ->model(User::class)
            ->enableNumberOfRowsPerPageChoice(false);
    }
}

按照相同的逻辑，您可以为可用的每页行数选项定义。

从全局设置选项，从 laravel-table.number_of_rows_per_page_default_options 配置数组值设置。
通过在表格上执行 numberOfRowsPerPageOptions() 方法覆盖全局选项。

第一个可用的选项将自动选中并应用于表格初始化。

namespace App\Tables;

use App\Models\User;
use Okipa\LaravelTable\Table;
use Okipa\LaravelTable\Abstracts\AbstractTableConfiguration;

class UsersTable extends AbstractTableConfiguration
{
    protected function table(): Table
    {
        return Table::make()
            ->model(User::class)
            // Table will display 5 rows on initialization and will allow displaying 10, 15, 20 or 25 rows.
            ->numberOfRowsPerPageOptions([5, 10, 15, 20, 25]);
    }
}

将根据要显示的行数和总行数以及导航状态自动处理分页。

两者都将显示在表格页脚中。

设置条件行类

通过将闭包参数传递给 rowClass 方法定义表格上的条件行类。

此闭包将允许您操作 Illuminate\Database\Eloquent $model 参数，并必须返回一个数组，其中数组键包含您希望添加的类或类，而值是一个布尔表达式。

namespace App\Tables;

use App\Models\User;
use Okipa\LaravelTable\Table;
use Okipa\LaravelTable\Abstracts\AbstractTableConfiguration;

class UsersTable extends AbstractTableConfiguration
{
    protected function table(): Table
    {
        return Table::make()
            ->model(User::class)
            ->rowClass(fn(User $user) => [
                'table-danger' => ! $user->active,
            ]);
    }
}

设置表格过滤器

配置表格过滤器将它们显示为表格上方专用栏上的 select HTML组件。

如果没有声明过滤器，过滤器栏将不会显示。

本软件包提供了以下内置过滤器：

值过滤器:
- 在实例化时需要 string $label、string $attribute、array $options 和 bool $multiple = true 参数
- 根据选定的选项（在多选模式禁用时为单个选项）的值是否出现在给定的属性中进行过滤表格
关系过滤器:
- 在实例化时需要 string $label、string $relationship、array $options 和 bool $multiple = true 参数
- 根据选定的选项（在多选模式禁用时为单个选项）的值是否出现在给定的关系中进行过滤表格
空值过滤器
- 在实例化时需要 string $attribute 参数
- 根据给定属性的值是否为 null 或非 null 进行过滤表格
布尔过滤器
- 在实例化时需要 string $label 和 string $attribute 参数
- 根据给定属性的值是否为 true 或 false 进行过滤表格

要使用它们，您需要将包含要声明的过滤器实例的数组传递给 filters 方法。

namespace App\Tables;

use App\Models\User;
use Okipa\LaravelTable\Table;
use Okipa\LaravelTable\Filters\NullFilter;
use Okipa\LaravelTable\Filters\ValueFilter;
use Okipa\LaravelTable\Filters\BooleanFilter;
use Okipa\LaravelTable\Filters\RelationshipFilter;
use Okipa\LaravelTable\Abstracts\AbstractTableConfiguration;

class UsersTable extends AbstractTableConfiguration
{
    protected function table(): Table
    {
        return Table::make()
            ->model(User::class)
            ->filters([
                new ValueFilter('Email', 'email', User::pluck('email', 'email')->toArray()),
                new RelationshipFilter('Categories', 'categories', UserCategory::pluck('name', 'id')->toArray()),
                new NullFilter('Email Verified', 'email_verified_at'),
                new BooleanFilter('Active', 'active'),
            ]);
    }
}

您可能需要创建自己的过滤器。为此，请执行以下命令：php artisan make:table:filter MyNewFilter。

您将在 app/Tables/Filters 目录中找到生成的表格过滤器。

现在您可以在表格中使用您的新过滤器。

namespace App\Tables;

use App\Models\User;
use Okipa\LaravelTable\Table;
use App\Tables\Filters\MyNewFilter;
use Okipa\LaravelTable\Abstracts\AbstractTableConfiguration;

class UsersTable extends AbstractTableConfiguration
{
    protected function table(): Table
    {
        return Table::make()
            ->model(User::class)
            ->filters([
                new MyNewFilter(),
            ]);
    }
}

定义表格头部操作

配置一个表格操作，该操作将作为按钮显示在表格头部右侧。

如果没有声明头部操作，表格头部中为其预留的专用槽位将保持为空。

本软件包提供了以下内置头部操作：

重定向头部操作:
- 在实例化时需要 string $url、string $label、string $icon、array $class = ['btn', 'btn-success'] 和 bool $openInNewWindow = false 参数
- 从按钮点击重定向到给定的 URL
创建头部操作:
- 在实例化时需要 string $createUrl 和 bool $openInNewWindow = false 参数
- 使用 $createUrl 作为 URL、__('Create') 作为标签、config('laravel-table.icon.create') 作为图标的预配置 RedirectHeadAction

要使用其中一个，您需要将其实例传递给 headAction 方法。

您可以将以下方法链接到您的头部操作中

when(bool $condition): Okipa\LaravelTable\Abstracts\AbstractHeadAction
- 确定头部操作是否应启用

namespace App\Tables;

use App\Models\User;
use Okipa\LaravelTable\Table;
use Okipa\LaravelTable\HeadActions\AddHeadAction;
use Okipa\LaravelTable\Abstracts\AbstractTableConfiguration;

class UsersTable extends AbstractTableConfiguration
{
    protected function table(): Table
    {
        return Table::make()
            ->model(User::class)
            // Create head action will not be available when authenticated user is not allowed to create users
            ->headAction((new AddHeadAction(route('user.create')))->when(Auth::user()->cannot('create_users')));
    }
}

您可能需要创建自己的头部操作。为此，请执行以下命令：php artisan make:table:head:action MyNewHeadAction。

您将在 app/Tables/HeadActions 目录中找到生成的表格头部操作。

现在您可以在表格中使用您的新头部操作。

namespace App\Tables;

use App\Models\User;
use Okipa\LaravelTable\Table;
use App\Tables\HeadActions\MyNewHeadAction;
use Okipa\LaravelTable\Abstracts\AbstractTableConfiguration;

class UsersTable extends AbstractTableConfiguration
{
    protected function table(): Table
    {
        return Table::make()
            ->model(User::class)
            ->headAction(new MyNewHeadAction());
    }
}

定义表格批量操作

配置表格批量操作，这些操作将在表格头部左侧的下拉菜单中可用。

如果您在表格上没有声明批量操作，则不会显示预留的专用列。

重要提示： 您需要设置几行 JavaScript 以确保批量操作的确认请求和反馈能正常工作。

本软件包提供了以下内置的批量操作：

验证电子邮件批量操作:
- 在实例化时需要 string $attribute 参数
- 更新所有选定行的给定属性为当前日期时间
取消验证电子邮件批量操作:
- 在实例化时需要 string $attribute 参数
- 将所有选定行的给定属性更新为 null
激活批量操作:
- 在实例化时需要 string $attribute 参数
- 将所有选定行的给定属性更新为 true
停用批量操作:
- 在实例化时需要 string $attribute 参数
- 将所有选定行的给定属性更新为 false
销毁批量操作:
- 销毁所有选定行

要使用它们，您需要将闭包参数传递给 bulkActions 方法。此闭包将允许您操作 Illuminate\Database\Eloquent $model 参数，并必须返回包含批量操作实例的数组。

您可以将以下方法链接到批量操作

when(bool $condition): Okipa\LaravelTable\Abstracts\AbstractBulkAction
- 确定是否在表格行上启用批量操作
confirmationQuestion(string|false $confirmationQuestion): Okipa\LaravelTable\Abstracts\AbstractBulkAction
- 覆盖默认操作确认消息
feedbackMessage(string|false $feedbackMessage): Okipa\LaravelTable\Abstracts\AbstractBulkAction:
- 覆盖默认操作反馈消息

namespace App\Tables;

use App\Models\User;
use Okipa\LaravelTable\Table;
use Okipa\LaravelTable\BulkActions\DestroyBulkAction;
use Okipa\LaravelTable\BulkActions\ActivateBulkAction;
use Okipa\LaravelTable\BulkActions\DeactivateBulkAction;
use Okipa\LaravelTable\BulkActions\VerifyEmailBulkAction;
use Okipa\LaravelTable\BulkActions\CancelEmailVerificationBulkAction;
use Okipa\LaravelTable\Abstracts\AbstractTableConfiguration;

class UsersTable extends AbstractTableConfiguration
{
    protected function table(): Table
    {
        return Table::make()
            ->model(User::class)
            ->bulkActions(fn(User $user) => [
                new VerifyEmailBulkAction('email_verified_at'),
                new CancelEmailVerificationBulkAction('email_verified_at'),
                new ActivateBulkAction('active'),
                new DeactivateBulkAction('active'),
                (new DestroyBulkAction())
                    // Destroy action will not be available for authenticated user
                    ->when(Auth::user()->isNot($user))
                    // Override the action default confirmation question
                    // Or set `false` if you do not want to require any confirmation for this action
                    ->confirmationQuestion('Are you sure you want to delete selected users ?')
                    // Override the action default feedback message
                    // Or set `false` if you do not want to trigger any feedback message for this action
                    ->feedbackMessage('Selected users have been deleted.'),
            ]);
    }
}

您可能需要创建自己的批量操作。为此，请执行以下命令：php artisan make:table:bulk:action MyNewBulkAction。

您将在 app/Tables/BulkActions 目录中找到生成的表格批量操作。

现在您可以在您的表格中使用新的批量操作了。

namespace App\Tables;

use App\Models\User;
use Okipa\LaravelTable\Table;
use App\Tables\BulkActions\MyNewBulkAction;
use Okipa\LaravelTable\Abstracts\AbstractTableConfiguration;

class UsersTable extends AbstractTableConfiguration
{
    protected function table(): Table
    {
        return Table::make()
            ->model(User::class)
            ->bulkActions(fn(User $user) => [
                new MyNewBulkAction(),
            ]);
    }
}

定义表格行操作

配置表格上的行操作，这些操作将在每行的末尾显示。

如果您的表格上没有声明行操作，则表格右侧的专用 Actions 列将不会显示。

重要提示： 您必须设置几行 JavaScript 以允许行操作确认请求和反馈正常工作。

此包提供了以下内置行操作

RedirectRowAction:
- 在实例化时需要 string $url、string $title、string $icon、array $class = ['link-info']、string|null $defaultConfirmationQuestion = null、string|null $defaultFeedbackMessage = null 和 bool $openInNewWindow = false 参数
- 从链接点击中重定向到给定的 URL
ShowRowAction:
- 在实例化时需要 string $showUrl 和 bool $openInNewWindow = false 参数
- 使用 $showUrl 作为 URL、__('Show') 作为标签和 config('laravel-table.icon.show') 作为图标实例化预配置的 RedirectRowAction
EditRowAction:
- 在实例化时需要 string $editUrl 参数
- 点击时重定向到模型编辑页面
DestroyRowAction:
- 在被要求确认后销毁行

要使用它们，您必须将闭包参数传递给 rowActions 方法。此闭包将允许您操作 Illuminate\Database\Eloquent $model 参数并必须返回一个包含行操作实例的数组。

您可以使用与批量操作相同的链式方法 => 见批量操作配置。

namespace App\Tables;

use App\Models\User;
use Okipa\LaravelTable\Table;
use Okipa\LaravelTable\RowActions\EditRowAction;
use Okipa\LaravelTable\RowActions\ShowRowAction;
use Okipa\LaravelTable\RowActions\DestroyRowAction;
use Okipa\LaravelTable\Abstracts\AbstractTableConfiguration;

class UsersTable extends AbstractTableConfiguration
{
    protected function table(): Table
    {
        return Table::make()
            ->model(User::class)
            ->rowActions(fn(User $user) => [
                new ShowRowAction(route('user.show', $user)),
                new EditRowAction(route('user.edit', $user)),
                (new DestroyRowAction())
                    // Destroy action will not be available for authenticated user
                    ->when(Auth::user()->isNot($user))
                    // Override the action default confirmation question
                    // Or set `false` if you do not want to require any confirmation for this action
                    ->confirmationQuestion('Are you sure you want to delete user ' . $user->name . '?')
                    // Override the action default feedback message
                    // Or set `false` if you do not want to trigger any feedback message for this action
                    ->feedbackMessage('User ' . $user->name . ' has been deleted.'),
            ]);
    }
}

您可能需要创建自己的行操作。为此，请执行以下命令：php artisan make:table:row:action MyNewRowAction。

您将在 app/Tables/RowActions 目录中找到生成的表格行操作。

现在您可以在您的表格中使用新的行操作了。

namespace App\Tables;

use App\Models\User;
use Okipa\LaravelTable\Table;
use App\Tables\RowActions\MyNewRowAction;
use Okipa\LaravelTable\Abstracts\AbstractTableConfiguration;

class UsersTable extends AbstractTableConfiguration
{
    protected function table(): Table
    {
        return Table::make()
            ->model(User::class)
            ->rowActions(fn(User $user) => [
                new MyNewRowAction(),
            ]);
    }
}

您可能需要行操作在执行之前进行确认并触发反馈消息。

您必须像为批量操作那样配置它们。

在表格上声明列

使用您的生成表格配置中可用的 columns 方法声明表格上的列，并返回一个包含列实例的数组。

要声明列，只需使用静态 make 方法，该方法将等待一个 string $attribute 参数。此属性将用于获取默认单元格值。

默认情况下，列标题将定义为 __('validation.attributes.<attribute>')，以便重用属性翻译。

如果需要，您可以使用 title 方法，该方法将等待一个 string $title 参数来设置特定的列标题，该标题将覆盖默认标题。

namespace App\Tables;

use App\Models\User;
use Okipa\LaravelTable\Table;
use Okipa\LaravelTable\Column;
use Okipa\LaravelTable\Abstracts\AbstractTableConfiguration;

class UsersTable extends AbstractTableConfiguration
{
    protected function table(): Table
    {
        return Table::make()->model(User::class);
    }
    
    protected function columns(): array
    {
        return [
            // Column attribute set to `id`, column value set from `$user->id` and colum title set to `__('validation.attributes.id')`
            Column::make('id'),
            // Column attribute set to `name`, value set from `$user->name` and column title set to `Username`
            Column::make('name')->title('Username'),
        ];
    }
}

格式化列值

有时您需要为您的列应用特定的格式。有几种方法可以实现这一点。

对于特定情况，您应将闭包参数传递给列上的 format 方法。

此闭包将允许您操作 Illuminate\Database\Eloquent $model 参数。

namespace App\Tables;

use App\Models\User;
use Okipa\LaravelTable\Table;
use Okipa\LaravelTable\Column;
use Okipa\LaravelTable\Abstracts\AbstractTableConfiguration;

class UsersTable extends AbstractTableConfiguration
{
    protected function table(): Table
    {
        return Table::make()->model(User::class);
    }
    
    protected function columns(): array
    {
        return [
            // Value set from `$user->id`
            Column::make('id'),
            // Value set from closure
            Column::make('username')
                ->format(fn(User $user) => '<b> ' . $user->companies->implode('name', ', ') . '</b>'),
        ];
    }
}

如果您想反复应用相同的格式化处理，您应该使用以下命令创建一个格式化器： php artisan make:table:formatter NewFormatter。

生成的格式化器可以在 app\Table\Formatters 目录中找到。

您可以在表格中重用此格式化器。

namespace App\Tables;

use App\Models\User;
use Okipa\LaravelTable\Table;
use Okipa\LaravelTable\Column;
use App\Tables\Formatters\NewFormatter;
use Okipa\LaravelTable\Abstracts\AbstractTableConfiguration;

class UsersTable extends AbstractTableConfiguration
{
    protected function table(): Table
    {
        return Table::make()->model(User::class);
    }
    
    protected function columns(): array
    {
        return [
            Column::make('id'),
            Column::make('name')->format(new NewFormatter()),
        ];
    }
}

此包提供以下内置格式化器

BooleanFormatter:
- 根据布尔值显示 config('laravel-table.icon.active') 激活图标或 config('laravel-table.icon.inactive') 未激活图标
DateFormatter:
- 实例化时需要 string $format 和 string $timezone 参数
- 从日期或日期时间值显示格式化的字符串
StrLimitFormatter:
- 实例化时允许可选的 int $limit 和 string $end 参数
- 显示带标题的截断字符串，允许在悬停时查看完整字符串

定义列操作

在您的表格中配置列操作，这些操作将在各自的单元格中显示。

列操作与行操作有很多共同之处。

重要提示： 您将需要设置几行javascript 以确保列操作确认请求和反馈能正常工作。

此包提供以下内置操作

ToggleBooleanColumnAction:
- 切换电子邮件验证状态
ToggleBooleanColumnAction:
- 切换布尔值

要使用它们，您必须向 action 方法传递一个闭包参数。此闭包将允许您操作 Illuminate\Database\Eloquent $model 参数并必须返回一个 AbstractColumnAction 实例。

您可以使用与批量操作相同的链式方法 => 见批量操作配置。

namespace App\Tables;

use App\Models\User;
use Okipa\LaravelTable\Table;
use Okipa\LaravelTable\ColumnActions\ToggleBooleanColumnAction;
use Okipa\LaravelTable\Abstracts\AbstractTableConfiguration;
use Okipa\LaravelTable\ColumnActions\ToggleBooleanColumnAction;

class UsersTable extends AbstractTableConfiguration
{
    protected function table(): Table
    {
        return Table::make()->model(User::class);
    }
    
    protected function columns(): array
    {
        return [
            Column::make('id'),
            Column::make('email_verified_at')
                // ToggleBooleanColumnAction action will not trigger any feedback message
                ->action(fn(User $user) => (new ToggleBooleanColumnAction()->feedbackMessage(false))
            Column::make('active')
                // ToggleBooleanColumnAction action will not be available for authenticated user
                ->action(fn(User $user) => (new ToggleBooleanColumnAction())->when(Auth::user()->isNot($user))),
        ];
    }
}

您可能需要创建自己的列操作。为此，执行以下命令： php artisan make:table:column:action MyNewColumnAction。

您生成的表格列操作可以在 app/Tables/ColumnActions 目录中找到。

现在您可以在表格中使用您的新列操作。

namespace App\Tables;

use App\Models\User;
use Okipa\LaravelTable\Table;
use App\Tables\ColumnActions\MyNewColumnAction;
use Okipa\LaravelTable\Abstracts\AbstractTableConfiguration;

class UsersTable extends AbstractTableConfiguration
{
    protected function table(): Table
    {
        return Table::make()->model(User::class);
    }

    protected function columns(): array
    {
        return [
            Column::make('id'),
            Column::make('action')->action(fn() => new MyNewColumnAction()),
        ];
    }
}

您可能需要在执行之前确认您的列操作并触发反馈消息。

您必须像为批量操作那样配置它们。

配置列搜索

通过调用 searching 方法允许在列上搜索。

当设置了可搜索字段时，搜索输入将在表格标题中显示。

可搜索的列标题将用于指示可以在搜索输入占位符中搜索哪个字段。

默认情况下，搜索将应用于定义的列键。

class UsersTable extends AbstractTableConfiguration
{
    protected function table(): Table
    {
        return Table::make()->model(User::class);
    }
    
    protected function columns(): array
    {
        return [
            // Column will not be searchable
            Column::make('id'),
            // Table will be searchable from `$user->name`
            Column::make('name')->searchable(),
        ];
    }
}

您可以通过将闭包传递给 searchable 方法来设置自定义的搜索行为。

此闭包将在触发表格搜索时执行，并允许您操作 Illuminate\Database\Eloquent\Builder $query 参数。

class UsersTable extends AbstractTableConfiguration
{
    protected function table(): Table
    {
        return Table::make()->model(User::class);
    }
    
    protected function columns(): array
    {
        return [
            // Column will not be searchable
            Column::make('id'),
            // Column will be searchable using this closure
            Column::make('owned_companies')
                // ... Your custom formatting here
                ->searchable(fn(Builder $query, string $searchBy) => $query->whereRelation(
                    'companies',
                    'name',
                    'LIKE',
                    '%' . $searchBy . '%'
                ),
        ];
    }
}

配置列排序

通过调用 sortable 方法允许在列上排序。

可排序的列将在其标题之前显示可点击的排序图标，以触发升序或降序排序。

默认情况下，排序将应用于定义的列键。

class UsersTable extends AbstractTableConfiguration
{
    protected function table(): Table
    {
        return Table::make()->model(User::class);
    }
    
    protected function columns(): array
    {
        return [
            // Column will not be sortable
            Column::make('id'),
            // Column will be sortable from `$user->name`
            Column::make('name')->sortable(),
        ];
    }
}

要默认排序列，请使用 sortByDefault 列方法，这将允许您传递一个 string $direction 参数。

您可以对不可排序的列进行默认排序。

class UsersTable extends AbstractTableConfiguration
{
    protected function table(): Table
    {
        return Table::make()->model(User::class);
    }
    
    protected function columns(): array
    {
        return [
            // Column will not be sortable
            Column::make('id'),
            // Column will be sorted descending by default on `$user->name`
            Column::make('name')->sortByDefault('desc'),
        ];
    }
}

您可以通过将闭包传递给 sortable 方法来设置自定义的排序行为。

此闭包将在触发列排序时执行，并允许您操作 Illuminate\Database\Eloquent\Builder $query 和 string $sortDir 参数（《asc》或《desc》）。

class UsersTable extends AbstractTableConfiguration
{
    protected function table(): Table
    {
        return Table::make()->model(User::class);
    }
    
    protected function columns(): array
    {
        return [
            // Column will not be sortable
            Column::make('id'),
            // Column will be sortable from this closure
            Column::make('companies_count') 
                // Custom formatting...
                ->sortable(fn(Builder $query, string $sortDir) => $query
                    ->withCount('companies')
                    ->orderBy('companies_count', $sortDir)),
        ];
    }
}

允许通过拖放操作重新排序列

通过在您的表格上调用 reorderable 方法允许列通过拖放操作进行重新排序。

此方法将等待一个第一个 string $attribute 参数，一个可选的第二个 string $title 参数，以及一个可选的第三个 string $sortDirByDefault 参数（接受 asc 或 desc 值）。

重要提示

您需要设置几行JavaScript代码，以便使重新排序动作反馈能够正常工作。
您需要安装Livewire Sortable 插件，该插件将为我们处理拖放功能。

激活此功能将：

在表中添加一个新列，显示在laravel-table.icon.drag_drop配置值中定义的拖放图标，后面跟着定义的模型顺序属性值。
按照定义的模型顺序属性（默认为asc）对行进行排序。
禁用其他列的排序，因为它与拖放重新排序不兼容。
当然，通过添加所有必要的Livewire Sortable Plugin标记，启用拖放列重新排序。

namespace App\Tables;

use App\Models\User;
use Okipa\LaravelTable\Table;
use Okipa\LaravelTable\Abstracts\AbstractTableConfiguration;

class UsersTable extends AbstractTableConfiguration
{
    protected function table(): Table
    {
        return Table::make()
            ->model(User::class)
            // A new column will display the drag-and-drop icon, followed by the `position` attribute value
            // Rows will be sorted from the `position` model attribute and all other columns sorting will be disable
            ->reorderable('position');
    }
}

提示：如果您正在使用类似spatie/eloquent-sortable的包来处理Eloquent模型的排序行为，并使用分组查询，您还必须在表格查询说明中设置此分组查询。

在表格上声明结果

要显示结果，您必须从您生成的表格配置中的results方法返回结果实例数组。

如果没有声明结果，其专用空间将保持为空。

结果应按以下方式声明：

使用静态make方法创建一个Result实例。
链式调用title方法，该方法将等待一个string $title参数。
链式调用format方法，该方法将等待一个闭包，让您可以操作Illuminate\Database\Query\Builder $totalRowsQuery和Illuminate\Support\Collection $displayedRowsCollection参数。

namespace App\Tables;

use App\Models\User;
use Okipa\LaravelTable\Table;
use Okipa\LaravelTable\Column;
use Okipa\LaravelTable\Result;
use Illuminate\Support\Collection;
use Illuminate\Database\Query\Builder;
use Okipa\LaravelTable\Abstracts\AbstractTableConfiguration;

class UsersTable extends AbstractTableConfiguration
{
    protected function table(): Table
    {
        return Table::make()->model(User::class);
    }
    
    protected function columns(): array
    {
        return [
            Column::make('id'),
        ];
    }
    
    protected function results(): array
    {
        return [
            // This result uses the first $totalRowsQuery closure param to compute its value.
            // In this example, all users contained in database with unverified email will be count.
            Result::make()
                ->title('Total of users with unverified email')
                ->format(static fn(Builder $totalRowsQuery) => $totalRowsQuery
                    ->whereNull('email_verified_at')
                    ->count()),
            // This result uses the second $displayedRowsCollection closure param to compute its value.
            // In this example, all displayed inactive users will be count.
            Result::make()
                ->title('Displayed inactive users')
                ->format(static fn(
                    Builder $totalRowsQuery,
                    Collection $displayedRowsCollection
                ) => $displayedRowsCollection->where('active', false)->count()),
        ];
    }
}

设置几行 JavaScript

一旦安装此包，您必须向项目中添加一些JavaScript代码，以便允许确认请求和动作反馈能够正常工作。

当动作请求用户确认时，它将不会直接执行。而是会发出一个带有以下参数的table:action:confirm Livewire事件：

动作类型
动作标识符
与您的动作相关的模型主键
您的动作中的$confirmationQuestion属性

如您在下面的代码片段中看到的，此事件的第4个参数是唯一一个您需要使用的参数，以请求用户确认。前3个参数仅存在于将它们发送回新事件，当动作被用户确认时。在您的处理中忽略它们。

您必须从自己的JS脚本中拦截此事件并提示确认请求。

当动作被用户确认时，您必须发出一个新的laraveltable:action:confirmed Livewire事件，该事件将触发动作执行。您必须传递table:action:confirm事件中提供的3个第一个参数。

动作类型
动作标识符
与您的动作相关的模型主键

以下是一个JS代码片段，说明如何进行操作：

// Listen to the action confirmation request
Livewire.on('laraveltable:action:confirm', (actionType, actionIdentifier, modelPrimary, confirmationQuestion) => {
    // You can replace this native JS confirm dialog by your favorite modal/alert/toast library implementation. Or keep it this way!
    if (window.confirm(confirmationQuestion)) {
        // As explained above, just send back the 3 first argument from the `table:action:confirm` event when the action is confirmed
        Livewire.emit('laraveltable:action:confirmed', actionType, actionIdentifier, modelPrimary);
    }
});

一旦动作执行，就会触发一个table:action:feedback Livewire事件（它有时取决于反馈消息的配置）。

按照相同的逻辑，您必须从下面的代码片段中的JS脚本中拦截它，以便向用户提供即时反馈。

Livewire.on('laraveltable:action:feedback', (feedbackMessage) => {
    // Replace this native JS alert by your favorite modal/alert/toast library implementation. Or keep it this way!
    window.alert(feedbackMessage);
});

最后，为了允许头部RedirectHeadAction和CreateHeadAction在新标签页中打开链接，您还必须添加以下JS代码片段：

Livewire.on('laraveltable:link:open:newtab', (url) => {
    window.open(url, '_blank').focus();
});

在表格加载时触发 Livewire 事件

您可能希望在表格加载时触发某些事件，例如加载UI第三方JS库。

您可以使用emitEventsOnLoad方法来实现，该方法将等待一个事件数组。

namespace App\Tables;

use App\Models\User;
use Okipa\LaravelTable\Table;
use Illuminate\Database\Eloquent\Builder;
use Okipa\LaravelTable\Abstracts\AbstractTableConfiguration;

class UsersTable extends AbstractTableConfiguration
{
    protected function table(): Table
    {
        return Table::make()
            ->model(User::class)
            // This event will be loaded each time your table will be rendered
            // in order to keep your UI third party libraries rendering,
            // even when its HTML is refreshed.
            ->emitEventsOnLoad(['js:selector:init' => ['some', 'params']]);
    }   
}

通过事件与您的表格交互

您可以通过发送以下Livewire事件与您的表格进行交互

laraveltable:refresh
- 允许可选的array $configParams = []和array $targetedConfigs = []参数
- 刷新您的表格，并（可选）设置外部表格配置数据，（可选）对特定表格进行定位以仅刷新它们（空$targetedConfigs数组将刷新一页上的所有表格）

测试

composer test

变更日志

有关最近更改的更多信息，请参阅更改日志。

贡献

有关详细信息，请参阅贡献指南。

鸣谢

许可协议

MIT许可协议（MIT）。有关更多信息，请参阅许可文件。

okipa / laravel-table

维护者

详细信息