mirror of
https://github.com/yiisoft/yii2.git
synced 2025-08-26 06:15:19 +08:00
finished data formatting guide [skip ci]
This commit is contained in:
Qiang Xue
@ -103,51 +103,53 @@ The following format shortcuts are supported (the examples assume `en_GB` is the
|
||||
|
||||
### Time Zones <span id="time-zones"></span>
|
||||
|
||||
When formatting date and time values, Yii will convert them to the default [[yii\i18n\Formatter::timeZone|time zone]].
|
||||
Therefore the input value is assumed to be in UTC unless a time zone is explicitly given. For this reason
|
||||
it is recommended to store all date and time values in UTC, preferably as a UNIX timestamp, which is always UTC by definition.
|
||||
If the input value is in a time zone different from UTC, the time zone has to be stated explicitly like in the following example:
|
||||
When formatting date and time values, Yii will convert them to the target [[yii\i18n\Formatter::timeZone|time zone]].
|
||||
The value being formatted is assumed to be in UTC, unless a time zone is explicitly given or you have configured
|
||||
[[yii\i18n\Formatter::defaultTimeZone]].
|
||||
|
||||
In the following examples, we assume the target [[yii\i18n\Formatter::timeZone|time zone]] is set as `Europe/Berlin`.
|
||||
|
||||
```php
|
||||
// assuming Yii::$app->timeZone = '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
|
||||
```
|
||||
|
||||
Since version 2.0.1 it is also possible to configure the time zone that is assumed for timestamps that do not include a time zone
|
||||
identifier like the second example in the code above. You can set [[yii\i18n\Formatter::defaultTimeZone]] to the time zone you use for data storage.
|
||||
|
||||
> Note: As time zones are subject to rules made by the governments around the world and may change frequently, it is
|
||||
> likely that you do not have the latest information in the time zone database installed on your system.
|
||||
> You may refer to the [ICU manual](http://userguide.icu-project.org/datetime/timezone#TOC-Updating-the-Time-Zone-Data)
|
||||
> for details on updating the time zone database.
|
||||
> See also: [Setting up your PHP environment for internationalization](tutorial-i18n.md#setup-environment).
|
||||
> for details on updating the time zone database. Please also read
|
||||
> [Setting up your PHP environment for internationalization](tutorial-i18n.md#setup-environment).
|
||||
|
||||
|
||||
Formatting Numbers <span id="numbers"></span>
|
||||
------------------
|
||||
## Formatting Numbers <span id="numbers"></span>
|
||||
|
||||
For formatting numeric values the formatter class provides the following methods:
|
||||
The formatter supports the following output formats that are related with numbers:
|
||||
|
||||
- [[yii\i18n\Formatter::asInteger()|integer]] - the value is formatted as an integer e.g. `42`.
|
||||
- [[yii\i18n\Formatter::asDecimal()|decimal]] - the value is formatted as a decimal number considering decimal and thousand
|
||||
- [[yii\i18n\Formatter::asInteger()|integer]]: the value is formatted as an integer e.g. `42`.
|
||||
- [[yii\i18n\Formatter::asDecimal()|decimal]]: the value is formatted as a decimal number considering decimal and thousand
|
||||
separators e.g. `2,542.123` or `2.542,123`.
|
||||
- [[yii\i18n\Formatter::asPercent()|percent]] - the value is formatted as a percent number e.g. `42%`.
|
||||
- [[yii\i18n\Formatter::asScientific()|scientific]] - the value is formatted as a number in scientific format e.g. `4.2E4`.
|
||||
- [[yii\i18n\Formatter::asCurrency()|currency]] - the value is formatted as a currency value e.g. `£420.00`.
|
||||
- [[yii\i18n\Formatter::asPercent()|percent]]: the value is formatted as a percent number e.g. `42%`.
|
||||
- [[yii\i18n\Formatter::asScientific()|scientific]]: the value is formatted as a number in scientific format e.g. `4.2E4`.
|
||||
- [[yii\i18n\Formatter::asCurrency()|currency]]: the value is formatted as a currency value e.g. `£420.00`.
|
||||
Note that for this function to work properly, the locale needs to include a country part e.g. `en_GB` or `en_US` because language only
|
||||
would be ambiguous in this case.
|
||||
- [[yii\i18n\Formatter::asSize()|size]] - the value that is a number of bytes is formatted as a human readable size e.g. `410 kibibytes`.
|
||||
- [[yii\i18n\Formatter::asShortSize()|shortSize]] - is the short version of [[yii\i18n\Formatter::asSize()|size]], e.g. `410 KiB`.
|
||||
- [[yii\i18n\Formatter::asSize()|size]]: the value that is a number of bytes is formatted as a human readable size e.g. `410 kibibytes`.
|
||||
- [[yii\i18n\Formatter::asShortSize()|shortSize]]: is the short version of [[yii\i18n\Formatter::asSize()|size]], e.g. `410 KiB`.
|
||||
|
||||
The format for number formatting can be adjusted using the [[yii\i18n\Formatter::decimalSeparator|decimalSeparator]] and
|
||||
[[yii\i18n\Formatter::thousandSeparator|thousandSeparator]] which are set by default according to the locale.
|
||||
[[yii\i18n\Formatter::thousandSeparator|thousandSeparator]], both of which take default values according to the
|
||||
active [[yii\i18n\Formatter::locale|locale]].
|
||||
|
||||
For more advanced configuration, [[yii\i18n\Formatter::numberFormatterOptions]] and [[yii\i18n\Formatter::numberFormatterTextOptions]]
|
||||
can be used to configure the internally used [NumberFormatter class](http://php.net/manual/en/class.numberformatter.php)
|
||||
|
||||
For example, to adjust the maximum and minimum value of fraction digits, you can configure [[yii\i18n\Formatter::numberFormatterOptions]] property like the following:
|
||||
can be used to configure the [NumberFormatter class](http://php.net/manual/en/class.numberformatter.php) used internally
|
||||
to implement the formatter. For example, to adjust the maximum and minimum value of fraction digits, you can configure
|
||||
the [[yii\i18n\Formatter::numberFormatterOptions]] property like the following:
|
||||
|
||||
```php
|
||||
'numberFormatterOptions' => [
|
||||
@ -156,62 +158,62 @@ For example, to adjust the maximum and minimum value of fraction digits, you can
|
||||
]
|
||||
```
|
||||
|
||||
Other formatters <span id="other"></span>
|
||||
----------------
|
||||
|
||||
In addition to date, time and number formatting, Yii provides a set of other useful formatters for different situations:
|
||||
## Other Formats <span id="other"></span>
|
||||
|
||||
- [[yii\i18n\Formatter::asRaw()|raw]] - the value is outputted as is, this is a pseudo-formatter that has no effect except that
|
||||
Besides date/time and number formats, Yii also supports other commonly used formats, including
|
||||
|
||||
- [[yii\i18n\Formatter::asRaw()|raw]]: the value is outputted as is, this is a pseudo-formatter that has no effect except that
|
||||
`null` values will be formatted using [[nullDisplay]].
|
||||
- [[yii\i18n\Formatter::asText()|text]] - the value is HTML-encoded.
|
||||
- [[yii\i18n\Formatter::asText()|text]]: the value is HTML-encoded.
|
||||
This is the default format used by the [GridView DataColumn](output-data-widgets.md#data-column).
|
||||
- [[yii\i18n\Formatter::asNtext()|ntext]] - the value is formatted as an HTML-encoded plain text with newlines converted
|
||||
- [[yii\i18n\Formatter::asNtext()|ntext]]: the value is formatted as an HTML-encoded plain text with newlines converted
|
||||
into line breaks.
|
||||
- [[yii\i18n\Formatter::asParagraphs()|paragraphs]] - the value is formatted as HTML-encoded text paragraphs wrapped
|
||||
- [[yii\i18n\Formatter::asParagraphs()|paragraphs]]: the value is formatted as HTML-encoded text paragraphs wrapped
|
||||
into `<p>` tags.
|
||||
- [[yii\i18n\Formatter::asHtml()|html]] - the value is purified using [[HtmlPurifier]] to avoid XSS attacks. You can
|
||||
- [[yii\i18n\Formatter::asHtml()|html]]: the value is purified using [[HtmlPurifier]] to avoid XSS attacks. You can
|
||||
pass additional options such as `['html', ['Attr.AllowedFrameTargets' => ['_blank']]]`.
|
||||
- [[yii\i18n\Formatter::asEmail()|email]] - the value is formatted as a `mailto`-link.
|
||||
- [[yii\i18n\Formatter::asImage()|image]] - the value is formatted as an image tag.
|
||||
- [[yii\i18n\Formatter::asUrl()|url]] - the value is formatted as a hyperlink.
|
||||
- [[yii\i18n\Formatter::asBoolean()|boolean]] - the value is formatted as a boolean. By default `true` is rendered
|
||||
- [[yii\i18n\Formatter::asEmail()|email]]: the value is formatted as a `mailto`-link.
|
||||
- [[yii\i18n\Formatter::asImage()|image]]: the value is formatted as an image tag.
|
||||
- [[yii\i18n\Formatter::asUrl()|url]]: the value is formatted as a hyperlink.
|
||||
- [[yii\i18n\Formatter::asBoolean()|boolean]]: the value is formatted as a boolean. By default `true` is rendered
|
||||
as `Yes` and `false` as `No`, translated to the current application language. You can adjust this by configuring
|
||||
the [[yii\i18n\Formatter::booleanFormat]] property.
|
||||
|
||||
`null`-values <span id="null-values"></span>
|
||||
-------------
|
||||
|
||||
For values that are `null` in PHP, the formatter class will print a placeholder instead of an empty string which
|
||||
defaults to `(not set)` translated to the current application language. You can configure the
|
||||
[[yii\i18n\Formatter::nullDisplay|nullDisplay]] property to set a custom placeholder.
|
||||
If you do not want special handling for `null` values, you can set [[yii\i18n\Formatter::nullDisplay|nullDisplay]] to `null`.
|
||||
## Null Values <span id="null-values"></span>
|
||||
|
||||
Null values are specially formatted. Instead of displaying an empty string, the formatter will convert it into a
|
||||
preset string which defaults to `(not set)` translated into the current application language. You can configure the
|
||||
[[yii\i18n\Formatter::nullDisplay|nullDisplay]] property to customize this string.
|
||||
|
||||
|
||||
## Localizing Data Format <span id="localizing-data-format"></span>
|
||||
|
||||
All output of the formatter is localized when the [PHP intl extension](http://php.net/manual/en/book.intl.php) is installed.
|
||||
You can configure the [[yii\i18n\Formatter::locale|locale]] property of the formatter for this. If not configured, the
|
||||
application [[yii\base\Application::language|language]] is used as the locale. See the [section on internationalization](tutorial-i18n.md) for more details.
|
||||
The Formatter will then choose the correct format for dates and numbers according to the locale including names of month and
|
||||
weekdays translated to the current language. Date formats are also affected by the [[yii\i18n\Formatter::timeZone|timeZone]]
|
||||
which will also be taken from the application [[yii\base\Application::timeZone|timeZone]] if not configured explicitly.
|
||||
|
||||
For example the date format call will output different results for different locales:
|
||||
As aforementioned, the formatter may use the currently active [[yii\i18n\Formatter::locale|locale]] to determine how
|
||||
to format a value that is suitable in the target country/region. For example, the same date value may be formatted
|
||||
differently for different locales:
|
||||
|
||||
```php
|
||||
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 г.
|
||||
```
|
||||
|
||||
> Note that formatting may differ between different versions of the ICU library compiled with PHP and also based on the fact whether the
|
||||
> [PHP intl extension](http://php.net/manual/en/book.intl.php) is installed or not. So to ensure your website works with the same output
|
||||
> in all environments it is recommended to install the PHP intl extension in all environments and verify that the version of the ICU library
|
||||
> is the same. See also: [Setting up your PHP environment for internationalization](tutorial-i18n.md#setup-environment).
|
||||
By default, the currently active [[yii\i18n\Formatter::locale|locale]] is determined by the value of
|
||||
[[yii\base\Application::language]]. You may override it by setting the [[yii\i18n\Formatter::locale]] property explicitly.
|
||||
|
||||
> Note: The Yii formatter relies on the [PHP intl extension](http://php.net/manual/en/book.intl.php) to support
|
||||
> localized data formatting. Because different versions of the ICU library compiled with PHP may cause different
|
||||
> formatting results, it is recommended that you use the same ICU version for all your environments. For more details,
|
||||
> please refer to [Setting up your PHP environment for internationalization](tutorial-i18n.md#setup-environment).
|
||||
>
|
||||
> Note also that even if the intl extension is installed, formatting date and time values for years >=2038 or <=1901
|
||||
> on 32bit systems will fall back to the PHP implementation, which does not provide localized month and day names,
|
||||
> because intl uses a 32bit UNIX timestamp internally. On a 64bit system the intl formatter is used in all cases if installed.
|
||||
> If the intl extension is not installed, the data will not be localized.
|
||||
>
|
||||
> Note that for date values that are before year 1901 or after 2038, they will not be localized on 32-bit systems, even
|
||||
> if the intl extension is installed. This is because in this case ICU is using 32-bit UNIX timestamps to date values.
|
||||
|
||||
@ -55,7 +55,7 @@ input-validation.md | Yes
|
||||
input-file-upload.md | Yes
|
||||
input-multiple-models.md |
|
||||
input-tabular-input.md |
|
||||
output-formatting.md |
|
||||
output-formatting.md | Yes
|
||||
output-pagination.md | Yes
|
||||
output-sorting.md | Yes
|
||||
output-data-providers.md | Yes
|
||||
|
||||
Reference in New Issue
Block a user