[Yii2笔记]058数据格式化(Data Formatting) [ 技术分享 ]

说明

学习Yii Framework 2（易2框架）的过程是漫长的，也是充满乐趣的，以下是我学习Yii2框架时对官网英文资料(请参见原文网址)的翻译和代码实现，提供了较完整的代码，供你参考。不妥之处，请多多指正！

原文网址：

http://www.yiiframework.com/doc-2.0/guide-output-formatting.html

本文主题：数据格式化(Data Formatting)

要为用户显示多种可读的格式，你可以使用应用组件格式化器（formatter）格式化他们。默认情况下，格式化器由yii\i18n\Formatter实现，它提供了一组方法可以将数据处理成日期、时间、数字、货币或其他常用格式。你能以如下方式使用格式化器：

$formatter = \Yii::$app->formatter;
// output: January 1, 2014
echo $formatter->asDate('2014-01-01', 'long');
// output: 12.50%
echo $formatter->asPercent(0.125, 2);
// output: <a href="mailto:cebe@example.com">cebe@example.com</a>
echo $formatter->asEmail('cebe@example.com'); 
// output: Yes
echo $formatter->asBoolean(true); 
// 它也能处理显示null值
// output: (not set)
echo $formatter->asDate(null); 

如你所见，所有的方法都命名为asXyz()，Xyz代表一种支持的格式。另外，你也可以使用类方法 format()来格式化数据，它允许你使用特定的格式，此方法通常在yii\grid\GridView和yii\widgets\DetailView中使用。例如：

// output: January 1, 2014
echo Yii::$app->formatter->format('2014-01-01', 'date'); 
// 你可以使用一个数组来定义格式化方法的参数：
// `2`是$decimals参数调用asPercent()方法时的参数（保留两位小数）
// output: 12.50%
echo Yii::$app->formatter->format(0.125, ['percent', 2]); 

注意：格式化器组件是为显示到终端用户进行数据格式化而设计的。如果你想要将用户输入转为机器格式，或者仅是格式化一个日期为一个机器格式，格式化器显示不适用此种场景。要转换用户输入的日期和数值，你可以分别使用yii\validators\DateValidator和yii\validators\NumberValidator。如果仅是转换时间格式为机器格式，使用PHP的date()函数即可。

1、Configuring Formatter（配置格式化器）

你可能在应用配置中设置formattre组件来自定义格式化规则，例如：

return [
    'components' => [
        'formatter' => [
            'dateFormat' => 'dd.MM.yyyy',//日期格式：01.01.2014
            'decimalSeparator' => ',',//实数的小数点表示符：, 默认值：.
            'thousandSeparator' => ' ',//千位数分隔符： （空格），默认值：,
            'currencyCode' => 'EUR',//货币符号：EUR，默认值：¤（从PHP的intl扩展中读取到的本地化设置，此值应是操作系统中的设置）
       ],
    ],
];

关于可以配置的属性请参考yii\i18n\Formatter： http://www.yiiframework.com/doc-2.0/yii-i18n-formatter.html

D:\phpwork\news\controllers\SiteController.php

        echo "<br>".$formatter->format(0.125,['percent',1]);
        echo "<br>".$formatter->format('2014-01-01','date');
        echo "<br>".$formatter->format(15826533,'decimal');
        echo "<br>".$formatter->format(1679,'currency');

测试结果：

/*
12.5%
01.01.2014
15 826 533
¤1 679.00
*/

2、Formatting Date and Time Values（格式化日期和时间值）

对于日期和时间，格式化器支持以下输出格式： date：格式化为一个日期，如 January 01, 2014 time：格式化为一个时间，如 14:23 datetime：格式化为日期和时间，如 January 01, 2014 14:23 timestamp：格式化为一个unix时间戳，如 1412609982 relativeTime：将一个时间与当前时间比较的值格式化为一个可读形式，如 1 hour ago duration：将一个时间段格式化为可读形式，如 1 day, 2 minutes 通过配置dateFormat、timeFormat和datetimeFormat可以修改使用date、time、datetime方法时的默认日期和时间格式。 你可以使用ICU格式定义日期和时间格式，也可以通过php:前缀使用PHP date()格式以区别于ICU格式，例如：

echo Yii::$app->formatter->asDate('now','yyyy-MM-dd');
echo Yii::$app->formatter->asDate('now','php:Y-m-d');

测试结果：

/*
2017-05-18
2017-05-18
*/

当应用要支持多语言时，你需要为不同的本地化配置定义不同的日期和时间格式。为了简化此项任务，你可以使用快捷格式（如long、short）来替代，格式化器将转换快捷格式（format shortcut）到当前有效区域配置的对应格式。系统支持以下快捷格式（本例假定有效区域配置是en_GB）： short：将输出日期06/10/2014和时间15:58 medium：将输出6 Oct 2014和15:58:42 long：将输出6 October 2014和15:58:42 GMT full：将输出Monday, 6 October 2014和15:58:42 GMT

自2.0.7版本起，可以在不同的日历系统中格式化日期了。如何设置一个不同的日历，请参考格式化器的$calendar 属性的API文档： http://www.yiiframework.com/doc-2.0/yii-i18n-formatter.html#$calendar-detail

Time Zones（时区）

当格式化日期和时间值时，Yii将转换它们到目标时区。格式化的日期被假定是处于UTC，除非是显式给定一个时区或你已配置了yii\i18n\Formatter::$defualtTimeZone 。 在下例中，我们假设目标时区已设置为Europe/Berlin：

// 格式化一个UNIX时间戳为时间
echo Yii::$app->formatter->asTime(1412599260); // 14:41:00

