ThinkPHP如何使用分页响应_分页响应实现方法【详解】-ThinkPHP-PHP中文网

paginate() 返回分页对象，不可直接 json() 或 toarray()，需手动提取 items()、total()、per_page() 等字段构造响应，并在 paginate 时传入 query 参数保留筛选条件，且 where/order 必须在 paginate 前调用，大数据量应改用游标分页。

thinkphp如何使用分页响应_分页响应实现方法【详解】

paginate() 返回的是分页对象，不是数组或 JSON，直接 json() 或 toArray() 会丢失分页上下文，导致 render() 失效、total() 不可用——这是 API 场景下最常踩的坑。

分页对象不能直接转 JSON

ThinkPHP 的分页对象（如 User::where()->paginate(10)）内部封装了查询元信息、总数、当前页数据、URL 参数等。一旦调用 $list->toArray() 或 json($list)，它就变成纯数组，所有分页方法（render()、lastPage()、hasPages()）全部不可用。

错误写法：return json($list); → 前端收不到分页导航，也拿不到 total 和 per_page
正确做法：手动构造响应结构，保留关键分页字段
必须显式提取：$list->items()（当前页数据）、$list->total()（总数）、$list->per_page()（每页条数）、$list->current_page()（当前页码）、$list->last_page()（总页数）

示例响应结构：

return json([
    'data' => $list->items(),
    'meta' => [
        'total'      => $list->total(),
        'per_page'   => $list->per_page(),
        'current_page' => $list->current_page(),
        'last_page'  => $list->last_page(),
        'has_next_page' => $list->hasMore(),
    ]
]);

API 分页需手动透传 query 参数

Web 页面分页靠 render() 自动拼 URL，但 API 接口不渲染 HTML，翻页链接得由前端自己拼。如果没保留搜索条件或过滤参数，?page=2 一发过去，条件全丢。

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

漏掉 query 配置，$list->currentPage() 能读，但前端无法生成带 keyword=xxx 的下一页 URL
必须在 paginate() 时传入：User::where($where)->paginate(10, false, ['query' => request()->param()])
注意：request()->param() 包含所有 GET 参数，但若 POST/JSON 请求带筛选条件，得手动提取并塞进 query
敏感字段（如 token、sign）建议白名单过滤，避免透传到分页链接里

分页后不能链式调用 where/order

分页对象是查询执行完的结果，不是查询构造器。对它再调 where() 或 order() 没有效果，也不会报错，只是静默失效。

错误写法：$list = User::paginate(10)->where('status', 1); → where() 完全被忽略
正确时机：所有 where、order、with 必须在 paginate() 之前完成
常见误操作：先 paginate()，再想“加个关联字段”，于是补 ->with('profile') —— 这只会让 items() 里的模型懒加载，但不会影响分页 SQL
如需关联预加载，必须写在前面：User::with('profile')->where(...)->paginate(10)