README

yii2-datecontrol      

日期控制模块允许在Yii Framework 2.0中分别对视图和模型的数据进行日期格式的控制。这样就可以在用户界面中以一种方式（格式/时区）展示日期，而在数据库中以另一种方式（格式/时区）保存。

请参阅变更日志以获取关于各个版本变更的详细信息。

注意：版本1.9.5有向后不兼容的变更。现在有一个新的属性widgetOptions可用。当设置autoWidget或widgetClass时，这个属性将替换options属性。

为什么需要日期控制？

在使用伟大的Yii框架时，我观察到的一个最常见的问题是需要对日期设置进行适当的控制。每个Yii应用的日期设置都是独特的，适用于每个应用和地区。大多数Yii开发者或用户几乎总是需要一个选项来以一种特定的格式显示日期和时间，但以另一种格式保存到数据库中。因此，总结来说，问题是：

• 缺乏一种单一的配置方法以一个格式显示日期和时间给用户（或视图）
• 缺乏一种配置方法以另一个格式保存日期和时间到数据库（或模型）

大多数现有的Yii解决方案试图通过在model->afterFind中设置格式（在视图中存在），然后在model->setAttributes或model->beforeValidate中取消格式来解决这个问题。当应用中有许多模型和视图，以及开发周期中的变化需要复制到许多地方时（更复杂的场景是多地区格式），这仍然是一个问题。

本模块通过在表示层面解决这些问题来填补这一巨大差距。该模块允许您分别配置显示和保存的日期和时间设置。这可以在全局设置或在每个DateControl小部件级别单独设置。而且如果这还不够用，它还可以自动启用任何日期/时间选择器小部件与之结合使用。

这个神奇的实现方式是，扩展仅仅更改表示层（视图）。它自动将基本模型输入设置为隐藏，并显示一个镜像输入，该输入设置为已设置的显示格式。然后在每个显示输入的编辑中，扩展捕获更改事件，并根据所需的保存格式覆盖隐藏的基本模型输入。另一个好处是，扩展还会自动触发基本模型输入的javascript更改事件。因此，所有客户端模型验证和Picker小部件需要的其他jQuery事件都会自动触发。

注意：本模块中使用的所有日期和时间格式遵循一个标准——即PHP 日期时间格式字符串。扩展自动提供三个小部件来显示和控制日期时间输入。

• \kartik\widgets\DatePicker或\kartik\date\DatePicker如果您的格式类型是date
• \kartik\widgets\TimePicker或\kartik\time\TimePicker如果您的格式类型是time
• \kartik\widgets\DateTimePicker或\kartik\time\DateTimePicker如果您的格式类型是datetime

模块

该扩展已被创建为一个模块，以使您能够访问应用程序的全局设置。此外，它允许您使用PHP DateTime对象在客户端和服务器之间读取和格式化日期时间。DateControl小部件使用Ajax处理将显示（视图）格式转换为模型（保存）格式。

use kartik\datecontrol\Module;
'modules' => [
   'datecontrol' =>  [
        'class' => 'kartik\datecontrol\Module',
        
        // format settings for displaying each date attribute (ICU format example)
        'displaySettings' => [
            Module::FORMAT_DATE => 'dd-MM-yyyy',
            Module::FORMAT_TIME => 'HH:mm:ss a',
            Module::FORMAT_DATETIME => 'dd-MM-yyyy HH:mm:ss a', 
        ],
    
        // format settings for saving each date attribute (PHP format example)
        'saveSettings' => [
            Module::FORMAT_DATE => 'php:U', // saves as unix timestamp
            Module::FORMAT_TIME => 'php:H:i:s',
            Module::FORMAT_DATETIME => 'php:Y-m-d H:i:s',
        ],
    
        // set your display timezone
        'displayTimezone' => 'Asia/Kolkata',

        // set your timezone for date saved to db
        'saveTimezone' => 'UTC',
        
        // automatically use kartik\widgets for each of the above formats
        'autoWidget' => true,
        
        // use ajax conversion for processing dates from display format to save format.
        'ajaxConversion' => true,

        // default settings for each widget from kartik\widgets used when autoWidget is true
        'autoWidgetSettings' => [
            Module::FORMAT_DATE => ['type'=>2, 'pluginOptions'=>['autoclose'=>true]], // example
            Module::FORMAT_DATETIME => [], // setup if needed
            Module::FORMAT_TIME => [], // setup if needed
        ],
        
        // custom widget settings that will be used to render the date input instead of kartik\widgets,
        // this will be used when autoWidget is set to false at module or widget level.
        'widgetSettings' => [
            Module::FORMAT_DATE => [
                'class' => 'yii\jui\DatePicker', // example
                'options' => [
                    'dateFormat' => 'php:d-M-Y',
                    'options' => ['class'=>'form-control'],
                ]
            ]
        ]
        // other settings
    ]
];

参数配置

该扩展允许在Yii应用程序参数级别配置dateControlDisplay和dateControlSave设置。参数配置将覆盖模块级别的设置。当需要动态更改这些参数设置时，此配置非常有用。设置可以在DateControl小部件级别进行覆盖。

有关详细信息，请参阅默认规则文档。

DateControl

渲染您视图上每个日期控制的主要小部件。许多设置将默认来自模块设置，但可以在小部件级别进行覆盖。以下是一个使用ActiveForm和\kartik\widgets\DateTimePicker的用法示例。注意，您可以使用ICU或PHP支持的日期时间格式传递日期时间格式。要设置PHP日期时间格式，请将格式字符串以php:开头，如下所示。

echo $form->field($model, 'datetime_2')->widget(DateControl::classname(), [
    'displayFormat' => 'php:d-M-Y H:i:s',
    'type'=>DateControl::FORMAT_DATETIME
]);

注意：从版本v1.2.0开始，此扩展可以使用新的Krajee jQuery库php-date-formatter来执行客户端日期格式转换，而不是使用Ajax，对于基本的日期格式（无时区）。因此，扩展现在可以轻松地在客户端和服务器端以统一格式（PHP DateTime）读取日期和时间戳。然而，如果您需要与PHP DateTime函数（如时区支持）无缝集成，建议使用ajaxConversion。

演示

您可以查看扩展的详细文档和用法、详细演示和API代码文档。

安装

安装此扩展的最佳方式是通过composer。

注意：请检查此扩展的composer.json以了解此扩展的要求和依赖项。阅读此网络提示/维基以了解如何为应用程序的composer.json设置minimum-stability设置。

运行以下命令之一：

$ php composer.phar require kartik-v/yii2-datecontrol "@dev"

或将其添加到您的composer.json文件的require部分：

"kartik-v/yii2-datecontrol": "@dev"

到

用法

use kartik\datecontrol\Module;
use kartik\datecontrol\DateControl;

许可

yii2-datecontrol是在BSD 3-Clause License下发布的。有关详细信息，请参阅附带LICENSE.md。