README

用于构建高级网格的数据网格包。

支持搜索、筛选、分页以及一些其他高级功能。

安装

您可以通过 composer 安装此包

composer require eawardie/data-grid-laravel

请注意，还需要一个配套的前端包来充分利用此包

npm install data-grid-vuetify

信息

此包的主要责任是提供一个易于理解的开发路径来创建简单或高级数据网格。尽管此包可以独立使用，但建议与配套的前端包 data-grid-vue 一起使用。此前端包提供了所有必要的工具，用于在前端渲染数据网格，包括利用此包提供的所有简单和高级功能。

使用方法

包的使用可以分为多个部分。所有内容将在下面讨论

初始设置

需要进行一些初始设置。最重要的是运行此包包含的迁移。

迁移

您可以使用以下命令发布和运行迁移

php artisan vendor:publish --tag="data-grid-migrations"
php artisan migrate

创建数据网格

您可以使用 DataGrid 门面在任何 PHP 类中创建数据网格。下面是一个简单的数据网格示例。以下将进行详细解释

$query = User::query();
$data = DataGrid::forQuery($query)
   ->addColumn('name', 'Name', 'text')
   ->get();

上面的示例展示了设置数据网格的最简单形式。数据网格主要由两个方面组成

用于数据的查询
用于构建数据网格的各种属性

查询

此查询将用于收集和显示数据网格中实际所需的所有数据。查询可以是任何基于 Laravel 的查询，使用模型、DB 门面或关系。然而，需要注意的是，预期的类型是 Illuminate\Database\Eloquent\Builder。在示例中使用 query() 辅助函数时，这体现在 User 模型上。此外，请注意，任何关系访问都应手动处理 join() 和 leftJoin()。

属性

最后，我们来看看数据网格属性。DataGrid 门面为开发者提供了大量的属性供使用。在上面的示例中，使用了 addColumn() 属性。正如其名称所示，它向数据网格添加了一个列。然而，有许多属性可以使用。从添加简单的列到添加高级列，指定数据网格设置到设置预定义的数据网格视图。所有这些内容都将进行详细解释。

完成您的数据网格

指定所有所需属性后，可以在数据网格实例上调用 get() 函数来获取一个格式良好的键值数组，包含数据网格项目和元数据。此数组可以传递到前端以使用 data-grid-vue 渲染数据网格。然而，如果以独立方式使用，此数组也可以按开发者的需求以任何方式使用。“items”键包含要渲染在数据网格中的实际项目。“metaData”键包含传递给数据网格的所有所需设置。下面是一个示例

array:2 [▼
  "items" => array:50 [▶]
  "metaData" => array:12 [▶]
]

数据网格属性

以下部分将解释数据网格实例上可用的每个属性。

`forQuery()`

此外，如上所述，forQuery() 函数用于将实际的数据查询传递给数据网格。

`setQuery()`

setQuery() 函数可以用来设置数据网格的查询。

`setRequest()`

setRequest() 函数可以用来设置当前请求。

`setPage()`

setPage() 函数可以用来设置当前页码。

`defaultOrderBy()`

defaultOrderBy() 函数用于向表格传递默认排序。如果没有用户输入，这些默认值将被应用。

`setColumns()`

setColumns() 函数可以用来设置数据网格的列。但是请注意，如果可能的话应避免使用此方法。数据网格列应使用内置的 addColumn()、addAdvancedColumn()、addIconColumn() 和 addFileColumn() 函数来设置。

`filterWithConfig()`

filterWithConfig() 函数用于应用设置，强制数据网格使用持久性配置来应用和消费过滤器。这允许数据网格过滤器在关闭应用程序后仍然持续。

`searchWithSession()`

searchWithSession() 函数用于应用设置，强制数据网格在搜索时使用会话存储，而不是路由参数。

`sortWithSession()`

sortWithSession() 函数用于应用设置，强制数据网格在排序时使用会话存储，而不是路由参数。

`pageWithSession()`

pageWithSession() 函数用于应用设置，强制数据网格在分页时使用会话存储，而不是路由参数。

