README

Vanguard 是一个针对 Laravel 的全栈式表格和搜索查询构建器包，附带使用 InertiaJS HTTP 协议规范的前端 Vue 可组合组件。它提供了一个优雅的 API 来定义表格、列、操作和精炼器。

安装

使用 composer 安装包。

composer require jdw5/vanguard

不需要配置文件。您可能想发布存根和命令来自定义默认表格。

php artisan vendor:publish --tag=vanguard-stubs

前端伴侣

通过 npm 提供了 Vue-Inertia 客户端库，该库提供了一个围绕精炼器和表格数据的可组合组件。在此查看文档。

npm install vanguard-client

使用方法如下：

import { useTable } from 'vanguard-client'

defineProps({
    propName: Object
})

const table = useTable('propName')

它包含内置的查询字符串解析和数据刷新、表格项的批量选择以及用于表格的 JavaScript 生成函数。

请参阅存储库以获取更多信息，以及 API 文档。

结构

核心功能是定义您的表格并自动执行过滤。精炼和操作也可以单独使用，无需表格，但结构将重点关注 Table 类。

使用 make:table 命令时，将生成以下样板代码：

您必须定义 model、table 属性或完成 defineQuery 方法来告诉表格要获取哪些数据。您也可以省略此操作，并将 Builder 实例传递给 UserTable::make(Model::query()) 方法。

表格期望一个唯一的列，或每个元素的标识符。这特别适用于生成模态框：推荐使用 based/momentum-modal 来提供模态端点。可以将在模型上定义的 key 或者在定义时将 asKey() 连接到列。

如果没有提供集合方法，则表格默认在检索记录时执行 get()。可以在创建类时提供这些方法

$table = UserTable::make()->paginate(10);

或者，推荐的方法是完成 public function paginate() 方法。这可以返回一个整数或一个整数数组。如果提供了数组，您已选择动态分页，并在表格上生成一个 show 属性以供前端使用。这允许用户更改每页记录数。

defineColumns 返回一个数组，您可以在其中指定要在前端显示的列。查询中选定的数据将减少，以便只传递列属性到客户端。它提供了在每列上定义可见性、断点、转换数据等功能。

defineRefinements 返回一个 Filter 和 Sort 子类数组，以定义用户可用的精炼。文档中包含了提供的 API 的完整规范。

defineActions 返回一个数组，您可以在其中指定要在数据上执行的操作。有三种操作类型可供使用：PageAction、InlineAction 和 BulkAction。

核心

我们为Vanguard提供的类和特性提供了完整的API文档，包括相关的命名空间。抽象类不包括在文档中，但可在源代码中找到。

表格

可以使用 php artisan make:table 命令行生成表格。

定义查询

该表格需要一个查询来获取数据。这可以通过以下方式之一提供，以下按优先级列出：

作为 Table::make($argument) 的唯一参数传递
在您的表格类中重写方法 protected function defineQuery()，返回一个 Builder|QueryBuilder 实例
设置属性 protected $model 为要获取数据的模型类

设置属性 protected $getModelClassesUsing 为一个解析模型类的函数
如果上述都没有提供，它将尝试从表名解析模型类

已弃用 要在提供的查询和获取的数据之间修改查询，可以添加另一个方法 protected function beforeFetch(Builder|QueryBuilder $query) 来应用任何额外的约束或修改，特别是用于更改排序顺序。

您还应该为表格中的每行定义一个唯一键。这可以通过将属性 protected $key 设置为列名，或者通过在定义列时将方法 asKey() 连接到列来完成。

定义列

列定义了传递到前端的数据，并且可以在传递之前更改数据，以及其他许多事情。列是通过使用方法 protected function defineColumns(): array 定义的，该方法应返回一个 Column 实例数组。请参阅列文档了解API。

还有一个额外的属性 protected $applyColumns，可以将其设置为 false 来禁用将列应用于查询。当您不想减少数据或对默认列满意时，这很有用。默认情况下，它设置为 true。

定义精炼器

Vanguard为 Query\Builder 和 Eloquent\Builder 提供了一个宏，将 Refinement 类应用于给定的查询。这在生成表格的管道中使用，允许您流畅地定义表格的优化。

要为您的表格添加优化，您可以定义方法 protected function defineRefinements(): array，该方法应返回一个 Refinement 实例数组。请参阅优化文档了解API。

定义分页和元数据

Vanguard提供了与Laravel查询构建器提供的默认获取方法几乎相同的API。您可以在创建表格时定义获取方法，定义属性或定义方法。支持的方法是：get、paginate、cursorPaginate 和 dynamicPaginate。按优先级排序：

在创建时设置方法 Table::make()->paginate()
设置 protected $paginateType 为 get、paginate、cursor 或 dynamic
重写方法 protected function paginate(): int|array 以返回每页的记录数

链式方法提供了与Laravel内置分页机制相同的API。如果您在创建时没有这样做，您可以覆盖表格上的相关属性。这些是 protected $pageName、protected $page、protected $columns，以及 protected $paginateType。

还有一个 dynamicPaginate 选项。这允许用户更改每页的记录数。这是安全地完成的，他们不能随意更改每页的记录数 - 它必须是提供的选项之一。要启用此选项，您必须从方法 protected function definePaginate() 返回一个整数数组，其中每个整数都是每页的有效记录数。或者，您可以手动将 perPage 属性设置为数组，并将 paginateType 设置为 dynamic - 但这不被推荐。

默认记录数设置为10，但可以通过更改属性protected $defaultPerPage进行覆盖。建议提供的作为页面选项的数组包含您设置的默认记录数。您还可以通过更改属性protected $showKey来覆盖查询参数的术语。默认情况下，术语是show。

