Yii Framework Zii 組件 CListView 列表視圖完整實戰指南

CListView 是 Yii 呈現資料列表的利器，支援自訂視圖模板、分頁、排序，並可透過 AJAX 實現局部更新，極大提升頁面響應速度。其設計理念類似 Android 的 ListView，靈活度極高。本文將從資料提供者配置、模板客製化、項目視圖編寫三個維度，完整解析 CListView 實戰技巧。

核心架構：DataProvider 驅動視圖

CListView 必須搭配 CActiveDataProvider（或其他實作 IDataProvider 的類別）使用。在 Controller 中配置分頁大小、預設排序：

public function actionIndex() {
    $dataProvider = new CActiveDataProvider('Customer', array(
        'pagination' => array('pageSize' => 10, 'pageVar' => 'page'),
        'sort' => array('defaultOrder' => 'Lastname'),
    ));
    $this->render('index', array('dataProvider' => $dataProvider));
}

Widget 參數深度解析

在 View 中呼叫 Widget，關鍵參數說明：

• dataProvider：資料來源，必要參數。
• ajaxUpdate：設為 false 可關閉 AJAX 分頁/排序，改用傳統頁面跳轉，利於 SEO 與除錯。
• template：版面模板，支援 {summary}（摘要）、{sorter}（排序）、{items}（列表）、{pager}（分頁）四個佔位符，自由組合排序。
• itemView：單筆資料渲染的局部視圖檔名（如 '_view' 對應 _view.php）。
• sortableAttributes：可排序欄位陣列，僅列出的欄位才會出現排序連結。
• pager：分頁器配置，如 maxButtonCount 控制顯示頁碼數量。

撰寫靈活的項目視圖 (_view.php)

項目視圖接收 $data 變數（對應 Model 實例），可自由發揮 HTML 結構：

<div class="item">
    <h3><?php echo CHtml::encode($data->FirstName . ' ' . $data->LastName); ?></h3>
    <b><?php echo CHtml::encode($data->getAttributeLabel('Company')); ?>:</b>
    <?php echo CHtml::encode($data->Company); ?><br />
    <b><?php echo CHtml::encode($data->getAttributeLabel('Address')); ?>:</b>
    <?php echo Yii::app()->format->formatUrl($data->Address); ?><br />
    <b><?php echo CHtml::encode($data->getAttributeLabel('Country')); ?>:</b>
    <?php echo CHtml::encode($data->Country); ?><br />
    <b><?php echo CHtml::encode($data->getAttributeLabel('Email')); ?>:</b>
    <?php echo Yii::app()->format->formatEmail($data->Email); ?><br />
</div>

善用 CHtml::encode() 防止 XSS，並利用 Yii::app()->format 格式化輸出。

實際執行效果

透過 template 參數調整元件順序，配合自訂 CSS，即可打造符合專案需求的資料列表介面。