README

Yii2 widget for vanillajs-datepicker - A lightweight, dependency-free date picker.

安装

通过 Composer 安装：

composer require jzkf/yii2-vanillajs-datepicker

使用方法

在 ActiveForm 中使用

use jzkf\vanillajsdatepicker\widgets\DatePicker;

<?= $form->field($model, 'date_field')->widget(DatePicker::class, [
    'options' => [
        'class' => 'form-control',
    ],
    'clientOptions' => [
        'format' => 'yyyy-mm-dd',
        'autohide' => true,
    ],
]) ?>

独立使用

use jzkf\vanillajsdatepicker\widgets\DatePicker;

<?= DatePicker::widget([
    'name' => 'date',
    'value' => date('Y-m-d'),
    'options' => [
        'class' => 'form-control',
        'id' => 'date-input',
    ],
    'clientOptions' => [
        'format' => 'yyyy-mm-dd',
        'autohide' => true,
    ],
]) ?>

使用 PHP 日期格式

<?= DatePicker::widget([
    'model' => $model,
    'attribute' => 'date_field',
    'dateFormat' => 'Y-m-d',  // 自动转换为 'yyyy-mm-dd'
]) ?>

设置语言

<?= DatePicker::widget([
    'model' => $model,
    'attribute' => 'date_field',
    'language' => 'zh-CN',  // 自动加载中文语言包
]) ?>

配置选项

Widget 选项

选项	类型	默认值	说明
`model`	\yii\base\Model	null	模型对象（用于 ActiveForm）
`attribute`	string	null	属性名称（用于 ActiveForm）
`name`	string	null	输入框 name 属性
`value`	string	null	输入框当前值
`options`	array	[]	HTML 输入框选项
`clientOptions`	array	[]	DatePicker 客户端配置选项
`registerAssets`	bool	true	是否自动注册资源文件
`dateFormat`	string	null	PHP 日期格式（如 'Y-m-d'）
`language`	string	null	语言代码（如 'zh-CN', 'en'）

DatePicker 客户端选项

常用的 clientOptions 配置：

'clientOptions' => [
    'format' => 'yyyy-mm-dd',      // 日期格式
    'autohide' => true,            // 选择日期后自动隐藏
    'todayHighlight' => true,      // 高亮今天
    'clearBtn' => true,            // 显示清除按钮
    'todayBtn' => true,            // 显示今天按钮
    'orientation' => 'bottom',     // 弹出方向：'top', 'bottom', 'left', 'right'
    'language' => 'zh-CN',         // 语言
    'weekStart' => 1,              // 一周开始日：0=周日, 1=周一
    'minDate' => '2024-01-01',     // 最小日期
    'maxDate' => '2024-12-31',     // 最大日期
    'datesDisabled' => ['2024-12-25'], // 禁用的日期
]

更多选项请参考 vanillajs-datepicker 官方文档。

事件

Widget 会在初始化时触发 datepicker:init 事件，可以通过 JavaScript 监听：

$('#date-input').on('datepicker:init', function(e, datepicker) {
    console.log('DatePicker initialized', datepicker);
    
    // 可以在这里添加自定义事件监听
    datepicker.element.addEventListener('changeDate', function(e) {
        console.log('Date selected:', e.detail.date);
    });
});

资源文件

默认使用 CDN 加载 vanillajs-datepicker 资源文件。如果需要使用本地文件或 npm 安装的版本，可以修改 DatePickerAsset 类：

// 使用 npm 安装的版本
public $sourcePath = '@npm/vanillajs-datepicker/dist';
public $css = ['css/datepicker.min.css'];
public $js = ['js/datepicker.min.js'];

许可证

BSD-3-Clause

jzkf / yii2-vanillajs-datepicker

Maintainers

Details