README

包状态

此包不再处于活跃开发状态。我们不再计划添加新功能。主要原因是我们公司的项目不再使用 DataTables。

如果您希望维护此包的分支，我将非常乐意提供链接。

Laratables

Laravel 包，用于处理 Datatables 的服务器端 Ajax。

简介

此包帮助处理将 Eloquent 模型中的数据显示到具有 Ajax 支持的 datatables 中，并提供简单的关联和列值定制。Laratables 目前不支持 DataTables Editor。

如何使用

基本方法是您可以在客户端指定 DataTable 配置和列，就像没有做任何重大更改一样，然后在服务器端调用一个方法来处理 Ajax 调用。该包将创建必要的查询以获取数据并自动使搜索和排序功能工作。如果需要，您可以通过在 Eloquent 模型或自定义类中添加方法来在各个阶段自定义查询/数据/逻辑。

客户端

$('#users-table').DataTable({
    serverSide: true,
    ajax: "{{ route('admin.users.datatables') }}",
    columns: [
        { name: 'id' },
        { name: 'name' },
        { name: 'email' },
        { name: 'role.name', orderable: false },
        { name: 'action', orderable: false, searchable: false }
    ],
    ...
});

⚠️ 重要说明 ⚠️ - 客户端代码决定要获取的列。如果您在公共页面显示表格，恶意用户可以修改 HTTP 请求以获取相应表和相关表的其它列的数据。强烈建议在返回数据之前验证请求。

服务器端

use App\User;
use Freshbitsweb\Laratables\Laratables;
...
return Laratables::recordsOf(User::class);

有多种方法可以自定义查询/数据/逻辑。请参阅下面的定制部分以获取详细信息。

⬆ 返回顶部

演示仓库

要求

安装

在您的终端/cmmd 中运行以下命令来安装包：

composer require freshbitsweb/laratables

可选，您可以通过在终端/cmmd 中运行以下命令来导入配置文件：

php artisan vendor:publish --tag=laratables_config

⬆ 返回顶部

定制

按照“如何使用”部分的步骤，您可以在一分钟内使用简单的 datatables 示例开始。然而，许多 datatables 需要定制能力。第一个用例是关于将额外的 where 条件应用到查询或加载额外的关联。

要实现这一点，您可以将闭包/可调用对象作为第二个参数传递给 recordsOf() 方法。它应该接受底层查询作为参数，并在应用条件后返回它。

use App\User;
use Freshbitsweb\Laratables\Laratables;
...
return Laratables::recordsOf(User::class, function($query)
{
    return $query->where('active', true);
});

有更多选项可以自定义查询/数据/逻辑。您可以在您的模型或自定义类中添加以下任何方法（以laratables词开头），以保持您的模型整洁。如果您想使用一个，请将自定义类的名称作为recordsOf()方法的第二个参数指定

use App\User;
use Freshbitsweb\Laratables\Laratables;
use App\Laratables\User as UserLaratables;
...
return Laratables::recordsOf(User::class, UserLaratables::class);

⬆ 返回顶部

控制查询

如果您希望每次使用模型来显示Laratable时都应用条件，请将laratablesQueryConditions()静态方法添加到模型/自定义类中。

/**
 * Fetch only active users in the datatables.
 *
 * @param \Illuminate\Database\Eloquent\Builder
 * @return \Illuminate\Database\Eloquent\Builder
 */
public static function laratablesQueryConditions($query)
{
    return $query->where('active', true);
}

此方法接受并返回一个$query对象。

控制关联查询

您还可以通过定义闭包来控制关系查询，该闭包可以在加载数据关系时使用。静态方法名称格式为laratables[RelationName]RelationQuery。

/**
 * Eager load media items of the role for displaying in the datatables.
 *
 * @return callable
 */
public static function laratablesRoleRelationQuery()
{
    return function ($query) {
        $query->with('media');
    };
}

将相关表连接到查询

laratablesQueryConditions()方法还可以用于在基表上添加连接。如果您需要根据相关模型定义自定义搜索和排序，这尤其有用

/**
 * Join roles to base users table.
 * Assumes roles -> users is a one-to-many relationship
 *
 * @param \Illuminate\Database\Eloquent\Builder
 * @return \Illuminate\Database\Eloquent\Builder
 */
public static function laratablesQueryConditions($query)
{
    return $query->join('roles', 'roles.id', 'users.role_id');
}

注意 - 如果根据连接表的列进行搜索/过滤，您还需要确保它们包含在选择的列中。以下是一些实现方式：