定义操作

使用protected defineActions(): array方法定义操作，该方法应返回一个Action实例数组。请参阅Action文档了解API。然后根据类型将它们分组，以便在前端访问。

定义首选项

首选项是一种根据用户更改选择动态更改发送到前端的数组的方法。默认情况下，此行为未启用。它将在表数据对象中添加一个paging_options属性，包含用作首选项的列。

要启用首选项，必须在搜索查询中定义用于首选项的键。这可以通过将属性protected $preferencesKey设置为所选名称（cols是一个常见的名称）或通过覆盖方法protected definePreferenceKey(): string来返回键来实现。

然后可以将您定义的列的preference()方法连接到它们上，以将它们用作首选项。如果应用了列，则这会防止发送到前端的任何不在这些首选项中的数据。但是，查询必须选择所有可能的首选项所需的所有列 - 因为首选项是在服务器级别完成的，而不是数据库。

此外，Vanguard提供了通过cookie存储用户给定表的偏好设置的功能。要启用此功能，必须在表类中定义cookie名称。这可以通过将属性protected $preferenceCookie设置为所选名称或通过覆盖方法protected definePreferenceCookie(): string来返回名称来实现。确保此键在所有表中都是唯一的，以防止冲突。

操作

操作允许您定义不属于表的多个操作。要定义Actions类，可以使用Actions::make(...BaseAction $actions)方法创建它。参数必须是InlineAction、PageAction或BulkAction实例。然后根据类型将操作分组，以便在前端访问。

细化器

细化器是一种定义搜索参数并将其应用于查询的方法，使用的是流畅API。然后根据类型将细化器分组，以便在前端访问。您可以使用Refiners类将它们分组，而不是属于表的一部分。可以使用Refiners::make(...Refinement $refiners)方法内联生成它。参数必须是Refinement实例。

组件文档

列

列仅用于Table类，以定义传递到前端的数据。它们可以用于在传递之前修改数据、定义可见性、断点等。使用Column::make($name)生成列。如果应用列，则$name参数应该是数据库中列的名称。其余属性是自动生成的，或需要使用以下方法进行链式调用

操作

扩展BaseAction的类用于定义用户可以在表上执行的基本方法。要生成操作，可以使用InlineAction::make(string $name)。名称用作操作在其组或表中的键。其余属性是自动生成的，或需要使用以下方法进行链式调用

行内操作

内联操作具有一个额外的默认属性，通常用于表示在单击行时要执行默认操作。

页面操作

目前，只有页面操作可以访问端点API，因为这些页面通常不需要传递数据，并且可以使用只有服务器数据构建。

精炼

细化是一种定义搜索参数并将其应用于查询的方法，使用的是流畅API。所有细化构造函数都稍微复杂一些。

Refinement::make(string $property, ?string $name)

属性字段是必需的，表示特定的数据库列。名称字段是可选的，用于在前端显示细化信息。如果没有提供名称，则使用属性作为名称。构造函数还会生成一个标签，该标签默认为名称然后是属性，但通常会被覆盖。以下提供了细化功能的其余API。

为您创建了一些特定的细化器，这些应该覆盖现实中几乎所有的用例。这些细化器是从基础组件构建的。

排序

《BaseSort》API为细化添加了一个方向，以便适应数据的排序。标准的《Sort》选项在没有任何额外参数的情况下扩展了这个基础排序。

《ToggleSort》API不可扩展，因此未提供。没有链式方法，因为所有操作都在内部处理。

过滤

过滤器提供了一种根据特定属性过滤数据的方法。《BaseFilter》API向细化添加了一个值，以便适应数据的过滤。

过滤

过滤器扩展了基础过滤器，并允许定义模式和操作符。

选择过滤

选择过滤器允许应用《whereIn》子句，即允许检查数组。它只有上面提到的操作符方法。

查询过滤

QueryFilter允许应用自定义查询到过滤器。这对于复杂查询或无法使用标准操作符表示的查询很有用。

选项

选项是查询术语可以采取的可用值。由于这个原因，它们可以通过多种方式生成，下面将详细介绍链式方法。创建选项的标准方式是使用《Option::make(string $value, ?string $label)》方法。

如前所述，创建选项的标准方式是使用《Option::make(string $value, ?string $label)》方法，其中选项的值是必需参数，可以可选地传递一个标签。在某些情况下，您可能希望从源创建选项，这些情况也将被涵盖。

从集合中，例如执行数据库查询，可以使用《Option::collection(Collection $collection, string\|callable $asValue, string\|callable $asLabel)》。集合是要使用的数据集合，两个可调用函数用于从集合中提取值和标签。这提供了一种映射数据并创建值、标签对的方法。可调用函数应接受集合的一个元素并分别返回值或标签。该方法默认使用《value》和《label》索引关联数组以检索数据。

从数组中，例如选项列表，可以使用《Option::array(array $array, string\|callable $asValue, string\|callable $asLabel)》。这与集合方法使用相同的API，但用于数组。

最后，可以使用《Option::enum(string $enum, string\|callable $asLabel)》生成选项。这将检查给定枚举字符串中的《BackedEnum》，值作为枚举值。然后，标签通过函数生成，该函数接收《BackedEnum》的一个实例或使用枚举上定义的方法，如果传递了一个字符串。

测试

在测试之前，请确保您的环境或容器有PHP Sqlite适配器，在Linux上：

sudo apt-get install php-sqlite3

执行《composer install》以检索所需的包。然后可以执行测试：

vendor/bin/phpunit

指定测试套件如下：

vendor/bin/phpunit --testsuite=Feature

jdw5 / vanguard

维护者

详细信息