`addColumn()`

addColumn() 函数用于向数据网格添加列。此函数需要一些参数来正确设置列。以下将介绍这些参数。

`addColumn(value, label, type, searchable, sortable, hidden)`

value 参数指示数据库列的值。重要提示，当在查询中使用连接时，值必须以表名作为前缀。

label 参数指示前端上列的实际标签。

type 参数指示列的数据类型。类型被数据网格用于应用搜索词和过滤器。可用的过滤器数量有限。这些将在稍后阶段列出并解释。

searchable 参数指示是否使此列可用于搜索。

sortable 参数指示是否使此列可用于排序。

hidden 参数用于指示列是否默认隐藏。

`addCustomColumn()`

addCustomColumn() 函数用于向数据网格添加非可搜索和非可排序的列，这些列不匹配有效的选择语句。此函数旨在用于在客户端使用 slots 变更的自定义列。此函数需要一个 identifier 参数作为槽的别名和一个 label 参数作为列标签。

`addAdvancedColumn()`

addAdvancedColumn() 函数也用于向数据网格添加列。然而，此函数接受一个类型为 ColumnDefinition 的回调函数。《ColumnDefinition》可用于对列进行精细控制并应用高级功能。定义将在稍后阶段详细说明。以下是一个示例。

->addAdvancedColumn(function (ColumnDefinition $column) {
   return $column->value('user.name')
      ->type('text')
      ->label('User')
      ->subtitle('client.name')
      ->subtitleType('text');
})

`addIconColumn()`

如名称所示，addIconColumn() 可用于向数据网格添加仅显示图标的列。此函数也接受一系列参数。以下将介绍这些参数。

addIconColumn(value, label, icon, color, searchable, sortable, hidden)

value 参数指示数据库列的值。重要提示，当在查询中使用连接时，值必须以表名作为前缀。

label 参数指示前端上列的实际标签。

《icon》参数可以接受字符串或回调函数，具体取决于列的需求。当以字符串形式传递图标时，该图标将用于所有情况。当传递回调函数时，它必须是《IconDefinition》类型。《IconDefinition》用于根据一系列条件对每个值进行精细控制，以确定每列显示哪个图标。以下是一个示例：

$query = User::query();
$data = DataGrid::forQuery($query)
   ->addIconColumn('user.mobile_verified_at', 'Verified', function (IconDefinition $icon) {
       return $icon->condition('account-lock', '=', null, 'error', 'No Password')
          ->condition('account-check', '!=', null, 'success', 'Has Password');
})

`views()`

《views》函数用于为用户预定义数据网格布局供其选择。预定义视图通过回调函数传递给此函数。每个回调都是《ViewDefinition》类型。《ViewDefinition》用于构建数据网格视图。以下是一个示例。

$query = User::query()->leftJoin('client', 'user.clientid', '=', 'client.clientid');
$data = DataGrid::forQuery($query)
   ->addColumn('user.name', 'Name', 'text')
   ->addColumn('client.name', 'Client', 'text')
   ->views(function (ViewDefinition $view) {
       return $view->column('client.name')
          ->label('Clients');
})

`hyperlinks()`

《hyperlinks》函数用于设置是否在前端将电子邮件地址标记为链接。

`load()`

《load》函数可以用来动态加载所需的模型关系。《load》可以接受每个关系的逗号分隔参数，或关系名称的《array》。加载的数据将被追加到行项中。

`addSelect()`

《addSelect》函数，正如其名称所暗示的，只是简单地添加一个选择到最终数据网格项列表中。这主要用于在额外数据需要但不是通过添加列自动选择时使用。

`addRawSelect()`

与《addSelect》相同，但使用原始语句。

`mapRow()`

《mapRow》函数用于修改当前页的行项。此函数接受一个回调函数，该函数接收当前页上的每个行项。需要注意的是，在这里所做的任何修改都将针对每个页项进行评估（默认为50），因此更复杂的修改可能会大大降低性能。以下示例将一个《has_mobile》属性添加到最终项列表中。

