docs: add Chinese documentation for the API of @ant-designs/graphs (#…

…2741) * refactor: adjust graph params * docs: add general properties * docs: add overview * docs: add dendrogram api docs * docs: add flow direction graph api docs * docs: add flow graph api docs * docs: add indented tree api docs * docs: add mind map api docs * docs: add network graph api docs * docs: add org chart api docs
ant-design · Oct 23, 2024 · e286c15 · e286c15
1 parent 7787d26
commit e286c15
Show file tree

Hide file tree

Showing 48 changed files with 1,615 additions and 27 deletions.
diff --git a/packages/graphs/src/components/flow-direction-graph/options.tsx b/packages/graphs/src/components/flow-direction-graph/options.tsx
@@ -5,11 +5,12 @@ import type { GraphOptions } from '../../types';
 const { TextNode } = RCNode;
 
 export const DEFAULT_OPTIONS: GraphOptions = {
+  padding: [20, 0, 0, 50],
   node: {
     type: 'react',
     style: {
       component: (data) => <TextNode type="filled" text={data.id} />,
-      size: [80, 40],
+      size: [100, 40],
       ports: [{ placement: 'left' }, { placement: 'right' }],
     },
     state: {

diff --git a/packages/graphs/src/components/flow-graph/options.tsx b/packages/graphs/src/components/flow-graph/options.tsx
@@ -5,11 +5,12 @@ import type { FlowGraphOptions } from './types';
 const { TextNode } = RCNode;
 
 export const DEFAULT_OPTIONS: FlowGraphOptions = {
+  padding: [20, 0, 0, 50],
   node: {
     type: 'react',
     style: {
       component: (data) => <TextNode type="filled" text={data.id} />,
-      size: [80, 40],
+      size: [100, 40],
       ports: [{ placement: 'left' }, { placement: 'right' }],
     },
     state: {

diff --git a/packages/graphs/src/components/indented-tree/index.tsx b/packages/graphs/src/components/indented-tree/index.tsx
@@ -17,11 +17,11 @@ export const IndentedTree: ForwardRefExoticComponent<
   PropsWithoutRef<PropsWithChildren<IndentedTreeOptions>> & RefAttributes<Graph>
 > = forwardRef<Graph, PropsWithChildren<IndentedTreeOptions>>(({ children, ...props }, ref) => {
   const options = useMemo(() => {
-    const { type = 'default', nodeMinWidth, nodeMaxWidth, mode = 'right', ...restProps } = props;
+    const { type = 'default', nodeMinWidth, nodeMaxWidth, direction = 'right', ...restProps } = props;
     const options = mergeOptions(
       COMMON_OPTIONS,
       DEFAULT_OPTIONS,
-      getIndentedTreeOptions({ type, nodeMinWidth, nodeMaxWidth, mode }),
+      getIndentedTreeOptions({ type, nodeMinWidth, nodeMaxWidth, direction }),
       restProps,
     );
     return options;

diff --git a/packages/graphs/src/components/indented-tree/options.tsx b/packages/graphs/src/components/indented-tree/options.tsx
@@ -80,8 +80,8 @@ export const getIndentedTreeOptions = ({
   type,
   nodeMinWidth,
   nodeMaxWidth,
-  mode,
-}: Pick<IndentedTreeOptions, 'type' | 'nodeMinWidth' | 'nodeMaxWidth' | 'mode'>): IndentedTreeOptions => {
+  direction,
+}: Pick<IndentedTreeOptions, 'type' | 'nodeMinWidth' | 'nodeMaxWidth' | 'direction'>): IndentedTreeOptions => {
   let options: IndentedTreeOptions = {};
   const minWidth = nodeMinWidth || 0;
   const maxWidth = nodeMaxWidth || 300;
@@ -201,10 +201,10 @@ export const getIndentedTreeOptions = ({
     };
   }
 
-  if (mode) {
+  if (direction) {
     options.layout ||= {} as SingleLayoutOptions;
     Object.assign(options.layout as SingleLayoutOptions, {
-      direction: mode === 'alternate' ? 'H' : mode === 'left' ? 'RL' : 'LR',
+      direction: direction === 'alternate' ? 'H' : direction === 'left' ? 'RL' : 'LR',
     });
   }
 

diff --git a/packages/graphs/src/components/indented-tree/types.ts b/packages/graphs/src/components/indented-tree/types.ts
@@ -7,10 +7,10 @@ export interface IndentedTreeOptions extends GraphOptions {
    */
   type?: 'default' | 'linear' | 'boxed';
   /**
-   * The mode of the mind map.
+   * The direction of the mind map.
    * @default 'right'
    */
-  mode?: 'left' | 'right' | 'alternate';
+  direction?: 'left' | 'right' | 'alternate';
   /**
    * The minimum width of the tree nodes. If the text of a tree node is too short, it will be centered.
    * @default 0

diff --git a/packages/graphs/src/components/mind-map/index.tsx b/packages/graphs/src/components/mind-map/index.tsx
@@ -17,11 +17,11 @@ export const MindMap: ForwardRefExoticComponent<
   PropsWithoutRef<PropsWithChildren<MindMapOptions>> & RefAttributes<Graph>
 > = forwardRef<Graph, PropsWithChildren<MindMapOptions>>(({ children, ...props }, ref) => {
   const options = useMemo(() => {
-    const { type = 'default', nodeMinWidth, nodeMaxWidth, mode = 'alternate', ...restProps } = props;
+    const { type = 'default', nodeMinWidth, nodeMaxWidth, direction = 'alternate', ...restProps } = props;
     const options = mergeOptions(
       COMMON_OPTIONS,
       DEFAULT_OPTIONS,
-      getMindMapOptions({ type, nodeMinWidth, nodeMaxWidth, mode }),
+      getMindMapOptions({ type, nodeMinWidth, nodeMaxWidth, direction }),
       restProps,
     );
     return options;

diff --git a/packages/graphs/src/components/mind-map/options.tsx b/packages/graphs/src/components/mind-map/options.tsx
@@ -77,10 +77,10 @@ export const DEFAULT_OPTIONS: MindMapOptions = {
 
 export function getMindMapOptions({
   type,
-  mode,
+  direction,
   nodeMinWidth,
   nodeMaxWidth,
-}: Pick<MindMapOptions, 'type' | 'nodeMaxWidth' | 'nodeMinWidth' | 'mode'>): MindMapOptions {
+}: Pick<MindMapOptions, 'type' | 'nodeMaxWidth' | 'nodeMinWidth' | 'direction'>): MindMapOptions {
   let options: MindMapOptions = {};
   if (type === 'boxed') {
     const minWidth = nodeMinWidth || 120;
@@ -209,9 +209,9 @@ export function getMindMapOptions({
     };
   }
 
-  if (mode) {
+  if (direction) {
     options.layout ||= {} as SingleLayoutOptions;
-    (options.layout as SingleLayoutOptions).direction = mode === 'alternate' ? 'H' : mode === 'left' ? 'RL' : 'LR';
+    (options.layout as SingleLayoutOptions).direction = direction === 'alternate' ? 'H' : direction === 'left' ? 'RL' : 'LR';
   }
 
   return options;

diff --git a/packages/graphs/src/components/mind-map/types.ts b/packages/graphs/src/components/mind-map/types.ts
@@ -7,10 +7,10 @@ export interface MindMapOptions extends GraphOptions {
    */
   type?: 'default' | 'linear' | 'boxed';
   /**
-   * The mode of the mind map.
+   * The direction of the mind map.
    * @default 'alternate'
    */
-  mode?: 'left' | 'right' | 'alternate';
+  direction?: 'left' | 'right' | 'alternate';
   /**
    * The minimum width of the node.
    * @default 0(default) 120(boxed)

diff --git a/packages/graphs/src/components/network-graph/options.tsx b/packages/graphs/src/components/network-graph/options.tsx
@@ -5,9 +5,6 @@ const SIZE = 32;
 export const DEFAULT_OPTIONS: NetworkGraphOptions = {
   node: {
     type: 'circle',
-    style: {
-      size: SIZE,
-    },
   },
   layout: {
     type: 'd3-force',

diff --git a/packages/graphs/src/components/organization-chart/options.tsx b/packages/graphs/src/components/organization-chart/options.tsx
@@ -5,12 +5,12 @@ import { OrganizationChartOptions } from './types';
 const { TextNode } = RCNode;
 
 export const DEFAULT_OPTIONS: OrganizationChartOptions = {
-  padding: [20, 0, 0, 40],
+  padding: [20, 0, 0, 50],
   node: {
     type: 'react',
     style: {
       component: (data) => <TextNode type="filled" text={data.id} />,
-      size: [80, 40],
+      size: [100, 40],
       ports: [{ placement: 'top' }, { placement: 'bottom' }],
     },
     state: {

diff --git a/packages/graphs/src/types.ts b/packages/graphs/src/types.ts
@@ -18,15 +18,15 @@ export interface GraphOptions extends ContainerConfig, Omit<G6GraphOptions, 'plu
   /**
    * 交互
    */
-  behaviors?: BehaviorOptions | ((this: Graph, prev: BehaviorOptions) => BehaviorOptions);
+  behaviors?: BehaviorOptions | ((this: Graph, behaviors: BehaviorOptions) => BehaviorOptions);
   /**
    * 画布插件
    */
-  plugins?: PluginOptions | ((this: Graph, prev: PluginOptions) => PluginOptions);
+  plugins?: PluginOptions | ((this: Graph, plugins: PluginOptions) => PluginOptions);
   /**
    * 数据转换器
    */
-  transforms?: TransformOptions | ((this: Graph, prev: TransformOptions) => TransformOptions);
+  transforms?: TransformOptions | ((this: Graph, transforms: TransformOptions) => TransformOptions);
 }
 
 export type ParsedGraphOptions = Required<GraphOptions>;
diff --git a/site/.dumirc.ts b/site/.dumirc.ts
@@ -138,6 +138,14 @@ export default defineConfig({
         },
         order: 10,
       },
+      {
+        slug: 'options/graphs',
+        title: {
+          zh: '关系图',
+          en: 'Relation Graph',
+        },
+        order: 1,
+      },
     ],
     examples: [
       {
@@ -160,7 +168,7 @@ export default defineConfig({
         slug: 'relations',
         icon: 'line',
         title: {
-          zh: '关系图表',
+          zh: '关系图',
           en: 'Relations',
         },
       },

diff --git a/site/docs/options/general-properties.zh.md b/site/docs/options/general-properties.zh.md
@@ -0,0 +1,14 @@
+---
+title: 通用属性
+---
+
+> Tips: 以下通用属性适用于 charts 组件，不支持的组件会单独说明。
+
+| 参数                | 说明                                                       | 类型                            | 默认值  |
+| ------------------- | ---------------------------------------------------------- | ------------------------------- | ------- |
+| containerStyle      | 配置图表容器的样式，接受一个包含 CSS 属性和值的对象        | `React.CSSProperties`           | -       |
+| containerAttributes | 为图表容器添加自定义的 HTML 属性                           | `Record<string, any>`           | -       |
+| className           | 添加在组件最外层的 className                               | `string`                        | -       |
+| loading             | 表示图表是否处于加载状态                                   | `boolean`                       | `false` |
+| loadingTemplate     | 自定义加载模板，当图表加载时显示的元素                     | `React.ReactElement`            | -       |
+| errorTemplate       | 自定义错误模板，当图表出错时调用的函数，返回显示的错误信息 | `(e: Error) => React.ReactNode` | -       |
diff --git a/site/docs/options/graphs/demos/dendrogram/collapse-expand.tsx b/site/docs/options/graphs/demos/dendrogram/collapse-expand.tsx
@@ -0,0 +1,50 @@
+import { Dendrogram, type DendrogramOptions } from '@ant-design/graphs';
+import React from 'react';
+
+const data = {
+  nodes: [
+    { id: 'Modeling Methods', depth: 0, children: ['Classification', 'Consensus', 'Regression'] },
+    { id: 'Classification', depth: 1 },
+    { id: 'Consensus', depth: 1, children: ['Models diversity', 'Methods', 'Common'] },
+    { id: 'Models diversity', depth: 2 },
+    { id: 'Methods', depth: 2 },
+    { id: 'Common', depth: 2 },
+    {
+      id: 'Regression', depth: 1, "children": [
+        "Multiple linear regression",
+        "Partial least squares",
+        "Multi-layer feedforward neural network",
+        "General regression neural network",
+        "Support vector regression"
+      ]
+    },
+    { "id": "Multiple linear regression", depth: 3 },
+    { "id": "Partial least squares", depth: 3 },
+    { "id": "Multi-layer feedforward neural network", depth: 3 },
+    { "id": "General regression neural network", depth: 3 },
+    { "id": "Support vector regression", depth: 3 },
+  ],
+  edges: [
+    { source: 'Modeling Methods', target: 'Classification' },
+    { source: 'Modeling Methods', target: 'Consensus' },
+    { source: 'Modeling Methods', target: 'Regression' },
+    { source: 'Consensus', target: 'Models diversity' },
+    { source: 'Consensus', target: 'Methods' },
+    { source: 'Consensus', target: 'Common' },
+    { source: 'Regression', target: 'Multiple linear regression' },
+    { source: 'Regression', target: 'Partial least squares' },
+    { source: 'Regression', target: 'Multi-layer feedforward neural network' },
+    { source: 'Regression', target: 'General regression neural network' },
+    { source: 'Regression', target: 'Support vector regression' },
+  ],
+};
+export default () => {
+  const options: DendrogramOptions = {
+    containerStyle: { height: '320px' },
+    autoFit: 'view',
+    data,
+    behaviors: (behaviors) => [...behaviors, 'collapse-expand'],
+  };
+
+  return <Dendrogram {...options} />
+};
diff --git a/site/docs/options/graphs/demos/dendrogram/compact.tsx b/site/docs/options/graphs/demos/dendrogram/compact.tsx
@@ -0,0 +1,56 @@
+import { Dendrogram, type DendrogramOptions } from '@ant-design/graphs';
+import React from 'react';
+
+const data = {
+  nodes: [
+    { id: 'Modeling Methods', depth: 0, children: ['Classification', 'Consensus', 'Regression'] },
+    { id: 'Classification', depth: 1 },
+    { id: 'Consensus', depth: 1, children: ['Models diversity', 'Methods', 'Common'] },
+    { id: 'Models diversity', depth: 2 },
+    { id: 'Methods', depth: 2 },
+    { id: 'Common', depth: 2 },
+    {
+      id: 'Regression', depth: 1, "children": [
+        "Multiple linear regression",
+        "Partial least squares",
+        "Multi-layer feedforward neural network",
+        "General regression neural network",
+        "Support vector regression"
+      ]
+    },
+    { "id": "Multiple linear regression", depth: 3 },
+    { "id": "Partial least squares", depth: 3 },
+    { "id": "Multi-layer feedforward neural network", depth: 3 },
+    { "id": "General regression neural network", depth: 3 },
+    { "id": "Support vector regression", depth: 3 },
+  ],
+  edges: [
+    { source: 'Modeling Methods', target: 'Classification' },
+    { source: 'Modeling Methods', target: 'Consensus' },
+    { source: 'Modeling Methods', target: 'Regression' },
+    { source: 'Consensus', target: 'Models diversity' },
+    { source: 'Consensus', target: 'Methods' },
+    { source: 'Consensus', target: 'Common' },
+    { source: 'Regression', target: 'Multiple linear regression' },
+    { source: 'Regression', target: 'Partial least squares' },
+    { source: 'Regression', target: 'Multi-layer feedforward neural network' },
+    { source: 'Regression', target: 'General regression neural network' },
+    { source: 'Regression', target: 'Support vector regression' },
+  ],
+};
+
+export default () => {
+  const options: DendrogramOptions = {
+    containerStyle: { height: '320px' },
+    compact: true,
+    autoFit: 'view',
+    data,
+    animation: false,
+  };
+
+  return <div style={{ display: 'grid', gridTemplateColumns: 'repeat(3, 1fr)' }}>
+    <Dendrogram {...options} direction='vertical' />
+    <Dendrogram {...options} direction='horizontal' />
+    <Dendrogram {...options} direction='radial' />
+  </div>;
+};
diff --git a/site/docs/options/graphs/demos/dendrogram/default.tsx b/site/docs/options/graphs/demos/dendrogram/default.tsx
@@ -0,0 +1,50 @@
+import { Dendrogram, type DendrogramOptions } from '@ant-design/graphs';
+import React from 'react';
+
+const data = {
+  nodes: [
+    { id: 'Modeling Methods', depth: 0, children: ['Classification', 'Consensus', 'Regression'] },
+    { id: 'Classification', depth: 1 },
+    { id: 'Consensus', depth: 1, children: ['Models diversity', 'Methods', 'Common'] },
+    { id: 'Models diversity', depth: 2 },
+    { id: 'Methods', depth: 2 },
+    { id: 'Common', depth: 2 },
+    {
+      id: 'Regression', depth: 1, "children": [
+        "Multiple linear regression",
+        "Partial least squares",
+        "Multi-layer feedforward neural network",
+        "General regression neural network",
+        "Support vector regression"
+      ]
+    },
+    { "id": "Multiple linear regression", depth: 3 },
+    { "id": "Partial least squares", depth: 3 },
+    { "id": "Multi-layer feedforward neural network", depth: 3 },
+    { "id": "General regression neural network", depth: 3 },
+    { "id": "Support vector regression", depth: 3 },
+  ],
+  edges: [
+    { source: 'Modeling Methods', target: 'Classification' },
+    { source: 'Modeling Methods', target: 'Consensus' },
+    { source: 'Modeling Methods', target: 'Regression' },
+    { source: 'Consensus', target: 'Models diversity' },
+    { source: 'Consensus', target: 'Methods' },
+    { source: 'Consensus', target: 'Common' },
+    { source: 'Regression', target: 'Multiple linear regression' },
+    { source: 'Regression', target: 'Partial least squares' },
+    { source: 'Regression', target: 'Multi-layer feedforward neural network' },
+    { source: 'Regression', target: 'General regression neural network' },
+    { source: 'Regression', target: 'Support vector regression' },
+  ],
+};
+export default () => {
+  const options: DendrogramOptions = {
+    containerStyle: { height: '320px' },
+    autoFit: 'view',
+    data,
+    animation: false,
+  };
+
+  return <Dendrogram {...options} />
+};