diff --git a/packages/g6/src/elements/effect.ts b/packages/g6/src/elements/effect.ts
index 1edc25dac10..0c3a6e01db5 100644
--- a/packages/g6/src/elements/effect.ts
+++ b/packages/g6/src/elements/effect.ts
@@ -7,7 +7,7 @@ import { getCachedStyle, setCacheStyle } from '../utils/cache';
* Control whether the function is executed based on whether the style attribute changes
* @param styler - 获取样式属性函数 | Get style attribute function
* @returns 装饰器 | Decorator
- * @description
+ * @remarks
* 仅指定 getStyle 的情况下，会分别使用当前的 attributes 和 新的 attributes 调用函数，若两者相同，则不执行函数。
*
* 如果指定了 shapeKey, 则会直接获取该图形的 attributes 作为原始样式属性，通常在 getStyle 函数中获取了包围盒时使用。
@@ -49,7 +49,7 @@ export function effect(styler: (self: any, attributes: Record)
* @param b - 样式属性 b | Style attribute b
* @param depth - 比较深度 | Comparison depth
* @returns 是否相等 | Whether they are equal
- * @description
+ * @remarks
* 进行第二层浅比较用于比较 badges、ports 等复合图形属性
*
* Perform a second-level shallow comparison to compare complex shape attributes such as badges and ports
diff --git a/packages/g6/src/elements/shapes/badge.ts b/packages/g6/src/elements/shapes/badge.ts
index 12d5a613e11..bb5d87d3864 100644
--- a/packages/g6/src/elements/shapes/badge.ts
+++ b/packages/g6/src/elements/shapes/badge.ts
@@ -15,7 +15,7 @@ export interface BadgeStyleProps extends LabelStyleProps {}
* 徽标
*
* Badge
- * @description
+ * @remarks
* 徽标是一种特殊的标签，通常用于展示数量或状态信息。
*
* Badge is a special label, usually used to display quantity or status information.
diff --git a/packages/g6/src/elements/shapes/icon.ts b/packages/g6/src/elements/shapes/icon.ts
index 746076a37f9..fcdd0cff8ea 100644
--- a/packages/g6/src/elements/shapes/icon.ts
+++ b/packages/g6/src/elements/shapes/icon.ts
@@ -13,7 +13,7 @@ export interface IconStyleProps extends BaseShapeStyleProps, Partial 图标
*
* Icon
- * @description
+ * @remarks
* 图标是一种特殊的图形，可以是图片或者文字。传入 src 属性时，会渲染图片；传入 text 属性时，会渲染文字。
*
* Icon is a special shape, which can be an image or text. When the src attribute is passed in, an image will be rendered; when the text attribute is passed in, text will be rendered.
diff --git a/packages/g6/src/elements/shapes/label.ts b/packages/g6/src/elements/shapes/label.ts
index 383cef824f8..cbd39d0947c 100644
--- a/packages/g6/src/elements/shapes/label.ts
+++ b/packages/g6/src/elements/shapes/label.ts
@@ -31,7 +31,7 @@ export interface LabelStyleProps extends TextStyleProps, Prefix<'background', Re
* 标签
*
* Label
- * @description
+ * @remarks
* 标签是一种具有背景的文本图形。
*
* Label is a text shape with background.
diff --git a/packages/g6/src/exports.ts b/packages/g6/src/exports.ts
index 52299e35bf0..6cbe72ee44a 100644
--- a/packages/g6/src/exports.ts
+++ b/packages/g6/src/exports.ts
@@ -167,6 +167,7 @@ export type {
TooltipOptions,
WatermarkOptions,
} from './plugins';
+export type { DataURLOptions } from './runtime/canvas';
export type { RuntimeContext } from './runtime/types';
export type {
BehaviorOptions,
@@ -197,6 +198,7 @@ export type {
DirectionalPlacement,
Edge,
EdgeArrowStyleProps,
+ EdgeDirection,
EdgeLabelStyleProps,
Element,
ElementDatum,
diff --git a/packages/g6/src/runtime/canvas.ts b/packages/g6/src/runtime/canvas.ts
index 20f5c34ff67..b697a4edcb9 100644
--- a/packages/g6/src/runtime/canvas.ts
+++ b/packages/g6/src/runtime/canvas.ts
@@ -1,12 +1,4 @@
-import type {
- Cursor,
- DisplayObject,
- CanvasConfig as GCanvasConfig,
- DataURLOptions as GDataURLOptions,
- IAnimation,
- IRenderer,
- PointLike,
-} from '@antv/g';
+import type { Cursor, DisplayObject, CanvasConfig as GCanvasConfig, IAnimation, IRenderer, PointLike } from '@antv/g';
import { CanvasEvent, Canvas as GCanvas } from '@antv/g';
import { Renderer as CanvasRenderer } from '@antv/g-canvas';
import { Plugin as DragNDropPlugin } from '@antv/g-plugin-dragndrop';
@@ -21,7 +13,7 @@ export interface CanvasConfig
background?: string;
}
-export interface DataURLOptions extends GDataURLOptions {
+export interface DataURLOptions {
/**
* 导出模式
* - viewport: 导出视口内容
@@ -32,6 +24,19 @@ export interface DataURLOptions extends GDataURLOptions {
* - overall: export the entire canvas
*/
mode?: 'viewport' | 'overall';
+ /**
+ * 图片类型
+ *
+ * image type
+ * @defaultValue 'image/png'
+ */
+ type: 'image/png' | 'image/jpeg' | 'image/webp' | 'image/bmp';
+ /**
+ * 图片质量, 仅对 image/jpeg 和 image/webp 有效，取值范围 0 ~ 1
+ *
+ * image quality, only valid for image/jpeg and image/webp, range 0 ~ 1
+ */
+ encoderOptions: number;
}
/**
diff --git a/packages/g6/src/runtime/graph.ts b/packages/g6/src/runtime/graph.ts
index 6b5656e470b..e6f56c06fb1 100644
--- a/packages/g6/src/runtime/graph.ts
+++ b/packages/g6/src/runtime/graph.ts
@@ -161,7 +161,7 @@ export class Graph extends EventEmitter {
}
/**
- * 获取当前图容器的大小
+ * 获取当前画布容器的尺寸
*
* Get the size of the current canvas container
* @returns 画布尺寸 | canvas size
@@ -173,7 +173,7 @@ export class Graph extends EventEmitter {
}
/**
- * 获取当前图容器的大小
+ * 获取当前画布容器的尺寸
*
* Get the size of the current canvas container
* @param width - 画布宽度 | canvas width
@@ -211,7 +211,11 @@ export class Graph extends EventEmitter {
* 设置节点样式映射
*
* Set node mapper
- * @param node - 节点配置 | node configuration
+ * @param node - 节点配置 | node options
+ * @remarks
+ * 即 `options.node` 的值
+ *
+ * The value of `options.node`
* @apiCategory element
*/
public setNode(node: NodeOptions): void {
@@ -223,7 +227,11 @@ export class Graph extends EventEmitter {
* 设置边样式映射
*
* Set edge mapper
- * @param edge - 边配置 | edge configuration
+ * @param edge - 边配置 | edge options
+ * @remarks
+ * 即 `options.edge` 的值
+ *
+ * The value of `options.edge`
* @apiCategory element
*/
public setEdge(edge: EdgeOptions): void {
@@ -235,7 +243,11 @@ export class Graph extends EventEmitter {
* 设置组合样式映射
*
* Set combo mapper
- * @param combo - 组合配置 | combo configuration
+ * @param combo - 组合配置 | combo options
+ * @remarks
+ * 即 `options.combo` 的值
+ *
+ * The value of `options.combo`
* @apiCategory element
*/
public setCombo(combo: ComboOptions): void {
@@ -247,7 +259,7 @@ export class Graph extends EventEmitter {
* 获取主题
*
* Get theme
- * @returns 主题配置 | theme configuration
+ * @returns 当前主题 | current theme
* @apiCategory theme
*/
public getTheme(): ThemeOptions {
@@ -258,7 +270,11 @@ export class Graph extends EventEmitter {
* 设置主题
*
* Set theme
- * @param theme - 主题配置 | theme configuration
+ * @param theme - 主题名 | theme name
+ * @example
+ * ```ts
+ * graph.setTheme('dark');
+ * ```
* @apiCategory theme
*/
public setTheme(theme: ThemeOptions | ((prev: ThemeOptions) => ThemeOptions)): void {
@@ -274,7 +290,13 @@ export class Graph extends EventEmitter {
* 设置布局
*
* Set layout
- * @param layout - 布局配置 | layout configuration
+ * @param layout - 布局配置 | layout options
+ * @example
+ * ```ts
+ * graph.setLayout({
+ * type: 'dagre',
+ * })
+ * ```
* @apiCategory layout
*/
public setLayout(layout: LayoutOptions | ((prev: LayoutOptions) => LayoutOptions)): void {
@@ -282,10 +304,10 @@ export class Graph extends EventEmitter {
}
/**
- * 获取布局
+ * 获取布局配置
*
- * Get layout
- * @returns 布局配置 | layout configuration
+ * Get layout options
+ * @returns 布局配置 | layout options
* @apiCategory layout
*/
public getLayout(): LayoutOptions {
@@ -296,7 +318,15 @@ export class Graph extends EventEmitter {
* 设置交互
*
* Set behaviors
- * @param behaviors - 交互配置 | behavior configuration
+ * @param behaviors - 交互配置 | behavior options
+ * @remarks
+ * 设置的交互会全量替换原有的交互，如果需要新增交互可以使用如下方式：
+ *
+ * The set behavior will completely replace the original behavior. If you need to add behavior, you can use the following method:
+ *
+ * ```ts
+ * graph.setBehaviors((behaviors) => [...behaviors, { type: 'zoom-canvas' }])
+ * ```
* @apiCategory behavior
*/
public setBehaviors(behaviors: BehaviorOptions | ((prev: BehaviorOptions) => BehaviorOptions)): void {
@@ -305,10 +335,21 @@ export class Graph extends EventEmitter {
}
/**
- * 更新交互
+ * 更新指定的交互配置
+ *
+ * Update specified behavior options
+ * @param behavior - 交互配置 | behavior options
+ * @remarks
+ * 如果要更新一个交互，那么必须在交互配置中指定 key 字段，例如：
+ *
+ * If you want to update a behavior, you must specify the key field in the behavior options, for example:
+ * ```ts
+ * {
+ * behaviors: [{ type: 'zoom-canvas', key: 'zoom-canvas' }]
+ * }
*
- * Update behavior
- * @param behavior - 交互配置 | behavior configuration
+ * graph.updateBehavior({ key: 'zoom-canvas', enable: false })
+ * ```
* @apiCategory behavior
*/
public updateBehavior(behavior: UpdateBehaviorOption): void {
@@ -323,10 +364,10 @@ export class Graph extends EventEmitter {
}
/**
- * 获取交互
+ * 获取交互配置
*
- * Get behaviors
- * @returns 交互配置 | behavior configuration
+ * Get behaviors options
+ * @returns 交互配置 | behavior options
* @apiCategory behavior
*/
public getBehaviors(): BehaviorOptions {
@@ -334,10 +375,17 @@ export class Graph extends EventEmitter {
}
/**
- * 设置插件
+ * 设置插件配置
*
- * Set plugins
- * @param plugins - 插件配置 | plugin configuration
+ * Set plugins options
+ * @param plugins - 插件配置 | plugin options
+ * @remarks
+ * 设置的插件会全量替换原有的插件配置，如果需要新增插件可以使用如下方式：
+ *
+ * The set plugin will completely replace the original plugin configuration. If you need to add a plugin, you can use the following method:
+ * ```ts
+ * graph.setPlugins((plugins) => [...plugins, { key: 'grid-line' }])
+ * ```
* @apiCategory plugin
*/
public setPlugins(plugins: PluginOptions | ((prev: PluginOptions) => PluginOptions)): void {
@@ -346,10 +394,21 @@ export class Graph extends EventEmitter {
}
/**
- * 更新插件
+ * 更新插件配置
+ *
+ * Update plugin options
+ * @param plugin - 插件配置 | plugin options
+ * @remarks
+ * 如果要更新一个插件，那么必须在插件配置中指定 key 字段，例如：
+ *
+ * If you want to update a plugin, you must specify the key field in the plugin options, for example:
+ * ```ts
+ * {
+ * plugins: [{ key: 'grid-line' }]
+ * }
*
- * Update plugin
- * @param plugin - 插件配置 | plugin configuration
+ * graph.updatePlugin({ key: 'grid-line', follow: true })
+ * ```
* @apiCategory plugin
*/
public updatePlugin(plugin: UpdatePluginOption): void {
@@ -364,10 +423,10 @@ export class Graph extends EventEmitter {
}
/**
- * 获取插件
+ * 获取插件配置
*
- * Get plugins
- * @returns 插件配置 | plugin configuration
+ * Get plugins options
+ * @returns 插件配置 | plugin options
* @apiCategory plugin
*/
public getPlugins(): PluginOptions {
@@ -380,6 +439,17 @@ export class Graph extends EventEmitter {
* Get plugin instance
* @param key - 插件 key | plugin key
* @returns 插件实例 | plugin instance
+ * @remarks
+ * 一些插件提供了 API 方法可供调用，例如全屏插件可以调用 `request` 和 `exit` 方法来请求和退出全屏
+ *
+ * Some plugins provide API methods for calling, such as the full-screen plugin can call the `request` and `exit` methods to request and exit full-screen
+ * ```ts
+ * const fullscreen = graph.getPluginInstance('fullscreen');
+ *
+ * fullscreen.request();
+ *
+ * fullscreen.exit();
+ * ```
* @apiCategory plugin
*/
public getPluginInstance(key: string) {
@@ -390,7 +460,11 @@ export class Graph extends EventEmitter {
* 设置数据转换器
*
* Set data transforms
- * @param transforms - 数据转换配置 | data transform configuration
+ * @param transforms - 数据转换配置 | data transform options
+ * @remarks
+ * 数据转换器能够在图渲染过程中执行数据转换，目前支持在渲染前对绘制数据进行转化。
+ *
+ * Data transforms can perform data transformation during the rendering process of the graph. Currently, it supports transforming the drawing data before rendering.
* @apiCategory transform
*/
public setTransforms(transforms: TransformOptions | ((prev: TransformOptions) => TransformOptions)): void {
@@ -402,7 +476,7 @@ export class Graph extends EventEmitter {
* 更新数据转换器
*
* Update data transform
- * @param transform - 数据转换配置 | data transform configuration
+ * @param transform - 数据转换器配置 | data transform options
* @apiCategory transform
*/
public updateTransform(transform: UpdateTransformOption): void {
@@ -418,10 +492,10 @@ export class Graph extends EventEmitter {
}
/**
- * 获取数据转换器
+ * 获取数据转换器配置
*
- * Get data transforms
- * @returns 数据转换器实例 | data transform instance
+ * Get data transforms options
+ * @returns 数据转换配置 | data transform options
* @apiCategory transform
*/
public getTransforms(): TransformOptions {
@@ -429,10 +503,13 @@ export class Graph extends EventEmitter {
}
/**
- * 获取数据
+ * 获取图数据
*
- * Get data
- * @returns 数据 | data
+ * Get graph data
+ * @returns 图数据 | Graph data
+ * 获取当前图的数据，包括节点、边、组合数据
+ *
+ * Get the data of the current graph, including node, edge, and combo data
* @apiCategory data
*/
public getData(): GraphData {
@@ -445,6 +522,10 @@ export class Graph extends EventEmitter {
* Get element data by ID
* @param id - 元素 ID | element ID
* @returns 元素数据 | element data
+ * @remarks
+ * 直接获取元素的数据而不必考虑元素类型
+ *
+ * Get element data directly without considering the element type
* @apiCategory data
*/
public getElementData(id: ID): ElementDatum;
@@ -453,6 +534,10 @@ export class Graph extends EventEmitter {
*
* Get multiple element data in batch
* @param ids - 元素 ID 数组 | element ID array
+ * @remarks
+ * 直接获取元素的数据而不必考虑元素类型
+ *
+ * Get element data directly without considering the element type
* @apiCategory data
*/
public getElementData(ids: ID[]): ElementDatum[];
@@ -475,6 +560,10 @@ export class Graph extends EventEmitter {
* Get single node data
* @param id - 节点 ID | node ID
* @returns 节点数据 | node data
+ * @example
+ * ```ts
+ * const node1 = graph.getNodeData('node-1');
+ * ```
* @apiCategory data
*/
public getNodeData(id: ID): NodeData;
@@ -484,6 +573,10 @@ export class Graph extends EventEmitter {
* Get multiple node data in batch
* @param ids - 节点 ID 数组 | node ID array
* @returns 节点数据 | node data
+ * @example
+ * ```ts
+ * const [node1, node2] = graph.getNodeData(['node-1', 'node-2']);
+ * ```
* @apiCategory data
*/
public getNodeData(ids: ID[]): NodeData[];
@@ -507,6 +600,10 @@ export class Graph extends EventEmitter {
* Get single edge data
* @param id - 边 ID | edge ID
* @returns 边数据 | edge data
+ * @example
+ * ```ts
+ * const edge1 = graph.getEdgeData('edge-1');
+ * ```
* @apiCategory data
*/
public getEdgeData(id: ID): EdgeData;
@@ -516,6 +613,10 @@ export class Graph extends EventEmitter {
* Get multiple edge data in batch
* @param ids - 边 ID 数组 | edge ID array
* @returns 边数据 | edge data
+ * @example
+ * ```ts
+ * const [edge1, edge2] = graph.getEdgeData(['edge-1', 'edge-2']);
+ * ```
* @apiCategory data
*/
public getEdgeData(ids: ID[]): EdgeData[];
@@ -539,6 +640,10 @@ export class Graph extends EventEmitter {
* Get single combo data
* @param id - 组合ID | combo ID
* @returns 组合数据 | combo data
+ * @example
+ * ```ts
+ * const combo1 = graph.getComboData('combo-1');
+ * ```
* @apiCategory data
*/
public getComboData(id: ID): ComboData;
@@ -548,6 +653,10 @@ export class Graph extends EventEmitter {
* Get multiple combo data in batch
* @param ids - 组合ID 数组 | combo ID array
* @returns 组合数据 | combo data
+ * @example
+ * ```ts
+ * const [combo1, combo2] = graph.getComboData(['combo-1', 'combo-2']);
+ * ```
* @apiCategory data
*/
public getComboData(ids: ID[]): ComboData[];
@@ -562,6 +671,10 @@ export class Graph extends EventEmitter {
*
* Set full data
* @param data - 数据 | data
+ * @remarks
+ * 设置全量数据会替换当前图中的所有数据，G6 会自动进行数据差异计算
+ *
+ * Setting full data will replace all data in the current graph, and G6 will automatically calculate the data difference
* @apiCategory data
*/
public setData(data: GraphData | ((prev: GraphData) => GraphData)): void {
@@ -573,6 +686,13 @@ export class Graph extends EventEmitter {
*
* Add element data
* @param data - 元素数据 | element data
+ * @example
+ * ```ts
+ * graph.addData({
+ * nodes: [{ id: 'node-1' }, { id: 'node-2' }],
+ * edges: [{ source: 'node-1', target: 'node-2' }],
+ * });
+ * ```
* @apiCategory data
*/
public addData(data: GraphData | ((prev: GraphData) => GraphData)): void {
@@ -584,6 +704,10 @@ export class Graph extends EventEmitter {
*
* Add node data
* @param data - 节点数据 | node data
+ * @example
+ * ```ts
+ * graph.addNodeData([{ id: 'node-1' }, { id: 'node-2' }]);
+ * ```
* @apiCategory data
*/
public addNodeData(data: NodeData[] | ((prev: NodeData[]) => NodeData[])): void {
@@ -595,6 +719,10 @@ export class Graph extends EventEmitter {
*
* Add edge data
* @param data - 边数据 | edge data
+ * @example
+ * ```ts
+ * graph.addEdgeData([{ source: 'node-1', target: 'node-2' }]);
+ * ```
* @apiCategory data
*/
public addEdgeData(data: EdgeData[] | ((prev: EdgeData[]) => EdgeData[])): void {
@@ -606,6 +734,10 @@ export class Graph extends EventEmitter {
*
* Add combo data
* @param data - 组合数据 | combo data
+ * @example
+ * ```ts
+ * graph.addComboData([{ id: 'combo-1' }]);
+ * ```
* @apiCategory data
*/
public addComboData(data: ComboData[] | ((prev: ComboData[]) => ComboData[])): void {
@@ -617,9 +749,20 @@ export class Graph extends EventEmitter {
*
* Update element data
* @param data - 元素数据 | element data
+ * @remarks
+ * 只需要传入需要更新的数据即可，不必传入完整的数据
+ *
+ * Just pass in the data that needs to be updated, no need to pass in the complete data
+ * @example
+ * ```ts
+ * graph.updateData({
+ * nodes: [{ id: 'node-1', style: { x: 100, y: 100 } }],
+ * edges: [{ id: 'edge-1', style: { lineWidth: 2 } }]
+ * });
+ * ```
* @apiCategory data
*/
- public updateData(data: PartialGraphData | ((prev: PartialGraphData) => PartialGraphData)): void {
+ public updateData(data: PartialGraphData | ((prev: GraphData) => PartialGraphData)): void {
this.context.model.updateData(isFunction(data) ? data(this.getData()) : data);
}
@@ -628,12 +771,18 @@ export class Graph extends EventEmitter {
*
* Update node data
* @param data - 节点数据 | node data
+ * @remarks
+ * 只需要传入需要更新的数据即可，不必传入完整的数据
+ *
+ * Just pass in the data that needs to be updated, no need to pass in the complete data
+ * @example
+ * ```ts
+ * graph.updateNodeData([{ id: 'node-1', style: { x: 100, y: 100 } }]);
+ * ```
* @apiCategory data
*/
public updateNodeData(
- data:
- | PartialNodeLikeData[]
- | ((prev: PartialNodeLikeData[]) => PartialNodeLikeData[]),
+ data: PartialNodeLikeData[] | ((prev: NodeData[]) => PartialNodeLikeData[]),
): void {
this.context.model.updateNodeData(isFunction(data) ? data(this.getNodeData()) : data);
}
@@ -643,11 +792,17 @@ export class Graph extends EventEmitter {
*
* Update edge data
* @param data - 边数据 | edge data
+ * @remarks
+ * 只需要传入需要更新的数据即可，不必传入完整的数据
+ *
+ * Just pass in the data that needs to be updated, no need to pass in the complete data
+ * @example
+ * ```ts
+ * graph.updateEdgeData([{ id: 'edge-1', style: { lineWidth: 2 } }]);
+ * ```
* @apiCategory data
*/
- public updateEdgeData(
- data: PartialEdgeData[] | ((prev: PartialEdgeData[]) => PartialEdgeData[]),
- ): void {
+ public updateEdgeData(data: PartialEdgeData[] | ((prev: EdgeData[]) => PartialEdgeData[])): void {
this.context.model.updateEdgeData(isFunction(data) ? data(this.getEdgeData()) : data);
}
@@ -656,21 +811,34 @@ export class Graph extends EventEmitter {
*
* Update combo data
* @param data - 组合数据 | combo data
+ * @remarks
+ * 只需要传入需要更新的数据即可，不必传入完整的数据
+ *
+ * Just pass in the data that needs to be updated, no need to pass in the complete data
+ * @example
+ * ```ts
+ * graph.updateComboData([{ id: 'combo-1', style: { x: 100, y: 100 } }]);
+ * ```
* @apiCategory data
*/
public updateComboData(
- data:
- | PartialNodeLikeData[]
- | ((prev: PartialNodeLikeData[]) => PartialNodeLikeData[]),
+ data: PartialNodeLikeData[] | ((prev: ComboData[]) => PartialNodeLikeData[]),
): void {
this.context.model.updateComboData(isFunction(data) ? data(this.getComboData()) : data);
}
/**
- * 删除多条元素数据
+ * 删除元素数据
*
- * Remove multiple element data
+ * Remove element data
* @param ids - 元素 ID 数组 | element ID array
+ * @example
+ * ```ts
+ * graph.removeData({
+ * nodes: ['node-1', 'node-2'],
+ * edges: ['edge-1'],
+ * });
+ * ```
* @apiCategory data
*/
public removeData(ids: DataID | ((data: GraphData) => DataID)): void {
@@ -678,10 +846,14 @@ export class Graph extends EventEmitter {
}
/**
- * 删除多条节点数据
+ * 删除节点数据
*
- * Remove multiple node data
+ * Remove node data
* @param ids - 节点 ID 数组 | node ID array
+ * @example
+ * ```ts
+ * graph.removeNodeData(['node-1', 'node-2']);
+ * ```
* @apiCategory data
*/
public removeNodeData(ids: ID[] | ((data: NodeData[]) => ID[])): void {
@@ -689,10 +861,18 @@ export class Graph extends EventEmitter {
}
/**
- * 删除多条边数据
+ * 删除边数据
*
- * Remove multiple edge data
+ * Remove edge data
* @param ids - 边 ID 数组 | edge ID array
+ * @remarks
+ * 如果传入边数据时仅提供了 source 和 target，那么需要通过 `idOf` 方法获取边的实际 ID
+ *
+ * If only the source and target are provided when passing in the edge data, you need to get the actual ID of the edge through the `idOf` method
+ * @example
+ * ```ts
+ * graph.removeEdgeData(['edge-1']);
+ * ```
* @apiCategory data
*/
public removeEdgeData(ids: ID[] | ((data: EdgeData[]) => ID[])): void {
@@ -700,10 +880,14 @@ export class Graph extends EventEmitter {
}
/**
- * 删除多条组合数据
+ * 删除组合数据
*
- * Remove multiple combo data
+ * Remove combo data
* @param ids - 组合 ID 数组 | 组合 ID array
+ * @example
+ * ```ts
+ * graph.removeComboData(['combo-1']);
+ * ```
* @apiCategory data
*/
public removeComboData(ids: ID[] | ((data: ComboData[]) => ID[])): void {
@@ -795,6 +979,10 @@ export class Graph extends EventEmitter {
* Get node data in a specific state
* @param state - 状态 | state
* @returns 节点数据 | node data
+ * @example
+ * ```ts
+ * const nodes = graph.getElementDataByState('node', 'selected');
+ * ```
* @apiCategory data
*/
public getElementDataByState(elementType: 'node', state: State): NodeData[];
@@ -804,6 +992,10 @@ export class Graph extends EventEmitter {
* Get edge data in a specific state
* @param state - 状态 | state
* @returns 边数据 | edge data
+ * @example
+ * ```ts
+ * const nodes = graph.getElementDataByState('edge', 'selected');
+ * ```
* @apiCategory data
*/
public getElementDataByState(elementType: 'edge', state: State): EdgeData[];
@@ -813,6 +1005,10 @@ export class Graph extends EventEmitter {
* Get combo data in a specific state
* @param state - 状态 | state
* @returns 组合数据 | combo data
+ * @example
+ * ```ts
+ * const nodes = graph.getElementDataByState('node', 'selected');
+ * ```
* @apiCategory data
*/
public getElementDataByState(elementType: 'combo', state: State): ComboData[];
@@ -879,7 +1075,11 @@ export class Graph extends EventEmitter {
* @remarks
* 此过程会执行数据更新、绘制元素、执行布局
*
+ * > ⚠️ render 为异步方法，如果需要在 render 后执行一些操作，可以使用 `await graph.render()` 或者监听 GraphEvent.AFTER_RENDER 事件
+ *
* This process will execute data update, element rendering, and layout execution
+ *
+ * > ⚠️ render is an asynchronous method. If you need to perform some operations after render, you can use `await graph.render()` or listen to the GraphEvent.AFTER_RENDER event
* @apiCategory render
*/
public async render(): Promise {
@@ -896,7 +1096,15 @@ export class Graph extends EventEmitter {
*
* Draw elements
* @returns 渲染结果 | draw result
- * @apiCategory element
+ * @remarks
+ * 仅执行元素绘制，不会重新布局
+ *
+ * ⚠️ draw 为异步方法，如果需要在 draw 后执行一些操作，可以使用 `await graph.draw()` 或者监听 GraphEvent.AFTER_DRAW 事件
+ *
+ * Only execute element drawing, no re-layout
+ *
+ * ⚠️ draw is an asynchronous method. If you need to perform some operations after draw, you can use `await graph.draw()` or listen to the GraphEvent.AFTER_DRAW event
+ * @apiCategory render
*/
public async draw(): Promise {
await this.prepare();
@@ -943,6 +1151,10 @@ export class Graph extends EventEmitter {
* 销毁当前图实例
*
* Destroy the current graph instance
+ * @remarks
+ * 销毁后无法进行任何操作，如果需要重新使用，需要重新创建一个新的图实例
+ *
+ * After destruction, no operations can be performed. If you need to reuse it, you need to create a new graph instance
* @apiCategory instance
*/
public destroy(): void {
@@ -1008,7 +1220,7 @@ export class Graph extends EventEmitter {
*
* Zoom the graph to fit the viewport and move it to the center of the viewport
* @param options - 适配配置 | fit options
- * @param animation - 动画配置 | animation configuration
+ * @param animation - 动画配置 | animation options
* @apiCategory viewport
*/
public async fitView(options?: FitViewOptions, animation?: ViewportAnimationEffectTiming): Promise {
@@ -1019,7 +1231,7 @@ export class Graph extends EventEmitter {
* 将图平移至视口中心
*
* Move the graph to the center of the viewport
- * @param animation - 动画配置 | animation configuration
+ * @param animation - 动画配置 | animation options
* @apiCategory viewport
*/
public async fitCenter(animation?: ViewportAnimationEffectTiming): Promise {
@@ -1041,11 +1253,15 @@ export class Graph extends EventEmitter {
}
/**
+ * 聚焦元素
+ *
+ * Focus on element
+ * @param id - 元素 ID | element ID
+ * @param animation - 动画配置 | animation options
+ * @remarks
* 移动图，使得元素对齐到视口中心
*
* Move the graph so that the element is aligned to the center of the viewport
- * @param id - 元素 ID | element ID
- * @param animation - 动画配置 | animation configuration
* @apiCategory viewport
*/
public async focusElement(id: ID | ID[], animation?: ViewportAnimationEffectTiming): Promise {
@@ -1053,11 +1269,11 @@ export class Graph extends EventEmitter {
}
/**
- * 基于当前缩放比例进行缩放
+ * 基于当前缩放比例进行缩放（相对缩放）
*
- * Zoom based on the current zoom ratio
+ * Zoom based on the current zoom ratio (relative zoom)
* @param ratio - 缩放比例 | zoom ratio
- * @param animation - 动画配置 | animation configuration
+ * @param animation - 动画配置 | animation options
* @param origin - 缩放中心(视口坐标) | zoom center(viewport coordinates)
* @remarks
*
@@ -1074,11 +1290,11 @@ export class Graph extends EventEmitter {
}
/**
- * 缩放画布至指定比例
+ * 缩放画布至指定比例（绝对缩放）
*
- * Zoom the canvas to the specified ratio
+ * Zoom the canvas to the specified ratio (absolute zoom)
* @param zoom - 指定缩放比例 | specified zoom ratio
- * @param animation - 动画配置 | animation configuration
+ * @param animation - 动画配置 | animation options
* @param origin - 缩放中心(视口坐标) | zoom center(viewport coordinates)
* @remarks
*
@@ -1108,11 +1324,11 @@ export class Graph extends EventEmitter {
}
/**
- * 基于当前旋转角度进行旋转
+ * 基于当前旋转角度进行旋转（相对旋转）
*
- * Rotate based on the current rotation angle
+ * Rotate based on the current rotation angle (relative rotation)
* @param angle - 旋转角度 | rotation angle
- * @param animation - 动画配置 | animation configuration
+ * @param animation - 动画配置 | animation options
* @param origin - 旋转中心(视口坐标) | rotation center(viewport coordinates)
* @apiCategory viewport
*/
@@ -1121,11 +1337,11 @@ export class Graph extends EventEmitter {
}
/**
- * 旋转画布至指定角度
+ * 旋转画布至指定角度 (绝对旋转)
*
- * Rotate the canvas to the specified angle
+ * Rotate the canvas to the specified angle (absolute rotation)
* @param angle - 目标角度 | target angle
- * @param animation - 动画配置 | animation configuration
+ * @param animation - 动画配置 | animation options
* @param origin - 旋转中心(视口坐标) | rotation center(viewport coordinates)
* @apiCategory viewport
*/
@@ -1145,11 +1361,11 @@ export class Graph extends EventEmitter {
}
/**
- * 将图平移指定距离
+ * 将图平移指定距离 (相对平移)
*
- * Translate the graph by the specified distance
+ * Translate the graph by the specified distance (relative translation)
* @param offset - 偏移量 | offset
- * @param animation - 动画配置 | animation configuration
+ * @param animation - 动画配置 | animation options
* @apiCategory viewport
*/
public async translateBy(offset: Point, animation?: ViewportAnimationEffectTiming): Promise {
@@ -1157,11 +1373,11 @@ export class Graph extends EventEmitter {
}
/**
- * 将图平移至指定位置
+ * 将图平移至指定位置 (绝对平移)
*
- * Translate the graph to the specified position
+ * Translate the graph to the specified position (absolute translation)
* @param position - 指定位置 | specified position
- * @param animation - 动画配置 | animation configuration
+ * @param animation - 动画配置 | animation options
* @apiCategory viewport
*/
public async translateTo(position: Point, animation?: ViewportAnimationEffectTiming): Promise {
@@ -1184,9 +1400,9 @@ export class Graph extends EventEmitter {
}
/**
- * 将元素平移指定距离
+ * 将元素平移指定距离 (相对平移)
*
- * Translate the element by the specified distance
+ * Translate the element by the specified distance (relative translation)
* @param id - 元素 ID | element ID
* @param offset - 偏移量 | offset
* @param animation - 是否启用动画 | whether to enable animation
@@ -1194,10 +1410,10 @@ export class Graph extends EventEmitter {
*/
public async translateElementBy(id: ID, offset: Point, animation?: boolean): Promise;
/**
- * 批量将元素平移指定距离
+ * 批量将元素平移指定距离 (相对平移)
*
- * Batch translate elements by the specified distance
- * @param offsets - 偏移量配置 | offset configuration
+ * Batch translate elements by the specified distance (relative translation)
+ * @param offsets - 偏移量配置 | offset options
* @param animation - 是否启用动画 | whether to enable animation
* @apiCategory element
*/
@@ -1216,9 +1432,9 @@ export class Graph extends EventEmitter {
}
/**
- * 将元素平移至指定位置
+ * 将元素平移至指定位置 (绝对平移)
*
- * Translate the element to the specified position
+ * Translate the element to the specified position (absolute translation)
* @param id - 元素 ID | element ID
* @param position - 指定位置 | specified position
* @param animation - 是否启用动画 | whether to enable animation
@@ -1226,10 +1442,10 @@ export class Graph extends EventEmitter {
*/
public async translateElementTo(id: ID, position: Point, animation?: boolean): Promise;
/**
- * 批量将元素平移至指定位置
+ * 批量将元素平移至指定位置 (绝对平移)
*
- * Batch translate elements to the specified position
- * @param positions - 位置配置 | position configuration
+ * Batch translate elements to the specified position (absolute translation)
+ * @param positions - 位置配置 | position options
* @param animation - 是否启用动画 | whether to enable animation
* @apiCategory element
*/
@@ -1267,7 +1483,7 @@ export class Graph extends EventEmitter {
* @returns 元素渲染样式 | element rendering style
* @apiCategory element
*/
- public getElementRenderStyle(id: ID) {
+ public getElementRenderStyle(id: ID): Record {
return omit(this.context.element!.getElement(id)!.attributes, ['context']);
}
@@ -1277,7 +1493,11 @@ export class Graph extends EventEmitter {
* Set element visibility
* @param id - 元素 ID | element ID
* @param visibility - 可见性 | visibility
- * @param animation - 动画配置 | animation configuration
+ * @param animation - 动画配置 | animation options
+ * @remarks
+ * 可见性配置包括 `visible` 和 `hidden` 两种状态
+ *
+ * Visibility configuration includes two states: `visible` and `hidden`
* @apiCategory element
*/
public async setElementVisibility(
@@ -1289,8 +1509,8 @@ export class Graph extends EventEmitter {
* 批量设置元素可见性
*
* Batch set element visibility
- * @param visibility - 可见性配置 | visibility configuration
- * @param animation - 动画配置 | animation configuration
+ * @param visibility - 可见性配置 | visibility options
+ * @param animation - 动画配置 | animation options
* @apiCategory element
*/
public async setElementVisibility(
@@ -1377,7 +1597,7 @@ export class Graph extends EventEmitter {
* 批量设置元素层级
*
* Batch set element z-index
- * @param zIndex - 层级配置 | z-index configuration
+ * @param zIndex - 层级配置 | z-index options
* @apiCategory element
*/
public async setElementZIndex(zIndex: Record): Promise;
@@ -1442,7 +1662,7 @@ export class Graph extends EventEmitter {
* Set element state
* @param id - 元素 ID | element ID
* @param state - 状态 | state
- * @param animation - 动画配置 | animation configuration
+ * @param animation - 动画配置 | animation options
* @apiCategory element
*/
public async setElementState(id: ID, state: State | State[], animation?: boolean): Promise;
@@ -1450,8 +1670,8 @@ export class Graph extends EventEmitter {
* 批量设置元素状态
*
* Batch set element state
- * @param state - 状态配置 | state configuration
- * @param animation - 动画配置 | animation configuration
+ * @param state - 状态配置 | state options
+ * @param animation - 动画配置 | animation options
* @apiCategory element
*/
public async setElementState(state: Record, animation?: boolean): Promise;
@@ -1506,7 +1726,7 @@ export class Graph extends EventEmitter {
private isCollapsingExpanding = false;
/**
- * 收起 Combo
+ * 收起组合
*
* Collapse Combo
* @param id - 元素 ID | element ID
@@ -1530,7 +1750,7 @@ export class Graph extends EventEmitter {
}
/**
- * 展开 Combo
+ * 展开组合
*
* Expand Combo
* @param id - 元素 ID | element ID
@@ -1563,7 +1783,7 @@ export class Graph extends EventEmitter {
* 导出画布内容为 DataURL
*
* Export canvas content as DataURL
- * @param options - 导出配置 | export configuration
+ * @param options - 导出配置 | export options
* @returns DataURL | DataURL
* @apiCategory exportImage
*/
@@ -1678,6 +1898,7 @@ export class Graph extends EventEmitter {
*
* Remove all event listeners
* @returns Graph 实例 | Graph instance
+ * @apiCategory event
*/
public off(): this;
/**
@@ -1686,6 +1907,7 @@ export class Graph extends EventEmitter {
* Remove all listeners for the specified event
* @param eventName - 事件名称 | event name
* @returns Graph 实例 | Graph instance
+ * @apiCategory event
*/
public off(eventName: string): this;
/**
@@ -1695,9 +1917,10 @@ export class Graph extends EventEmitter {
* @param eventName - 事件名称 | event name
* @param callback - 回调函数 | callback function
* @returns Graph 实例 | Graph instance
+ * @apiCategory event
*/
- public off(eventName: string, callback: (event: IEvent) => void): this;
- public off(eventName?: string, callback?: (event: IEvent) => void) {
+ public off(eventName: string, callback: (...args: any[]) => void): this;
+ public off(eventName?: string, callback?: (...args: any[]) => void) {
return super.off(eventName, callback);
}
}
diff --git a/packages/g6/src/types/data.ts b/packages/g6/src/types/data.ts
index 72bf81ff5fa..2133c62c9b3 100644
--- a/packages/g6/src/types/data.ts
+++ b/packages/g6/src/types/data.ts
@@ -56,7 +56,7 @@ export type PartialGraphData = {
* 层级结构类别
*
* Hierarchy structure category
- * @description
+ * @remarks
* G6 中树形层级结构和组合层级结构是相互独立的，分别对应不同的数据结构
* 一些 API 需要指定层级结构类别，例如 getAncestorsData、getParentData
*
diff --git a/packages/g6/src/types/edge.ts b/packages/g6/src/types/edge.ts
index 2798decb746..a56921d0e9c 100644
--- a/packages/g6/src/types/edge.ts
+++ b/packages/g6/src/types/edge.ts
@@ -4,6 +4,17 @@ import type { BadgeStyleProps, LabelStyleProps } from '../elements/shapes';
import type { CardinalPlacement, CornerPlacement } from './placement';
import { Size } from './size';
+/**
+ * 边的方向
+ * - `'in'`: 入边
+ * - `'out'`: 出边
+ * - `'both'`: 双向边
+ *
+ * Edge direction
+ * - `'in'`: Inbound edge
+ * - `'out'`: Outbound edge
+ * - `'both'`: Bidirectional edge
+ */
export type EdgeDirection = 'in' | 'out' | 'both';
export type EdgeKey = Line | Path | Polyline;
diff --git a/packages/g6/src/types/element.ts b/packages/g6/src/types/element.ts
index 9d80e524fc9..aa29b9e68b0 100644
--- a/packages/g6/src/types/element.ts
+++ b/packages/g6/src/types/element.ts
@@ -30,7 +30,7 @@ export interface Node extends DisplayObject, ElementHooks, ElementMethods {
* Get the intersection point
* @param point - 外部位置 | external position
* @returns 交点位置 | intersection point
- * @description
+ * @remarks
* 给定一个外部位置，返回当前节点与该位置的连边与节点的交点位置
*
* Given an external position, return the intersection point of the edge between the current node and the position and the node
diff --git a/packages/g6/src/utils/layout.ts b/packages/g6/src/utils/layout.ts
index 0b36441db39..003e1d9c6cc 100644
--- a/packages/g6/src/utils/layout.ts
+++ b/packages/g6/src/utils/layout.ts
@@ -202,7 +202,7 @@ export function layoutAdapter(
* 调用布局成员方法
*
* Call layout member methods
- * @description
+ * @remarks
* 提供一种通用的调用方式来调用 G6 布局和 \@antv/layout 布局上的方法
*
* Provide a common way to call methods on G6 layout and \@antv/layout layout
diff --git a/packages/g6/src/utils/style.ts b/packages/g6/src/utils/style.ts
index 18d1dde3f70..5188bea6c61 100644
--- a/packages/g6/src/utils/style.ts
+++ b/packages/g6/src/utils/style.ts
@@ -48,7 +48,7 @@ export function mergeOptions(opt1: DisplayObjectConfig, opt2: DisplayObject
* Get the style of the sub-shape of the graphic
* @param style - 图形样式 | graphic style
* @returns 子图形样式 | sub-shape style
- * @description
+ * @remarks
* 从给定的属性对象中提取图形样式属性。删除特定的属性，如位置、变换和类名
*
* Extracts the graphic style properties from a given attribute object.
diff --git a/packages/site/src/MarkdownDocumenter.ts b/packages/site/src/MarkdownDocumenter.ts
index 65f2c0f887b..9ad167ba687 100644
--- a/packages/site/src/MarkdownDocumenter.ts
+++ b/packages/site/src/MarkdownDocumenter.ts
@@ -907,6 +907,8 @@ export class MarkdownDocumenter {
this._writeHeritageTypes(output, apiMember);
}
+ this._writeRemarksSection(output, apiMember);
+
const detailSection = new DocSection({ configuration });
const hasParameterAndReturn = this._writeParameterTables(