在上述->select()方法中链接 - 例如 $query->join(...)->select(['roles.name as role_name'])，或者
使用选择额外列中描述的laratablesAdditionalColumns()方法。

⬆ 返回顶部

自定义列

通常，我们需要一个或多个不在数据库表中存在的列。最常见的一个例子是“操作”列，提供编辑或删除记录的选项。您可以在您的模型/自定义类中添加一个静态方法laratablesCustom[ColumnName]()来指定自定义列值。按照我们的示例，它可以是

/**
 * Returns the action column html for datatables.
 *
 * @param \App\User
 * @return string
 */
public static function laratablesCustomAction($user)
{
    return view('admin.users.includes.index_action', compact('user'))->render();
}

如您所观察到的，您将收到一个记录的eloquent对象作为参数，以在您的方法中使用记录详情。

⬆ 返回顶部

关系列

我们还需要显示相关模型的数据，对吧？在这里，这非常简单。对于简单的关联，无需在服务器端进行任何操作。只需在列数组中指定关系的名称和客户端上的列名称。

columns: [
    ...
    { name: 'role.name', orderable: false },
    ...
],

在Laravel中，按关系列排序记录不受支持，因为主表记录首先被检索，然后发出另一个查询以检索相关表的记录。因此，您应始终将关系表列设置为orderable: false。

注意 - 该包目前不支持嵌套关系。您可以使用自定义列功能来获取嵌套关系数据，但请确保您预加载关系记录。

⬆ 返回顶部

自定义列值

有时，您可能需要在显示在表格中之前自定义表格列的值。只需在您的eloquent模型/自定义类中添加一个静态方法laratables[ColumnName]()即可

/**
 * Returns truncated name for the datatables.
 *
 * @param \App\User
 * @return string
 */
public static function laratablesName($user)
{
    return Str::limit($user->name, 15);
}

关系列也可以通过添加一个格式为laratables[RelationName][ColumnName]()的静态方法来自定义。

这些静态方法使用记录的eloquent对象作为参数在eloquent模型/自定义类上调用。

注意 - 在v1.*.*中，这些方法是常规方法

⬆ 返回顶部

搜索

Datatables提供搜索功能，可以根据任何显示列的值过滤结果。虽然此包自动应用带有like运算符的orWhere条件，但您可以为任何列设置自己的条件。我们为此提供静态方法laratablesSearch[ColumnName]()。

/**
 * Adds the condition for searching the name of the user in the query.
 *
 * @param \Illuminate\Database\Eloquent\Builder
 * @param string search term
 * @return \Illuminate\Database\Eloquent\Builder
 */
public static function laratablesSearchName($query, $searchValue)
{
    return $query->orWhere('first_name', 'like', '%'. $searchValue. '%')
        ->orWhere('surname', 'like', '%'. $searchValue. '%')
    ;
}

如果任何列是关系列，则该包足够智能，可以应用带有必要闭包的orWhereHas查询以相应地过滤记录。您可以添加laratablesSearch[RelationName][ColumnName]()静态方法到您的eloquent模型/自定义类中，以覆盖该行为。

注意 - 您可以在 Datatables 配置（客户端）中的任何列中添加 searchable: false 以防止对该列进行搜索操作。或者，您也可以将列名添加到配置文件中的 non_searchable_columns 数组中。

⬆ 返回顶部

排序（排序）

默认情况下，常规表列的排序功能正常。还支持多列排序。对于关系列或自定义列，您应该在 Datatables 列配置中添加 orderable: false，或者添加一个静态方法 laratablesOrder[ColumnName]() 并返回用于排序记录的主表列名。例如，如果您的表包含 first_name 且 Datatables 只有 name，您可以添加

/**
 * first_name column should be used for sorting when name column is selected in Datatables.
 *
 * @return string
 */
public static function laratablesOrderName()
{
    return 'first_name';
}

您还可以通过添加静态方法 laratablesOrderRaw[ColumnName]() 并返回我们将要放在查询的 orderByRaw() 中的原始语句来按原始语句排序行。该函数接收 $direction 变量，它将是 asc 或 desc。

/**
 * first_name and last_name columns should be used for sorting when name column is selected in Datatables.
 *
 * @param string Direction
 * @return string
 */
public static function laratablesOrderRawName($direction)
{
    return 'first_name '.$direction.', last_name '.$direction;
}

⬆ 返回顶部

选择额外列

我们以这种方式编写了包，查询仅从数据库表中选择所需的列。如果您在自定义列值时需要额外的列值，您可以在 laratablesAdditionalColumns() 静态方法中的数组中指定它们。例如，如果您在表中具有 first_name 和 surname，而您正在使用自定义列 name，您可以添加

