README

日期控制 模块允许在 Yii Framework 2.0 中分别控制视图和模型的日期格式。因此，它允许以不同的方式显示日期（格式/时区）并保存到数据库中（格式/时区）。

注意：版本 1.5.0 有 BC 兼容性破坏性更改。此版本现在添加了对 ICU 和 PHP 日期格式模式的支持。默认情况下，格式将解析为 ICU 日期模式。要传递 PHP 日期格式，请将格式模式前缀为字符串 php:。

为什么需要日期控制？

已发布版本 1.9.2。有关详细信息，请参阅 更改日志。

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

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

大多数现有的 Yii 解决方案试图通过在 model->afterFind 中设置格式，然后在视图中呈现，并在 model->setAttribues 或 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。

演示

您可以在扩展中查看详细的 文档和用法 以及 演示。

安装

安装此扩展的首选方法是使用 composer。

注意：请检查此扩展的 composer.json 以了解其要求和依赖关系。阅读有关为您的应用程序的composer.json设置 minimum-stability 设置的此 web提示/wiki。

运行以下命令之一：

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

或

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

将其添加到您的 composer.json 文件的 require 部分中。

使用

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

许可证

yii2-datecontrol 在BSD 3-Clause许可证下发布。有关详细信息，请参阅捆绑的 LICENSE.md 文件。