数据格式化 ¶

为了以更易读的格式向用户显示数据，可以使用 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:[email protected]">[email protected]</a>
echo $formatter->asEmail('[email protected]'); 

// output: Yes
echo $formatter->asBoolean(true); 
// it also handles display of null values:

// 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'); 

// you can also use an array to specify parameters for the format method:
// `2` is the value for the $decimals parameter of the asPercent()-method.
// output: 12.50%
echo Yii::$app->formatter->format(0.125, ['percent', 2]); 

注意：格式化器组件旨在将值格式化为供最终用户显示。如果您想将用户输入转换为机器可读格式，或者只是以机器可读格式格式化日期，那么格式化器不是合适的工具。要转换日期和数字值的输入，可以使用 yii\validators\DateValidator 和 yii\validators\NumberValidator。对于机器可读日期和时间格式之间的简单转换，PHP 的 date() 函数就足够了。

配置格式化器 ¶

可以通过在 应用程序配置 中配置 formatter 组件来自定义格式化规则。例如：

return [
    'components' => [
        'formatter' => [
            'dateFormat' => 'dd.MM.yyyy',
            'decimalSeparator' => ',',
            'thousandSeparator' => ' ',
            'currencyCode' => 'EUR',
       ],
    ],
];

请参考 yii\i18n\Formatter 来了解可以配置的属性。

格式化日期和时间值 ¶

格式化器支持以下与日期和时间相关的输出格式

• 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。

用于 date、time 和 datetime 方法的默认日期和时间格式可以通过配置全局来定制
dateFormat、timeFormat 和 datetimeFormat。

您可以使用 ICU 语法 指定日期和时间格式。您还可以使用 PHP date() 语法，并在前面加上 php: 前缀以将其与 ICU 语法区分开来。例如，

// ICU format
echo Yii::$app->formatter->asDate('now', 'yyyy-MM-dd'); // 2014-10-06

// PHP date()-format
echo Yii::$app->formatter->asDate('now', 'php:Y-m-d'); // 2014-10-06

信息：PHP 格式语法的某些字母不受 ICU 支持，因此 PHP intl 扩展也不能在 Yii 格式化器中使用。其中大多数（w、t、L、B、u、I、Z）对格式化日期实际上没有用，而是在进行日期计算时使用。但是，S 和 U 可能有用。可以通过以下方法实现它们的行为

• 对于 S，它是月份日期的英文序数后缀（例如，st、nd、rd 或 th），可以使用以下替换

  $f = Yii::$app->formatter;
  $d = $f->asOrdinal($f->asDate('2017-05-15', 'php:j'));
  echo "On the $d day of the month.";  // prints "On the 15th day of the month."
  

• 对于 U，Unix 时间戳，您可以使用 时间戳 格式。

在处理需要支持多种语言的应用程序时，您经常需要为不同的区域设置指定不同的日期和时间格式。为了简化此任务，您可以改用格式快捷方式（例如，long、short）。格式化器将根据当前活动的 区域设置 将格式快捷方式转换为适当的格式。支持以下格式快捷方式（示例假定 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 版本开始，还可以使用不同的日历系统格式化日期。请参阅格式化器的 API 文档 $calendar 属性，了解如何设置不同的日历。

时区 ¶

在格式化日期和时间值时，Yii 将将其转换为目标 时区。除非显式给出时区，或者您已配置 yii\i18n\Formatter::$defaultTimeZone，否则假定要格式化的值为 UTC。

在以下示例中，我们假设目标 时区 设置为 Europe/Berlin。

// formatting a UNIX timestamp as a time
echo Yii::$app->formatter->asTime(1412599260); // 14:41:00

// formatting a datetime string (in UTC) as a time 
echo Yii::$app->formatter->asTime('2014-10-06 12:41:00'); // 14:41:00

// formatting a datetime string (in CEST) as a time
echo Yii::$app->formatter->asTime('2014-10-06 14:41:00 CEST'); // 14:41:00

如果未在格式化器组件上显式设置 时区，则使用 应用程序中配置的时区，该时区与 PHP 配置中设置的时区相同。

