Qiang Xue
10 years ago
5 changed files with 296 additions and 18 deletions
@ -0,0 +1,180 @@ |
|||||||
|
数据格式器 |
||||||
|
============== |
||||||
|
|
||||||
|
Yii提供一个格式化类来格式化输出,以使输出数据对终端用户更友好易读, |
||||||
|
[[yii\i18n\Formatter]] 是一个助手类,作为 [应用组件](structure-application-components.md) 使用,默认名为`formatter`。 |
||||||
|
|
||||||
|
它提供一些方法用来格式化数据,如日期/时间、数字或其他常用的本地化格式, |
||||||
|
两种方式使用格式器: |
||||||
|
|
||||||
|
1. 直接使用格式化方法(所有的格式器方法以 `as`做前缀): |
||||||
|
|
||||||
|
```php |
||||||
|
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()|format()]] 方法和格式化名, |
||||||
|
该方法也被一些小部件如[[yii\grid\GridView]] 和 [[yii\widgets\DetailView]]使用,在小部件配置中可以指定列的数据格式。 |
||||||
|
|
||||||
|
```php |
||||||
|
echo Yii::$app->formatter->format('2014-01-01', 'date'); // 输出: January 1, 2014 |
||||||
|
// 可使用数组来指定格式化方法的参数: |
||||||
|
// `2` 是asPercent()方法的参数$decimals的值 |
||||||
|
echo Yii::$app->formatter->format(0.125, ['percent', 2]); // 输出: 12.50% |
||||||
|
``` |
||||||
|
|
||||||
|
当[PHP intl extension](http://php.net/manual/en/book.intl.php)安装时,格式器的输出会本地化, |
||||||
|
为此可配置格式器的 [[yii\i18n\Formatter::locale|locale]] 属性,如果没有配置, |
||||||
|
应用配置 [[yii\base\Application::language|language]] 作为当前区域,更多详情参考 [国际化](tutorial-i18n.md)一节。 |
||||||
|
然后格式器根据当前区域为日期和数字选择正确的格式,包括月份和星期也会转换到当前语言, |
||||||
|
日期格式也会被 [[yii\i18n\Formatter::timeZone|timeZone]] 参数影响, |
||||||
|
该参数如果没有明确配置会使用应用的 [[yii\base\Application::timeZone|from the application]] 参数。 |
||||||
|
|
||||||
|
日期格式根据不同区域输出不同的结果,如下例所示: |
||||||
|
For example the date format call will output different results for different locales: |
||||||
|
|
||||||
|
```php |
||||||
|
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](http://php.net/manual/en/book.intl.php)有没有安装,PHP编译的ICU库不同,格式化结果可能不同, |
||||||
|
> 所以为确保不同环境下得到相同的输出,推荐在每个环境下安装PHP intl扩展以及相同的ICU库, |
||||||
|
> 可参考: [为国际化设置PHP环境](tutorial-i18n.md#setup-environment). |
||||||
|
|
||||||
|
|
||||||
|
配置格式器 <a name="configuring-format"></a> |
||||||
|
------------------------- |
||||||
|
|
||||||
|
可配置[[yii\i18n\Formatter|formatter class]]的属性来调整格式器方法的默认格式, |
||||||
|
可以在[应用主体配置](concept-configurations.md#application-configurations) 中配置 `formatter` 组件应用到整个项目, |
||||||
|
配置样例如下所示, |
||||||
|
更多关于可用属性的详情请参考 [[yii\i18n\Formatter|API documentation of the Formatter class]] 和接下来一小节。 |
||||||
|
|
||||||
|
```php |
||||||
|
'components' => [ |
||||||
|
'formatter' => [ |
||||||
|
'dateFormat' => 'dd.MM.yyyy', |
||||||
|
'decimalSeparator' => ',', |
||||||
|
'thousandSeparator' => ' ', |
||||||
|
'currencyCode' => 'EUR', |
||||||
|
], |
||||||
|
], |
||||||
|
``` |
||||||
|
|
||||||
|
格式化日期和时间 <a name="date-and-time"></a> |
||||||
|
------------------------------- |
||||||
|
|
||||||
|
格式器类为格式化日期和时间提供了多个方法: |
||||||
|
The formatter class provides different methods for formatting date and time values. These are: |
||||||
|
|
||||||
|
- [[yii\i18n\Formatter::asDate()|date]] - 值被格式化成日期,如 `January, 01 2014`. |
||||||
|
- [[yii\i18n\Formatter::asTime()|time]] - 值被格式化成时间,如 `14:23`. |
||||||
|
- [[yii\i18n\Formatter::asDatetime()|datetime]] - 值被格式化成日期和时间,如 `January, 01 2014 14:23`. |
||||||
|
- [[yii\i18n\Formatter::asTimestamp()|timestamp]] - 值被格式化成 [unix 时间戳](http://en.wikipedia.org/wiki/Unix_time) 如 `1412609982`. |
||||||
|
- [[yii\i18n\Formatter::asRelativeTime()|relativeTime]] - 值被格式化成和当前时间比较的时间间隔并用人们易读的格式,如`1 hour ago`. |
||||||
|
|
||||||
|
可配置格式器的属性[[yii\i18n\Formatter::$dateFormat|$dateFormat]], [[yii\i18n\Formatter::$timeFormat|$timeFormat]] |
||||||
|
和[[yii\i18n\Formatter::$datetimeFormat|$datetimeFormat]]来全局指定[[yii\i18n\Formatter::asDate()|date]], |
||||||
|
[[yii\i18n\Formatter::asTime()|time]] 和 [[yii\i18n\Formatter::asDatetime()|datetime]] 方法的日期和时间格式。 |
||||||
|
|
||||||
|
格式器默认会使用一个快捷格式,它根据当前启用的区域来解析, |
||||||
|
这样日期和时间会格式化成用户国家和语言通用的格式, |
||||||
|
有四种不同的快捷格式: |
||||||
|
|
||||||
|
- `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`. |
||||||
|
|
||||||
|
另外你可使用[ICU 项目](http://site.icu-project.org/) 定义的语法来自定义格式, |
||||||
|
ICU项目在该URL:<http://userguide.icu-project.org/formatparse/datetime>下的手册有介绍, |
||||||
|
或者可使用PHP [date()](http://php.net/manual/de/function.date.php) 方法的语法字符串并加上前缀`php:`. |
||||||
|
|
||||||
|
```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 |
||||||
|
``` |
||||||
|
|
||||||
|
### 时区 <a name="time-zones"></a> |
||||||
|
|
||||||
|
当格式化日期和时间时,Yii会将它们转换为对应的 [[yii\i18n\Formatter::timeZone|configured time zone]] 时区, |
||||||
|
输入的值在没有指定时区时候会被当作UTC时间,因此,推荐存储所有的日期和时间为UTC而不是UNIX时间戳,UNIX通常也是UTC。 |
||||||
|
如果输入值所在的时区不同于UTC,时区应明确指定,如下所示: |
||||||
|
|
||||||
|
```php |
||||||
|
// 假定 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](http://userguide.icu-project.org/datetime/timezone#TOC-Updating-the-Time-Zone-Data) |
||||||
|
> 关于更新时区数据库的详情, |
||||||
|
> 也可参考:[为国际化设置PHP环境](tutorial-i18n.md#setup-environment). |
||||||
|
|
||||||
|
|
||||||
|
格式化数字 <a name="numbers"></a> |
||||||
|
------------------ |
||||||
|
|
||||||
|
格式器类提供如下方法格式化数值: |
||||||
|
For formatting numeric values the formatter class provides the following methods: |
||||||
|
|
||||||
|
- [[yii\i18n\Formatter::asInteger()|integer]] - 值被格式化成整型,如 `42`. |
||||||
|
- [[yii\i18n\Formatter::asDecimal()|decimal]] - 值被格式化成十进制数字并带有小数位和千分位,如 `42.123`. |
||||||
|
- [[yii\i18n\Formatter::asPercent()|percent]] - 值被格式化成百分率,如 `42%`. |
||||||
|
- [[yii\i18n\Formatter::asScientific()|scientific]] - 值被格式化成科学计数型,如`4.2E4`. |
||||||
|
- [[yii\i18n\Formatter::asCurrency()|currency]] - 值被格式化成货币格式,如 `£420.00`. |
||||||
|
- [[yii\i18n\Formatter::asSize()|size]] - 字节值被格式化成易读的值,如 `410 kibibytes`. |
||||||
|
|
||||||
|
可配置[[yii\i18n\Formatter::decimalSeparator|decimalSeparator]] 和 [[yii\i18n\Formatter::thousandSeparator|thousandSeparator]] |
||||||
|
属性来调整数字格式化的格式,默认和当前区域相同。 |
||||||
|
|
||||||
|
更多高级配置, [[yii\i18n\Formatter::numberFormatterOptions]] 和 [[yii\i18n\Formatter::numberFormatterTextOptions]] |
||||||
|
可用于配置内部使用 [Numberformatter class](http://php.net/manual/en/class.numberformatter.php) |
||||||
|
|
||||||
|
为调整数字的小数部分的最大值和最小值,可配置如下属性: |
||||||
|
|
||||||
|
```php |
||||||
|
[ |
||||||
|
NumberFormatter::MIN_FRACTION_DIGITS => 0, |
||||||
|
NumberFormatter::MAX_FRACTION_DIGITS => 2, |
||||||
|
] |
||||||
|
``` |
||||||
|
|
||||||
|
其他格式器 <a name="other"></a> |
||||||
|
---------------- |
||||||
|
|
||||||
|
除了日期、时间和数字格式化外,Yii提供其他用途提供一些实用的格式器: |
||||||
|
Additional to date, time and number formatting, Yii provides a set of other useful formatters for different purposes: |
||||||
|
|
||||||
|
- [[yii\i18n\Formatter::asRaw()|raw]] - 输出值和原始值一样,除了`null`值会用[[nullDisplay]]格式化,这是一个伪格式器; |
||||||
|
- [[yii\i18n\Formatter::asText()|text]] - 值会经过HTML编码; |
||||||
|
这是[GridView DataColumn](output-data-widgets.md#data-column)默认使用的格式; |
||||||
|
- [[yii\i18n\Formatter::asNtext()|ntext]] - 值会格式化成HTML编码的纯文本,新行会转换成换行符; |
||||||
|
- [[yii\i18n\Formatter::asParagraphs()|paragraphs]] - 值会转换成HTML编码的文本段落,用`<p>`标签包裹; |
||||||
|
- [[yii\i18n\Formatter::asHtml()|html]] - 值会被[[HtmlPurifier]]过滤来避免XSS跨域攻击,可传递附加选项如`['html', ['Attr.AllowedFrameTargets' => ['_blank']]]; |
||||||
|
- [[yii\i18n\Formatter::asEmail()|email]] - 值会格式化成 `mailto`-链接; |
||||||
|
- [[yii\i18n\Formatter::asImage()|image]] - 值会格式化成图片标签; |
||||||
|
- [[yii\i18n\Formatter::asUrl()|url]] - 值会格式化成超链接; |
||||||
|
- [[yii\i18n\Formatter::asBoolean()|boolean]] - 值会格式化成布尔型值,默认情况下 `true` 对应 `Yes`,`false` 对应 `No`, |
||||||
|
可根据应用语言配置进行翻译,可以配置[[yii\i18n\Formatter::booleanFormat]]-属性来调整; |
||||||
|
|
||||||
|
`null`-值 <a name="null-values"></a> |
||||||
|
------------- |
||||||
|
|
||||||
|
对于PHP的`null`值,格式器类会打印一个占位符而不是空字符串,空字符串默认会显示对应当前语言`(not set)`, |
||||||
|
可配置[[yii\i18n\Formatter::nullDisplay|nullDisplay]]-属性配置一个自定义占位符, |
||||||
|
如果对处理`null`值没有特殊要求,可设置[[yii\i18n\Formatter::nullDisplay|nullDisplay]] 为 `null`. |
@ -0,0 +1,92 @@ |
|||||||
|
路由 |
||||||
|
======= |
||||||
|
|
||||||
|
当[入口脚本](structure-entry-scripts.md)在调用 [[yii\web\Application::run()|run()]] |
||||||
|
方法时,它进行的第一个操作就是解析输入的请求,然后实例化对应的[控制器操作](structure-controllers.md)处理这个请求。该过程就被称为**引导路由(routing)**。(译者注:中文里既是动词也是名词) |
||||||
|
|
||||||
|
|
||||||
|
## 解析路由 <a name="resolving-route"></a> |
||||||
|
|
||||||
|
引导路由第一步,是解析输入请求为一个路由。如 [控制器(Controllers)](structure-controllers.md#routes) |
||||||
|
所描述的那样,路由是一个用于定位控制器操作的地址。这个过程通过 `request` 应用组件的 [[yii\web\Request::resolve()|resolve()]] |
||||||
|
方法实现,该方法会调用 [URL 管理器](runtime-url-handling.md) 进行实质上的请求解析工作。 |
||||||
|
|
||||||
|
The first step of routing is to parse the incoming request into a route which, as described in |
||||||
|
the [Controllers](structure-controllers.md#routes) section, is used to address a controller action. |
||||||
|
This is done by [[yii\web\Request::resolve()|resolve()]] method of the `request` application component. |
||||||
|
The method invokes the [URL manager](runtime-url-handling.md) to do the actual request parsing work. |
||||||
|
|
||||||
|
默认情况下,输入请求会包含一个名为 `r` 的 `GET` 参数,它的值即被视为路由。但是如果启用 |
||||||
|
[[yii\web\UrlManager::enablePrettyUrl|pretty URL feature]],确定请求路由时则会进行更多处理。具体的细节请参考 |
||||||
|
[URL 的解析与生成](runtime-url-handling.md) 章节。 |
||||||
|
|
||||||
|
By default, if the incoming request contains a `GET` parameter named `r`, its value will be considered |
||||||
|
as the route. However, if the [[yii\web\UrlManager::enablePrettyUrl|pretty URL feature]] is enabled, |
||||||
|
more work will be done to determine the requested route. For more details, please refer to |
||||||
|
the [URL Parsing and Generation](runtime-url-handling.md) section. |
||||||
|
|
||||||
|
若好死不死地路由最终无法被确定,那么 `request` 组件会抛出 [[yii\web\NotFoundHttpException]] 异常(译者注:大名鼎鼎的 404)。 |
||||||
|
|
||||||
|
In case a route cannot be determined, the `request` component will throw a [[yii\web\NotFoundHttpException]]. |
||||||
|
|
||||||
|
|
||||||
|
### 默认路由 <a name="default-route"></a> |
||||||
|
|
||||||
|
If an incoming request does not specify a route, which often happens to the request for homepages, |
||||||
|
the route specified by [[yii\web\Application::defaultRoute]] will be used. The default value of this property |
||||||
|
is `site/index`, which refers to the `index` action of the `site` controller. You may customize this property |
||||||
|
in the application configuration like the following: |
||||||
|
|
||||||
|
```php |
||||||
|
return [ |
||||||
|
// ... |
||||||
|
'defaultRoute' => 'main/index', |
||||||
|
]; |
||||||
|
``` |
||||||
|
|
||||||
|
|
||||||
|
### `catchAll` 路由(全拦截路由) <a name="catchall-route"></a> |
||||||
|
|
||||||
|
Sometimes, you may want to put your Web application in maintenance mode temporarily and display the same |
||||||
|
informational page for all requests. There are many ways to accomplish this goal. But one of the simplest |
||||||
|
ways is to configure the [[yii\web\Application::catchAll]] property like the following in the application configuration: |
||||||
|
|
||||||
|
```php |
||||||
|
return [ |
||||||
|
// ... |
||||||
|
'catchAll' => ['site/offline'], |
||||||
|
]; |
||||||
|
``` |
||||||
|
|
||||||
|
The `catchAll` property should take an array whose first element specifies a route, and |
||||||
|
the rest of the elements (name-value pairs) specify the parameters to be bound to the action. |
||||||
|
|
||||||
|
When the `catchAll` property is set, it will replace any route resolved from the incoming requests. |
||||||
|
With the above configuration, the same `site/offline` action will be used to handle all incoming requests. |
||||||
|
|
||||||
|
|
||||||
|
## 创建一个操作 <a name="creating-action"></a> |
||||||
|
|
||||||
|
Once the requested route is determined, the next step is to create the action object corresponding to the route. |
||||||
|
|
||||||
|
The route is broken down into multiple parts by the slashes in it. For example, `site/index` will be |
||||||
|
broken into `site` and `index`. Each part is an ID which may refer to a module, a controller or an action. |
||||||
|
|
||||||
|
Starting from the first part in the route, the application conducts the following steps to create modules (if any), |
||||||
|
the controller and the action: |
||||||
|
|
||||||
|
1. Set the application as the current module. |
||||||
|
2. Check if the [[yii\base\Module::controllerMap|controller map]] of the current module contains the current ID. |
||||||
|
If so, a controller object will be created according to the controller configuration found in the map, |
||||||
|
and do Step 5 with the rest parts of the route. |
||||||
|
3. Check if the ID refers to a module listed in the [[yii\base\Module::modules|modules]] property of |
||||||
|
the current module. If so, a module is created according to the configuration found in the module list, |
||||||
|
and do Step 2 with the next part in the route under the context of the newly created module. |
||||||
|
4. Treat the ID as a controller ID and create a controller object. Do the next step with the rest part of |
||||||
|
the route. |
||||||
|
5. The controller looks for the current ID in its [[yii\base\Controller::actions()|action map]]. If found, |
||||||
|
it creates an action according to the configuration found in the map. Otherwise, the controller will |
||||||
|
attempt to create an inline action which is defined by an action method corresponding to the current ID. |
||||||
|
|
||||||
|
Among the above steps, if any error occurs, a [[yii\web\NotFoundHttpException]] will be thrown, indicating |
||||||
|
failure of the routing. |
Loading…
Reference in new issue