$query = User::query();
$data = DataGrid::forQuery($query)
   ->addSelect('mobile')
   ->addColumn('name', 'Name', 'text')
   ->mapRow(function ($row) {
      return collect($row)
         ->put('has_mobile', !!$row['mobile'])
         ->toArray();
})

`get()`

《get》函数用于返回最终的《DataGrid》数据数组。如果将数据传递到前端，则需要此函数。此函数始终在《DataGrid》实例上最后调用。

数据网格定义

存在多个定义，用于与《DataGrid》外观一起使用。以下介绍了所有当前可用的定义。

ColumnDefinition

《ColumnDefinition》类用于定义数据网格的高级列。《ColumnDefinition》实例可以接受以下属性函数：

`avatar(identifier, preview)`

《avatar》函数用于为您的先进列添加头像。它接受一个文件标识符，例如fileid，以及一个布尔值用于头像预览。如果您的查询包含连接，则应将标识符前缀为数据库列名称。预览选项简单地通过单击它使用户能够在前端预览更大的头像。

`icon()`

《icon》函数用于向您的先进列传递图标。此函数的工作方式与前面介绍的《addIconColumn》完全相同。

`value()`

《value》函数用于传递用于显示列实际值的数据库列值。此函数类似于《addColumn》函数上的《value》参数。还应注意的是，当使用原始语句时，使用《value》函数用于该语句的别名。

`rawValue()`

当您需要高级数据检索时，使用《rawValue》函数。需要注意的是，当使用《rawValue》函数时，还必须使用《value》函数传递原始语句的别名。因此，您**不得**在原始语句中添加《AS》部分。

`subtitle()`

《subtitle》函数用于向您的列添加副标题值。值参数是您想要显示的值的数据库列标识符。此值也用作使用原始语句时的别名。

`rawSubtitle()`

rawSubtitle() 函数用于传递用于字幕的原始 SQL/MySQL 语句。请注意，当使用 rawSubtitle() 函数时，还需要使用 subtitle() 函数来传递对该原始语句的别名。因此，您不要在您的原始语句中添加一个 AS 部分。

`type()`

type() 函数用于指定列本身的列类型。不同的列类型将应用不同的样式、搜索参数和过滤器到该列。可用的类型有：

text - 简单文本格式 - 使用搜索
email - 邮件格式，并在点击时打开邮件客户端 - 使用搜索
number - 数字格式 - 使用过滤器
perc - 在前端绘制进度条 - 使用过滤器
timestamp - 格式化值为时间戳 - 使用过滤器
enum - 格式化值为枚举 - 使用过滤器
icon - 向列添加图标 - 使用过滤器

`subtitleType()`

subtitleType() 函数用于指定主要列字幕类型。字幕类型仅用于在前端应用格式。 后续版本将添加对字幕的搜索和过滤。

`label()`

label() 函数用于为列添加标签。标签将在前端显示。

`enumerators()`

enumerators() 函数用于添加该列可用枚举值的 键 -> 值 对。此函数仅在列 type 为 enum 时使用。当使用 enum 类型的列时，列将自动检测枚举值。但是，如果这些值渲染不正确，此函数可以覆盖这些值。

`hidden()`

hidden() 函数用于标记该列为隐藏。隐藏的列不会在前端渲染。此函数不推荐使用，因为隐藏属性通常通过 views() 函数设置。如果列应该默认隐藏，则最好根本不包含该列。

`searchable()`

searchable() 函数用于指示列是否可以搜索。当将此选项应用于可搜索类型的列时，该值将添加到搜索建议中。

`timestampFormat()`

timestampFormat() 列可用于覆盖数据网格的默认时间戳格式。此函数仅在列类型为 timestamp 时推荐使用。例如：D MMM YYYY。

IconDefinition

IconDefinition 类用于定义列的高级图标。此类可以与 addIconColumn() 或 addAdvancedColumn() 函数一起使用。 IconDefinition 实例可以接受以下属性：

`condition()`

condition() 函数用于为列上的特定图标添加条件。该函数接受 5 个可能的参数