注意：由于时区受世界各地政府制定的规则约束，并且可能经常更改，因此您很可能没有在系统上安装最新的时区数据库信息。您可以参考 ICU 手册，了解有关更新时区数据库的详细信息。请还阅读 为国际化设置 PHP 环境。

格式化数字 ¶

格式化器支持以下与数字相关的输出格式

• integer：该值被格式化为整数，例如 42。
• decimal：该值被格式化为十进制数，考虑十进制和千位分隔符，例如 2,542.123 或 2.542,123。
• percent：该值被格式化为百分比数字，例如 42%。
• scientific：该值被格式化为科学记数法，例如 4.2E4。
• currency：该值被格式化为货币值，例如 £420.00。请注意，为了使此函数正常工作，区域设置需要包含一个国家/地区部分，例如 en_GB 或 en_US，因为在这种情况下仅语言将是模棱两可的。
• size：表示字节数的值被格式化为人类可读的大小，例如 410 kibibytes。
• shortSize：是 size 的简短版本，例如 410 KiB。

可以使用 decimalSeparator 和 thousandSeparator 调整数字格式的格式，这两个参数都根据活动 区域设置 获取默认值。

对于更高级的配置，可以使用 yii\i18n\Formatter::$numberFormatterOptions 和 yii\i18n\Formatter::$numberFormatterTextOptions 配置内部使用的 NumberFormatter 类 来实现格式化器。例如，要调整小数位数的最大值和最小值，可以按如下方式配置 yii\i18n\Formatter::$numberFormatterOptions 属性

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

其他格式 ¶

除了日期/时间和数字格式外，Yii 还支持其他常用的格式，包括

• raw：该值按原样输出，这是一个伪格式化器，除了 null 值将使用 nullDisplay 进行格式化外，它没有任何效果。
• text：该值经过 HTML 编码。这是 GridView DataColumn 使用的默认格式。
• ntext：该值被格式化为 HTML 编码的纯文本，其中换行符转换为换行符。
• paragraphs：该值被格式化为 HTML 编码的文本段落，并包装在 <p> 标签中。
• html：该值使用 HtmlPurifier 进行净化，以避免 XSS 攻击。您可以传递其他选项，例如 ['html', ['Attr.AllowedFrameTargets' => ['_blank']]]。
• email：该值被格式化为 mailto 链接。
• image：该值被格式化为图像标签。
• url：该值被格式化为超链接。
• boolean：该值被格式化为布尔值。默认情况下，true 呈现为 Yes，false 呈现为 No，并翻译为当前应用程序语言。您可以通过配置 yii\i18n\Formatter::$booleanFormat 属性来调整它。

空值 ¶

空值是特殊格式的。格式化器不会显示空字符串，而是将其转换为预设字符串，默认值为 (not set)，并翻译为当前应用程序语言。您可以配置 nullDisplay 属性来自定义此字符串。

本地化数据格式 ¶

如前所述，格式化器可能会使用当前活动的 区域设置 来确定如何格式化适合目标国家/地区的值。例如，相同的日期值可能在不同的区域设置中以不同的方式格式化

Yii::$app->formatter->locale = 'en-US';
echo Yii::$app->formatter->asDate('2014-01-01'); // output: January 1, 2014

Yii::$app->formatter->locale = 'de-DE';
echo Yii::$app->formatter->asDate('2014-01-01'); // output: 1. Januar 2014

Yii::$app->formatter->locale = 'ru-RU';
echo Yii::$app->formatter->asDate('2014-01-01'); // output: 1 января 2014 г.

默认情况下，当前活动的 区域设置 由 yii\base\Application::$language 的值确定。您可以通过显式设置 yii\i18n\Formatter::$locale 属性来覆盖它。

注意：Yii 格式化器依赖于 PHP intl 扩展 来支持本地化数据格式。由于使用 PHP 编译的 ICU 库的不同版本可能会导致不同的格式结果，因此建议您在所有环境中使用相同的 ICU 版本。有关更多详细信息，请参阅 为国际化设置 PHP 环境。

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

请注意，对于在 1901 年之前或 2038 年之后的日期值，即使安装了 intl 扩展，它们也不会在 32 位系统上被本地化。这是因为在这种情况下，ICU 使用 32 位 UNIX 时间戳来表示日期值。