diff --git a/aio/content/translations/cn/api-plan.md b/aio/content/translations/cn/api-plan.md index 0b8544f5d8..eb2dd24ace 100644 --- a/aio/content/translations/cn/api-plan.md +++ b/aio/content/translations/cn/api-plan.md @@ -2,106 +2,104 @@ 按照下列优先级进行翻译： -URL|浏览量|占比 ----|---|---- -common/http/HttpClient | 7,263 | 2.26 -common/NgForOf | 6,281 | 1.95 -forms/NgModel | 5,648 | 1.75 -core/Component | 5,582 | 1.73 -common/NgIf | 4,940 | 1.53 -core/NgModule | 4,097 | 1.27 -router/Router | 4,049 | 1.26 -animations/animate | 3,817 | 1.19 -common/NgClass | 3,715 | 1.15 -common/DatePipe | 3,576 | 1.11 -/docs/ts/latest | 3,489 | 1.08 -forms/FormsModule | 3,381 | 1.05 -core/Input | 3,354 | 1.04 -core/EventEmitter | 3,202 | 0.99 -core/Injectable | 3,177 | 0.99 -forms/FormGroup | 3,096 | 0.96 -forms/FormControl | 3,034 | 0.94 -router/ActivatedRoute | 2,993 | 0.93 -forms/AbstractControl | 2,930 | 0.91 -router/RouterLink | 2,929 | 0.91 -core/ViewChild | 2,870 | 0.89 -core/Directive | 2,767 | 0.86 -router/Routes | 2,331 | 0.72 -router/RouterModule | 2,227 | 0.69 -router/Route | 2,223 | 0.69 -http/Http | 2,220 | 0.69 -common/http/HttpClientModule | 2,167 | 0.67 -core/ElementRef | 2,163 | 0.67 -core/OnInit | 2,136 | 0.66 -common/UpperCasePipe | 2,078 | 0.65 -common/NgStyle | 1,935 | 0.60 -router/RouterOutlet | 1,908 | 0.59 -forms/Validators | 1,900 | 0.59 -common/http/HttpHeaders | 1,790 | 0.56 -core/Pipe | 1,673 | 0.52 -common/NgSwitch | 1,670 | 0.52 -forms/NgForm | 1,597 | 0.50 -core/Renderer2 | 1,562 | 0.49 -core/HostListener | 1,501 | 0.47 -common/AsyncPipe | 1,447 | 0.45 -core/ViewContainerRef | 1,367 | 0.42 -common/NgTemplateOutlet | 1,337 | 0.42 -common/Location | 1,306 | 0.41 -platform-browser/BrowserModule | 1,281 | 0.40 -common/DecimalPipe | 1,275 | 0.40 -common/CurrencyPipe | 1,260 | 0.39 -router/RouterLinkActive | 1,231 | 0.38 -core/TemplateRef | 1,212 | 0.38 -forms/FormBuilder | 1,205 | 0.37 -common/http/HttpParams | 1,131 | 0.35 -core/OnChanges | 1,116 | 0.35 -forms/FormControlName | 1,082 | 0.34 -core/Output | 1,067 | 0.33 -common/http/HttpInterceptor | 968 | 0.30 -common/http/HttpRequest | 925 | 0.29 -router/CanActivate | 863 | 0.27 -router | 848 | 0.26 -animations/style | 804 | 0.25 -common/SlicePipe | 799 | 0.25 -router/Event | 796 | 0.25 -common/JsonPipe | 793 | 0.25 -forms/FormArray | 792 | 0.25 -common/CommonModule | 787 | 0.24 -router/NavigationExtras | 776 | 0.24 -core/HostBinding | 732 | 0.23 -core/ContentChild | 719 | 0.22 -core/ViewChildren | 717 | 0.22 -common/http/HttpResponse | 714 | 0.22 -router/ActivatedRouteSnapshot | 700 | 0.22 -common/http | 683 | 0.21 -core/ChangeDetectorRef | 670 | 0.21 -router/NavigationStart | 663 | 0.21 -common/formatDate | 662 | 0.21 -core/ComponentFactoryResolver | 638 | 0.20 -forms/Form | 635 | 0.20 -common/http/HttpErrorResponse | 629 | 0.20 -core/QueryList | 620 | 0.19 -forms | 618 | 0.19 -animations/state | 598 | 0.19 -common | 596 | 0.19 -router/LoadChildren | 593 | 0.18 -router/ParamMap | 588 | 0.18 -animations/trigger | 584 | 0.18 -router/RouterLinkWithHref | 584 | 0.18 -core/AfterViewInit | 579 | 0.18 -forms/ReactiveFormsModule | 576 | 0.18 -common/http/HTTP_INTERCEPTORS | 574 | 0.18 -platform-browser/DomSanitizer | 573 | 0.18 -core/PipeTransform | 572 | 0.18 -core/SimpleChange | 570 | 0.18 -core/SimpleChanges | 568 | 0.18 -forms/NgSelectOption | 560 | 0.17 -common/PercentPipe | 557 | 0.17 -forms/ValidatorFn | 557 | 0.17 -http/RequestOptionsArgs | 551 | 0.17 -animations/animation | 549 | 0.17 -common/NgSwitchCase | 521 | 0.16 -core/testing/async | 518 | 0.16 +状态|URL|浏览量|占比 +---|---|---|---- +[x] |common/http/HttpClient | 7,263 | 2.26 +[x] |common/NgForOf | 6,281 | 1.95 +[x] |forms/NgModel | 5,648 | 1.75 +[x] |core/Component | 5,582 | 1.73 +[x] |common/NgIf | 4,940 | 1.53 +[x] |core/NgModule | 4,097 | 1.27 +[x] |router/Router | 4,049 | 1.26 +[ ] |animations/animate | 3,817 | 1.19 +[ ] |common/NgClass | 3,715 | 1.15 +[ ] |common/DatePipe | 3,576 | 1.11 +[ ] |forms/FormsModule | 3,381 | 1.05 +[x] |core/Input | 3,354 | 1.04 +[x] |core/EventEmitter | 3,202 | 0.99 +[ ] |core/Injectable | 3,177 | 0.99 +[ ] |forms/FormGroup | 3,096 | 0.96 +[ ] |forms/FormControl | 3,034 | 0.94 +[ ] |router/ActivatedRoute | 2,993 | 0.93 +[ ] |forms/AbstractControl | 2,930 | 0.91 +[ ] |router/RouterLink | 2,929 | 0.91 +[ ] |core/ViewChild | 2,870 | 0.89 +[x] |core/Directive | 2,767 | 0.86 +[ ] |router/Routes | 2,331 | 0.72 +[ ] |router/RouterModule | 2,227 | 0.69 +[ ] |router/Route | 2,223 | 0.69 +[ ] |common/http/HttpClientModule | 2,167 | 0.67 +[ ] |core/ElementRef | 2,163 | 0.67 +[ ] |core/OnInit | 2,136 | 0.66 +[ ] |common/UpperCasePipe | 2,078 | 0.65 +[ ] |common/NgStyle | 1,935 | 0.60 +[ ] |router/RouterOutlet | 1,908 | 0.59 +[ ] |forms/Validators | 1,900 | 0.59 +[ ] |common/http/HttpHeaders | 1,790 | 0.56 +[x] |core/Pipe | 1,673 | 0.52 +[ ] |common/NgSwitch | 1,670 | 0.52 +[ ] |forms/NgForm | 1,597 | 0.50 +[ ] |core/Renderer2 | 1,562 | 0.49 +[x] |core/HostListener | 1,501 | 0.47 +[ ] |common/AsyncPipe | 1,447 | 0.45 +[ ] |core/ViewContainerRef | 1,367 | 0.42 +[ ] |common/NgTemplateOutlet | 1,337 | 0.42 +[ ] |common/Location | 1,306 | 0.41 +[ ] |platform-browser/BrowserModule | 1,281 | 0.40 +[ ] |common/DecimalPipe | 1,275 | 0.40 +[ ] |common/CurrencyPipe | 1,260 | 0.39 +[ ] |router/RouterLinkActive | 1,231 | 0.38 +[ ] |core/TemplateRef | 1,212 | 0.38 +[ ] |forms/FormBuilder | 1,205 | 0.37 +[ ] |common/http/HttpParams | 1,131 | 0.35 +[ ] |core/OnChanges | 1,116 | 0.35 +[ ] |forms/FormControlName | 1,082 | 0.34 +[x] |core/Output | 1,067 | 0.33 +[ ] |common/http/HttpInterceptor | 968 | 0.30 +[ ] |common/http/HttpRequest | 925 | 0.29 +[ ] |router/CanActivate | 863 | 0.27 +[ ] |router | 848 | 0.26 +[ ] |animations/style | 804 | 0.25 +[ ] |common/SlicePipe | 799 | 0.25 +[ ] |router/Event | 796 | 0.25 +[ ] |common/JsonPipe | 793 | 0.25 +[ ] |forms/FormArray | 792 | 0.25 +[ ] |common/CommonModule | 787 | 0.24 +[ ] |router/NavigationExtras | 776 | 0.24 +[x] |core/HostBinding | 732 | 0.23 +[x] |core/ContentChild | 719 | 0.22 +[x] |core/ViewChildren | 717 | 0.22 +[ ] |common/http/HttpResponse | 714 | 0.22 +[ ] |router/ActivatedRouteSnapshot | 700 | 0.22 +[ ] |common/http | 683 | 0.21 +[ ] |core/ChangeDetectorRef | 670 | 0.21 +[ ] |router/NavigationStart | 663 | 0.21 +[ ] |common/formatDate | 662 | 0.21 +[ ] |core/ComponentFactoryResolver | 638 | 0.20 +[ ] |forms/Form | 635 | 0.20 +[ ] |common/http/HttpErrorResponse | 629 | 0.20 +[ ] |core/QueryList | 620 | 0.19 +[ ] |forms | 618 | 0.19 +[ ] |animations/state | 598 | 0.19 +[ ] |common | 596 | 0.19 +[ ] |router/LoadChildren | 593 | 0.18 +[ ] |router/ParamMap | 588 | 0.18 +[ ] |animations/trigger | 584 | 0.18 +[ ] |router/RouterLinkWithHref | 584 | 0.18 +[ ] |core/AfterViewInit | 579 | 0.18 +[ ] |forms/ReactiveFormsModule | 576 | 0.18 +[ ] |common/http/HTTP_INTERCEPTORS | 574 | 0.18 +[ ] |platform-browser/DomSanitizer | 573 | 0.18 +[ ] |core/PipeTransform | 572 | 0.18 +[ ] |core/SimpleChange | 570 | 0.18 +[ ] |core/SimpleChanges | 568 | 0.18 +[ ] |forms/NgSelectOption | 560 | 0.17 +[ ] |common/PercentPipe | 557 | 0.17 +[ ] |forms/ValidatorFn | 557 | 0.17 +[ ] |http/RequestOptionsArgs | 551 | 0.17 +[ ] |animations/animation | 549 | 0.17 +[ ] |common/NgSwitchCase | 521 | 0.16 +[ ] |core/testing/async | 518 | 0.16 ## 翻译方式 @@ -111,4 +109,4 @@ core/testing/async | 518 | 0.16 ## 翻译内容 -优先翻译函数主形态（如在 `common/http/src/client.ts` 中它通常都是重载形式中的最后一个），先不必翻译各个重载形态，否则工作量太大。 +优先翻译函数主形态（如在 `common/http/src/client.ts` 中它通常都是重载形式中的最后一个），可以先不翻译各个重载形态。 diff --git a/packages/router/src/router.ts b/packages/router/src/router.ts index 8ce079e304..20a91462ab 100644 --- a/packages/router/src/router.ts +++ b/packages/router/src/router.ts @@ -34,14 +34,18 @@ import {TreeNode, nodeChildrenAsMap} from './utils/tree'; * * Represents the extra options used during navigation. * - * + * 表示在导航时用到的额外选项。 */ export interface NavigationExtras { /** * Enables relative navigation from the current ActivatedRoute. * + * 允许从当前激活的路由进行相对导航。 + * * Configuration: * + * 配置： + * * ``` * [{ * path: 'parent', @@ -58,6 +62,8 @@ export interface NavigationExtras { * * Navigate to list route from child route: * + * 从 `child` 路由导航到 `list` 路由： + * * ``` * @Component({...}) * class ChildComponent { @@ -74,6 +80,8 @@ export interface NavigationExtras { /** * Sets query parameters to the URL. * + * 设置 URL 的查询参数。 + * * ``` * // Navigate to /results?page=1 * this.router.navigate(['/results'], { queryParams: { page: 1 } }); @@ -84,6 +92,8 @@ export interface NavigationExtras { /** * Sets the hash fragment for the URL. * + * 设置 URL 的哈希片段（`#`）。 + * * ``` * // Navigate to /results#top * this.router.navigate(['/results'], { fragment: 'top' }); @@ -94,8 +104,12 @@ export interface NavigationExtras { /** * Preserves the query parameters for the next navigation. * + * 在后续导航时保留查询（`?`）参数。 + * * deprecated, use `queryParamsHandling` instead * + * 已废弃，请用 `queryParamsHandling` 代替 + * * ``` * // Preserve query params from /results?page=1 to /view?page=1 * this.router.navigate(['/view'], { preserveQueryParams: true }); @@ -108,6 +122,8 @@ export interface NavigationExtras { /** * config strategy to handle the query parameters for the next navigation. * + * 配置后续导航时对查询（`?`）参数的处理策略。 + * * ``` * // from /results?page=1 to /view?page=1&page=2 * this.router.navigate(['/view'], { queryParams: { page: 2 }, queryParamsHandling: "merge" }); @@ -117,6 +133,8 @@ export interface NavigationExtras { /** * Preserves the fragment for the next navigation * + * 在后续导航时保留`#`片段 + * * ``` * // Preserve fragment from /results#top to /view#top * this.router.navigate(['/view'], { preserveFragment: true }); @@ -126,6 +144,8 @@ export interface NavigationExtras { /** * Navigates without pushing a new state into history. * + * 导航时不要把新状态记入历史 + * * ``` * // Navigate silently to /view * this.router.navigate(['/view'], { skipLocationChange: true }); @@ -135,6 +155,8 @@ export interface NavigationExtras { /** * Navigates while replacing the current state in history. * + * 导航时不要把当前状态记入历史 + * * ``` * // Navigate to /view * this.router.navigate(['/view'], { replaceUrl: true }); @@ -148,10 +170,14 @@ export interface NavigationExtras { * * Error handler that is invoked when a navigation errors. * + * 错误处理器会在导航出错时调用。 + * * If the handler returns a value, the navigation promise will be resolved with this value. * If the handler throws an exception, the navigation promise will be rejected with * the exception. * + * 如果该处理器返回一个值，那么本次导航返回的 Promise 就会使用这个值进行解析（resolve）。 + * 如果该处理器抛出异常，那么本次导航返回的 Promise 就会使用这个异常进行拒绝（reject）。 * */ export type ErrorHandler = (error: any) => any; @@ -208,8 +234,12 @@ function defaultRouterHook(snapshot: RouterStateSnapshot, runExtras: { * * Provides the navigation and url manipulation capabilities. * + * 提供导航和操纵 URL 的能力。 + * * See `Routes` for more details and examples. * + * 查看 `Routes` 以了解详情和范例。 + * * @ngModule RouterModule * * @@ -231,7 +261,11 @@ export class Router { /** * Error handler that is invoked when a navigation errors. * + * 当导航发生错误时要调用的错误处理器。 + * * See `ErrorHandler` for more information. + * + * 欲知详情，参见 `ErrorHandler`。 */ errorHandler: ErrorHandler = defaultErrorHandler; @@ -239,6 +273,9 @@ export class Router { * Malformed uri error handler is invoked when `Router.parseUrl(url)` throws an * error due to containing an invalid character. The most common case would be a `%` sign * that's not encoded and is not part of a percent encoded sequence. + * + * uri 格式无效错误的处理器，在 `Router.parseUrl(url)` 由于 `url` 包含无效字符而报错时调用。 + * 最常见的情况可能是 `%` 本身既没有被编码，又不是正常 `%` 编码序列的一部分。 */ malformedUriErrorHandler: (error: URIError, urlSerializer: UrlSerializer, @@ -246,6 +283,8 @@ export class Router { /** * Indicates if at least one navigation happened. + * + * 表示是否发生过至少一次导航。 */ navigated: boolean = false; private lastSuccessfulId: number = -1; @@ -262,6 +301,8 @@ export class Router { /** * Extracts and merges URLs. Used for AngularJS to Angular migrations. + * + * 提取并合并 URL。在 AngularJS 向 Angular 迁移时会用到。 */ urlHandlingStrategy: UrlHandlingStrategy = new DefaultUrlHandlingStrategy(); @@ -272,6 +313,10 @@ export class Router { * 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' = 'ignore'; @@ -279,9 +324,17 @@ export class Router { * 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' = 'emptyOnly'; @@ -292,18 +345,31 @@ export class Router { * 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' = 'deferred'; /** * See {@link RouterModule} for more information. + * + * 欲知详情，参见 {@link RouterModule}。 */ relativeLinkResolution: 'legacy'|'corrected' = 'legacy'; /** * Creates the router service. + * + * 创建路由器服务。 */ // TODO: vsavkin make internal after the final is out. constructor( @@ -337,6 +403,8 @@ export class Router { /** * Sets up the location change listener and performs the initial navigation. + * + * 设置位置变化监听器，并执行首次导航。 */ initialNavigation(): void { this.setUpLocationChangeListener(); @@ -347,6 +415,8 @@ export class Router { /** * Sets up the location change listener. + * + * 设置位置变化监听器。 */ setUpLocationChangeListener(): void { // Don't need to use Zone.wrap any more, because zone.js @@ -365,7 +435,10 @@ export class Router { } } - /** The current url */ + /** The current url + * + * 当前 URL + */ get url(): string { return this.serializeUrl(this.currentUrlTree); } /** @internal */ @@ -374,8 +447,12 @@ export class Router { /** * Resets the configuration used for navigation and generating links. * + * 重置供导航和生成链接使用的配置项。 + * * ### Usage * + * ### 用法 + * * ``` * router.resetConfig([ * { path: 'team/:id', component: TeamCmp, children: [ @@ -395,7 +472,10 @@ export class Router { /** @docsNotRequired */ ngOnDestroy(): void { this.dispose(); } - /** Disposes of the router */ + /** Disposes of the router + * + * 销毁路由器 + */ dispose(): void { if (this.locationSubscription) { this.locationSubscription.unsubscribe(); @@ -406,11 +486,18 @@ export class Router { /** * Applies an array of commands to the current url tree and creates a new url tree. * + * 把一个命令数组应用于当前的 URL 树，并创建一个新的 URL 树。 + * * When given an activate route, applies the given commands starting from the route. * When not given a route, applies the given command starting from the root. * + * 如果指定了激活路由，就以该路由为起点应用这些命令。 + * 如果没有指定激活路由，就以根路由为起点应用这些命令。 + * * ### Usage * + * ### 用法 + * * ``` * // create /team/33/user/11 * router.createUrlTree(['/team', 33, 'user', 11]); @@ -476,13 +563,28 @@ export class Router { /** * Navigate based on the provided url. This navigation is always absolute. * + * 基于所提供的 url 进行导航。这种导航永远使用绝对路径。 + * * Returns a promise that: + * + * 返回一个 Promise： + * * - resolves to 'true' when navigation succeeds, + * + * 当导航成功时解析为 `'true'`， + * * - resolves to 'false' when navigation fails, + * + * 当导航失败时解析为 `'false'`， + * * - is rejected when an error happens. * + * 当出错时拒绝（reject）。 + * * ### Usage * + * ### 用法 + * * ``` * router.navigateByUrl("/team/33/user/11"); * @@ -492,6 +594,8 @@ export class Router { * * In opposite to `navigate`, `navigateByUrl` takes a whole URL * and does not apply any delta to the current one. + * + * 与 `navigate` 不同，`navigateByUrl` 只接收完整的 URL，而不会管当前 URL。 */ navigateByUrl(url: string|UrlTree, extras: NavigationExtras = {skipLocationChange: false}): Promise { @@ -505,13 +609,29 @@ export class Router { * Navigate based on the provided array of commands and a starting point. * If no starting route is provided, the navigation is absolute. * + * 基于所提供的命令数组和起点路由进行导航。 + * 如果没有指定起点路由，则从根路由开始进行绝对导航。 + * * Returns a promise that: + * + * 返回一个 Promise： + * * - resolves to 'true' when navigation succeeds, + * + * 当导航成功时解析为 `'true'`， + * * - resolves to 'false' when navigation fails, + * + * 当导航失败时解析为 `'false'`， + * * - is rejected when an error happens. * + * 当出错时拒绝（reject）。 + * * ### Usage * + * ### 用法 + * * ``` * router.navigate(['team', 33, 'user', 11], {relativeTo: route}); * @@ -528,10 +648,16 @@ export class Router { return this.navigateByUrl(this.createUrlTree(commands, extras), extras); } - /** Serializes a `UrlTree` into a string */ + /** Serializes a `UrlTree` into a string + * + * 把 `UrlTree` 序列化为字符串 + */ serializeUrl(url: UrlTree): string { return this.urlSerializer.serialize(url); } - /** Parses a string into a `UrlTree` */ + /** Parses a string into a `UrlTree` + * + * 把字符串解析为 `UrlTree` + */ parseUrl(url: string): UrlTree { let urlTree: UrlTree; try { @@ -542,7 +668,10 @@ export class Router { return urlTree; } - /** Returns whether the url is activated */ + /** Returns whether the url is activated + * + * 返回指定的 `url` 是否处于激活状态 + */ isActive(url: string|UrlTree, exact: boolean): boolean { if (url instanceof UrlTree) { return containsTree(this.currentUrlTree, url, exact); @@ -789,6 +918,8 @@ export class Router { /** * Performs the logic of activating routes. This is a synchronous process by default. While this * is a private method, it could be overridden to make activation asynchronous. + * + * 执行激活路由的逻辑。默认情况下这是一个同步过程。虽然这是一个私有方法，但仍然可以覆盖它，以进行异步激活。 */ private activateRoutes( state: Observable