docs: 翻译 tree 部分的剩余文档

Author: Zhicheng WANG

src/material/tree/data-source/flat-data-source.ts

@@ -15,7 +15,12 @@ import {map, take} from 'rxjs/operators';
  * Tree flattener to convert a normal type of node to node with children & level information.
  * Transform nested nodes of type `T` to flattened nodes of type `F`.
  *
+ * 树展平器，用于将普通类型的节点转换为具有子级和级别信息的节点。把 `T` 型嵌套节点转换为 `F` 型扁平节点。
+ *
  * For example, the input data of type `T` is nested, and contains its children data:
+ *
+ * 例如，类型为 `T` 的输入数据是嵌套的，并包含其子数据：
+ *
  *   SomeNode: {
  *     key: 'Fruits',
  *     children: [
@@ -27,7 +32,11 @@ import {map, take} from 'rxjs/operators';
  *      }
  *    ]
  *  }
+ *
  *  After flattener flatten the tree, the structure will become
+ *
+ * 当展平之后，其结构变为：
+ *
  *  SomeNode: {
  *    key: 'Fruits',
  *    expandable: true,
@@ -43,9 +52,9 @@ import {map, take} from 'rxjs/operators';
  *   expandable: false,
  *   level: 2
  * }
+ *
  * and the output flattened type is `F` with additional information.
  *
