README

本包为 Laravel 的查询构建器和 Eloquent ORM 提供基于游标的分页功能。它通过检查请求的 GET 参数自动计算 SQL 查询限制，并为您自动构建下一页和上一页的 URL。

兼容性

本包已在 Laravel 5.6 上进行了测试，我们期望它也能在新版本上工作，但它从未经过测试。

安装

您可以通过 composer 使用以下命令安装此包：

composer require aloware/laravel-cursor-pagination

包将自动注册自己。

它是如何工作的

游标分页的核心思想是它需要一个上下文来知道显示哪些结果。所以你不说 page=2，你这样说

cursor=eyJpZCI6MTAsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0=

游标值是经过编码的(base64)。如果你解码它，你会看到类似的东西

{"id":10,"_pointsToNextItems":true}

结果是和传统的页面分页一样，但现在你对输出的控制更多了，因为它应该总是返回相同的。

这种分页方式在按最新排序时非常有用，因此你可以使用 cursor 实现无限滚动，每次滚动到页面底部时都可以使用 cursor，或者当你需要刷新顶部列表时也可以使用 cursor，如果你发送第一个游标，结果将只获取新的数据。

基本用法

分页查询构建器结果

有几种分页项的方式。最简单的是使用 查询构建器 或 Eloquent 查询 上的 cursorPaginate 方法。cursorPaginate 方法会自动设置适当的限制并基于用户查看的游标获取下一页或上一页元素。默认情况下，cursor 会通过 HTTP 请求中页面查询字符串参数的值来检测。此值由包自动检测，同时考虑您的自定义配置，并且也由分页器自动插入链接和元数据。

public function index()
{
    $users = DB::table('users')->cursorPaginate();
    return $users;
}

分页 Eloquent 结果

您还可以分页 Eloquent 查询。在这个例子中，我们将使用 15 项每页分页 User 模型。如您所见，语法与分页查询构建器结果相同

$users = User::cursorPaginate(15);

当然，您可以在设置查询的其他约束之后调用 paginate，例如 where 子句

$users = User::where('votes', '>', 100)->cursorPaginate(15);

或对结果进行排序

$users = User::orderBy('id', 'desc')->cursorPaginate(15);

不用担心，包会检测模型的主键是否用于排序，并相应地调整，以确保下一页和上一页按预期工作。

标识符

分页器标识符基本上是游标属性。用于分页的模型属性。这个标识符在结果中必须是 唯一的。重复的标识符可能会导致某些记录没有显示，所以请小心。

自动检测标识符

如果没有定义标识符，游标将尝试自己找出它。首先，它会检查是否有任何 orderBy 子句。如果有，它将使用排序的第一个列。如果没有 orderBy 子句，它会检查它是否是一个 Eloquent 模型，并使用它的 primaryKey（默认为 'id'）。如果不是 Eloquent 模型，则使用 id。

示例

// Will use Booking's primaryKey
Bookings::cursorPaginate(10);

// Will use hardcoded 'id'
DB::table('bookings')->cursorPaginate(10);

// Will use 'created_by'
Bookings::orderBy('created_by', 'asc')
    ->cursorPaginate(10);

自定义标识符

只需定义 identifier 选项

// Will use id, ignoring everything else.
Bookings::cursorPaginate(10, ['*'], 'cursor', 'id');

致谢

哈梅德·卡姆拉瓦

许可证

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

aloware / laravel-cursor-pagination

维护者

详情