docs: perf element api docs (#6575)

* docs: node configuration options

* docs: modify node

* docs: add node animation doc

* docs: update grammar

* docs: edge configurations

* docs: update base node links

* docs: update base edge doc

* refactor: complete graph options comment

* docs: add chinese combo options docs

* docs: element options docs

* docs: update element demos

* docs: update element docs

* docs: update custom-element doc

* docs: fix typo

---------

Co-authored-by: Aaron <yangtao.yangtao@antgroup.com>

packages/g6/src/behaviors/optimize-viewport-transform.ts

@@ -24,7 +24,7 @@ export interface OptimizeViewportTransformOptions extends BaseBehaviorOptions {
   /**
    * <zh/> 指定始终显示的图形元素。应用此交互后，在画布操作过程中，只有通过该属性指定的图形元素会保持可见，其余图形元素将被隐藏，从而提升渲染性能。默认情况下，节点始终可见，而其他图形元素在操作画布过程中会自动隐藏
    *
-   * <en/> Specify the graphic elements that are always visible. After applying this interaction, only the graphic elements specified by this property will remain visible during the canvas operation, and the rest of the graphic elements will be hidden to improve rendering performance. By default, nodes are always visible, while other graphic elements are automatically hidden during canvas operations
+   * <en/> Specify the shapes that are always visible. After applying this interaction, only the shapes specified by this property will remain visible during the canvas operation, and the rest of the shapes will be hidden to improve rendering performance. By default, nodes are always visible, while other shapes are automatically hidden during canvas operations
    */
   shapes?:
     | { node?: string[]; edge?: string[]; combo?: string[] }

packages/g6/src/elements/edges/base-edge.ts

@@ -126,33 +126,33 @@ export interface BaseEdgeStyleProps
   /**
    * <zh/> 在 “起点” 处添加一个标记图形，其中 “起始点” 为边与起始节点的交点
    *
-   * <en/> Add a marker graphic at the "start point", where the "start point" is the intersection of the edge and the source node
+   * <en/> Add a marker at the "start point", where the "start point" is the intersection of the edge and the source node
    */
   markerStart?: DisplayObject | null;
   /**
    * <zh/> 调整 “起点” 处标记图形的位置，正偏移量向内，负偏移量向外
    *
-   * <en/> Adjust the position of the marker graphic at the "start point", positive offset inward, negative offset outward
+   * <en/> Adjust the position of the marker at the "start point", positive offset inward, negative offset outward
    * @defaultValue 0
    */
   markerStartOffset?: number;
   /**
    * <zh/> 在 “终点” 处添加一个标记图形，其中 “终点” 为边与终止节点的交点
    *
-   * <en/> Add a marker graphic at the "end point", where the "end point" is the intersection of the edge and the target node
+   * <en/> Add a marker at the "end point", where the "end point" is the intersection of the edge and the target node
    */
   markerEnd?: DisplayObject | null;
   /**
    * <zh/> 调整 “终点” 处标记图形的位置，正偏移量向内，负偏移量向外
    *
-   * <en/> Adjust the position of the marker graphic at the "end point", positive offset inward, negative offset outward
+   * <en/> Adjust the position of the marker at the "end point", positive offset inward, negative offset outward
    * @defaultValue 0
    */
   markerEndOffset?: number;
   /**
    * <zh/> 在路径除了 “起点” 和 “终点” 之外的每一个顶点上放置标记图形。在内部实现中，由于我们会把路径中部分命令转换成 C 命令，因此这些顶点实际是三阶贝塞尔曲线的控制点
    *
-   * <en/> Place a marker graphic on each vertex of the path except for the "start point" and "end point". In the internal implementation, because we will convert some commands in the path to C commands, these controlPoints are actually the control points of the cubic Bezier curve
+   * <en/> Place a marker on each vertex of the path except for the "start point" and "end point". In the internal implementation, because we will convert some commands in the path to C commands, these controlPoints are actually the control points of the cubic Bezier curve
    */
   markerMid?: DisplayObject | null;
   /**

packages/g6/src/elements/nodes/base-node.ts

@@ -85,6 +85,7 @@ export interface BaseNodeStyleProps
    * <zh/> 仅在树图中生效
    *
    * <en/> Only valid in the tree graph
+   * @ignore
    */
   childrenNode?: ID[];
   /**
@@ -95,6 +96,7 @@ export interface BaseNodeStyleProps
    * <zh/> 仅在树图中生效。如果当前节点为收起状态，children 可能为空，通过 childrenData 能够获取完整的子元素数据
    *
    * <en/> Only valid in the tree graph. If the current node is collapsed, children may be empty, and the complete child element data can be obtained through childrenData
+   * @ignore
    */
   childrenData?: NodeData[];
   /**
@@ -450,7 +452,7 @@ export abstract class BaseNode<S extends BaseNodeStyleProps = BaseNodeStyleProps
 /**
  * <zh/> 在离屏画布中获取图形包围盒
  *
- * <en/> Get the bounding box of the graphic in the off-screen canvas
+ * <en/> Get the bounding box of the shape in the off-screen canvas
  * @param context - <zh/> 运行时上下文 <en/> Runtime context
  * @param shape - <zh/> 图形实例 <en/> Graphic instance
  * @returns <zh/> 图形包围盒 <en/> Graphic bounding box
@@ -460,7 +462,7 @@ function getBoundsInOffscreen(context: RuntimeContext, shape: DisplayObject) {
 
   // 将主图形靠背至全局空间，避免受到父级 transform 的影响
   // 合理的操作应该是拷贝至离屏画布，但目前 G 有点问题
-  // Move the main graphic to the global space to avoid being affected by the parent transform
+  // Move the main shape to the global space to avoid being affected by the parent transform
   // The reasonable operation should be moved to the off-screen canvas, but there is a problem with G at present
   const canvas = context.canvas.getLayer();
   const substitute = shape.cloneNode();

packages/g6/src/elements/shapes/base-shape.ts

@@ -153,8 +153,8 @@ export abstract class BaseShape<StyleProps extends BaseShapeStyleProps> extends
   /**
    * <zh/> 从给定的属性对象中提取图形样式属性。删除特定的属性，如位置、变换和类名
    *
-   * <en/> Extracts the graphic style properties from a given attribute object.
-   * Removes specific properties like position, transformation, and class name.
+   * <en/> Extracts the shape styles from a given attribute object.
+   * Removes specific styles like position, transformation, and class name.
    * @param style - <zh/> 属性对象 | <en/> attribute object
    * @returns <zh/> 仅包含样式属性的对象 | <en/> An object containing only the style properties.
    */

packages/g6/src/plugins/minimap/index.ts

@@ -58,7 +58,7 @@ export interface MinimapOptions extends BasePluginOptions {
    * - 也可以传入一个函数，接收元素的 id 和类型，返回一个图形
    *
    * <en/>
-   * - 'key' uses the key shape of the element as the thumbnail graphic
+   * - 'key' uses the key shape of the element as the thumbnail shape
    * - You can also pass in a function that receives the id and type of the element and returns a shape
    */
   shape?: 'key' | ((id: string, elementType: ElementType) => DisplayObject);

packages/g6/src/spec/canvas.ts

@@ -18,37 +18,61 @@ export interface CanvasOptions {
    * <zh/> 画布宽度
    *
    * <en/> canvas width
+   * @remarks
+   * <zh/> 如果未设置，则会自动获取容器宽度
+   *
+   * <en/> If not set, the container width will be automatically obtained
    */
   width?: number;
   /**
    * <zh/> 画布高度
    *
    * <en/> canvas height
+   * @remarks
+   * <zh/> 如果未设置，则会自动获取容器高度
+   *
+   * <en/> If not set, the container height will be automatically obtained
    */
   height?: number;
   /**
-   * <zh/> 获取渲染器
+   * <zh/> 手动置顶渲染器
+   *
+   * <en/> manually set renderer
+   * @remarks
+   * <zh/> G6 采用了分层渲染的方式，分为 background、main、label、transient 四层，用户可以通过该配置项分别设置每层画布的渲染器
    *
-   * <en/> get renderer
+   * <en/> G6 adopts a layered rendering method, divided into four layers: background, main, label, transient. Users can set the renderer of each layer canvas separately through this configuration item
    */
   renderer?: (layer: 'background' | 'main' | 'label' | 'transient') => IRenderer;
   /**
    * <zh/> 是否自动调整画布大小
    *
    * <en/> whether to auto resize canvas
    * @defaultValue false
+   * @remarks
+   * <zh/> 基于 window.onresize 事件自动调整画布大小
+   *
+   * <en/> Automatically adjust the canvas size based on the window.onresize event
    */
   autoResize?: boolean;
   /**
    * <zh/> 画布背景色
    *
    * <en/> canvas background color
+   * @remarks
+   * <zh/> 该颜色作为导出图片时的背景色
+   *
+   * <en/> This color is used as the background color when exporting images
    */
   background?: string;
   /**
    * <zh/> 设备像素比
    *
    * <en/> device pixel ratio
+   * @remarks
+   * <zh/> 用于高清屏的设备像素比，默认为 [window.devicePixelRatio](https://developer.mozilla.org/zh-CN/docs/Web/API/Window/devicePixelRatio)
+   *
+   * <en/> Device pixel ratio for high-definition screens, default is [window.devicePixelRatio](https://developer.mozilla.org/en-US/docs/Web/API/Window/devicePixelRatio)
    */
   devicePixelRatio?: number;
   /**

packages/g6/src/spec/graph.ts

@@ -40,30 +40,50 @@ export interface GraphOptions extends CanvasOptions, ViewportOptions {
    * <zh/> 数据
    *
    * <en/> Data
+   * @remarks
+   * <zh/> 详见 [Data](/api/data/graph-data)
+   *
+   * <en/> See [Data](/en/api/data/graph-data)
    */
   data?: GraphData;
   /**
-   * <zh/> 布局
+   * <zh/> 布局配置项
+   *
+   * <en/> Layout options
+   * @remarks
+   * <zh/> 详见 [Layout](/api/layouts/antv-dagre-layout)
    *
-   * <en/> Layout
+   * <en/> See [Layout](/en/api/layouts/antv-dagre-layout)
    */
   layout?: LayoutOptions;
   /**
-   * <zh/> 节点
+   * <zh/> 节点配置项
+   *
+   * <en/> Node options
+   * @remarks
+   * <zh/> 详见 [Node](/api/elements/nodes/base-node)
    *
-   * <en/> Node
+   * <en/> See [Node](/en/api/elements/nodes/base-node)
    */
   node?: NodeOptions;
   /**
-   * <zh/> 边
+   * <zh/> 边配置项
    *
-   * <en/> Edge
+   * <en/> Edge options
+   * @remarks
+   * <zh/> 详见 [Edge](/api/elements/edges/base-edge)
+   *
+   * <en/> See [Edge](/en/api/elements/edges/base-edge)
    */
   edge?: EdgeOptions;
   /**
-   * <zh/> Combo
+   * <zh/> 组合配置项
    *
-   * <en/> Combo
+   * <en/> Combo options
+   * @remarks
+   * <zh/> 详见 [Combo](/api/elements/combos/base-combo)
+   *
+   * <en/> See [Combo](/en/api/elements/combos/base-combo)
    */
   combo?: ComboOptions;
   /**
@@ -73,15 +93,43 @@ export interface GraphOptions extends CanvasOptions, ViewportOptions {
    */
   theme?: ThemeOptions;
   /**
-   * <zh/> 交互
+   * <zh/> 启用交互
+   *
+   * <en/> Enable interactions
+   * @remarks
+   * <zh/>
+   * - 概念：[核心概念 - 交互](/manual/core-concept/behavior)
+   *
+   * - 内置交互: [交互](/api/behaviors/auto-adapt-label)
+   *
+   * - 自定义交互: [自定义扩展 - 自定义交互](/manual/advanced/custom-behavior)
    *
-   * <en/> Behaviors
+   * <en/>
+   * - Concept: [Concepts - Behavior](/en/manual/core-concept/behavior)
+   *
+   * - Built-in behaviors: [Behavior](/en/api/behaviors/auto-adapt-label)
+   *
+   * - Custom behaviors: [Custom Extension - Custom Behavior](/en/manual/advanced/custom-behavior)
    */
   behaviors?: BehaviorOptions;
   /**
-   * <zh/> 画布插件
+   * <zh/> 启用插件
+   *
+   * <en/> Enable plugins
+   * @remarks
+   * <zh/>
+   * - 概念：[核心概念 - 插件](/manual/core-concept/plugin)
+   *
+   * - 内置插件: [插件](/en/api/plugins/background)
+   *
+   * - 自定义插件: [自定义扩展 - 自定义插件](/manual/advanced/custom-plugin)
+   *
+   * <en/>
+   * - Concept: [Concepts - Plugin](/en/manual/core-concept/plugin)
+   *
+   * - Built-in plugins: [Plugin](/en/api/plugins/background)
    *
-   * <en/> Canvas plugins
+   * - Custom plugins: [Custom Extension - Custom Plugin](/en/manual/advanced/custom-plugin)
    */
   plugins?: PluginOptions;
   /**

packages/g6/src/spec/viewport.ts

@@ -24,6 +24,10 @@ export interface ViewportOptions {
    * <zh/> 是否自动适应
    *
    * <en/> whether to auto fit
+   * @remarks
+   * <zh/> 每次执行 `render` 时，都会根据 `autoFit` 进行自适应
+   *
+   * <en/> Every time `render` is executed, it will be adapted according to `autoFit`
    */
   autoFit?:
     | { type: 'view'; options?: FitViewOptions; animation?: ViewportAnimationEffectTiming }

packages/g6/src/utils/cache.ts

@@ -8,8 +8,8 @@ const getStyleCacheKey = (name: string) => `__${name}__`;
 /**
  * <zh/> 缓存图形样式
  *
- * <en/> Cache graphic style
- * @param element - <zh/> 图形元素 | <en/> graphic element
+ * <en/> Cache shape style
+ * @param element - <zh/> 图形元素 | <en/> shape element
  * @param name - <zh/> 样式名 | <en/> style name
  */
 export function cacheStyle(element: DisplayObject, name: string | string[]) {
@@ -24,7 +24,7 @@ export function cacheStyle(element: DisplayObject, name: string | string[]) {
  * <zh/> 获取缓存的样式
  *
  * <en/> Get cached style
- * @param element - <zh/> 图形元素 | <en/> graphic element
+ * @param element - <zh/> 图形元素 | <en/> shape element
  * @param name - <zh/> 样式名 | <en/> style name
  * @returns <zh/> 样式值 | <en/> style value
  */
@@ -36,7 +36,7 @@ export function getCachedStyle(element: DisplayObject, name: string) {
  * <zh/> 是否有缓存的样式
  *
  * <en/> Whether there is a cached style
- * @param element - <zh/> 图形元素 | <en/> graphic element
+ * @param element - <zh/> 图形元素 | <en/> shape element
  * @param name - <zh/> 样式名 | <en/> style name
  * @returns <zh/> 是否有缓存的样式 | <en/> Whether there is a cached style
  */
@@ -48,7 +48,7 @@ export function hasCachedStyle(element: DisplayObject, name: string) {
  * <zh/> 设置缓存的样式
  *
  * <en/> Set cached style
- * @param element - <zh/> 图形元素 | <en/> graphic element
+ * @param element - <zh/> 图形元素 | <en/> shape element
  * @param name - <zh/> 样式名 | <en/> style name
  * @param value - <zh/> 样式值 | <en/> style value
  */

packages/g6/src/utils/style.ts

@@ -34,7 +34,7 @@ export function computeElementCallbackStyle(
 /**
  * <zh/> 合并图形配置项
  *
- * <en/> Merge graphic configuration
+ * <en/> Merge shape configuration
  * @param opt1 - <zh/> 配置项1 | <en/> configuration 1
  * @param opt2 - <zh/> 配置项2 | <en/> configuration 2
  * @returns <zh/> 合并后的配置项 | <en/> merged configuration
@@ -50,14 +50,14 @@ export function mergeOptions(opt1: DisplayObjectConfig<any>, opt2: DisplayObject
 /**
  * <zh/> 获取图形子图形样式
  *
- * <en/> Get the style of the sub-shape of the graphic
- * @param style - <zh/> 图形样式 | <en/> graphic style
+ * <en/> Get the style of the sub-shape of the shape
+ * @param style - <zh/> 图形样式 | <en/> shape style
  * @returns <zh/> 子图形样式 | <en/> sub-shape style
  * @remarks
  * <zh/> 从给定的属性对象中提取图形样式属性。删除特定的属性，如位置、变换和类名
  *
- * <en/> Extracts the graphic style properties from a given attribute object.
- * Removes specific properties like position, transformation, and class name.
+ * <en/> Extracts the shape styles from a given attribute object.
+ * Removes specific styles like position, transformation, and class name.
  */
 export function getSubShapeStyle<T extends Record<string, any>>(
   style: T,

packages/site/common/api/elements/combos/circle-combo.md

@@ -23,3 +23,5 @@ createGraph(
   },
 );
 ```
+
+设置 `combo.type` 为 `circle` 以使用圆形组合。

packages/site/common/api/elements/combos/rect-combo.md

@@ -24,3 +24,5 @@ createGraph(
   },
 );
 ```
+
+设置 `combo.type` 为 `rect` 以使用矩形组合。

packages/site/common/api/elements/edges/cubic-horizontal.md

@@ -64,3 +64,5 @@ createGraph(
   },
 );
 ```
+
+设置 `edge.type` 为 `cubic-horizontal` 以使用水平方向的三次贝塞尔曲线。

packages/site/common/api/elements/edges/cubic-vertical.md

@@ -64,3 +64,5 @@ createGraph(
   },
 );
 ```
+
+设置 `edge.type` 为 `cubic-vertical` 以使用垂直方向的三次贝塞尔曲线。

packages/site/common/api/elements/edges/cubic.md

@@ -50,3 +50,5 @@ createGraph(
   },
 );
 ```
+
+设置 `edge.type` 为 `cubic` 以使用三次贝塞尔曲线。

packages/site/common/api/elements/edges/line.md

@@ -36,3 +36,5 @@ createGraph(
   },
 );
 ```
+
+设置 `edge.type` 为 `line` 以使用直线。

packages/site/common/api/elements/edges/polyline.md

@@ -102,3 +102,5 @@ createGraph(
   },
 );
 ```
+
+设置 `edge.type` 为 `polyline` 以使用折线。

packages/site/common/api/elements/edges/quadratic.md

@@ -50,3 +50,5 @@ createGraph(
   },
 );
 ```
+
+设置 `edge.type` 为 `quadratic` 以使用曲线。