icon - 如果条件评估为真，则显示的图标
operator - 比较运算符 - 可用运算符：===, !=, <, >, <=, >=
value - 用于比较的值
color - 要使用的图标颜色
tooltip - 如果设置，则图标在悬停时将显示工具提示

`default()`

default() 函数用于指定如果没有条件评估为 true，则要显示的默认图标。也接受一个颜色作为第二个参数。默认为 灰色。

`label()`

使用 label() 函数为图标指定标签。该标签将在前端过滤器菜单中显示。如果没有指定标签，则默认为列标签，并附加一个 "(I)"。建议指定标签。

`视图定义`

ViewDefinition 类用于为您的数据网格定义视图（布局）。ViewDefinition 实例可以采用以下属性函数

`column()`

column 函数用于指定该视图中列的默认状态。column 函数接受一个列标识符作为其第一个参数，并接受一个布尔值作为其第二个参数，以指示是否隐藏该列。

value - 列标识符 - 必须存在于添加的列中
hidden - 是否隐藏列

以下是一个示例

function (ViewDefinition $view) use ($progressRaw) {
   return $view->column('name')
      ->column('progress', true)

`label()`

标签函数是必需的，并接受一个字符串作为预定义视图的标识符。当在前端选择此视图时使用此标签。

`search()`，`filters` 和 `sort`

这些函数可以用来传递开发者所需的预定义搜索、过滤器或排序。以下是一个示例

function (ViewDefinition $view) use ($progressRaw) {
   return $view->column('name')
      ->column('progress')
      ->search(['name' => ['john']])
      ->sortBy(['name' => 'asc'])
      ->filters([progress => ['value' => 50, 'operator' => '<']])

稍后将添加这些定义

其他可用的定义有 EnumDefinition 和 FileDefinition。然而，它们仍在开发中，并计划在以后的版本中发布。

结论

这便是数据网格-laravel 的文档总结。如有问题，请联系 EA-wardie。

致谢

许可证

MIT 许可证 (MIT)。有关更多信息，请参阅许可证文件。

eawardie / data-grid-laravel

维护者

详细信息

README

用于构建高级网格的数据网格包。

支持搜索、筛选、分页以及一些其他高级功能。

安装

信息

使用方法

初始设置

迁移

创建数据网格

查询

属性

完成您的数据网格

数据网格属性

forQuery()

setQuery()

setRequest()

setPage()

defaultOrderBy()

setColumns()

filterWithConfig()

searchWithSession()

sortWithSession()

pageWithSession()

addColumn()

addColumn(value, label, type, searchable, sortable, hidden)

addCustomColumn()

addAdvancedColumn()

addIconColumn()

views()

hyperlinks()

load()

addSelect()

addRawSelect()

mapRow()

get()

数据网格定义

ColumnDefinition

avatar(identifier, preview)

icon()

value()

rawValue()

subtitle()

rawSubtitle()

type()

subtitleType()

label()

enumerators()

hidden()

searchable()

timestampFormat()

IconDefinition

condition()

default()

label()

视图定义

column()

label()

search()，filters 和 sort

结论

致谢

许可证

`forQuery()`

`setQuery()`

`setRequest()`

`setPage()`

`defaultOrderBy()`

`setColumns()`

`filterWithConfig()`

`searchWithSession()`

`sortWithSession()`

`pageWithSession()`

`addColumn()`

`addColumn(value, label, type, searchable, sortable, hidden)`

`addCustomColumn()`

`addAdvancedColumn()`

`addIconColumn()`

`views()`

`hyperlinks()`

`load()`

`addSelect()`

`addRawSelect()`

`mapRow()`

`get()`

`avatar(identifier, preview)`

`icon()`

`value()`

`rawValue()`

`subtitle()`

`rawSubtitle()`

`type()`

`subtitleType()`

`label()`

`enumerators()`

`hidden()`

`searchable()`

`timestampFormat()`

`condition()`

`default()`

`label()`

`视图定义`

`column()`

`label()`

`search()`，`filters` 和 `sort`