README

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

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

安装

您可以通过composer安装此包

composer require fitt-tech/data-grid-laravel

请注意，要充分发挥此包的功能，还需要一个配套的前端包

npm install vuetify-data-grid

信息

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

用法

包的用法可以分为多个部分。以下将详细讨论

初始设置

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

迁移

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

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的查询，使用模型、数据库外观或关系。然而，需要注意的是预期的类型是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() 函数用于该语句的别名。因此，您不应在原始语句中添加 AS 部分。

rawValue()

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

subtitle()

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

rawSubtitle()

《rawSubtitle()`函数》用于传递用于副标题的原始SQL/MySQL语句。需要注意的是，当使用《rawSubtitle()`函数》时，还需要使用《subtitle()`函数》来传递该原始语句的别名。因此，您不要在原始语句中添加《AS》部分。

type()

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

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

subtitleType()

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

label()

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

enumerators()

《enumerators()`函数》用于添加该列可用枚举值的《key -> value》对。此函数仅用于当列《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()`函数》用于指定在没有任何条件评估为真时显示的默认图标。也接受一个颜色作为第二个参数。默认为《grey》。

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。然而，这些仍然处于开发中，并计划在以后的版本中发布。

结论

这就完成了 data-grid-laravel 的文档。

许可证

MIT 许可证 (MIT)。请参阅许可证文件以获取更多信息。