分页

Laravel 的分页功能允许你查询数据的子集,并为用户提供在这些结果的页面之间导航的能力。

由于 Laravel 的分页器是为静态应用程序设计的,在非 Livewire 应用中,每次页面导航都会触发浏览器访问包含所需页面的新 URL(?page=2)。

然而,当你在 Livewire 组件内使用分页时,用户可以在页面之间导航而保持在同一页面上。Livewire 将在幕后处理一切,包括使用当前页面更新 URL 查询字符串。

基础用法

下面是在 show-posts 组件内使用分页每次只显示十篇帖子的最基本示例:

你必须使用 WithPagination trait

要使用 Livewire 的分页功能,每个包含分页的组件都必须使用 Livewire\WithPagination trait。

php

<?php // resources/views/components/⚡show-posts.blade.php

use Livewire\Attributes\Computed;
use Livewire\WithPagination;
use Livewire\Component;
use App\Models\Post;

new class extends Component
{
    use WithPagination;

    #[Computed]
    public function posts()
    {
        return Post::paginate(10);
    }
};

blade

<div>
    <div>
        @foreach ($this->posts as $post)
            <!-- ... -->
        @endforeach
    </div>

    {{ $this->posts->links() }}
</div>

正如你所见,除了通过 Post::paginate() 方法限制显示的帖子数量外,我们还将使用 $this->posts->links() 来渲染页面导航链接。

有关使用 Laravel 分页的更多信息,请查看 Laravel 的综合分页文档。

禁用 URL 查询字符串跟踪

默认情况下,Livewire 的分页器在浏览器 URL 的查询字符串中跟踪当前页面,如: ?page=2。

如果你想仍然使用 Livewire 的分页工具,但禁用查询字符串跟踪,你可以使用 WithoutUrlPagination trait:

php

use Livewire\WithoutUrlPagination;
use Livewire\WithPagination;
use Livewire\Component;

class ShowPosts extends Component
{
    use WithPagination, WithoutUrlPagination; // [tl! highlight]

    // ...
}

现在,分页将按预期工作,但当前页面不会显示在查询字符串中。这也意味着当前页面不会在页面更改时持久化。

自定义滚动行为

默认情况下,Livewire 的分页器在每次页面更改后滚动到页面顶部。

你可以通过将 false 传递给 links() 方法的 scrollTo 参数来禁用此行为:

blade

{{ $posts->links(data: ['scrollTo' => false]) }}

或者,你可以向 scrollTo 参数提供任何 CSS 选择器,Livewire 将找到与该选择器匹配的最近元素,并在每次导航后滚动到它:

blade

{{ $posts->links(data: ['scrollTo' => '#paginated-posts']) }}

重置页面

在排序或过滤结果时,通常希望将页码重置回 1。

为此,Livewire 提供了 $this->resetPage() 方法,允许你从组件中的任何位置重置页码。

以下组件演示了在提交搜索表单后使用此方法重置页面:

php

<?php // resources/views/components/⚡search-posts.blade.php

use Livewire\Attributes\Computed;
use Livewire\WithPagination;
use Livewire\Component;
use App\Models\Post;

new class extends Component
{
    use WithPagination;

    public $query = '';

    public function search()
    {
        $this->resetPage();
    }

    #[Computed]
    public function posts()
    {
        return Post::where('title', 'like', '%'.$this->query.'%')->paginate(10);
    }
};

blade

<div>
    <form wire:submit="search">
        <input type="text" wire:model="query">

        <button type="submit">Search posts</button>
    </form>

    <div>
        @foreach ($this->posts as $post)
            <!-- ... -->
        @endforeach
    </div>

    {{ $this->posts->links() }}
</div>

现在,如果用户在结果的第 5 页,然后通过按下“Search posts”进一步过滤结果,页面将重置回 1。

除了 $this->resetPage(),Livewire 还提供了其他有用的方法从组件中编程方式在页面之间导航:

方法	描述
`$this->setPage($page)`	将分页器设置为特定页码
`$this->resetPage()`	将页面重置回 1
`$this->nextPage()`	转到下一页
`$this->previousPage()`	转到上一页