/**
 * Additional columns to be loaded for datatables.
 *
 * @return array
 */
public static function laratablesAdditionalColumns()
{
    return ['first_name', 'surname'];
}

⬆ 返回顶部

指定额外可搜索列

如果您需要在 Datatables 未显示的表列中搜索值，您可以在 laratablesSearchableColumns() 静态方法中的数组中指定它们。例如，如果您在表中具有 first_name 和 surname，并希望用户能够通过这些列进行搜索，即使它们不在 Datatables 中显示，您也可以添加

/**
 * Additional searchable columns to be used for datatables.
 *
 * @return array
 */
public static function laratablesSearchableColumns()
{
    return ['first_name', 'surname'];
}

⬆ 返回顶部

Carbon 实例的日期格式

默认情况下，Laravel 将 created_at 和 updated_at 视为 Carbon 实例，您也可以将您的表中的任何其他列视为 Carbon 实例。此包有一个配置选项 date_format，用于指定应返回给 Datatables 的日期格式。默认格式为 'Y-m-d H:i:s'。

修改获取的记录

有时，我们需要在记录已检索后与之一起工作。您可以将 laratablesModifyCollection() 静态方法添加到您的模型/自定义类中，以处理集合并返回更新后的一个。注意，如果您从集合中添加/删除任何项，Datatables 计数将不匹配。

/**
 * Set user full name on the collection.
 *
 * @param \Illuminate\Support\Collection
 * @return \Illuminate\Support\Collection
 */
public static function laratablesModifyCollection($users)
{
    return $users->map(function ($user) {
        $user->full_name = $user->first_name . ' '. $user->last_name;

        return $user;
    });
}

⬆ 返回顶部

额外的 `data-` Datatables 属性

Datatables 接受每个记录的额外 data- 属性。以下是由此包支持的

DT_RowId：此数据属性默认添加到每个记录中。您可以通过更新 row_id_prefix 配置选项来设置该记录 ID 的前缀。
DT_RowClass：您可以将 laratablesRowClass() 静态方法添加到您的模型/自定义类中，并返回一个 html 类名。示例

/**
 * Specify row class name for datatables.
 *
 * @param \App\User
 * @return string
 */
public static function laratablesRowClass($user)
{
    return $user->is_active ? 'text-success' : 'text-warning';
}

注意 - 在 v1.*.* 中，此方法是一个常规方法。

DT_RowData：您可以将 laratablesRowData() 静态方法添加到您的模型/自定义类中，并返回一个数组，键为属性名，对应的值为值。示例

/**
 * Returns the data attribute for url to the edit page of the user.
 *
 * @param \App\User
 * @return array
 */
public static function laratablesRowData($user)
{
    return [
        'edit-url' => route('admin.user.edit', ['user' => $user->id]),
    ];
}

注意 - 在 v1.*.* 中，此方法是一个常规方法。

作者

Gaurav Makhecha - 初始工作

请参阅参与此项目的贡献者列表。

许可协议

本项目采用 MIT 许可协议 - 有关详细信息，请参阅 LICENSE 文件。

免费软件

您可以自由使用此包，但如果它进入您的生产环境，我将非常感激您为世界买一棵树。

现在人们都知道，应对气候危机并保持气温不超过1.5摄氏度的最佳工具之一是植树。如果您为我们的森林做出贡献，您将为当地家庭创造就业机会并恢复野生动物栖息地。

您可以在offset.earth/treeware购买树木以支持我们的森林。

了解更多关于Treeware的信息，请访问treeware.earth

特别感谢

Laravel 社区

freshbitsweb / laratables

维护者

详细信息

README

包状态

Laratables

目录

简介

如何使用

客户端

服务器端

演示仓库

要求

安装

定制

控制查询

控制关联查询

将相关表连接到查询

自定义列

关系列

自定义列值

搜索

排序（排序）

选择额外列

指定额外可搜索列

Carbon 实例的日期格式

修改获取的记录

额外的 `data-` Datatables 属性

作者

许可协议

免费软件

特别感谢

freshbitsweb / laratables

维护者

详细信息

README

包状态

Laratables

目录

简介

如何使用

客户端

服务器端

演示仓库

要求

安装

定制

控制查询

控制关联查询

将相关表连接到查询

自定义列

关系列

自定义列值

搜索

排序（排序）

选择额外列

指定额外可搜索列

Carbon 实例的日期格式

修改获取的记录

额外的 data- Datatables 属性

作者

许可协议

免费软件

特别感谢

额外的 `data-` Datatables 属性