docs: adjust docs of data (#5211)

* docs: adjust docs of data * docs: update api docs
antvis · Dec 1, 2023 · 3534d46 · 3534d46
1 parent 989051e
commit 3534d46
Showing 80 changed files with 1,626 additions and 2,686 deletions.
diff --git a/packages/site/.dumirc.ts b/packages/site/.dumirc.ts
@@ -159,27 +159,34 @@ export default defineConfig({
         },
         order: 2,
       },
+      {
+        slug: 'apis/item',
+        title: {
+          zh: '元素',
+          en: 'Elements',
+        },
+      },
       {
         slug: 'apis/item/node',
         title: {
-          zh: '元素 - 节点',
-          en: 'Item - Node',
+          zh: '节点',
+          en: 'Node',
         },
         order: 3,
       },
       {
         slug: 'apis/item/edge',
         title: {
-          zh: '元素 - 边',
-          en: 'Item - Edge',
+          zh: '边',
+          en: 'Edge',
         },
         order: 4,
       },
       {
         slug: 'apis/item/combo',
         title: {
-          zh: '元素 - Combo',
-          en: 'Item - Combo',
+          zh: 'Combo',
+          en: 'Combo',
         },
         order: 5,
       },

diff --git a/packages/site/docs/apis/data/ComboDisplayModel.en.md b/packages/site/docs/apis/data/ComboDisplayModel.en.md
diff --git a/packages/site/docs/apis/data/ComboDisplayModel.zh.md b/packages/site/docs/apis/data/ComboDisplayModel.zh.md
@@ -1,238 +1,44 @@
 ---
 title: ComboDisplayModel 渲染数据
-order: 12
+order: 11
 ---
 
-ComboDisplayModel（Combo 的渲染/展示数据） 由 ComboModel（内部流转数据）通过您配置在图实例上 mapper（[specification.combo](../graph/Specification.zh.md#combo)）映射后的结果，仅用于内部渲染时消费，您在其他任何地方不会消费它。数据类型继承自内部流转的 Combo 数据类型 [`ComboModel`](./ComboModel.zh.md)，扩展后定义如下：
+ComboDisplayModel 为 Combo 的渲染数据，由 [ComboModel](./ComboModel.zh.md) 经过[数据映射](./DataIntro.zh.md#mappers-数据映射)后的结果，该数据仅能被 G6 访问。
 
-```typescript
-interface ComboDisplayModel {
-  id: string | number;
-  data: ComboDisplayModelData; // 扩展了 ComboModelData
-}
-```
+<embed src="../../common/DataID.zh.md"></embed>
 
-## id
+## data <Badge type="error">必须</Badge>
 
-Combo 的唯一 ID，Combo 创建后，ID 不可被修改。
+基于 [ComboModel](./ComboModel.zh.md) 的内容额外加上了图形样式配置。
 
-- **是否必须**: 是；
-- **类型**: `string|number`
+<embed src="../../common/DataAttrTips.zh.md"></embed>
 
-## data
+<embed src="../../common/LodLevels.zh.md"></embed>
 
-ComboDisplayModelData 中的数据已经是 ComboModel 通过 Graph 实例上配置的对应 mapper（[specification.combo](../graph/Specification.zh.md#combo)）映射后的结果，这里面应当存储所有 ComboModel 的内容，再额外加上许多的图形样式配置。
+<embed src="../../common/DataAnimates.zh.md"></embed>
 
-- **是否必须**: 是；
-- **类型**: [`ComboDisplayModelData`](#combodisplaymodeldatalodlevels)，基于 [`ComboModel`](./ComboModel.zh.md#combomodeldatatype) 额外扩展内容如下文：
+### keyShape
 
-### ComboDisplayModelData.lodLevels
+**类型**：`ShapeStyle`
 
-对于该 Combo 而言，设定图缩放等级的划分方式。是一个缩放系数范围的数组，表示缩放等级的划分。其中有一项的 `primary` 应当为 `true`，代表该层级的序号为 0，`zoomRange` 小于当前层级的，序号递减；大于当前层级的，序号递增。序号为在下面的图形配置中 `lod` 所对应的值。
+主图形的样式配置
 
-- **是否必须**: 否；
-- **类型**: `LodLevel`[]，其中 `LodLevel` 如下表：
+> `'circle-combo'` 的主图形是 ['circle'](/apis/shape/circle-style-props)；`'rect-combo'` 的主图形是 ['rect'](/apis/shape/rect-style-props)
 
-| Name        | Type               | Description                                                                                                                                                                                                                              |
-| :---------- | :----------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `zoomRange` | `[number, number]` | 本层级所定义的图缩放等级范围，当图缩放等级 zoom >= zoomRange[0] && zoom < zoomRange[1] 时，表示在该层级下                                                                                                                                |
-| `primary`   | `boolean`          | 是否为主层级，若为 `true` 则代表该层级的序号为 0，`zoomRange` 小于当前层级的，序号递减；大于当前层级的，序号递增。序号为在下面的图形配置中 `lod` 所对应的值。在 `ComboDisplayModelData.lodLevels` 中，应当只有一个层级为 `primary: true` |
+<embed src="../../common/DataHaloShape.zh.md"></embed>
 
-### ComboDisplayModelData.animates
+<embed src="../../common/DataLabelShape.zh.md"></embed>
 
-出现、消失、显示、隐藏、更新时，各个图形动画配置。支持一次更新，多个动画的顺序执行（`order`）。[动画 DEMO](/zh/examples/scatter/changePosition/#itemAnimates)。
+<embed src="../../common/DataLabelBackgroundShape.zh.md"></embed>
 
-- **是否必须**: 否；
-- **类型**: `IAnimates`，定义如下：
+<embed src="../../common/DataBadgeShapes.zh.md"></embed>
 
-```typescript
-interface IAnimates {
-  buildIn?: IAnimate[]; // Combo 中某些图形创建时的动画
-  buildOut?: IAnimate[]; // Combo 中某些图形销毁时的动画
-  show?: IAnimate[]; // Combo 中某些图形从隐藏变为显示时的动画
-  hide?: IAnimate[]; // Combo 中某些图形从显示变为隐藏时的动画
-  update?: (IAnimate | IStateAnimate)[]; // Combo 中某些图形在相关数据或状态更新时的动画
-}
-```
+<embed src="../../common/DataAnchorShapes.zh.md"></embed>
 
-其中，`IAnimate` 定义如下：
+<embed src="../../common/DataOtherShapes.zh.md"></embed>
 
-| Name                   | Type       | Default                                      | Description                                                                                                                                   |
-| :--------------------- | :--------- | :------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------- |
-| `IAnimate.fields`      | `string[]` | `undefined`                                  | 该动画相关的图形样式属性名称，例如 `['fill', 'lineWidth']`                                                                                    |
-| `IAnimate.shapeId`     | `string`   | `group`                                      | 该动画需要在哪个图形上执行，此处指定该图形的 ID。不指定则代表整个图形分组上的动画                                                             |
-| `IAnimate.order?`      | `number`   | `0`                                          | 该动画在 `IAnimate[]` 中执行的顺序，借此可实现一次更新多个动画的顺序播放                                                                      |
-| `IAnimate.duration?`   | `number`   | `500`                                        | 该动画执行一次所使用的时间，该值越小，则动画速度越快                                                                                          |
-| `IAnimate.iterations?` | `number`   | `1`                                          | 该动画执行的次数，-1 代表循环执行                                                                                                             |
-| `IAnimate.easing?`     | `string`   | `'cubic-bezier(0.250, 0.460, 0.450, 0.940)'` | 该动画的缓动函数，可以设置的值可参考 [MDN easing 定义](https://developer.mozilla.org/en-US/docs/Web/API/KeyframeEffect/KeyframeEffect#easing) |
-
-`IStateAnimate` 定义如下，即在 `IAnimate` 基础上增加了一个指定状态的字段 `states`，表示该动画在这些状态变更的时候执行：
-
-```typescript
-interface IStateAnimate extends IAnimate {
-  states: string[];
-}
-```
-
-### ComboDisplayModelData.keyShape
-
-Combo 主图形的样式配置。Combo 的主图形表达了 Combo 的主要形状。还用于计算边的连入位置。
-
-- **是否必须**: 否；
-- **类型**: `ShapeStyle`，根据不同的主图形，图形样式配置项不同。例如 `'circle-combo'` 的主图形是 `'circle'` 参考 [Circle 图形样式](../shape/CircleStyleProps.zh.md)；`'rect-combo'` 的主图形是 `'rect'` 参考 [Rect 图形样式](../shape/RectStyleProps.zh.md)。
-
-### ComboDisplayModelData.haloShape
-
-在内置的 Combo 和主题中，`haloShape` 指的是 Combo 在 `active`（一般在鼠标 hover 时该状态被触发） 和 `selected`（一般在选中状态下该状态被触发） 状态下，主图形 (`keyShape`) 周围展示的光晕效果的图形。在内置 Combo 的逻辑中，`haloShape` 的图形类型、颜色跟随主图形 (`keyShape`)。
-
-- **是否必须**: 否；
-- **类型**: `ShapeStyle`，`haloShape` 的图形类型跟随主图形(`keyShape`)。根据不同的主图形，图形样式配置项不同。例如 `'circle-combo'` 的主图形是 `'circle'` 参考 [Circle 图形样式](../shape/CircleStyleProps.zh.md)；`'rect-combo'` 的主图形是 `'rect'` 参考 [Rect 图形样式](../shape/RectStyleProps.zh.md)。
-
-### ComboDisplayModelData.labelShape
-
-Combo 的文本图形，内置 Combo 或继承内置 Combo（未复写相关内容）的自定义 Combo 均支持。
-
-- **是否必须**: 否；
-- **类型**:
-
-```typescript
-  TextStyleProps & {
-    /**
-     * 文本相对于 Combo 主图形 (keyShape) 的位置，可指定方位以及在 combo 的内部或外部
-     */
-    position?: 'top' | 'bottom' | 'left' | 'right' | 'left-top' | 'ouside-top'| 'ouside-left' | 'ouside-right' | 'ouside-bottom';
-    /**
-     * 文本图形相对于主图形 (keyShape) 在 x 方向上的偏移量
-     */
-    offsetX?: number;
-    /**
-     * 文本图形相对于主图形 (keyShape) 在 y 方向上的偏移量
-     */
-    offsetY?: number;
-    /**
-     * 文本图形相对于主图形 (keyShape) 在 z 方向上的偏移量
-     */
-    offsetZ?: number;
-    /**
-     * 允许文本的最大宽度，若指定为数字，则表示像素值，若指定为带有 '%' 的文本，代表相对于主图形 (keyShape) 包围盒大小的百分比。默认值为 '200%'，表示文本图形的最大宽度不可以超过主图形宽度的两倍。若超过，则自动截断并在末尾增加省略号 '...'
-     */
-    maxWidth?: string | number;
-    /**
-     * 文本旋转角度（弧度制）
-     */
-    angle?: number;
-  };
-```
-
-其中，相关的图形样式参考 [Text 图形样式](../shape/TextStyleProps.zh.md)。
-
-### ComboDisplayModelData.labelBackgroundShape
-
-Combo 的文本的背景图形，是一个矩形。若不设置则不显示。设置为 `{}` 将使用主题中默认的样式显示文本背景图形。
-
-- **是否必须**: 否；
-- **类型**:
-
-```typescript
-ShapeStyle & {
-  padding?: number | number[]; // 文本距离背景矩形四周的留白距离
-};
-```
-
-其中，参考矩形样式类型 [`RectStyleProps`](../shape/RectStyleProps.zh.md)。
-
-### ComboDisplayModelData.badgeShapes
-
-Combo 四周的徽标，单个徽标包括了 Combo 和背景图形，badgeShapes 配置的是多个徽标。
-
-- **是否必须**: 否；
-- **类型**:
-
-```typescript
-  {
-    /**
-     * 徽标的背景颜色（对所有徽标生效，优先级低于下面单个徽标的 color 设置）
-     */
-    color?: string;
-    /**
-     * 徽标背景颜色的色板，意味着下面各个徽标将自动取用该色板中的颜色。
-     * 优先级低于下面单个徽标的 color 设置
-     */
-    palette?: string[];
-    /**
-     * 徽标上文本的颜色（对所有徽标生效，优先级低于下面单个徽标的 textColor 设置）
-     */
-    textColor?: string;
-    /**
-     * 单个徽标的样式配置，由县局高于上面的配置
-     */
-    [key: number]: ShapeStyle & {
-     /**
-       * 该徽标的位置，支持的取值见下文
-       */
-      position?: IBadgePosition;
-      /**
-       * 该徽标的背景色
-       */
-      color?: string;
-      /**
-       * 该徽标的文本色
-       */
-      textColor?: string;
-    };
-  }
-```
-
-`BadgePosition` 取值如下：
-
-| Value           | Description                |
-| :-------------- | :------------------------- |
-| `'rightTop'`    | 右上角，推荐               |
-| `'right'`       | 右侧中间，推荐             |
-| `'rightBottom'` | 右下角，推荐               |
-| `'leftTop'`     | 左上角                     |
-| `'left'`        | 左侧中间                   |
-| `'leftBottom'`  | 左下角                     |
-| `'bottom'`      | 下方中间                   |
-| `'top'`         | 上方中间                   |
-| `'bottomRight'` | 右下角，同 `'rightBottom'` |
-| `'bottomLeft'`  | 左下角，同 `'leftBottom'`  |
-| `'topRight'`    | 右上角，同 `'rightTop'`    |
-| `'topLeft'`     | 左上角，同 `'leftTop'`     |
-
-### ComboDisplayModelData.anchorShapes
-
-Combo 四周的边连入位置圆形图形（连接桩），anchorShapess 配置的是多个连接桩。
-
-- **是否必须**: 否；
-- **类型**:
-
-```typescript
-// 外层可配置对所有连接桩（圆形）的样式，优先级低于单独的连接桩配置
-CircleStyleProps & {
-  // 单独的连接桩图形配置，优先级高于外层的 CircleStyleProps
-  [key: number]: CircleStyleProps & {
-    // 该连接桩的位置，可配置字符串或数字数组表示相对于主图形 (keyShape) 包围盒的百分比位置，例如 [0.5, 1] 表示位于主图形的右侧中间
-    position?: 'top' | 'left' | 'bottom' | 'right' | [number, number];
-  };
-};
-```
-
-其中，相关的图形样式参考 [`CircleStyleProps` 圆形图形样式](../shape/CircleStyleProps.zh.md)。
-
-### ComboDisplayModelData.otherShapes
-
-上面所有的 xxShape(s) 均为 G6 定义的规范 Combo 中可能存在的图形。自定义 Combo 中的其他图形应当定义和配置在 `otherShapes` 中。
-
-- **是否必须**: 否；
-- **类型**:
-
-```typescript
-{
-  // key 为图形 id，规范格式为 xxShape
-  // value 为图形样式配置（不同图形配置不同，见图形相关文档），以及图形的动画
-  [shapeId: string]: ShapeStyleProps;
-}
-```
-
-其中，不同的图形样式参考[图形样式](../shape/BaseStyleProps.zh.md)目录下对应的图形类型文档。
+:::info{title=提示}
+下列属性继承自 [ComboModel](./ComboModel.zh.md)
+:::
+
+<embed src="../../common/ComboUserModel.zh.md"></embed>
diff --git a/packages/site/docs/apis/data/ComboModel.en.md b/packages/site/docs/apis/data/ComboModel.en.md
@@ -1,77 +1,16 @@
 ---
 title: ComboModel
-order: 8
+order: 10
 ---
 
-ComboModel is the combo data that is internally circulated, which is calculated from `ComboUserModel` through transformations on the graph instance. The data you consume anywhere later is based on this data. Each item in Combo inherits from [`ComboUserModel`](./ComboUserModel.en.md) and is defined as follows after extension:
+ComboModel is the internal combo data, which is obtained by [ComboUserModel](./ComboUserModel.en.md) through [transforms](./DataIntro.en.md#transforms).
 
-```typescript
-interface ComboModel {
-  id: string | number;
-  data: ComboModelData; // = ComboModelData
-}
-```
+<embed src="../../common/DataInnerModelTips.en.md"></embed>
 
-## id
+<embed src="../../common/DataID.en.md"></embed>
 
-The unique ID of the combo. After the combo is created, the ID cannot be modified.
+## data <Badge type="error">Required</Badge>
 
-- **Required**: True;
-- **Type**: `string|number`
+<embed src="../../common/DataAttrTips.en.md"></embed>
 
-## data
-
-The data in InnerModelData has been generated from UserModelData through a series of transform functions on the graph instance. The business data may have been transformed, filtered, and merged.
-
-- **Required**: True;
-- **Type**: `ComboModelData`, the definition is the same as [`ComboUserModel`](./ComboUserModel.en.md#ComboModelDatatype), as follows:
-
-### ComboModelData.type
-
-The rendering type of the combo, which can be a combo type registered on the graph class. The built-in and default registered types are `'circle-combo'` and `'rect-combo'`. The default is `'circle-combo'`.
-
-- **Required**: False;
-- **Type**: `string`；
-
-### ComboModelData.visible
-
-Whether the combo is displayed by default.
-
-- **Required**: False;
-- **Type**: `boolean`；
-
-### ComboModelData.color
-
-The theme color of the key shape (`keyShape`) of the combo, with a value in hexadecimal string format. Provided for simple configuration. More style configurations should be configured in the Combo mapper of the graph instance, including keyShape and various graphic styles.
-
-- **Required**: False;
-- **Type**: `string`；
-
-### ComboModelData.label
-
-The text content of the `labelShape` of the combo. Provided for simple configuration. More style configurations should be configured in the Combo mapper of the graph instance, including the `text` value of `labelShape` or other graphic styles.
-
-- **Required**: False;
-- **Type**: `string`；
-
-### ComboModelData.icon
-
-The configuration of the icon on the combo. The built-in combo's icon is drawn after the text. Provided for simple configuration. More style configurations should be configured in the Combo mapper of the graph instance, including the graphic style of the iconShape.
-
-- **Required**: False;
-- **Type**:
-
-```typescript
-{
-  type: 'text' | 'icon',
-  img?: string, // Required when type is 'text'
-  text?: string, // Required when type is 'icon'
-}
-```
-
-### ComboModelData.parentId
-
-The ID of the parent combo to which the combo belongs. `undefined` means it is a root.
-
-- **Required**: False;
-- **Type**: `string | number`；
+<embed src="../../common/ComboUserModel.en.md"></embed>