格式化輸出數(shù)據(jù)（Data Formatting）

數(shù)據(jù)格式器

Yii提供一個(gè)格式化類來格式化輸出，以使輸出數(shù)據(jù)對(duì)終端用戶更友好易讀， yii\i18n\Formatter 是一個(gè)助手類，作為?應(yīng)用組件?使用，默認(rèn)名為formatter。

它提供一些方法用來格式化數(shù)據(jù)，如日期/時(shí)間、數(shù)字或其他常用的本地化格式， 兩種方式使用格式器：

1. 直接使用格式化方法(所有的格式器方法以?as做前綴):

   echo Yii::$app->formatter->asDate('2014-01-01', 'long'); // 輸出: January 1, 2014
   echo Yii::$app->formatter->asPercent(0.125, 2); // 輸出: 12.50%
   echo Yii::$app->formatter->asEmail('cebe@example.com'); // 輸出: <a href="mailto:cebe@example.com">cebe@example.com</a>
   echo Yii::$app->formatter->asBoolean(true); // 輸出: Yes
   // 也可處理null值的輸出顯示:
   echo Yii::$app->formatter->asDate(null); // 輸出: (Not set)

2. 使用 yii\i18n\Formatter::format() 方法和格式化名， 該方法也被一些小部件如yii\grid\GridView 和 yii\widgets\DetailView使用，在小部件配置中可以指定列的數(shù)據(jù)格式。

   echo Yii::$app->formatter->format('2014-01-01', 'date'); // 輸出: January 1, 2014
   // 可使用數(shù)組來指定格式化方法的參數(shù)：
   // `2` 是asPercent()方法的參數(shù)$decimals的值
   echo Yii::$app->formatter->format(0.125, ['percent', 2]); // 輸出: 12.50%

當(dāng)PHP intl extension安裝時(shí)，格式器的輸出會(huì)本地化， 為此可配置格式器的 yii\i18n\Formatter::locale 屬性，如果沒有配置， 應(yīng)用配置 yii\base\Application::language 作為當(dāng)前區(qū)域，更多詳情參考?國(guó)際化一節(jié)。 然后格式器根據(jù)當(dāng)前區(qū)域?yàn)槿掌诤蛿?shù)字選擇正確的格式，包括月份和星期也會(huì)轉(zhuǎn)換到當(dāng)前語言， 日期格式也會(huì)被 yii\i18n\Formatter::timeZone 參數(shù)影響， 該參數(shù)如果沒有明確配置會(huì)使用應(yīng)用的 yii\base\Application::timeZone 參數(shù)。

日期格式根據(jù)不同區(qū)域輸出不同的結(jié)果，如下例所示： For example the date format call will output different results for different locales:

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庫(kù)不同，格式化結(jié)果可能不同， 所以為確保不同環(huán)境下得到相同的輸出，推薦在每個(gè)環(huán)境下安裝PHP intl擴(kuò)展以及相同的ICU庫(kù)， 可參考：?為國(guó)際化設(shè)置PHP環(huán)境.

配置格式器

可配置yii\i18n\Formatter的屬性來調(diào)整格式器方法的默認(rèn)格式， 可以在應(yīng)用主體配置?中配置?formatter?組件應(yīng)用到整個(gè)項(xiàng)目， 配置樣例如下所示， 更多關(guān)于可用屬性的詳情請(qǐng)參考 yii\i18n\Formatter 和接下來一小節(jié)。

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

格式化日期和時(shí)間

格式器類為格式化日期和時(shí)間提供了多個(gè)方法： The formatter class provides different methods for formatting date and time values. These are:

• yii\i18n\Formatter::asDate() - 值被格式化成日期，如?January, 01 2014.
• yii\i18n\Formatter::asTime() - 值被格式化成時(shí)間，如?14:23.
• yii\i18n\Formatter::asDatetime() - 值被格式化成日期和時(shí)間，如?January, 01 2014 14:23.
• yii\i18n\Formatter::asTimestamp() - 值被格式化成?unix 時(shí)間戳?如?1412609982.
• yii\i18n\Formatter::asRelativeTime() - 值被格式化成和當(dāng)前時(shí)間比較的時(shí)間間隔并用人們易讀的格式，如1 hour ago.

可配置格式器的屬性yii\i18n\Formatter::$dateFormat, yii\i18n\Formatter::$timeFormat 和yii\i18n\Formatter::$datetimeFormat來全局指定yii\i18n\Formatter::asDate(), yii\i18n\Formatter::asTime() 和 yii\i18n\Formatter::asDatetime() 方法的日期和時(shí)間格式。

格式器默認(rèn)會(huì)使用一個(gè)快捷格式，它根據(jù)當(dāng)前啟用的區(qū)域來解析， 這樣日期和時(shí)間會(huì)格式化成用戶國(guó)家和語言通用的格式， 有四種不同的快捷格式：

• en_GB區(qū)域的?short?會(huì)打印日期為?06/10/2014，時(shí)間為?15:58
• medium?會(huì)分別打印?6 Oct 2014?和?15:58:42,
• long?會(huì)分別打印?6 October 2014?和?15:58:42 GMT,
• full?會(huì)分別打印?Monday, 6 October 2014?和?15:58:42 GMT.

