README

yii2-datecontrol      

新版本，无需guessdate。当日期格式不符合要求时，输入字段不会更新。《日期控制》模块允许单独为Yii Framework 2.0的视图和模型控制日期格式。因此，它允许以一种方式（格式/时区）显示给用户，以另一种方式（格式/时区）保存到数据库。

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

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

为什么需要日期控制？

在与优秀的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，对于基本日期格式（无时区）。因此，扩展现在可以轻松地在客户端和服务器之间以 ONE 格式（PHP DateTime）一致地读取日期和时间戳。但是，如果您需要与 PHP DateTime 函数（如时区支持）的无缝集成，则建议使用 ajaxConversion。

演示

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

安装

安装此扩展的最佳方式是通过 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。