多个分页器

由于 Laravel 和 Livewire 都使用 URL 查询字符串参数来存储和跟踪当前页码,如果单个页面包含多个分页器,重要的是为它们分配不同的名称。

为了更清楚地演示该问题,考虑以下 show-clients 组件:

php

<?php // resources/views/components/⚡show-clients.blade.php

use Livewire\Attributes\Computed;
use Livewire\WithPagination;
use Livewire\Component;
use App\Models\Client;

new class extends Component
{
    use WithPagination;

    #[Computed]
    public function clients()
    {
        return Client::paginate(10);
    }
};

正如你所见,上面的组件包含一组分页的客户。如果用户导航到此结果集的第 2 页,URL 可能如下所示:

http://application.test/?page=2

假设页面还包含一个也使用分页的 show-invoices 组件。要独立跟踪每个分页器的当前页面,你需要为第二个分页器指定一个名称,如下所示:

php

<?php // resources/views/components/⚡show-invoices.blade.php

use Livewire\Attributes\Computed;
use Livewire\WithPagination;
use Livewire\Component;
use App\Models\Invoice;

new class extends Component
{
    use WithPagination;

    #[Computed]
    public function invoices()
    {
        return Invoice::paginate(10, pageName: 'invoices-page');
    }
};

现在,由于已将 pageName 参数添加到 paginate 方法中,当用户访问发票的第 2 页时,URL 将包含以下内容:

https://application.test/customers?page=2&invoices-page=2

在命名分页器上使用 Livewire 的页面导航方法时,你必须提供页面名称作为额外参数:

php

$this->setPage(2, pageName: 'invoices-page');

$this->resetPage(pageName: 'invoices-page');

$this->nextPage(pageName: 'invoices-page');

$this->previousPage(pageName: 'invoices-page');

钩入页面更新

Livewire 允许你通过在组件内定义以下任一方法来在页面更新前后执行代码:

php

<?php // resources/views/components/⚡show-posts.blade.php

use Livewire\Attributes\Computed;
use Livewire\WithPagination;
use Livewire\Component;
use App\Models\Post;

new class extends Component
{
    use WithPagination;

    public function updatingPage($page)
    {
        // 在此组件的页面更新之前运行...
    }

    public function updatedPage($page)
    {
        // 在此组件的页面更新之后运行...
    }

    #[Computed]
    public function posts()
    {
        return Post::paginate(10);
    }
};

命名分页器钩子

先前的钩子仅适用于默认分页器。如果你使用命名分页器,你必须使用分页器的名称定义方法。

例如,下面是一个名为 invoices-page 的分页器的钩子示例:

php

public function updatingInvoicesPage($page)
{
    //
}

通用分页器钩子

如果你不想在钩子方法名称中引用分页器名称,你可以使用更通用的替代方法,并简单地将 $pageName 作为钩子方法的第二个参数接收:

php

public function updatingPaginators($page, $pageName)
{
    // 在此组件的页面更新之前运行...
}

public function updatedPaginators($page, $pageName)
{
    // 在此组件的页面更新之后运行...
}

使用简单主题

你可以使用 Laravel 的 simplePaginate() 方法而不是 paginate(),以提高速度和简洁性。

使用此方法对结果进行分页时,将仅向用户显示下一页和上一页导航链接,而不是每个页码的单独链接:

php

public function render()
{
    return view('show-posts', [
        'posts' => Post::simplePaginate(10),
    ]);
}

有关简单分页的更多信息,请查看 Laravel 的“simplePaginator”文档。

使用游标分页

Livewire 也支持使用 Laravel 的游标分页 —— 一种适用于大型数据集的更快的分页方法:

php

public function render()
{
    return view('show-posts', [
        'posts' => Post::cursorPaginate(10),
    ]);
}

通过使用 cursorPaginate() 而不是 paginate() 或 simplePaginate(),应用程序 URL 中的查询字符串将存储编码的游标而不是标准页码。例如:

https://example.com/posts?cursor=eyJpZCI6MTUsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0

有关游标分页的更多信息,请查看 Laravel 的游标分页文档。

