Yii2 DropDownList 下拉選單完整用法指南：ActiveForm、Html 類、預設值、資料來源、樣式客製化

Yii2 提供兩種產生下拉選單的方式：ActiveForm::field()->dropDownList() (整合驗證、樣式) 與 Html::activeDropDownList() (輕量、完全控制屬性)。本文系統整理資料來源準備、基本用法、預設提示、模型綁定、Html 類替代方案、多維陣列分組、常見問題與最佳實踐。

資料來源準備：ArrayHelper::map()

use yii\helpers\ArrayHelper;
use app\models\Country;

$countries = Country::find()->all(); // 或 asArray()->all()
$listData = ArrayHelper::map($countries, 'code', 'name'); // [ 'TW' => '台灣', 'US' => '美國' ]

• 第一參數：資料陣列 (ActiveRecord 或 關聯陣列)
• 第二參數：value 欄位 (對應 option value)
• 第三參數：label 欄位 (對應顯示文字)
• 第四參數 (可選)：分組欄位，產生 <optgroup>

方式一：ActiveForm::field()->dropDownList() (推薦)

use yii\widgets\ActiveForm;
use yii\helpers\Html;

$form = ActiveForm::begin();

// 基本用法
echo $form->field($model, 'country_code')->dropDownList($listData);

// 帶預設提示
echo $form->field($model, 'country_code')->dropDownList($listData, [
    'prompt' => '請選擇國家', // 產生 請選擇國家
    'class' => 'form-control',
    'id' => 'country-select'
]);

// 多維分組 (optgroup)
$grouped = ArrayHelper::map($countries, 'continent', 'code', 'name');
// $grouped = ['Asia' => ['TW'=>'台灣', 'JP'=>'日本'], 'America' => ['US'=>'美國']]
echo $form->field($model, 'country_code')->dropDownList($grouped, ['prompt' => '請選擇']);

ActiveForm::end();

優點

• 自動綁定模型屬性、驗證錯誤訊息顯示
• 自動產生 id、name 屬性符合 Yii 命名規則
• 整合 Bootstrap 樣式 (預設 form-control)
• 支援 enableAjaxValidation、enableClientValidation

方式二：Html::activeDropDownList() (完全控制)

use yii\helpers\Html;

echo Html::activeDropDownList($model, 'country_code', $listData, [
    'prompt' => '請選擇國家',
    'class' => 'custom-select',
    'style' => 'width: 200px;',
    'data-api' => '/country/info',
    'onchange' => 'loadInfo(this.value)'
]);

// 無模型綁定的純下拉選單
echo Html::dropDownList('country', null, $listData, [
    'prompt' => '請選擇',
    'class' => 'form-control'
]);

適用場景

• 非 ActiveForm 環境 (如局部 AJAX 回傳片段)
• 需大量自訂 HTML 屬性 (data-*, on* 事件)
• 效能極度敏感頁面 (避免 ActiveForm 物件建立開銷)

預設值設定完整對照

控制器完整範例

public function actionCreate() {
    $model = new UserForm();
    $model->country_code = 'TW'; // 預設值
    
    $countries = Country::find()->asArray()->all();
    $listData = ArrayHelper::map($countries, 'code', 'name');
    
    if ($model->load(Yii::$app->request->post()) && $model->validate()) {
        // 儲存邏輯
    }
    return $this->render('create', [
        'model' => $model,
        'listData' => $listData,
    ]);
}

視圖完整範例

<?php
use yii\widgets\ActiveForm;
use yii\helpers\Html;
$form = ActiveForm::begin();
?>

<?= $form->field($model, 'username')->textInput() ?>

<?= $form->field($model, 'country_code')->dropDownList($listData, [
    'prompt' => '請選擇國家',
    'class' => 'form-control'
]) ?>

<?= Html::submitButton('送出', ['class' => 'btn btn-primary']) ?>

<?php ActiveForm::end(); ?>

常見問題排查

• ❌ 下拉選單空白 → $listData 為空、鍵名錯誤 (如用 'id' 但模型存 'code')
• ❌ 預設值不生效 → 模型屬性名與 field() 第二參數不符、$listData 鍵值型別不符 (字串 vs 整數)
• ❌ 驗證失敗不顯示錯誤 → 模型 rules() 缺少該欄位規則、ActiveForm 未正確 begin()/end()
• ❌ 分組不顯示 → ArrayHelper::map 第四參數欄位名錯誤、資料未正確分組

最佳實踐總結

1. 優先使用 ActiveForm::field()->dropDownList()，享受框架整合優勢。
2. 資料來源統一用 ArrayHelper::map() 轉換，保持控制器/視圖分離。
3. 預設提示務必加 'prompt' => '請選擇...'，提升 UX 並利驗證。
4. 大量選項 (>50) 改用 Select2/Choices.js 搜尋式下拉，原生 select 體驗差。
5. 選項文字務必 Html::encode() (ArrayHelper::map 自動處理 ActiveRecord 屬性)，防 XSS。

相關專題：《Yii 框架入門及常用技巧總結》、《PHP 優秀開發框架總結》。