docs: 翻译 API 文档

Author: Zhicheng WANG

src/cdk-experimental/menu/menu.md

@@ -113,7 +113,7 @@ layed out horizontally or vertically (defaulting to horizontal). If the layout c
 the `orientation` attribute to match in order for the keyboard navigation to work properly and for
 menus to open up in the correct location.
 
-`CdkMenuBar` 指令遵循 [ARIA 菜单栏][menubar]规范，其行为类似桌面应用de 菜单栏。它包括至少一个触发子菜单的 `CdkMenuItem`。菜单栏可以使用水平或垂直布局（默认为水平布局）。如果该布局发生了变化，你必须先设置与之匹配的 `orientation` 属性。这样才能让键盘导航正常工作，并让菜单在正确的位置打开。
+`CdkMenuBar` 指令遵循 [ARIA 菜单栏][menubar]规范，其行为类似桌面应用 de 菜单栏。它包括至少一个触发子菜单的 `CdkMenuItem`。菜单栏可以使用水平或垂直布局（默认为水平布局）。如果该布局发生了变化，你必须先设置与之匹配的 `orientation` 属性。这样才能让键盘导航正常工作，并让菜单在正确的位置打开。
 
 <!-- example({
   "example": "cdk-menu-menubar",

src/cdk/a11y/a11y.md

@@ -212,19 +212,19 @@ defaults to `false` if not specified. The `monitor` method will return an Observ
 
 * `'mouse'` indicates the element was focused with the mouse
 
-  `'mouse'`表示该元素是通过鼠标获得焦点的
+  `'mouse'` 表示该元素是通过鼠标获得焦点的
 
 * `'keyboard'` indicates the element was focused with the keyboard
 
-  `'keyboard'`表示该元素是通过键盘获得焦点的
+  `'keyboard'` 表示该元素是通过键盘获得焦点的
 
 * `'touch'` indicates the element was focused by touching on a touchscreen
 
-  `'touch'`表示该元素是通过触摸屏获得焦点的
+  `'touch'` 表示该元素是通过触摸屏获得焦点的
 
 * `'program'` indicates the element was focused programmatically
 
-  `'program'`表示该元素是通过编程方式获得焦点的
+  `'program'` 表示该元素是通过编程方式获得焦点的
 
 * `null` indicates the element was blurred
 

src/cdk/a11y/fake-mousedown.ts

@@ -12,6 +12,9 @@
  * mousedown events and real mousedown events using the "buttons" property. While
  * real mousedowns will indicate the mouse button that was pressed (e.g. "1" for
  * the left mouse button), faked mousedowns will usually set the property value to 0.
+ *
+ * 当使用键盘激活可获得焦点的元素时，屏幕阅读器通常会触发一个伪 mousedown 事件。我们通常可以使用 “buttons” 属性来区分这些伪 mousedown 事件和真实的 mousedown 事件。真实的 mousedown 会指出被按下的鼠标按键（比如鼠标左键是“1”），而伪造的 mousedown 通常会把该属性值设置为 0。
+ *
  */
 export function isFakeMousedownFromScreenReader(event: MouseEvent): boolean {
   return event.buttons === 0;

src/cdk/accordion/accordion-item.ts

@@ -22,12 +22,20 @@ import {CDK_ACCORDION, CdkAccordion} from './accordion';
 import {BooleanInput, coerceBooleanProperty} from '@angular/cdk/coercion';
 import {Subscription} from 'rxjs';
 
-/** Used to generate unique ID for each accordion item. */
+/**
+ * Used to generate unique ID for each accordion item.
+ *
+ * 用来为每个手风琴条目生成唯一的 ID。
+ *
+ */
 let nextId = 0;
 
 /**
  * An basic directive expected to be extended and decorated as a component.  Sets up all
  * events and attributes needed to be managed by a CdkAccordion parent.
+ *
+ * 一个基本指令，供使用者扩展并改成组件装饰器。设置所有要由 CdkAccordion 的父指令管理的事件和属性。
+ *
  */
 @Directive({
   selector: 'cdk-accordion-item, [cdkAccordionItem]',
@@ -39,26 +47,59 @@ let nextId = 0;
   ],
 })
 export class CdkAccordionItem implements OnDestroy {
-  /** Subscription to openAll/closeAll events. */
+  /**
+   * Subscription to openAll/closeAll events.
+   *
+   * 订阅 openAll / closeAll 事件。
+   *
+   */
   private _openCloseAllSubscription = Subscription.EMPTY;
-  /** Event emitted every time the AccordionItem is closed. */
+  /**
+   * Event emitted every time the AccordionItem is closed.
+   *
+   * 每次关闭此条目时都会发出本事件。
+   *
+   */
   @Output() closed: EventEmitter<void> = new EventEmitter<void>();
-  /** Event emitted every time the AccordionItem is opened. */
+  /**
+   * Event emitted every time the AccordionItem is opened.
+   *
+   * 每次打开此条目时都会发出本事件。
+   *
+   */
   @Output() opened: EventEmitter<void> = new EventEmitter<void>();
-  /** Event emitted when the AccordionItem is destroyed. */
+  /**
+   * Event emitted when the AccordionItem is destroyed.
+   *
+   * 当此条目被销毁时会发出本事件。
+   *
+   */
   @Output() destroyed: EventEmitter<void> = new EventEmitter<void>();
 
   /**
    * Emits whenever the expanded state of the accordion changes.
    * Primarily used to facilitate two-way binding.
+   *
+   * 每当手风琴展开状态发生变化时，就会触发。主要是为了方便进行双向绑定。
+   *
    * @docs-private
    */
   @Output() expandedChange: EventEmitter<boolean> = new EventEmitter<boolean>();
 
-  /** The unique AccordionItem id. */
+  /**
+   * The unique AccordionItem id.
+   *
+   * AccordionItem 的唯一 id。
+   *
+   */
   readonly id: string = `cdk-accordion-child-${nextId++}`;
 
-  /** Whether the AccordionItem is expanded. */
+  /**
+   * Whether the AccordionItem is expanded.
+   *
+   * 此条目是否已经展开了。
+   *
+   */
   @Input()
   get expanded(): any { return this._expanded; }
   set expanded(expanded: any) {
@@ -74,6 +115,9 @@ export class CdkAccordionItem implements OnDestroy {
         /**
          * In the unique selection dispatcher, the id parameter is the id of the CdkAccordionItem,
          * the name value is the id of the accordion.
+         *
+         * 在唯一选项派发器中，其 id 参数是 CdkAccordionItem 的 id，其 name 的值是这个手风琴的 id。
+         *
          */
         const accordionId = this.accordion ? this.accordion.id : this.id;
         this._expansionDispatcher.notify(this.id, accordionId);
@@ -88,13 +132,23 @@ export class CdkAccordionItem implements OnDestroy {
   }
   private _expanded = false;
 
-  /** Whether the AccordionItem is disabled. */
+  /**
+   * Whether the AccordionItem is disabled.
+   *
+   * 此条目是否被禁用了。
+   *
+   */
   @Input()
   get disabled() { return this._disabled; }
   set disabled(disabled: any) { this._disabled = coerceBooleanProperty(disabled); }
   private _disabled: boolean = false;
 
-  /** Unregister function for _expansionDispatcher. */
+  /**
+   * Unregister function for \_expansionDispatcher.
+   *
+   * 取消注册 \_expansionDispatcher 的函数。
+   *
+   */
   private _removeUniqueSelectionListener: () => void = () => {};
 
   constructor(@Optional() @Inject(CDK_ACCORDION) @SkipSelf() public accordion: CdkAccordion,
@@ -114,7 +168,12 @@ export class CdkAccordionItem implements OnDestroy {
     }
   }
 
-  /** Emits an event for the accordion item being destroyed. */
+  /**
+   * Emits an event for the accordion item being destroyed.
+   *
+   * 发出此条目被销毁的事件。
+   *
+   */
   ngOnDestroy() {
     this.opened.complete();
     this.closed.complete();
@@ -124,21 +183,36 @@ export class CdkAccordionItem implements OnDestroy {
     this._openCloseAllSubscription.unsubscribe();
   }
 
-  /** Toggles the expanded state of the accordion item. */
+  /**
+   * Toggles the expanded state of the accordion item.
+   *
+   * 切换此条目的展开状态。
+   *
+   */
   toggle(): void {
     if (!this.disabled) {
       this.expanded = !this.expanded;
     }
   }
 
-  /** Sets the expanded state of the accordion item to false. */
+  /**
+   * Sets the expanded state of the accordion item to false.
+   *
+   * 把此条目的展开状态设置为 false。
+   *
+   */
   close(): void {
     if (!this.disabled) {
       this.expanded = false;
     }
   }
 
-  /** Sets the expanded state of the accordion item to true. */
+  /**
+   * Sets the expanded state of the accordion item to true.
+   *
+   * 把此条目的展开状态设置为 true。
+   *
+   */
   open(): void {
     if (!this.disabled) {
       this.expanded = true;

src/cdk/accordion/accordion.ts

@@ -10,46 +10,93 @@ import {BooleanInput, coerceBooleanProperty} from '@angular/cdk/coercion';
 import {Directive, InjectionToken, Input, OnChanges, OnDestroy, SimpleChanges} from '@angular/core';
 import {Subject} from 'rxjs';
 
-/** Used to generate unique ID for each accordion. */
+/**
+ * Used to generate unique ID for each accordion.
+ *
+ * 用于为每个手风琴生成唯一的 ID。
+ *
+ */
 let nextId = 0;
 
 /**
  * Injection token that can be used to reference instances of `CdkAccordion`. It serves
  * as alternative token to the actual `CdkAccordion` class which could cause unnecessary
  * retention of the class and its directive metadata.
+ *
+ * 这个注入令牌可以用来引用一些 `CdkAccordion` 实例。它可以作为真实 `CdkAccordion` 类的备用令牌，直接使用该类可能导致该类及其指令的元数据无法被优化掉。
+ *
  */
 export const CDK_ACCORDION = new InjectionToken<CdkAccordion>('CdkAccordion');
 
 /**
  * Directive whose purpose is to manage the expanded state of CdkAccordionItem children.
+ *
+ * 该指令的用途是管理 CdkAccordionItem 子组件的展开状态。
+ *
  */
 @Directive({
   selector: 'cdk-accordion, [cdkAccordion]',
   exportAs: 'cdkAccordion',
-  providers: [{provide: CDK_ACCORDION, useExisting: CdkAccordion}],
+  providers: [{ provide: CDK_ACCORDION, useExisting: CdkAccordion }],
 })
 export class CdkAccordion implements OnDestroy, OnChanges {
-  /** Emits when the state of the accordion changes */
+  /**
+   * Emits when the state of the accordion changes
+   *
+   * 当手风琴状态发生变化时会触发
+   *
+   */
   readonly _stateChanges = new Subject<SimpleChanges>();
 
-  /** Stream that emits true/false when openAll/closeAll is triggered. */
+  /**
+   * Stream that emits true/false when openAll/closeAll is triggered.
+   *
+   * 当 openAll/closeAll 被触发时，此流会发出 true/false。
+   *
+   */
   readonly _openCloseAllActions: Subject<boolean> = new Subject<boolean>();
 
-  /** A readonly id value to use for unique selection coordination. */
+  /**
+   * A readonly id value to use for unique selection coordination.
+   *
+   * 一个只读的 id 值，用于在单选模式下进行协调。
+   *
+   */
   readonly id = `cdk-accordion-${nextId++}`;
 
-  /** Whether the accordion should allow multiple expanded accordion items simultaneously. */
+  /**
+   * Whether the accordion should allow multiple expanded accordion items simultaneously.
+   *
+   * 手风琴是否应该允许同时展开多个手风琴条目。
+   *
+   */
   @Input()
-  get multi(): boolean { return this._multi; }
-  set multi(multi: boolean) { this._multi = coerceBooleanProperty(multi); }
+  get multi(): boolean {
+    return this._multi;
+  }
+
+  set multi(multi: boolean) {
+    this._multi = coerceBooleanProperty(multi);
+  }
+
   private _multi: boolean = false;
 
-  /** Opens all enabled accordion items in an accordion where multi is enabled. */
+  /**
+   * Opens all enabled accordion items in an accordion where multi is enabled.
+   *
+   * 允许多选时，可以同时打开手风琴中的所有可用条目。
+   *
+   */
   openAll(): void {
     this._openCloseAll(true);
   }
 
-  /** Closes all enabled accordion items in an accordion where multi is enabled. */
+  /**
+   * Closes all enabled accordion items in an accordion where multi is enabled.
+   *
+   * 允许多选时，可以同时关闭手风琴中的所有可用条目。
+   *
+   */
   closeAll(): void {
     this._openCloseAll(false);
   }

src/cdk/bidi/dir-document-token.ts

@@ -14,14 +14,22 @@ import {inject, InjectionToken} from '@angular/core';
  * Injection token used to inject the document into Directionality.
  * This is used so that the value can be faked in tests.
  *
+ * 用于把 document 注入到 Directionality 中的注入令牌。这是为了可以在测试中伪造该值。
+ *
  * We can't use the real document in tests because changing the real `dir` causes geometry-based
  * tests in Safari to fail.
  *
+ * 我们不能在测试中使用真正的 document，因为改变真实的 `dir` 会导致 Safari 中基于几何的测试失败。
+ *
  * We also can't re-provide the DOCUMENT token from platform-brower because the unit tests
  * themselves use things like `querySelector` in test code.
  *
+ * 我们也无法从 platform-browser 中重新提供 DOCUMENT 令牌，因为单元测试本身会在测试代码中使用 `querySelector` 等。
+ *
  * This token is defined in a separate file from Directionality as a workaround for
- * https://github.com/angular/angular/issues/22559
+ * <https://github.com/angular/angular/issues/22559>
+ *
+ * 这个令牌是在 Directionality 的一个独立文件中定义的，用于解决 <https://github.com/angular/angular/issues/22559> 问题。
  *
  * @docs-private
  */