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

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

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

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

   echo Yii::$app->formatter->asDate('2014-01-01', 'long'); // 輸出: January 1, 2014echo Yii::$app->formatter->asPercent(0.125, 2); // 輸出: 12.50%echo Yii::$app->formatter->asEmail('cebe@example.com'); // 輸出: <a target="_blank" 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%

當PHP intl extension安裝時，格式器的輸出會本地化， 為此可配置格式器的 yii\i18n\Formatter::locale 屬性，如果沒有配置， 應(yīng)用配置 yii\base\Application::language 作為當前區(qū)域，更多詳情參考?國際化一節(jié)。 然后格式器根據(jù)當前區(qū)域為日期和數(shù)字選擇正確的格式，包括月份和星期也會轉(zhuǎn)換到當前語言， 日期格式也會被 yii\i18n\Formatter::timeZone 參數(shù)影響， 該參數(shù)如果沒有明確配置會使用應(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庫不同，格式化結(jié)果可能不同， 所以為確保不同環(huán)境下得到相同的輸出，推薦在每個環(huán)境下安裝PHP intl擴展以及相同的ICU庫， 可參考：?為國際化設(shè)置PHP環(huán)境.

配置格式器

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

'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::asTime() - 值被格式化成時間，如?14:23.
• yii\i18n\Formatter::asDatetime() - 值被格式化成日期和時間，如?January, 01 2014 14:23.
• yii\i18n\Formatter::asTimestamp() - 值被格式化成?unix 時間戳?如?1412609982.
• yii\i18n\Formatter::asRelativeTime() - 值被格式化成和當前時間比較的時間間隔并用人們易讀的格式，如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() 方法的日期和時間格式。

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

• en_GB區(qū)域的?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.

另外你可使用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

時區(qū)

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

// 假定 Yii::$app->timeZone = 'Europe/Berlin';echo Yii::$app->formatter->asTime(1412599260); // 14:41:00echo Yii::$app->formatter->asTime('2014-10-06 12:41:00'); // 14:41:00echo Yii::$app->formatter->asTime('2014-10-06 14:41:00 CEST'); // 14:41:00

注意：時區(qū)從屬于全世界各國政府定的規(guī)則，可能會頻繁的變更，因此你的系統(tǒng)的時區(qū)數(shù)據(jù)庫可能不是最新的信息， 可參考?ICU manual?關(guān)于更新時區(qū)數(shù)據(jù)庫的詳情， 也可參考：為國際化設(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() - 值被格式化成十進制數(shù)字并帶有小數(shù)位和千分位，如?42.123.
• yii\i18n\Formatter::asPercent() - 值被格式化成百分率，如?42%.
• yii\i18n\Formatter::asScientific() - 值被格式化成科學計數(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ù)字格式化的格式，默認和當前區(qū)域相同。

更多高級配置， 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ù)字格式化外，Yii提供其他用途提供一些實用的格式器： Additional to date, time and number formatting, Yii provides a set of other useful formatters for different purposes:

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

null-值