ThinkPHP数据分页实现教程

ThinkPHP 的分页功能，很多人以为调个 paginate() 就完事了。但真正容易踩坑的地方，恰恰在于它必须直接链式作用在“尚未执行”的查询构造器上——一旦提前调用了 select()、all() 或 get()，分页就会悄悄退化成 PHP 数组切片，总数不准、性能崩塌、翻页空白。这个问题在项目里几乎每天都有新手踩中。

为什么 paginate() 必须链式调用，不能对数组分页

常见错误写法有两种：Db::name('user')->where('status', 1)->select()->paginate(10) 或者 UserModel::all()->paginate(10)。这两种写法都会提前触发数据库查询，返回的是 PHP 数组或 think\Collection 对象——而它们根本没有 paginate() 方法，会直接报 Call to undefined method think\Collection::paginate()。就算某些场景下不报错，也只是对内存里的全表数据做切片，总数统计不走 SQL，total() 偏小甚至为 0。

正确的做法是让 paginate() 接管整个查询链，这样它才能自动生成两条 SQL：一条 COUNT(*) 算总数，另一条带 LIMIT 的主查询。举个例子：

• Db::name('user')->where('status', 1)->order('id desc')->paginate(15) ✅
• UserModel::where('score', '>', 60)->paginate(10) ✅
• 如果涉及 join() 或子查询这类复杂场景，务必确保关联字段有数据库索引，否则 COUNT 可能变慢

翻页后搜索条件丢失？查 query 参数传没传

带关键词搜索的列表页，点“下一页”突然回到第一页、keyword 凭空消失——90% 的情况是没透传 GET 参数。默认情况下 paginate() 只读取 $_GET['page']，其他参数（比如 ?keyword=abc&type=2）不会自动带到下一页的 URL 里。

安全写法是显式传入 query 配置项：

• ->paginate(10, false, ['query' => request()->param()])：透传全部 GET 参数（注意过滤敏感键，比如 token）
• ->paginate(10, false, ['query' => ['keyword' => $keyword, 'type' => $type]])：精准控制，避免注入风险
• 如果参数含数组（比如复选框多值），request()->param() 能自动处理，手动构造时要确保键名结构一致

模板里怎么取数据和渲染分页 HTML

控制器中用 $this->assign('list', $list) 后，模板里不要写 {$page}，也不该调用 toArray()——分页对象本身既是数据容器，又是元信息携带者。

• 循环数据：{volist name="list" id="item"}{$item.name}{/volist}（list 就是你在控制器里 assign 的变量名）
• 输出分页 HTML：{$list->render()}，不是 {$list->show()}，也不是 {$page|raw}
• 取总数：{$list->total()}；当前页：{$list->currentPage()}；总页数：{$list->lastPage()}
• API 场景下不要直接 return $list，应该拆解返回：['data' => $list->items(), 'total' => $list->total(), 'per_page' => $list->listRows()]

API 分页、POST 请求或自定义页码参数怎么办

paginate() 默认从 $_GET['page'] 读取页码，但如果接口走 POST、JSON body 或者 header 传参，这个逻辑就会失效，分页永远卡在第一页。必须显式指定页码来源：

• ->paginate(10, false, ['page' => input('p/d', 1)])：把页码参数名改成 p，URL 变成 ?p=2
• ->paginate(10, false, ['page' => input('page/d', 1), 'query' => ['keyword' => $keyword]])：同时支持自定义页码和搜索透传
• 如果每页条数也想动态传（比如 ?size=20），记得把第二个参数设为 false，否则 page 会被解析两次，导致跳转错乱

整个分页流程里，最容易被忽略的两个地方：一是「总数统计逻辑」，二是「URL 参数继承」。前者出问题表现为最后一页空白、页码跳变；后者就是点下一页回到首页、搜索条件消失。这两个点上线前不验证一遍，用户反馈第一句话往往是“翻不了页”。