另外你可使用ICU 項(xiàng)目?定義的語法來自定義格式， ICU項(xiàng)目在該URL：http://userguide.icu-project.org/formatparse/datetime下的手冊(cè)有介紹， 或者可使用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

時(shí)區(qū)

當(dāng)格式化日期和時(shí)間時(shí)，Yii會(huì)將它們轉(zhuǎn)換為對(duì)應(yīng)的 yii\i18n\Formatter::timeZone 時(shí)區(qū)， 輸入的值在沒有指定時(shí)區(qū)時(shí)候會(huì)被當(dāng)作UTC時(shí)間，因此，推薦存儲(chǔ)所有的日期和時(shí)間為UTC而不是UNIX時(shí)間戳，UNIX通常也是UTC。 如果輸入值所在的時(shí)區(qū)不同于UTC，時(shí)區(qū)應(yīng)明確指定，如下所示：

// 假定 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

注意：時(shí)區(qū)從屬于全世界各國(guó)政府定的規(guī)則，可能會(huì)頻繁的變更，因此你的系統(tǒng)的時(shí)區(qū)數(shù)據(jù)庫(kù)可能不是最新的信息， 可參考?ICU manual?關(guān)于更新時(shí)區(qū)數(shù)據(jù)庫(kù)的詳情， 也可參考：為國(guó)際化設(shè)置PHP環(huán)境.

格式化數(shù)字

格式器類提供如下方法格式化數(shù)值： For formatting numeric values the formatter class provides the following methods:

• yii\i18n\Formatter::asInteger() - 值被格式化成整型，如?42.
• yii\i18n\Formatter::asDecimal() - 值被格式化成十進(jìn)制數(shù)字并帶有小數(shù)位和千分位，如?42.123.
• yii\i18n\Formatter::asPercent() - 值被格式化成百分率，如?42%.
• yii\i18n\Formatter::asScientific() - 值被格式化成科學(xué)計(jì)數(shù)型，如4.2E4.
• yii\i18n\Formatter::asCurrency() - 值被格式化成貨幣格式，如?￡420.00.
• yii\i18n\Formatter::asSize() - 字節(jié)值被格式化成易讀的值，如?410 kibibytes.

可配置yii\i18n\Formatter::decimalSeparator 和 yii\i18n\Formatter::thousandSeparator 屬性來調(diào)整數(shù)字格式化的格式，默認(rèn)和當(dāng)前區(qū)域相同。

更多高級(jí)配置， yii\i18n\Formatter::numberFormatterOptions 和 yii\i18n\Formatter::numberFormatterTextOptions 可用于配置內(nèi)部使用Numberformatter class

為調(diào)整數(shù)字的小數(shù)部分的最大值和最小值，可配置如下屬性：

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

其他格式器

除了日期、時(shí)間和數(shù)字格式化外，Yii提供其他用途提供一些實(shí)用的格式器： Additional to date, time and number formatting, Yii provides a set of other useful formatters for different purposes:

• yii\i18n\Formatter::asRaw() - 輸出值和原始值一樣，除了null值會(huì)用nullDisplay格式化，這是一個(gè)偽格式器；
• yii\i18n\Formatter::asText() - 值會(huì)經(jīng)過HTML編碼； 這是GridView DataColumn默認(rèn)使用的格式；
• yii\i18n\Formatter::asNtext() - 值會(huì)格式化成HTML編碼的純文本，新行會(huì)轉(zhuǎn)換成換行符；
• yii\i18n\Formatter::asParagraphs() - 值會(huì)轉(zhuǎn)換成HTML編碼的文本段落，用<p>標(biāo)簽包裹；
• yii\i18n\Formatter::asHtml() - 值會(huì)被HtmlPurifier過濾來避免XSS跨域攻擊，可傳遞附加選項(xiàng)如`['html', ['Attr.AllowedFrameTargets' => ['_blank']]]；
• yii\i18n\Formatter::asEmail() - 值會(huì)格式化成?mailto-鏈接；
• yii\i18n\Formatter::asImage() - 值會(huì)格式化成圖片標(biāo)簽；
• yii\i18n\Formatter::asUrl() - 值會(huì)格式化成超鏈接；
• yii\i18n\Formatter::asBoolean() - 值會(huì)格式化成布爾型值，默認(rèn)情況下?true?對(duì)應(yīng)?Yes，false?對(duì)應(yīng)?No， 可根據(jù)應(yīng)用語言配置進(jìn)行翻譯，可以配置yii\i18n\Formatter::booleanFormat-屬性來調(diào)整；

null-值

對(duì)于PHP的null值，格式器類會(huì)打印一個(gè)占位符而不是空字符串，空字符串默認(rèn)會(huì)顯示對(duì)應(yīng)當(dāng)前語言(not set), 可配置yii\i18n\Formatter::nullDisplay-屬性配置一個(gè)自定義占位符， 如果對(duì)處理null值沒有特殊要求，可設(shè)置yii\i18n\Formatter::nullDisplay 為?null.