CListView 核心特性
- 列表視圖，支援自定義項目模板 (
itemView) 靈活渲染。
- 內建分頁 (
CPagination)、排序 (CSort)、AJAX 更新 (ajaxUpdate)。
- 需搭配
IDataProvider (通常 CActiveDataProvider) 提供資料。
- 類似 Android ListView 概念：資料 + 模板 = 列表。
基本配置範例
// Controller
public function actionIndex() {
$dataProvider = new CActiveDataProvider('Customer', [
'pagination' => ['pageSize' => 10, 'pageVar' => 'page'],
'sort' => ['defaultOrder' => 'LastName'],
]);
$this->render('index', ['dataProvider' => $dataProvider]);
}
// View (index.php)
widget('zii.widgets.CListView', [
'dataProvider' => $dataProvider,
'ajaxUpdate' => false, // 關閉 AJAX 分頁 (SEO/除錯友善)
'template' => '{sorter}{pager}{summary}{items}{pager}', // 頁面結構
'itemView' => '_view', // 項目模板視圖
'pager' => ['maxButtonCount' => 7], // 分頁器選項
'sortableAttributes' => ['FirstName', 'LastName', 'Country'], // 可排序欄位
'summaryText' => '顯示 {start}-{end} 筆，共 {count} 筆',
'emptyText' => '無資料',
'htmlOptions' => ['class' => 'list-view'],
]); ?>
項目模板 視圖
// protected/views/site/_view.php
FirstName . ' ' . $data->LastName); ?>
getAttributeLabel('Company')); ?>:
Company); ?>
getAttributeLabel('Address')); ?>:
format->formatUrl($data->Address); ?>
getAttributeLabel('Country')); ?>:
Country); ?>
getAttributeLabel('Email')); ?>:
format->formatEmail($data->Email); ?>
關鍵屬性詳細說明
| 屬性 | 說明 | 預設值 |
|---|
| dataProvider | IDataProvider 實例 (必填) | - |
| itemView | 項目模板視圖名稱 (相對當前 Controller view 目錄) | - |
| template | 頁面結構佔位符：{summary} {sorter} {items} {pager} | {sorter}{summary}{items}{pager} |
| ajaxUpdate | 是否啟用 AJAX 分頁/排序 (true/false/選擇器字串) | true |
| pager | 分頁器配置陣列 (CPagination 屬性、cssFile、header、footer 等) | [] |
| sorter | 排序器配置陣列 (CSort 屬性、cssFile 等) | [] |
| sortableAttributes | 允許排序的屬性陣列 (對應 CSort attributes) | [] |
| summaryText | 摘要文字模板：{count} {start} {end} | Displaying {start}-{end} of {count} results. |
| emptyText | 空資料提示文字 | No results found. |
| itemsTagName | 包裹項目容器標籤 | div |
| itemTagName | 單一項目包裹標籤 | div |
AJAX 分頁/排序運作原理
- 使用者點擊分頁連結或排序表頭。
- jQuery 攔截點擊，發送 AJAX 請求至當前 URL (附帶
page/sort 參數)。
- Controller 重新建構 DataProvider，只渲染局部視圖 (
ajaxUpdate 指定的容器 ID)。
- 回傳 HTML 片段，替換頁面對應區塊。
- URL 更新 (HTML5 History API) 保持書籤可用。
進階：讓項目標題變連結 (導向 DetailView)
// _view.php 修改標題行
FirstName . ' ' . $data->LastName),
$this->createUrl('view', ['CustomerId' => $data->CustomerId])
); ?>
完整範例下載
ListViewDemo.zip
