README

yii2-datecontrol

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

请参考变更日志以了解各版本更改的详细信息。

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

为什么需要日期控制？

在使用伟大的 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 设置的 网络提示 /wiki。

运行以下命令之一：

$ 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.md 文件。