// 格式化一个日期字符串(UTC)为时间
echo Yii::$app->formatter->asTime('2014-10-06 12:41:00'); // 14:41:00

// 格式化一个日期字符串(CEST)为时间
echo Yii::$app->formatter->asTime('2014-10-06 14:41:00 CEST'); // 14:41:00

注意：时区因全球各国政府规则的制约而经常变化，在系统中安装的时区数据库中你可能没有最新的时区信息。你可以参考ICU手册来查看更新时区数据库的详情： http://userguide.icu-project.org/datetime/timezone#TOC-Updating-the-Time-Zone-Data 也请阅读Setting up your PHP environment for internationalization： http://www.yiiframework.com/doc-2.0/guide-tutorial-i18n.html#setup-environment

3、Formatting Numbers（格式化数字）

关于数字，格式化器支持以下输出格式： integer：格式为一个整数，如 42 decimal：格式化为一个实数，会添加千位分隔符，如 2,542.123 percent：格式化为一个百分数，如 42% scientific：格式化为一个科学计数法数字，如 4.2E4 currency：格式化为货币值，如 £420.00，注意：要使此函数工作正常，需要在本地化配置中添加国家设置，如en_GB或en_US，因为在此情况下语言会引发歧义。 size：字节数(bytes)格式化为可读形式，如：410 kibibytes shortSize，是size的短格式，如410 KiB

D:\phpwork\news\controllers\SiteController.php

    $formatter=Yii::$app->formatter;
    echo "<br>".$formatter->format(1679,'decimal');
    echo "<br>".$formatter->format(1679.158923,['decimal',2]);

测试结果：

http://localhost:8085/
/*
1,679
1,679.16
*/

数字的格式可以使用decimalSeparator和thousandSeparator进行调整，这两个属性的默认值是从当前的本地设置中来的。 关于更多的高级配置，yii\i18n\Formatter::$numberFormatterOptions 和yii\i18n\Formatter::$numberFormatterTextOptions 可以用来配置NumberFormatter class，此类用于内部实现格式化器。例如，要调整分数位的最大值和最小值，你可以配置yii\i18n\Formatter::$numberFormatterOptions 属性，代码如下：

'numberFormatterOptions' => [
    NumberFormatter::MIN_FRACTION_DIGITS => 0,
    NumberFormatter::MAX_FRACTION_DIGITS => 2,
]

4、Other Formats（其他格式）

除了日期/时间和数字格式外，Yii还支持其他常用格式，包括： raw：原样输出，这是一个伪格式化器，不会有任何效果，除了将null值格式化为nullDisplay。 text：格式化为HTML编码，这是GridView的DataColumn的默认格式。 ntext：格式化为HTML编码的纯文本，换行将转为换行符。 paragraphs：格式化为HTML编码的文本段落，使用

标签包含。 html：使用HtmlPurifier净化数据，以避免XSS攻击，你可以传递其他选项，如['html',['Attr.AllowedFrameTargets'=>['_blank']]] email：格式化为一个mailto链接 image：格式化为一个图片链接 url：格式化为一个超链接 boolean：格式化为一个布尔值。默认情况下，true被渲染为Yes，false为No，翻译为当前的应用语言。你可以配置yii\i18n\Formatter::$booleanFormat 属性来更改它。

D:\phpwork\news\controllers\SiteController.php

	echo "<br>".$formatter->format('<a href="">text\n Format</a>','text');
	echo "<br>".$formatter->format('<a href="">text\n Format</a>','ntext');
	echo "<br>".$formatter->format('<a href="">text\n Format</a>','paragraphs');

测试结果：

http://localhost:8085/
/*
<a href="">text\n Format</a>
<a href="">text\n Format</a>
<p><a href="">text\n Format</a></p>
*/

5、Null Values（空值）

null值是被指定格式化的。格式化器将null值转为一个预设的字符串（默认值是not set，与当前应用的语言相对应），而不是显示一个空字符串。你可以配置nullDisplay属性去自定义这个字符串。

6、Localizing Data Format（本地化数据格式）

如前所述，格式化器可以使用当前本地化配置去格式化一个值，这是与所在的国家/地区相适应的。例如，相同的日期可以被格式化为不同的本地化形式：

D:\phpwork\news\controllers\SiteController.php

Yii::$app->formatter->locale='en-US';
echo "<br>".Yii::$app->formatter->asDate('2014-01-01');

Yii::$app->formatter->locale='de-DE';
echo "<br>".Yii::$app->formatter->asDate('2014-01-01');

Yii::$app->formatter->locale='ru-RU';
echo "<br>".Yii::$app->formatter->asDate('2014-01-01');

Yii::$app->formatter->locale='zh-CN';
echo "<br>".Yii::$app->formatter->asDate('2014-01-01');

测试结果：

http://localhost:8085/
/*
Jan 1, 2014
01.01.2014
1 янв. 2014 г.
2014年1月1日
*/

默认情况下，当前本土设置由yii\base\Application::$language 决定，你也可以显式设置yii\i18n\Formatter::$locale 属性来覆盖它。

注意：Yii格式化器依赖于PHP intl扩展来提供本地数据格式。因为PHP编译时使用不同的ICU库版本，所以格式化结果也可能不同，推荐在你所有的环境中都使用相同的ICU版本。查看更多细节，请参考Setting up your PHP environment for internationalization： http://www.yiiframework.com/doc-2.0/guide-tutorial-i18n.html#setup-environment

如果没有安装intl扩展，则数据不会被本地化。

注意：在32位系统中，尽管已安装了intl扩展，但早于1901年和晚于2038年的日期值将不会被本地化。这是因为在此种情况下ICU使用的是32位的UNIX时间戳表示日期值。

（全文完）