docs: 翻译内部 API 文档

Author: Zhicheng WANG

src/cdk/a11y/focus-trap/configurable-focus-trap-factory.ts

@@ -65,6 +65,9 @@ export class ConfigurableFocusTrapFactory {
 
   /**
    * @deprecated Pass a config object instead of the `deferCaptureElements` flag.
+   *
+   * 传递一个配置对象，而不是 `deferCaptureElements` 标志。
+   *
    * @breaking-change 11.0.0
    */
   create(element: HTMLElement, deferCaptureElements: boolean): ConfigurableFocusTrap;

src/cdk/drag-drop/directives/drop-list.ts

@@ -50,6 +50,9 @@ let _uniqueIdCounter = 0;
 /**
  * Internal compile-time-only representation of a `CdkDropList`.
  * Used to avoid circular import issues between the `CdkDropList` and the `CdkDrag`.
+ *
+ * `CdkDropList` 内部的仅编译时表示法。 用来解决 `CdkDropList` 和 `CdkDrag` 之间的循环导入问题。
+ *
  * @docs-private
  */
 export interface CdkDropListInternal extends CdkDropList {}

src/cdk/drag-drop/drag-ref.ts

@@ -1728,7 +1728,7 @@ export class DragRef<T = any> {
   /**
    * Cleans up any cached element dimensions that we don't need after dragging has stopped.
    *
-   * 清理拖动停止后我们不再需要的所有缓存元素尺寸。
+   * 清理拖动停止后我们不再需要的所有缓存元素规格。
    *
    */
   private _cleanupCachedDimensions() {
@@ -1986,7 +1986,7 @@ function getRootNode(viewRef: EmbeddedViewRef<any>, _document: Document): HTMLEl
  *
  * @param sourceRect Dimensions of the source element.
  *
- * 源元素的尺寸。
+ * 源元素的规格。
  *
  */
 function matchElementSize(target: HTMLElement, sourceRect: ClientRect): void {

src/cdk/drag-drop/drag-styling.ts

@@ -77,7 +77,7 @@ export function toggleNativeDragInteractions(element: HTMLElement, enable: boole
 /**
  * Toggles whether an element is visible while preserving its dimensions.
  *
- * 在保留元素尺寸的同时，切换元素是否可见。
+ * 在保留元素规格的同时，切换元素是否可见。
  *
  * @param element Element whose visibility to toggle
  *

src/cdk/drag-drop/drop-list-ref.ts

@@ -61,7 +61,7 @@ interface CachedItemPosition {
   /**
    * Dimensions of the item.
    *
-   * 此条目的尺寸。
+   * 此条目的规格。
    *
    */
   clientRect: ClientRect;
@@ -246,7 +246,7 @@ export class DropListRef<T = any> {
   /**
    * Cache of the dimensions of all the items inside the container.
    *
-   * 缓存容器内所有条目的尺寸。
+   * 缓存容器内所有条目的规格。
    *
    */
   private _itemPositions: CachedItemPosition[] = [];
@@ -1478,7 +1478,7 @@ function incrementHorizontalScroll(node: HTMLElement | Window, amount: number) {
  *
  * @param clientRect Dimensions of the node.
  *
- * 该节点的尺寸。
+ * 该节点的规格。
  *
  * @param pointerY Position of the user's pointer along the y axis.
  *
@@ -1505,7 +1505,7 @@ function getVerticalScrollDirection(clientRect: ClientRect, pointerY: number) {
  *
  * @param clientRect Dimensions of the node.
  *
- * 该节点的尺寸。
+ * 该节点的规格。
  *
  * @param pointerX Position of the user's pointer along the x axis.
  *

src/cdk/drag-drop/parent-position-tracker.ts

@@ -23,7 +23,7 @@ interface ScrollPosition {
 /**
  * Keeps track of the scroll position and dimensions of the parents of an element.
  *
- * 跟踪元素父级的滚动位置和尺寸。
+ * 跟踪元素父级的滚动位置和规格。
  *
  */
 export class ParentPositionTracker {

src/cdk/overlay/position/connected-position-strategy.ts

@@ -34,11 +34,17 @@ import {PositionStrategy} from './position-strategy';
  * 放置浮层的策略。使用此策略，可以为浮层提供相对于某原点元素的隐式位置。此相对位置是指浮层元素上的点相对于所连接的原点元素上的点。例如，一个基本的下拉列表将其原点的左下角连接到此浮层的左上角。
  *
  * @deprecated Use `FlexibleConnectedPositionStrategy` instead.
+ *
+ * 请改用 `FlexibleConnectedPositionStrategy` 。
+ *
  * @breaking-change 8.0.0
  */
 export class ConnectedPositionStrategy implements PositionStrategy {
   /**
    * Reference to the underlying position strategy to which all the API calls are proxied.
+   *
+   * 所有 API 调用所基于的底层定位策略的引用。
+   *
    * @docs-private
    */
   _positionStrategy: FlexibleConnectedPositionStrategy;
@@ -131,6 +137,9 @@ export class ConnectedPositionStrategy implements PositionStrategy {
   /**
    * Updates the position of the overlay element, using whichever preferred position relative
    * to the origin fits on-screen.
+   *
+   * 使用屏幕上适合于原点的任何首选位置来更新浮层元素的位置。
+   *
    * @docs-private
    */
   apply(): void {

src/cdk/overlay/position/connected-position.ts

@@ -13,7 +13,7 @@ export type HorizontalConnectionPos = 'start' | 'center' | 'end';
 /**
  * Vertical dimension of a connection point on the perimeter of the origin or overlay element.
  *
- * 在原点周边或浮层元素上的连接点的垂直尺寸。
+ * 在原点周边或浮层元素上的连接点的垂直规格。
  *
  */
 export type VerticalConnectionPos = 'top' | 'center' | 'bottom';
@@ -97,31 +97,32 @@ export class ConnectionPositionPair {
  * Set of properties regarding the position of the origin and overlay relative to the viewport
  * with respect to the containing Scrollable elements.
  *
+ * 一组属性，表示原点和浮层相对于包含可滚动元素的视口的位置。
+ *
  * The overlay and origin are clipped if any part of their bounding client rectangle exceeds the
  * bounds of any one of the strategy's Scrollable's bounding client rectangle.
  *
+ * 如果浮层和原点的边界矩形的任何部分超出了本策略的可滚动边界矩形，则将对其进行裁剪。
+ *
  * The overlay and origin are outside view if there is no overlap between their bounding client
  * rectangle and any one of the strategy's Scrollable's bounding client rectangle.
  *
- * ```
- *   -----------                    -----------
- *   | outside |                    | clipped |
- *   |  view   |              --------------------------
- *   |         |              |     |         |        |
- *   ----------               |     -----------        |
- * ```
+ * 如果浮层和原点的边界矩形与本策略的可滚动对象边界矩形中的任何一个都没有重叠，则浮层和原点位于外部视图中。
  *
- *  \--------------------------    \|                        \|
+ *       -----------                    -----------
+ *       | outside |                    | clipped |
+ *       |  view   |              --------------------------
+ *       |         |              |     |         |        |
+ *       ----------               |     -----------        |
+ *  --------------------------    |                        |
  *  |                        |    |      Scrollable        |
- *  \|                        \|    \|                        \|
- *  \|                        \|     --------------------------
+ *  |                        |    |                        |
+ *  |                        |     --------------------------
  *  |      Scrollable        |
- *  \|                        \|
+ *  |                        |
+ *  --------------------------
  *
- * \-------------------------- | | | | | Scrollable | | | | | | | -------------------------- | Scrollable | | |
- *
- * * * *
- * @docs-private
+ *  @docs-private
  */
 export class ScrollingVisibility {
   isOriginClipped: boolean;
@@ -133,7 +134,7 @@ export class ScrollingVisibility {
 /**
  * The change event emitted by the strategy when a fallback position is used.
  *
- * 使用后备位置时，本策略发出的更改事件。
+ * 使用回退位置时，本策略发出的更改事件。
  *
  */
 export class ConnectedOverlayPositionChange {
@@ -146,8 +147,17 @@ export class ConnectedOverlayPositionChange {
 
 /**
  * Validates whether a vertical position property matches the expected values.
+ *
+ * 验证垂直位置属性是否与期望值匹配。
+ *
  * @param property Name of the property being validated.
+ *
+ * 要验证的属性的名称。
+ *
  * @param value Value of the property being validated.
+ *
+ * 待验证属性的值。
+ *
  * @docs-private
  */
 export function validateVerticalPosition(property: string, value: VerticalConnectionPos) {
@@ -159,8 +169,17 @@ export function validateVerticalPosition(property: string, value: VerticalConnec
 
 /**
  * Validates whether a horizontal position property matches the expected values.
+ *
+ * 验证水平位置属性是否与期望值匹配。
+ *
  * @param property Name of the property being validated.
+ *
+ * 要验证的属性的名称。
+ *
  * @param value Value of the property being validated.
+ *
+ * 待验证属性的值。
+ *
  * @docs-private
  */
 export function validateHorizontalPosition(property: string, value: HorizontalConnectionPos) {

src/cdk/overlay/position/flexible-connected-position-strategy.ts

@@ -139,15 +139,15 @@ export class FlexibleConnectedPositionStrategy implements PositionStrategy {
   /**
    * Cached overlay dimensions
    *
-   * 缓存的浮层尺寸
+   * 缓存的浮层规格
    *
    */
   private _overlayRect: ClientRect;
 
   /**
    * Cached viewport dimensions
    *
-   * 缓存的视口尺寸
+   * 缓存的视口规格
    *
    */
   private _viewportRect: ClientRect;
@@ -334,15 +334,31 @@ export class FlexibleConnectedPositionStrategy implements PositionStrategy {
    * Updates the position of the overlay element, using whichever preferred position relative
    * to the origin best fits on-screen.
    *
+   * 使用相对于屏幕最适合原点的首选位置来更新叠加元素的位置。
+   *
    * The selection of a position goes as follows:
    *
+   * 位置的选择逻辑如下：
+   *
    * - If any positions fit completely within the viewport as-is,
    *     choose the first position that does so.
+   *
+   *   如果任何位置能完全按原样放置在视口中，请选择第一个适合的位置。
+   *
    * - If flexible dimensions are enabled and at least one satifies the given minimum width/height,
    *     choose the position with the greatest available size modified by the positions' weight.
+   *
+   *   如果启用了灵活规格，并且其中至少有一个满足给定的最小宽度/高度，请选择最大的可用规格（根据位置的权重修订）的位置。
+   *
    * - If pushing is enabled, take the position that went off-screen the least and push it
    *     on-screen.
+   *
+   *   如果启用了推入功能，则让离开屏幕的位置尽可能少，然后将其推入屏幕。
+   *
    * - If none of the previous criteria were met, use the position that goes off-screen the least.
+   *
+   *   如果没有满足先前的条件，就使用屏幕外部分最少的位置。
+   *
    * @docs-private
    */
   apply(): void {
@@ -851,7 +867,7 @@ export class FlexibleConnectedPositionStrategy implements PositionStrategy {
    *
    * @param overlay Dimensions of the overlay.
    *
-   * 浮层的尺寸。
+   * 浮层的规格。
    *
    * @param scrollPosition Current viewport scroll position.
    *
@@ -1587,7 +1603,7 @@ interface BoundingBoxRect {
 /**
  * Record of measures determining how well a given position will fit with flexible dimensions.
  *
- * 确定指定位置与灵活尺寸的适应程度的测量记录。
+ * 确定指定位置与灵活规格的适应程度的测量记录。
  *
  */
 interface FlexibleFit {

src/cdk/overlay/position/global-position-strategy.ts

@@ -138,8 +138,10 @@ export class GlobalPositionStrategy implements PositionStrategy {
    * @param value New width for the overlay
    *
    * 浮层的新宽度
-   *
    * @deprecated Pass the `width` through the `OverlayConfig`.
+   *
+   * 通过 `OverlayConfig` 传递 `width` 。
+   *
    * @breaking-change 8.0.0
    */
   width(value: string = ''): this {
@@ -160,8 +162,10 @@ export class GlobalPositionStrategy implements PositionStrategy {
    * @param value New height for the overlay
    *
    * 浮层的新高度
-   *
    * @deprecated Pass the `height` through the `OverlayConfig`.
+   *
+   * 通过 `OverlayConfig` 传递 `height` 。
+   *
    * @breaking-change 8.0.0
    */
   height(value: string = ''): this {
@@ -210,6 +214,9 @@ export class GlobalPositionStrategy implements PositionStrategy {
 
   /**
    * Apply the position to the element.
+   *
+   * 将此位置应用于元素。
+   *
    * @docs-private
    */
   apply(): void {
@@ -258,6 +265,9 @@ export class GlobalPositionStrategy implements PositionStrategy {
 
   /**
    * Cleans up the DOM changes from the position strategy.
+   *
+   * 从定位策略中清除 DOM 更改。
+   *
    * @docs-private
    */
   dispose(): void {