diff --git a/aio/content/translations/cn/api-plan.md b/aio/content/translations/cn/api-plan.md index 9d8d7fabd6..7c59e8a2c6 100644 --- a/aio/content/translations/cn/api-plan.md +++ b/aio/content/translations/cn/api-plan.md @@ -26,7 +26,7 @@ [x] |core/ViewChild | 2,870 | 0.89 [x] |core/Directive | 2,767 | 0.86 [x] |router/Routes | 2,331 | 0.72 -[ ] |router/RouterModule | 2,227 | 0.69 +[x] |router/RouterModule | 2,227 | 0.69 [x] |router/Route | 2,223 | 0.69 [ ] |common/http/HttpClientModule | 2,167 | 0.67 [ ] |core/ElementRef | 2,163 | 0.67 diff --git a/packages/router/src/router_module.ts b/packages/router/src/router_module.ts index 384f7e987a..7c7db0023d 100644 --- a/packages/router/src/router_module.ts +++ b/packages/router/src/router_module.ts @@ -35,6 +35,7 @@ import {flatten} from './utils/collection'; * * Contains a list of directives * + * 所含指令的列表 * */ const ROUTER_DIRECTIVES = @@ -45,7 +46,7 @@ const ROUTER_DIRECTIVES = * * Is used in DI to configure the router. * - * + * DI 用它来配置路由器。 */ export const ROUTER_CONFIGURATION = new InjectionToken('ROUTER_CONFIGURATION'); @@ -86,16 +87,28 @@ export function routerNgProbeToken() { * Since the router deals with a global shared resource--location, we cannot have * more than one router service active. * + * RouterModule 可能会被多次导入:每个惰性加载的发布包都会导入一次。 + * 但由于路由器要和全局共享的资源 - location 打交道,所以不能同时激活一个以上的 `Router` 服务。 + * * That is why there are two ways to create the module: `RouterModule.forRoot` and * `RouterModule.forChild`. * + * 这就是需要两种方式来创建本模块的原因:`RouterModule.forRoot` 和 `RouterModule.forChild`。 + * * * `forRoot` creates a module that contains all the directives, the given routes, and the router * service itself. + * + * `forRoot` 创建一个包含所有指令、指定的路由和 `Router` 服务本身的模块。 + * * * `forChild` creates a module that contains all the directives and the given routes, but does not * include the router service. * + * `forChild` 会创建一个包含所有指令、指定的路由,但不含 `Router` 服务的模块。 + * * When registered at the root, the module should be used as follows * + * 当注册在根模块时,该模块应该这样用: + * * ``` * @NgModule({ * imports: [RouterModule.forRoot(ROUTES)] @@ -105,6 +118,8 @@ export function routerNgProbeToken() { * * For submodules and lazy loaded submodules the module should be used as follows: * + * 对于子模块和惰性加载的子模块,该模块应该这样用: + * * ``` * @NgModule({ * imports: [RouterModule.forChild(ROUTES)] @@ -116,18 +131,26 @@ export function routerNgProbeToken() { * * Adds router directives and providers. * + * 添加路由器指令和服务提供商。 + * * Managing state transitions is one of the hardest parts of building applications. This is * especially true on the web, where you also need to ensure that the state is reflected in the URL. * In addition, we often want to split applications into multiple bundles and load them on demand. * Doing this transparently is not trivial. * + * 在构建应用时,管理状态的转换是最难的任务之一。对 Web 来说尤其如此,你还要确保这个状态同时在 URL 中反映出来。 + * 另外,我们通常会希望把应用拆分成多个发布包,并按需加载。要让这些工作透明化,可没那么简单。 + * * The Angular router solves these problems. Using the router, you can declaratively specify * application states, manage state transitions while taking care of the URL, and load bundles on * demand. * + * Angular 的路由器解决了这些问题。使用路由器,你可以声明式的指定应用的状态、管理状态的转换,还可以处理好 URL,还可以按需加载发布包。 + * * [Read this developer guide](https://angular.io/docs/ts/latest/guide/router.html) to get an * overview of how the router should be used. * + * [阅读开发指南](/guide/router) 以获得如何使用路由器的全景图。 * */ @NgModule({ @@ -143,17 +166,43 @@ export class RouterModule { * Creates a module with all the router providers and directives. It also optionally sets up an * application listener to perform an initial navigation. * + * 创建一个带有所有路由器服务提供商和指令的模块。它还可以(可选的)设置一个应用监听器,来执行首次导航。 + * * Options (see `ExtraOptions`): + * + * 选项(参见 `ExtraOptions`): + * * * `enableTracing` makes the router log all its internal events to the console. + * + * `enableTracing` 让路由器把它所有的内部事件都记录到控制台中。 + * * * `useHash` enables the location strategy that uses the URL fragment instead of the history * API. + * + * `useHash` 修改位置策略(`LocationStrategy`),用 URL 片段(`#`)代替 `history` API。 + * * * `initialNavigation` disables the initial navigation. + * + * `initialNavigation` 禁用首次导航。 + * * * `errorHandler` provides a custom error handler. + * + * `errorHandler` 提供一个自定义的错误处理器。 + * * * `preloadingStrategy` configures a preloading strategy (see `PreloadAllModules`). + * + * `preloadingStrategy` 配置预加载策略(参见 `PreloadAllModules`)。 + * * * `onSameUrlNavigation` configures how the router handles navigation to the current URL. See * `ExtraOptions` for more details. + * + * `onSameUrlNavigation` 会配置路由器在导航到当前 URL 时该如何处理。欲知详情,参见 `ExtraOptions`。 + * * * `paramsInheritanceStrategy` defines how the router merges params, data and resolved data * from parent to child routes. + * + * `paramsInheritanceStrategy` 定义了路由器要如何把父路由的参数、数据和解析出的数据合并到子路由中。 + * */ static forRoot(routes: Routes, config?: ExtraOptions): ModuleWithProviders { return { @@ -192,6 +241,8 @@ export class RouterModule { /** * Creates a module with all the router directives and a provider registering routes. + * + * 创建一个具有所有路由器指令和一个用于注册路由的提供商。 */ static forChild(routes: Routes): ModuleWithProviders { return {ngModule: RouterModule, providers: [provideRoutes(routes)]}; @@ -225,8 +276,12 @@ export function provideForRootGuard(router: Router): any { * * Registers routes. * + * 注册路由。 + * * ### Example * + * ### 例子 + * * ``` * @NgModule({ * imports: [RouterModule.forChild(ROUTES)], @@ -249,24 +304,47 @@ export function provideRoutes(routes: Routes): any { * * Represents an option to configure when the initial navigation is performed. * + * 一个选项,用于控制执行首次导航的时机。 + * * * 'enabled' - the initial navigation starts before the root component is created. * The bootstrap is blocked until the initial navigation is complete. + * + * 'enabled' - 在根组件创建之前就开始首次导航。在首次导航完成之前,引导过程都会被阻塞。 + * * * 'disabled' - the initial navigation is not performed. The location listener is set up before * the root component gets created. + * + * 'disabled' - 不执行首次导航。在根组件创建之前,就会挂接上位置变更监听器。 + * * * 'legacy_enabled'- the initial navigation starts after the root component has been created. * The bootstrap is not blocked until the initial navigation is complete. @deprecated + * + * 'legacy_enabled' - 在根组件创建完之后开始首次导航。在首次导航之前不阻塞引导过程。@deprecated + * * * 'legacy_disabled'- the initial navigation is not performed. The location listener is set up * after @deprecated * the root component gets created. + * + * 'legacy_disabled' - 不执行首次导航。在根组件创建完之后设置路径监听器。@deprecated + * * * `true` - same as 'legacy_enabled'. @deprecated since v4 + * + * `true` - 同 'legacy_enabled'. @deprecated since v4 + * * * `false` - same as 'legacy_disabled'. @deprecated since v4 * + * `false` - 同 'legacy_disabled'. @deprecated since v4 + * * The 'enabled' option should be used for applications unless there is a reason to have * more control over when the router starts its initial navigation due to some complex * initialization logic. In this case, 'disabled' should be used. * + * 应用应该默认使用 'enabled'。如果在一些复杂的初始化逻辑中,需要在路由器开始首次导航之前进行更多的控制,则应该使用 'disabled'。 + * * The 'legacy_enabled' and 'legacy_disabled' should not be used for new applications. * + * 新的应用中不应该再使用 'legacy_enabled' 和 'legacy_disabled'。 + * * @experimental */ export type InitialNavigation = @@ -277,31 +355,42 @@ export type InitialNavigation = * * Represents options to configure the router. * + * 表示路由器的配置项。 * */ export interface ExtraOptions { /** * Makes the router log all its internal events to the console. + * + * 让路由器将其所有的内部事件都记录到控制台中。 */ enableTracing?: boolean; /** * Enables the location strategy that uses the URL fragment instead of the history API. + * + * 修改位置策略(`LocationStrategy`),用 URL 片段(`#`)代替 `history` API。 */ useHash?: boolean; /** * Disables the initial navigation. + * + * 禁用首次导航 */ initialNavigation?: InitialNavigation; /** * A custom error handler. + * + * 自定义的错误处理器。 */ errorHandler?: ErrorHandler; /** * Configures a preloading strategy. See `PreloadAllModules`. + * + * 配置预加载策略,参见 `PreloadAllModules`。 */ preloadingStrategy?: any; @@ -310,22 +399,41 @@ export interface ExtraOptions { * By default, the router will ignore this navigation. However, this prevents features such * as a "refresh" button. Use this option to configure the behavior when navigating to the * current URL. Default is 'ignore'. + * + * 规定当路由器收到一个导航到当前 URL 的请求时该如何处理。 + * 默认情况下,路由器会忽略本次导航。不过,这会阻止实现类似于"刷新"按钮的功能。 + * 使用该选项可以控制导航到当前 URL 时的行为。默认为 'ignore'。 */ onSameUrlNavigation?: 'reload'|'ignore'; /** * Configures if the scroll position needs to be restored when navigating back. * + * 配置是否需要在导航回来的时候恢复滚动位置。 + * * * 'disabled'--does nothing (default). + * + * 'disabled' - 什么也不做(默认)。 + * * * 'top'--set the scroll position to 0,0.. + * + * 'top' - 把滚动位置设置为 0,0。 + * * * 'enabled'--set the scroll position to the stored position. This option will be the default in * the future. * + * 'enabled' - 把滚动位置设置为以前保存的位置。将来这个选项会变成默认值。 + * * When enabled, the router store store scroll positions when navigating forward, and will * restore the stored positions whe navigating back (popstate). When navigating forward, * the scroll position will be set to [0, 0], or to the anchor if one is provided. * + * 当启用时,路由器会在向前导航时保存滚动位置,导航回来(popstate)时则恢复所保存的位置。当向前导航时,滚动位置会设置为 [0, 0],如果指定了锚点,则跳转到那个锚点。 + * * You can implement custom scroll restoration behavior as follows. + * + * 你可以自定义滚动位置的恢复策略。 + * * ```typescript * class AppModule { * constructor(router: Router, viewportScroller: ViewportScroller, store: Store) { @@ -346,6 +454,8 @@ export interface ExtraOptions { * * You can also implement component-specific scrolling like this: * + * 你还可以像这样在组件级实现滚动位置恢复策略: + * * ```typescript * class ListComponent { * list: any[]; @@ -367,20 +477,34 @@ export interface ExtraOptions { /** * Configures if the router should scroll to the element when the url has a fragment. * + * 配置当 url 中带有片段(`#`)时路由器是否滚动到那个元素。 + * * * 'disabled'--does nothing (default). + * + * 'disabled' - 什么也不做(默认)。 + * * * 'enabled'--scrolls to the element. This option will be the default in the future. * + * 'enabled' - 滚动到该元素。将来该选项会变为默认值。 + * * Anchor scrolling does not happen on 'popstate'. Instead, we restore the position * that we stored or scroll to the top. + * + * 在 'popstate' 时,不会自动滚动到锚点,而是恢复应用中保存的滚动位置,或滚动到顶部。 */ anchorScrolling?: 'disabled'|'enabled'; /** * Configures the scroll offset the router will use when scrolling to an element. * + * 配置当滚动到一个元素时,路由器使用的滚动偏移。 + * * When given a tuple with two numbers, the router will always use the numbers. * When given a function, the router will invoke the function every time it restores scroll * position. + * + * 当给出两个数字时,路由器总会使用它们。 + * 当给出一个函数时,路由器每当要恢复滚动位置时,都会调用该函数。 */ scrollOffset?: [number, number]|(() => [number, number]); @@ -388,9 +512,16 @@ export interface ExtraOptions { * Defines how the router merges params, data and resolved data from parent to child * routes. Available options are: * + * 定义路由器如何把父路由的参数、数据和解析出的数据合并到子路由。有效的选项包括: + * * - `'emptyOnly'`, the default, only inherits parent params for path-less or component-less * routes. + * + * `'emptyOnly'`,默认值,只从无路径或无组件的路由中继承父路由的参数。 + * * - `'always'`, enables unconditional inheritance of parent params. + * + * `'always'`,无条件继承父路由的参数。 */ paramsInheritanceStrategy?: 'emptyOnly'|'always'; @@ -399,9 +530,20 @@ export interface ExtraOptions { * invalid character sequences. The default implementation is to redirect to the root url dropping * any path or param info. This function passes three parameters: * + * 一个自定义的 URI 格式无效错误的处理器。每当 encodeURI 包含无效字符序列时,就会调用该处理器。默认的实现是跳转到根路径,抛弃任何路径和参数信息。该函数传入三个参数: + * * - `'URIError'` - Error thrown when parsing a bad URL + * + * `'URIError'` - 当传入错误的 URL 时抛出的错误 + * * - `'UrlSerializer'` - UrlSerializer that’s configured with the router. + * + * `'UrlSerializer'` - 路由器所配置的 UrlSerializer。 + * * - `'url'` - The malformed URL that caused the URIError + * + * `'url'` - 导致 URIError 的格式无效的 URL + * * */ malformedUriErrorHandler?: (error: URIError, urlSerializer: UrlSerializer, url: string) => UrlTree; @@ -413,8 +555,17 @@ export interface ExtraOptions { * URL early so if navigation fails, you can show an error message with the URL that failed. * Available options are: * + * 定义路由器要何时更新浏览器的 URL。默认行为是在每次成功的导航之后更新。 + * 不过,有些应用会更愿意在导航开始时就更新。最常见的情况是尽早更新 URL,这样当导航失败时,你就可以在出错的 URL 上显示一条错误信息了。 + * 可用的选项包括: + * * - `'deferred'`, the default, updates the browser URL after navigation has finished. + * + * `'deferred'`,默认值,在导航完毕后更新浏览器 URL。 + * * - `'eager'`, updates browser URL at the beginning of navigation. + * + * `'eager'`,在导航开始时更新浏览器的 URL。 */ urlUpdateStrategy?: 'deferred'|'eager'; @@ -422,6 +573,8 @@ export interface ExtraOptions { * Enables a bug fix that corrects relative link resolution in components with empty paths. * Example: * + * 启用 BUG 补丁,纠正空路径组件的相对链接解析问题。 + * * ``` * const routes = [ * { @@ -437,14 +590,20 @@ export interface ExtraOptions { * * From the `ContainerComponent`, this will not work: * + * 在 `ContainerComponent` 中不能这样用: + * * `Link to A` * * However, this will work: * + * 不过,可以这样用: + * * `Link to A` * * In other words, you're required to use `../` rather than `./`. The current default in v6 * is `legacy`, and this option will be removed in v7 to default to the corrected behavior. + * + * 换句话说,要使用 `../` 而不是 `./`。目前 v6 版本的默认值是 `legacy`,到 v7 就会移除该选项,以纠正此行为。 */ relativeLinkResolution?: 'legacy'|'corrected'; } @@ -509,13 +668,21 @@ export function rootRoute(router: Router): ActivatedRoute { /** * To initialize the router properly we need to do in two steps: * + * 要正确初始化路由器,我们需要完成两个步骤: + * * We need to start the navigation in a APP_INITIALIZER to block the bootstrap if * a resolver or a guards executes asynchronously. Second, we need to actually run * activation in a BOOTSTRAP_LISTENER. We utilize the afterPreactivation * hook provided by the router to do that. * + * 为了让解析器或路由守卫能异步执行,我们需要在 APP_INITIALIZER 中开始导航,以便阻塞引导过程。 + * 其次,我们要在 BOOTSTRAP_LISTENER 中实际运行激活逻辑。 + * 我们利用路由器提供的 `afterPreactivation`(预激活完成后) 钩子来做到这一点。 + * * The router navigation starts, reaches the point when preactivation is done, and then * pauses. It waits for the hook to be resolved. We then resolve it only in a bootstrap listener. + * + * 路由器开始导航,当预激活(`preactivation`)完成之后,就到达了这个时间点,并等待。它会一直等到这个钩子被解析之后才会继续。以后我们就只会在引导过程监听器中解析它了。 */ @Injectable() export class RouterInitializer { @@ -607,6 +774,8 @@ export function getBootstrapListener(r: RouterInitializer) { /** * A token for the router initializer that will be called after the app is bootstrapped. * + * 一个代表路由器初始化器的令牌,应用引导完毕后就会调用它。 + * * @experimental */ export const ROUTER_INITIALIZER =