Yii2 接入 kartik-v 日期/時間選擇器組件：安裝配置、ActiveForm/獨立模式雙模用法、中文化與進階客製化

前言

Yii2 生態中最受歡迎的日期時間選擇器擴展非 kartik-v/yii2-widget-datetimepicker 與 kartik-v/yii2-widget-datepicker 莫屬。它們基於 Bootstrap DateTimePicker，支援 ActiveForm 雙向綁定、獨立 Widget 模式、多語言、多主題、範圍選擇、內聯模式等豐富特性。本文從 Composer 安裝到實戰落地，提供完整配置清單與避坑指南。

一、安裝擴展包

# 日期時間選擇器（含時間）
composer require kartik-v/yii2-widget-datetimepicker "@dev"

# 僅日期選擇器
composer require kartik-v/yii2-widget-datepicker "@dev"

# 若需中文語言包（已內置），無需額外安裝

注意： 使用 @dev 穩定性較好；正式項目可鎖定具體版本（如 ^1.4）。

二、應用配置：啟用中文語系

// config/main.php 或 main-local.php
return [
    'language' => 'zh-CN', // 關鍵：全局語言設為中文，組件自動讀取對應翻譯
    'components' => [
        // ...
    ],
];

三、ActiveForm 雙向綁定模式（推薦）

1. DateTimePicker（日期+時間）

use kartik\datetime\DateTimePicker;
use yii\widgets\ActiveForm;

$form = ActiveForm::begin();

echo $form->field($model, 'created_at')->widget(DateTimePicker::class, [
    'options' => [
        'placeholder' => '請選擇日期時間',
        'class' => 'form-control',
    ],
    'pluginOptions' => [
        'autoclose' => true,           // 選擇後自動關閉
        'todayHighlight' => true,      // 高亮今天
        'format' => 'yyyy-mm-dd hh:ii:ss', // 顯示格式
        'todayBtn' => true,            // 顯示「今天」按鈕
        'startView' => 2,              // 0=時,1=日,2=月,3=年,4=十年
        'minView' => 0,                // 最小視圖：0=時分
        'pickerPosition' => 'bottom-left',
        'language' => 'zh-CN',         // 顯式指定（可省略，繼承應用 language）
    ],
    // 'pluginEvents' => [              // 事件綁定示例
    //     'changeDate' => 'function(e) { console.log("日期變更:", e.date); }',
    // ],
]);

ActiveForm::end();

2. DatePicker（僅日期）

use kartik\date\DatePicker;

echo $form->field($model, 'birth_date')->widget(DatePicker::class, [
    'options' => ['placeholder' => '請選擇出生日期'],
    'pluginOptions' => [
        'autoclose' => true,
        'todayHighlight' => true,
        'format' => 'yyyy-mm-dd',
        'todayBtn' => 'linked', // linked: 點擊跳轉到今天月份
        'startView' => 2,
        'minView' => 2,          // 最小視圖：月
        'language' => 'zh-CN',
    ],
]);

四、獨立 Widget 模式（非 ActiveForm）

適用於前端頁面、AJAX 動態渲染、無模型綁定場景。

use kartik\datetime\DateTimePicker;

echo '發布時間';
echo DateTimePicker::widget([
    'name' => 'Article[created_at]', // 表單提交字段名
    'value' => $model->isNewRecord ? date('Y-m-d H:i:s') : $model->created_at, // 更新時必填
    'options' => [
        'placeholder' => '點擊選擇...',
        'id' => 'article-created-at',
    ],
    'pluginOptions' => [
        'autoclose' => true,
        'format' => 'yyyy-mm-dd hh:ii:ss',
        'todayHighlight' => true,
        'language' => 'zh-CN',
    ],
    // 客戶端事件
    'pluginEvents' => [
        'changeDate' => 'function(e) {
            $("#article-created-at-hidden").val(e.date.getTime() / 1000);
        }',
    ],
]);

五、進階客製化

1. 日期範圍選擇（開始/結束聯動）

// 視圖
echo DatePicker::widget([
    'name' => 'date_from',
    'value' => $dateFrom,
    'options' => ['id' => 'date-from'],
    'pluginOptions' => ['format' => 'yyyy-mm-dd', 'autoclose' => true],
    'pluginEvents' => [
        'changeDate' => 'function(e) {
            $("#date-to").data("datepicker").setStartDate(e.date);
        }',
    ],
]);

echo DatePicker::widget([
    'name' => 'date_to',
    'value' => $dateTo,
    'options' => ['id' => 'date-to'],
    'pluginOptions' => ['format' => 'yyyy-mm-dd', 'autoclose' => true],
    'pluginEvents' => [
        'changeDate' => 'function(e) {
            $("#date-from").data("datepicker").setEndDate(e.date);
        }',
    ],
]);

2. 內聯模式（嵌入頁面，不彈出）

echo DatePicker::widget([
    'name' => 'inline_date',
    'type' => DatePicker::TYPE_INLINE, // 關鍵
    'pluginOptions' => ['format' => 'yyyy-mm-dd'],
]);

3. 自定義模板與按鈕

echo DateTimePicker::widget([
    'name' => 'custom_dt',
    'template' => '{input}{button}', // 隱藏移除按鈕
    'buttonOptions' => ['class' => 'btn btn-outline-secondary', 'label' => ''],
    'pluginOptions' => ['format' => 'yyyy-mm-dd hh:ii'],
]);

4. 禁用特定日期（如節假日、過期日期）

'pluginOptions' => [
    'format' => 'yyyy-mm-dd',
    'autoclose' => true,
    'daysOfWeekDisabled' => [0, 6], // 禁用週末
    'datesDisabled' => ['2024-01-01', '2024-02-10'], // 禁用具體日期
    'startDate' => date('Y-m-d'), // 不可選今天之前
    'endDate' => '+1 year',       // 限制一年內
],

六、常見問題排查

七、資產包優化（生產環境）

預設會註冊 kartik\datetime\DateTimePickerAsset，包含 CSS/JS。若需合併壓縮，可配置 Asset Bundles 或使用 yii\web\AssetManager 的 bundles 映射到 CDN/本地壓縮版本。

總結

kartik-v 日期時間組件功能強大、API 穩定、中文支援完善。掌握「ActiveForm 雙向綁定、獨立 Widget、語言配置、範圍聯動、內聯模式、禁用日期」等核心用法，即可覆蓋 95% 以上的業務場景。建議在項目基礎組件庫中封裝統一的 DatePickerWidget / DateTimePickerWidget，統一主題、格式、語言、事件，實現「一行代碼接入，全站風格一致」。