使用 Bootstrap 而不是 Tailwind

如果你使用 Bootstrap 而不是 Tailwind 作为应用程序的 CSS 框架,你可以配置 Livewire 使用 Bootstrap 样式的分页视图而不是默认的 Tailwind 视图。

要实现此目的,请在应用程序的 config/livewire.php 文件中设置 pagination_theme 配置值:

php

'pagination_theme' => 'bootstrap',

发布 Livewire 配置文件

在自定义分页主题之前,你必须先通过运行以下命令将 Livewire 的配置文件发布到应用程序的 /config 目录:

shell

php artisan livewire:publish --config

修改默认分页视图

如果你想修改 Livewire 的分页视图以适应应用程序的风格,你可以通过使用以下命令发布它们:

shell

php artisan livewire:publish --pagination

运行此命令后,以下四个文件将被插入到 resources/views/vendor/livewire 目录中:

视图文件名	描述
`tailwind.blade.php`	标准 Tailwind 分页主题
`tailwind-simple.blade.php`	简单 Tailwind 分页主题
`bootstrap.blade.php`	标准 Bootstrap 分页主题
`bootstrap-simple.blade.php`	简单 Bootstrap 分页主题

文件发布后,你就可以完全控制它们。当在模板内使用分页结果的 ->links() 方法渲染分页链接时,Livewire 将使用这些文件而不是自己的。

使用自定义分页视图

如果你希望完全绕过 Livewire 的分页视图,你可以通过以下两种方式之一渲染自己的视图:

在 Blade 视图中使用 ->links() 方法
在组件中使用 paginationView() 或 paginationSimpleView() 方法

通过 `->links()`

第一种方法是直接将自定义分页 Blade 视图名称传递给 ->links() 方法:

blade

{{ $posts->links('custom-pagination-links') }}

渲染分页链接时,Livewire 现在将在 resources/views/custom-pagination-links.blade.php 中查找视图。

通过 `paginationView()` 或 `paginationSimpleView()`

第二种方法是在组件内声明 paginationView 或 paginationSimpleView 方法,该方法返回你想要使用的视图名称:

php

public function paginationView()
{
    return 'custom-pagination-links-view';
}

public function paginationSimpleView()
{
    return 'custom-simple-pagination-links-view';
}

分页视图示例

下面是一个简单 Livewire 分页视图的无样式示例,供你参考。

正如你所见,你可以直接在模板内使用 Livewire 的页面导航助手,如 $this->nextPage(),通过将 wire:click="nextPage" 添加到按钮:

blade

<div>
    @if ($paginator->hasPages())
        <nav role="navigation" aria-label="Pagination Navigation">
            <span>
                @if ($paginator->onFirstPage())
                    <span>Previous</span>
                @else
                    <button wire:click="previousPage" wire:loading.attr="disabled" rel="prev">Previous</button>
                @endif
            </span>

            <span>
                @if ($paginator->onLastPage())
                    <span>Next</span>
                @else
                    <button wire:click="nextPage" wire:loading.attr="disabled" rel="next">Next</button>
                @endif
            </span>
        </nav>
    @endif
</div>

分页 ​

基础用法 ​

禁用 URL 查询字符串跟踪 ​

自定义滚动行为 ​

重置页面 ​

可用的页面导航方法 ​

多个分页器 ​

钩入页面更新 ​

命名分页器钩子 ​

通用分页器钩子 ​

使用简单主题 ​

使用游标分页 ​

使用 Bootstrap 而不是 Tailwind ​

修改默认分页视图 ​

使用自定义分页视图 ​

通过 ->links() ​

通过 paginationView() 或 paginationSimpleView() ​

分页视图示例 ​

分页

基础用法

禁用 URL 查询字符串跟踪

自定义滚动行为

重置页面

可用的页面导航方法

多个分页器

钩入页面更新

命名分页器钩子

通用分页器钩子

使用简单主题

使用游标分页

使用 Bootstrap 而不是 Tailwind

修改默认分页视图

使用自定义分页视图

通过 `->links()`

通过 `paginationView()` 或 `paginationSimpleView()`

分页视图示例