格式化输出数据(Data Formatting)
数据格式器
Yii提供一个格式化类来格式化输出,以使输出数据对终端用户更友好易读, yii\i18n\Formatter 是一个助手类,作为 应用组件 使用,默认名为formatter
。
它提供一些方法用来格式化数据,如日期/时间、数字或其他常用的本地化格式, 两种方式使用格式器:
1. 直接使用格式化方法(所有的格式器方法都使用as
作为前缀):
当PHP intl extension安装时,格式器的输出会本地化, 为此可配置格式器的 yii\i18n\Formatter::locale 属性,如果没有配置, 应用配置 yii\base\Application::language 作为当前区域,更多详情参考 国际化一节。 然后格式器根据当前区域为日期和数字选择正确的格式,包括月份和星期也会转换到当前语言, 日期格式也会被 yii\i18n\Formatter::timeZone 参数影响, 该参数如果没有明确配置会使用应用的 yii\base\Application::timeZone 参数。
日期格式根据不同区域输出不同的结果,如下例所示:
Yii::$app->formatter->locale = 'en-US';
echo Yii::$app->formatter->asDate('2014-01-01' // 输出: January 1, 2014
Yii::$app->formatter->locale = 'de-DE';
echo Yii::$app->formatter->asDate('2014-01-01' // 输出: 1\. Januar 2014
Yii::$app->formatter->locale = 'ru-RU';
echo Yii::$app->formatter->asDate('2014-01-01' // 输出: 1 января 2014 г.
注意不管PHP intl extension有没有安装,PHP编译的ICU库不同,格式化结果可能不同, 所以为确保不同环境下得到相同的输出,推荐在每个环境下安装PHP intl扩展以及相同的ICU库, 可参考: 为国际化设置PHP环境。
配置格式器
可配置yii\i18n\Formatter的属性来调整格式器方法的默认格式, 可以在应用主体配置 中配置 formatter
组件应用到整个项目, 配置样例如下所示, 更多关于可用属性的详情请参考 yii\i18n\Formatter 和接下来一小节。
'components' => [
'formatter' => [
'dateFormat' => 'dd.MM.yyyy',
'decimalSeparator' => ',',
'thousandSeparator' => ' ',
'currencyCode' => 'EUR',
],
],
格式化日期和时间
格式器类为格式化日期和时间提供了多个方法: The formatter class provides different methods for formatting date and time values. These are:
- yii\i18n\Formatter::asDate() - 值被格式化成日期,如
January, 01 2014
.
可配置格式器的属性yii\i18n\Formatter::$dateFormat, yii\i18n\Formatter::$timeFormat 和yii\i18n\Formatter::$datetimeFormat来全局指定yii\i18n\Formatter::asDate(), yii\i18n\Formatter::asTime() 和 yii\i18n\Formatter::asDatetime() 方法的日期和时间格式。
格式器默认会使用一个快捷格式,它根据当前启用的区域来解析, 这样日期和时间会格式化成用户国家和语言通用的格式, 有四种不同的快捷格式:
en_GB
区域的short
会打印日期为06/10/2014
,时间为15:58
另外你可使用ICU 项目 定义的语法来自定义格式, ICU项目在该URL:http://userguide.icu-project.org/formatparse/datetime下的手册有介绍, 或者可使用PHP date() 方法的语法字符串并加上前缀php:
.
// ICU 格式化
echo Yii::$app->formatter->asDate('now', 'yyyy-MM-dd' // 2014-10-06
// PHP date()-格式化
echo Yii::$app->formatter->asDate('now', 'php:Y-m-d' // 2014-10-06
时区
当格式化日期和时间时,Yii会将它们转换为对应的 yii\i18n\Formatter::timeZone 时区, 输入的值在没有指定时区时候会被当作UTC时间,因此,推荐存储所有的日期和时间为UTC而不是UNIX时间戳,UNIX通常也是UTC。 如果输入值所在的时区不同于UTC,时区应明确指定,如下所示:
// 假定 Yii::$app->timeZone = 'Europe/Berlin';
echo Yii::$app->formatter->asTime(1412599260 // 14:41:00
echo Yii::$app->formatter->asTime('2014-10-06 12:41:00' // 14:41:00
echo Yii::$app->formatter->asTime('2014-10-06 14:41:00 CEST' // 14:41:00
注意:时区从属于全世界各国政府定的规则,可能会频繁的变更,因此你的系统的时区数据库可能不是最新的信息, 可参考 ICU manual 关于更新时区数据库的详情, 也可参考:为国际化设置PHP环境.
格式化数字
格式器类提供如下方法格式化数值: For formatting numeric values the formatter class provides the following methods:
- yii\i18n\Formatter::asInteger() - 值被格式化成整型,如
42
.
可配置yii\i18n\Formatter::decimalSeparator 和 yii\i18n\Formatter::thousandSeparator 属性来调整数字格式化的格式,默认和当前区域相同。
更多高级配置, yii\i18n\Formatter::numberFormatterOptions 和 yii\i18n\Formatter::numberFormatterTextOptions 可用于配置内部使用Numberformatter class
为调整数字的小数部分的最大值和最小值,可配置如下属性:
[
NumberFormatter::MIN_FRACTION_DIGITS => 0,
NumberFormatter::MAX_FRACTION_DIGITS => 2,
]
其他格式器
除了日期、时间和数字格式化外,Yii提供其他用途提供一些实用的格式器: Additional to date, time and number formatting, Yii provides a set of other useful formatters for different purposes:
- yii\i18n\Formatter::asRaw() - 输出值和原始值一样,除了
null
值会用null
Display格式化,这是一个伪格式器;
null-值
对于PHP的null
值,格式器类会打印一个占位符而不是空字符串,空字符串默认会显示对应当前语言(not set)
, 可配置yii\i18n\Formatter::null
Display-属性配置一个自定义占位符, 如果对处理null
值没有特殊要求,可设置yii\i18n\Formatter::null
Display 为 null
.