Yii CActiveForm AJAX 驗證完整實作：前端開啟、後端攔截與錯誤回顯流程

前言

Yii CActiveForm 內建 AJAX 驗證機制，能在使用者輸入時即時回饋錯誤，無需重新整理頁面。本文詳細拆解視圖啟用、控制器攔截、模型規則三環節，並提供完整可執行程式碼。

視圖：啟用 AJAX 驗證

beginWidget('CActiveForm', array(
    'id' => 'zdzone-form',
    'enableAjaxValidation' => true,   // 關鍵：開啟 AJAX 驗證
    'enableClientValidation' => true, // 同時開啟客戶端 JS 驗證（雙重保險）
    'action' => '/manage/adzone/createAdzone',
    'htmlOptions' => array('enctype' => 'multipart/form-data'), // 檔案上傳需加此行
));
?>
    

        labelEx($model, 'name'); ?>
        textField($model, 'name', array('size' => 60, 'maxlength' => 256)); ?>
        error($model, 'name'); // 錯誤訊息容器 ?>
    

    

        isNewRecord ? '建立' : '更新'); ?>
    
endWidget(); ?>

控制器：攔截 AJAX 請求並回傳錯誤

public function actionCreateAdzone() {
    $model = new AdZone;

    // 1. 處理 AJAX 驗證請求（必須在載入 POST 資料之前）
    if (isset($_POST['ajax']) && $_POST['ajax'] === 'zdzone-form') {
        echo CActiveForm::validate($model);
        Yii::app()->end(); // 直接結束，不渲染視圖
    }

    // 2. 一般表單提交處理
    if (isset($_POST['AdZone'])) {
        $model->attributes = $_POST['AdZone'];
        if ($model->validate()) { // 伺服器端再次驗證
            if ($model->save()) {
                $this->redirect(array('view', 'id' => $model->id));
            }
        }
    }

    $this->render('create', array('model' => $model));
}

模型：定義驗證規則

class AdZone extends CActiveRecord {
    public function rules() {
        return array(
            array('name', 'required', 'message' => '廣告位名稱不得為空'),
            array('name', 'length', 'max' => 256),
            array('width, height', 'numerical', 'integerOnly' => true, 'min' => 1),
            array('code', 'match', 'pattern' => '/^[a-zA-Z0-9_]+$/', 'message' => '代碼僅限英數底線'),
            array('status', 'in', 'range' => array(0, 1)),
            array('id, name, width, height, code, status', 'safe', 'on' => 'search'),
        );
    }
}

完整流程時序圖

使用者輸入 name 欄位 → 焦點移出 (blur)
    ↓
jQuery.yii 發送 POST /manage/adzone/createAdzone
    參數：ajax=zdzone-form, AdZone[name]=xxx
    ↓
控制器 actionCreateAdzone()
    ↓
isset($_POST['ajax']) 為真
    ↓
CActiveForm::validate($model)
    ↓
執行 rules() 所有驗證器
    ↓
回傳 JSON：{"AdZone_name":["廣告位名稱不得為空"]}
    ↓
前端 jQuery 解析 JSON → 更新對應 error 容器顯示紅字
    ↓
使用者修正 → 再次觸發驗證 → 通過 → 錯誤訊息消失

關鍵細節與避坑指南

1. 表單 ID 唯一：id='zdzone-form' 必須與 $_POST['ajax'] 比對值完全一致。
2. 驗證順序：AJAX 驗證攔截必須在 isset($_POST['Model']) 之前，否則會進入一般儲存流程。
3. Yii::app()->end()：驗證回傳後必須終止執行，避免輸出多餘 HTML 破壞 JSON 格式。
4. 檔案上傳表單：需加 'htmlOptions'=>array('enctype'=>'multipart/form-data')，且 AJAX 驗證不支援檔案欄位（瀏覽器安全限制）。
5. 客戶端驗證：enableClientValidation=true 會依據 rules() 產生 JS 驗證碼，減少 AJAX 請求次數。
6. CSRF 保護：若啟用 enableCsrfValidation，AJAX 請求需攜帶 YII_CSRF_TOKEN（CActiveForm 自動處理）。

進階：自訂 AJAX 驗證回傳格式

if (isset($_POST['ajax']) && $_POST['ajax'] === 'zdzone-form') {
    $errors = CActiveForm::validate($model);
    if ($errors !== '[]') {
        // 統一錯誤格式
        echo CJSON::encode(array(
            'success' => false,
            'errors'  => CJSON::decode($errors),
        ));
    } else {
        echo CJSON::encode(array('success' => true));
    }
    Yii::app()->end();
}

相關專題推薦

• Yii 框架入門及常用技巧總結
• PHP 面向對象程序設計入門教程
• PHP 常見資料庫操作技巧匯總

CActiveForm AJAX 驗證的核心在於三步驟：視圖開啟 enableAjaxValidation、控制器攔截 $_POST['ajax']、模型定義 rules()。照著本文流程落地，即可為表單加上流暢的即時驗證體驗。