- * For example, the input data of type `T` is nested, and contains its children data: SomeNode: { key: 'Fruits', children: \[ NodeOne: { key: 'Apple', }, NodeTwo: { key: 'Pear', } ] } After flattener flatten the tree, the structure will become SomeNode: { key: 'Fruits', expandable: true, level: 1 }, NodeOne: { key: 'Apple', expandable: false, level: 2 }, NodeTwo: { key: 'Pear', expandable: false, level: 2 } and the output flattened type is `F` with additional information.
  *
  */
 export class MatTreeFlattener<T, F, K = F> {
@@ -89,6 +98,9 @@ export class MatTreeFlattener<T, F, K = F> {
    * Flatten a list of node type T to flattened version of node F.
    * Please note that type T may be nested, and the length of `structuredData` may be different
    * from that of returned list `F[]`.
+   *
+   * 将节点类型为 T 的列表展平为节点类型为 F 的展平版本。请注意，类型 T 可能是嵌套的，而 `structuredData` 的长度可能与返回列表 `F[]` 的长度不同。
+   *
    */
   flattenNodes(structuredData: T[]): F[] {
     let resultNodes: F[] = [];
@@ -99,6 +111,9 @@ export class MatTreeFlattener<T, F, K = F> {
   /**
    * Expand flattened node with current expansion status.
    * The returned list may have different length.
+   *
+   * 根据当前展开状态展开已展平的节点。返回的列表长度可能不同。
+   *
    */
   expandFlattenedNodes(nodes: F[], treeControl: TreeControl<F, K>): F[] {
     let results: F[] = [];
@@ -127,6 +142,9 @@ export class MatTreeFlattener<T, F, K = F> {
  * to `MatTree`.
  * The nested tree nodes of type `T` are flattened through `MatTreeFlattener`, and converted
  * to type `F` for `MatTree` to consume.
+ *
+ * 扁平树的数据源。数据源需要处理树节点的展开/折叠，并将数据提更改为 `MatTree`。`T` 型的嵌套树节点由 `MatTreeFlattener` 展平，并转换为 `F` 型，供 `MatTree` 使用。
+ *
  */
 export class MatTreeFlatDataSource<T, F, K = F> extends DataSource<F> {
   _flattenedData = new BehaviorSubject<F[]>([]);

src/material/tree/data-source/nested-data-source.ts

@@ -13,14 +13,22 @@ import {map} from 'rxjs/operators';
 /**
  * Data source for nested tree.
  *
+ * 嵌套树的数据源。
+ *
  * The data source for nested tree doesn't have to consider node flattener, or the way to expand
  * or collapse. The expansion/collapsion will be handled by TreeControl and each non-leaf node.
+ *
+ * 嵌套树的数据源不必考虑节点展平器，也不必考虑展开或折叠的方式。展开/折叠将由 TreeControl 和每个非叶节点处理。
+ *
  */
 export class MatTreeNestedDataSource<T> extends DataSource<T> {
   _data = new BehaviorSubject<T[]>([]);
 
   /**
    * Data for the nested tree
+   *
+   * 嵌套树的数据
+   *
    */
   get data() { return this._data.value; }
   set data(value: T[]) { this._data.next(value); }

src/material/tree/testing/node-harness.ts

@@ -14,9 +14,19 @@ import {
 import {TreeNodeHarnessFilters} from './tree-harness-filters';
 import {coerceBooleanProperty, coerceNumberProperty} from '@angular/cdk/coercion';
 
-/** Harness for interacting with a standard Angular Material tree node. */
+/**
+ * Harness for interacting with a standard Angular Material tree node.
+ *
+ * 与标准 Angular Material 树节点进行交互的组件测试工具。
+ *
+ */
 export class MatTreeNodeHarness extends ContentContainerComponentHarness<string> {
-  /** The selector of the host element of a `MatTreeNode` instance. */
+  /**
+   * The selector of the host element of a `MatTreeNode` instance.
+   *
+   * `MatTreeNode` 实例的宿主元素的选择器。
+   *
+   */
   static hostSelector = '.mat-tree-node, .mat-nested-tree-node';
 
   _toggle = this.locatorForOptional('[matTreeNodeToggle]');
@@ -27,6 +37,9 @@ export class MatTreeNodeHarness extends ContentContainerComponentHarness<string>
    * 获取一个可用来使用指定属性搜索树节点的 `HarnessPredicate`。
    *
    * @param options Options for narrowing the search
+   *
+   * 缩小搜索范围的选项
+   *
    * @return a `HarnessPredicate` configured with the given options.
    *
    * 用指定选项配置过的 `HarnessPredicate` 服务。
@@ -35,42 +48,77 @@ export class MatTreeNodeHarness extends ContentContainerComponentHarness<string>
     return getNodePredicate(MatTreeNodeHarness, options);
   }
 
-  /** Whether the tree node is expanded. */
+  /**
+   * Whether the tree node is expanded.
+   *
+   * 此树节点是否已展开。
+   *
+   */
   async isExpanded(): Promise<boolean> {
     return coerceBooleanProperty(await (await this.host()).getAttribute('aria-expanded'));
   }
 
-  /** Whether the tree node is disabled. */
+  /**
+   * Whether the tree node is disabled.
+   *
+   * 此树节点是否已禁用。
+   *
+   */
   async isDisabled(): Promise<boolean> {
     return coerceBooleanProperty(await (await this.host()).getProperty('aria-disabled'));
   }
 
-  /** Gets the level of the tree node. Note that this gets the aria-level and is 1 indexed. */
+  /**
+   * Gets the level of the tree node. Note that this gets the aria-level and is 1 indexed.
+   *
+   * 获取此树节点的级别。请注意，这将获得 aria-level，并且起始索引为 1。
+   *
+   */
   async getLevel(): Promise<number> {
     return coerceNumberProperty(await (await this.host()).getAttribute('aria-level'));
   }
 
-  /** Gets the tree node's text. */
+  /**
+   * Gets the tree node's text.
+   *
+   * 获取此树节点的文本。
+   *
+   */
   async getText(): Promise<string> {
     return (await this.host()).text({exclude: '.mat-tree-node, .mat-nested-tree-node, button'});
   }
 
-  /** Toggles node between expanded/collapsed. Only works when node is not disabled. */
+  /**
+   * Toggles node between expanded/collapsed. Only works when node is not disabled.
+   *
+   * 在展开/折叠之间切换节点。仅在未禁用节点时起作用。
+   *
+   */
   async toggle(): Promise<void> {
     const toggle = await this._toggle();
     if (toggle) {
       return toggle.click();
     }
   }
 
-  /** Expands the node if it is collapsed. Only works when node is not disabled. */
+  /**
+   * Expands the node if it is collapsed. Only works when node is not disabled.
+   *
+   * 如果节点已折叠，则将其展开。仅在未禁用节点时起作用。
+   *
+   */
   async expand(): Promise<void> {
     if (!(await this.isExpanded())) {
       await this.toggle();
     }
   }
 
-  /** Collapses the node if it is expanded. Only works when node is not disabled. */
+  /**
+   * Collapses the node if it is expanded. Only works when node is not disabled.
+   *
+   * 如果节点已展开，则使其折叠。仅在未禁用节点时起作用。
+   *
+   */
   async collapse(): Promise<void> {
     if (await this.isExpanded()) {
       await this.toggle();

src/material/tree/testing/tree-harness-filters.ts

@@ -8,11 +8,21 @@
 
 import {BaseHarnessFilters} from '@angular/cdk/testing';
 
-/** A set of criteria that can be used to filter a list of tree harness instances */
+/**
+ * A set of criteria that can be used to filter a list of tree harness instances
+ *
+ * 一组条件，可用于筛选树测试工具实例的列表
+ *
+ */
 export interface TreeHarnessFilters extends BaseHarnessFilters {
 }
 
-/** A set of criteria that can be used to filter a list of node harness instances. */
+/**
+ * A set of criteria that can be used to filter a list of node harness instances.
+ *
+ * 一组条件，可用于筛选节点测试工具实例的列表。
+ *
+ */
 export interface TreeNodeHarnessFilters extends BaseHarnessFilters {
   /**
    * Only find instances whose text matches the given value.
@@ -22,12 +32,27 @@ export interface TreeNodeHarnessFilters extends BaseHarnessFilters {
    */
   text?: string | RegExp;
 
-  /** Only find instances whose disabled state matches the given value. */
+  /**
+   * Only find instances whose disabled state matches the given value.
+   *
+   * 仅查找其禁用状态与给定值匹配的实例。
+   *
+   */
   disabled?: boolean;
 
-  /** Only find instances whose expansion state matches the given value. */
+  /**
+   * Only find instances whose expansion state matches the given value.
+   *
+   * 仅查找其展开状态与给定值匹配的实例。
+   *
+   */
   expanded?: boolean;
 
-  /** Only find instances whose level matches the given value. */
+  /**
+   * Only find instances whose level matches the given value.
+   *
+   * 仅查找其级别与给定值匹配的实例。
+   *
+   */
   level?: number;
 }

src/material/tree/testing/tree-harness.ts

@@ -22,7 +22,12 @@ export type TextTree = {
  *
  */
 export class MatTreeHarness extends ComponentHarness {
-  /** The selector for the host element of a `MatTableHarness` instance. */
+  /**
+   * The selector for the host element of a `MatTableHarness` instance.
+   *
+   * `MatTableHarness` 实例的宿主元素选择器。
+   *
+   */
   static hostSelector = '.mat-tree';
 
   /**
@@ -31,6 +36,9 @@ export class MatTreeHarness extends ComponentHarness {
    * 获取一个可用来使用指定属性搜索树的 `HarnessPredicate`。
    *
    * @param options Options for narrowing the search
+   *
+   * 缩小搜索范围的选项
+   *
    * @return a `HarnessPredicate` configured with the given options.
    *
    * 用指定选项配置过的 `HarnessPredicate` 服务。
@@ -39,7 +47,12 @@ export class MatTreeHarness extends ComponentHarness {
     return new HarnessPredicate(MatTreeHarness, options);
   }
 
-  /** Gets all of the nodes in the tree. */
+  /**
+   * Gets all of the nodes in the tree.
+   *
+   * 获取树中的所有节点。
+   *
+   */
   async getNodes(filter: TreeNodeHarnessFilters = {}): Promise<MatTreeNodeHarness[]> {
     return this.locatorForAll(MatTreeNodeHarness.with(filter))();
   }
@@ -49,6 +62,9 @@ export class MatTreeHarness extends ComponentHarness {
    * If a node is under an unexpanded node it will not be included.
    * Eg.
    * Tree (all nodes expanded):
+   *
+   * 获取可见树结构的对象表示形式。如果某个节点位于未展开的节点之下，则不会包含该节点。例如下面这棵树（所有节点都已展开）：
+   *
    * `<mat-tree>
    *   <mat-tree-node>Node 1<mat-tree-node>
    *   <mat-nested-tree-node>
@@ -66,7 +82,10 @@ export class MatTreeHarness extends ComponentHarness {
    * </mat-tree>`
    *
    * Tree structure:
-   * {
+   *
+   * 树结构：
+   *
+   * `{
    *  children: \[
    *    {
    *      text: 'Node 1',
@@ -84,7 +103,7 @@ export class MatTreeHarness extends ComponentHarness {
    *      ]
    *    }
    *  ]
-   * };
+   * };`
    */
   async getTreeStructure(): Promise<TextTree> {
     const nodes = await this.getNodes();
@@ -96,9 +115,21 @@ export class MatTreeHarness extends ComponentHarness {
 
   /**
    * Recursively collect the structured text of the tree nodes.
+   *
+   * 递归收集树节点的结构化文本。
+   *
    * @param nodes A list of tree nodes
+   *
+   * 树节点列表
+   *
    * @param level The level of nodes that are being accounted for during this iteration
+   *
+   * 在此迭代期间要考虑的各个节点的级别
+   *
    * @param parentExpanded Whether the parent of the first node in param nodes is expanded
+   *
+   * 参数节点中第一个节点的父节点是否已展开
+   *
    */
   private _getTreeStructure(nodes: [number, string, boolean][], level: number,
                                      parentExpanded: boolean): TextTree {