ListView 渲染前必须配置 DataProvider（如 ActiveDataProvider 或 ArrayDataProvider），否则报错或空白；itemView 为视图路径，变量含 $model/$key/$index；分页排序须在 DataProvider 层配置，非 ListView；性能瓶颈多在查询而非渲染。
ListView 渲染前必须配好 dataProvider
Yii 的 ListView 不是直接传数组就能用的，它强依赖 DataProvider 实例——最常用的是 ActiveDataProvider 或 ArrayDataProvider。漏掉这步，页面会空白或报 Calling unknown method: yii\widgets\ListView::getModels() 错误。
实操建议：
- 查模型数据：用
ActiveDataProvider时，query必须是ActiveQuery实例，不能是执行后的数组 - 查静态数据：用
ArrayDataProvider时，确保传入的allModels是已索引数组（非关联数组也行，但键要连续） - 分页失效？检查
pagination配置是否被设为false，或totalCount是否为 0
itemView 指向的视图文件怎么写才不报错
itemView 是字符串路径，不是 PHP 文件名也不是 URL。它会被 Yii::$app->getView()->render() 解析，所以路径规则和 render() 一致：相对当前控制器视图目录，或以 @app/views/xxx 开头的别名路径。
常见错误现象：
- 报
Unable to resolve the request: xxx/index：说明路径写成路由了，比如写了'post/list-item'而不是'_item' - 变量取不到：
ListView会把当前模型作为$model、索引作为$key、数据提供者为$index（注意不是$i）传入，视图里直接用，别再use或extract - 想复用已有视图但缺上下文？加
viewParams配置传额外参数，比如'viewParams' => ['showActions' => true]
分页和排序控制必须在 DataProvider 层做
ListView 本身不处理分页逻辑，它只读 dataProvider 的 models 和 pagination。排序也是同理——sort 配置必须提前塞进 ActiveDataProvider，而不是丢给 ListView。
典型配置差异：
-
ActiveDataProvider中'sort' => ['defaultOrder' => ['created_at' => SORT_DESC]]才生效；写在ListView的options里完全无效 - 禁用分页？设
'pagination' => false在ActiveDataProvider构造参数里，不是ListView的pager选项 - 想自定义分页样式？改
pager选项，但它只影响渲染，不影响数据切片逻辑
性能差、卡顿？先关掉 enableSorting 和 enablePagination
默认开启的排序和分页会触发额外 SQL 查询（比如 COUNT(*)），尤其在大数据量 + 复杂 JOIN 场景下，很容易拖慢首屏。这不是 ListView 的锅，而是 ActiveDataProvider 的行为。
优化建议：
- 纯展示、无交互需求？构造
ActiveDataProvider时显式关掉：'sort' => false, 'pagination' => false - 要分页但 COUNT 很慢？用
'totalCount' => $approxCount手动设估算值，避免 COUNT(*) - 列表项里调用
$model->relation导致 N+1？提前在ActiveQuery里用with()预加载
真正容易被忽略的是：ListView 的模板渲染开销很小，瓶颈几乎全在 dataProvider 构建和数据库查询上。盯着 ListView 本身调优，大概率走偏。
