README

节省时间，轻松从 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 JscDev\LaravelTable\Table;
use JscDev\LaravelTable\Column;
use JscDev\LaravelTable\Formatters\Date;
use JscDev\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 hadyjsc/laravel-table-dev:dev-master

此包在底层使用 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 JscDev\LaravelTable\Table;
use JscDev\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 JscDev\LaravelTable\Table;
use JscDev\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 JscDev\LaravelTable\Table;
use Illuminate\Database\Eloquent\Builder;
use JscDev\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 JscDev\LaravelTable\Table;
use JscDev\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 JscDev\LaravelTable\Table;
use JscDev\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 JscDev\LaravelTable\Table;
use JscDev\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 组件出现在表上方的专用栏中。

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

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

ValueFilter:
- 实例化时需要 string $label、string $attribute、array $options 和 bool $multiple = true 参数
- 根据所选选项（如果启用多选模式，则为单个选项）的值是否在给定的属性中找到来过滤表
RelationshipFilter:
- 实例化时需要 string $label、string $relationship、array $options 和 bool $multiple = true 参数
- 根据所选选项（如果启用多选模式，则为单个选项）的值是否在给定的关系中找到来过滤表
NullFilter
- 实例化时需要 string $attribute 参数
- 根据给定属性的值是否为 null 来过滤表
BooleanFilter
- 实例化时需要 string $label 和 string $attribute 参数
- 根据给定属性的值是否为 true 或 false 来过滤表

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

namespace App\Tables;

use App\Models\User;
use JscDev\LaravelTable\Table;
use JscDev\LaravelTable\Filters\NullFilter;
use JscDev\LaravelTable\Filters\ValueFilter;
use JscDev\LaravelTable\Filters\BooleanFilter;
use JscDev\LaravelTable\Filters\RelationshipFilter;
use JscDev\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 JscDev\LaravelTable\Table;
use App\Tables\Filters\MyNewFilter;
use JscDev\LaravelTable\Abstracts\AbstractTableConfiguration;

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

定义表格头部操作

配置一个将作为位于表头右侧的按钮显示的表操作。

如果没有声明表头操作，表头中的专用插槽将保持为空。

此软件包提供了以下内置表头操作

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

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

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

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

namespace App\Tables;

use App\Models\User;
use JscDev\LaravelTable\Table;
use JscDev\LaravelTable\HeadActions\AddHeadAction;
use JscDev\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 JscDev\LaravelTable\Table;
use App\Tables\HeadActions\MyNewHeadAction;
use JscDev\LaravelTable\Abstracts\AbstractTableConfiguration;

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

定义表格批量操作

配置将位于表头左侧下拉菜单中的表批量操作。

如果您在表中未声明批量操作，则将不会显示专用列。

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

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

VerifyEmailBulkAction:
- 实例化时需要 string $attribute 参数
- 将当前日期时间更新为所选所有行的给定属性
CancelEmailVerificationBulkAction:
- 实例化时需要 string $attribute 参数
- 将所选所有行的给定属性更新为 null
激活批量操作:
- 实例化时需要 string $attribute 参数
- 将所有选中行的指定属性更新为 true
禁用批量操作:
- 实例化时需要 string $attribute 参数
- 将所有选中行的指定属性更新为 false
销毁批量操作:
- 销毁所有选中行

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

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

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

namespace App\Tables;

use App\Models\User;
use JscDev\LaravelTable\Table;
use JscDev\LaravelTable\BulkActions\DestroyBulkAction;
use JscDev\LaravelTable\BulkActions\ActivateBulkAction;
use JscDev\LaravelTable\BulkActions\DeactivateBulkAction;
use JscDev\LaravelTable\BulkActions\VerifyEmailBulkAction;
use JscDev\LaravelTable\BulkActions\CancelEmailVerificationBulkAction;
use JscDev\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 JscDev\LaravelTable\Table;
use App\Tables\BulkActions\MyNewBulkAction;
use JscDev\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 JscDev\LaravelTable\Table;
use JscDev\LaravelTable\RowActions\EditRowAction;
use JscDev\LaravelTable\RowActions\ShowRowAction;
use JscDev\LaravelTable\RowActions\DestroyRowAction;
use JscDev\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 JscDev\LaravelTable\Table;
use App\Tables\RowActions\MyNewRowAction;
use JscDev\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 JscDev\LaravelTable\Table;
use JscDev\LaravelTable\Column;
use JscDev\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 JscDev\LaravelTable\Table;
use JscDev\LaravelTable\Column;
use JscDev\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 JscDev\LaravelTable\Table;
use JscDev\LaravelTable\Column;
use App\Tables\Formatters\NewFormatter;
use JscDev\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:
- 显示来自 boolean 值的 config('laravel-table.icon.active') 活跃图标或 config('laravel-table.icon.inactive') 不活跃图标
DateFormatter:
- 实例化时需要 string $format 和 string $timezone 参数
- 从 date 或 datetime 值显示格式化的字符串
StrLimitFormatter:
- 实例化时允许可选的 int $limit 和 string $end 参数
- 显示一个带有标题的截断字符串，允许在悬停时查看完整字符串

定义列操作

在您的表中配置列操作，它们将在自己的单元格中显示。

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

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

此软件包提供了以下内置操作

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

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

您可以将与批量操作相同的相同方法链接到行操作中 => 查看批量操作配置。

namespace App\Tables;

use App\Models\User;
use JscDev\LaravelTable\Table;
use JscDev\LaravelTable\ColumnActions\ToggleBooleanColumnAction;
use JscDev\LaravelTable\Abstracts\AbstractTableConfiguration;
use JscDev\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 JscDev\LaravelTable\Table;
use App\Tables\ColumnActions\MyNewColumnAction;
use JscDev\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 插件 标记来启用拖放列排序

namespace App\Tables;

use App\Models\User;
use JscDev\LaravelTable\Table;
use JscDev\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 JscDev\LaravelTable\Table;
use JscDev\LaravelTable\Column;
use JscDev\LaravelTable\Result;
use Illuminate\Support\Collection;
use Illuminate\Database\Query\Builder;
use JscDev\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，它将触发操作执行。您必须传递在 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 事件（有时这取决于反馈消息的配置）。

按照相同的逻辑，您需要从下面的代码片段中拦截它，以便为用户提供即时反馈

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 JscDev\LaravelTable\Table;
use Illuminate\Database\Eloquent\Builder;
use JscDev\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)。有关更多信息，请参阅许可文件

hadyjsc / laravel-table-dev

维护者

详细信息