Skip to content

Commit

Permalink
docs: adjust docs of data
Browse files Browse the repository at this point in the history
  • Loading branch information
@Aarebecca
Aarebecca committed Nov 29, 2023
1 parent 48308e0 commit 16af916
Show file tree
Hide file tree
Showing 48 changed files with 1,211 additions and 1,979 deletions.
190 changes: 26 additions & 164 deletions packages/site/docs/apis/data/ComboDisplayModel.en.md
View file

Large diffs are not rendered by default.

202 changes: 32 additions & 170 deletions packages/site/docs/apis/data/ComboDisplayModel.zh.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ title: ComboDisplayModel 渲染数据
order: 12
---

ComboDisplayModel（Combo 的渲染/展示数据） 由 ComboModel（内部流转数据）通过您配置在图实例上 mapper（[specification.combo](../graph/Specification.zh.md#combo)）映射后的结果，仅用于内部渲染时消费，您在其他任何地方不会消费它。数据类型继承自内部流转的 Combo 数据类型 [`ComboModel`](./ComboModel.zh.md)，扩展后定义如下：
ComboDisplayModel（Combo 的渲染/展示数据） 由 ComboModel（内部流转数据）通过您配置在图实例上 mapper（[specification.combo](../graph/Specification.zh.md#combo)）映射后的结果，仅用于内部渲染时消费，您在其他任何地方不会消费它。数据类型继承自内部流转的 Combo 数据类型 [ComboModel](./ComboModel.zh.md)，扩展后定义如下：

```typescript
interface ComboDisplayModel {
Expand All @@ -12,200 +12,61 @@ interface ComboDisplayModel {
}
```

## id
## id <Badge type="error">必须</Badge>

Combo 的唯一 ID，Combo 创建后，ID 不可被修改。
**类型**：`string | number`

- **是否必须**: 是；
- **类型**: `string|number`
Combo 的唯一 ID，Combo 创建后，ID 不可被修改。

## data
## data <Badge type="error">必须</Badge>

ComboDisplayModelData 中的数据已经是 ComboModel 通过 Graph 实例上配置的对应 mapper（[specification.combo](../graph/Specification.zh.md#combo)）映射后的结果，这里面应当存储所有 ComboModel 的内容，再额外加上许多的图形样式配置。

- **是否必须**: 是；
- **类型**: [`ComboDisplayModelData`](#combodisplaymodeldatalodlevels)，基于 [`ComboModel`](./ComboModel.zh.md#combomodeldatatype) 额外扩展内容如下文：

### ComboDisplayModelData.lodLevels

对于该 Combo 而言，设定图缩放等级的划分方式。是一个缩放系数范围的数组，表示缩放等级的划分。其中有一项的 `primary` 应当为 `true`，代表该层级的序号为 0，`zoomRange` 小于当前层级的，序号递减；大于当前层级的，序号递增。序号为在下面的图形配置中 `lod` 所对应的值。

- **是否必须**: 否；
- **类型**: `LodLevel`[]，其中 `LodLevel` 如下表：

| Name | Type | Description |
| :---------- | :----------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `zoomRange` | `[number, number]` | 本层级所定义的图缩放等级范围，当图缩放等级 zoom >= zoomRange[0] && zoom < zoomRange[1] 时，表示在该层级下 |
| `primary` | `boolean` | 是否为主层级，若为 `true` 则代表该层级的序号为 0，`zoomRange` 小于当前层级的，序号递减；大于当前层级的，序号递增。序号为在下面的图形配置中 `lod` 所对应的值。在 `ComboDisplayModelData.lodLevels` 中，应当只有一个层级为 `primary: true` |

### ComboDisplayModelData.animates

出现、消失、显示、隐藏、更新时，各个图形动画配置。支持一次更新，多个动画的顺序执行（`order`）。[动画 DEMO](/zh/examples/scatter/changePosition/#itemAnimates)。

- **是否必须**: 否；
- **类型**: `IAnimates`，定义如下：
<embed src="../../common/DataAttrTips.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/LodLevels.zh.md"></embed>

其中，`IAnimate` 定义如下：
### animates

| 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) |
**类型**：`IAnimates`

`IStateAnimate` 定义如下，即在 `IAnimate` 基础上增加了一个指定状态的字段 `states`，表示该动画在这些状态变更的时候执行：
出现、消失、显示、隐藏、更新时，各个图形动画配置。支持一次更新，多个动画的顺序执行（`order`）。[动画 DEMO](/zh/examples/scatter/changePosition/#itemAnimates)

```typescript
interface IStateAnimate extends IAnimate {
states: string[];
}
```
<embed src="../../common/IAnimates.zh.md"></embed>

### ComboDisplayModelData.keyShape
### keyShape

Combo 主图形的样式配置。Combo 的主图形表达了 Combo 的主要形状。还用于计算边的连入位置。
**类型**：`ShapeStyle`，根据不同的主图形，图形样式配置项不同。例如

- **是否必须**: 否；
- **类型**: `ShapeStyle`，根据不同的主图形，图形样式配置项不同。例如 `'circle-combo'` 的主图形是 `'circle'` 参考 [Circle 图形样式](../shape/CircleStyleProps.zh.md)；`'rect-combo'` 的主图形是 `'rect'` 参考 [Rect 图形样式](../shape/RectStyleProps.zh.md)。
Combo 主图形的样式配置。Combo 的主图形表达了 Combo 的主要形状。还用于计算边的连入位置。 `'circle-combo'` 的主图形是 `'circle'` 参考 [CircleStyleProps](/apis/shape/circle-style-props)；`'rect-combo'` 的主图形是 `'rect'` 参考 [RectStyleProps](/apis/shape/rect-style-props)

### ComboDisplayModelData.haloShape
### haloShape

在内置的 Combo 和主题中，`haloShape` 指的是 Combo 在 `active`（一般在鼠标 hover 时该状态被触发） 和 `selected`（一般在选中状态下该状态被触发） 状态下，主图形 (`keyShape`) 周围展示的光晕效果的图形。在内置 Combo 的逻辑中，`haloShape` 的图形类型、颜色跟随主图形 (`keyShape`)。
**类型**：`ShapeStyle`，`haloShape`

- **是否必须**: 否；
- **类型**: `ShapeStyle`，`haloShape` 的图形类型跟随主图形(`keyShape`)。根据不同的主图形，图形样式配置项不同。例如 `'circle-combo'` 的主图形是 `'circle'` 参考 [Circle 图形样式](../shape/CircleStyleProps.zh.md)；`'rect-combo'` 的主图形是 `'rect'` 参考 [Rect 图形样式](../shape/RectStyleProps.zh.md)。
在内置的 Combo 和主题中，`haloShape` 指的是 Combo 在 `active`（一般在鼠标 hover 时该状态被触发） 和 `selected`（一般在选中状态下该状态被触发） 状态下，主图形 (`keyShape`) 周围展示的光晕效果的图形。在内置 Combo 的逻辑中，`haloShape` 的图形类型、颜色跟随主图形 (`keyShape`) 的图形类型跟随主图形(`keyShape`)根据不同的主图形，图形样式配置项不同。例如 `'circle-combo'` 的主图形是 `'circle'` 参考 [CircleStyleProps](/apis/shape/circle-style-props)；`'rect-combo'` 的主图形是 `'rect'` 参考 [RectStyleProps](/apis/shape/rect-style-props)

### ComboDisplayModelData.labelShape
<embed src="../../common/LabelShape.zh.md"></embed>

Combo 的文本图形，内置 Combo 或继承内置 Combo（未复写相关内容）的自定义 Combo 均支持。
### labelBackgroundShape

- **是否必须**: 否；
- **类型**:

```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 配置的是多个徽标。

- **是否必须**: 否；
- **类型**:
> 其中，参考矩形样式类型 [RectStyleProps](/apis/shape/rect-style-props)
```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'` |
Combo 的文本的背景图形，是一个矩形。若不设置则不显示。设置为 `{}` 将使用主题中默认的样式显示文本背景图形。

### ComboDisplayModelData.anchorShapes
<embed src="../../common/BadgeShapes.zh.md"></embed>

Combo 四周的边连入位置圆形图形（连接桩），anchorShapess 配置的是多个连接桩。
### anchorShapes

- **是否必须**: 否；
- **类型**:
**类型**：

```typescript
// 外层可配置对所有连接桩（圆形）的样式，优先级低于单独的连接桩配置
Expand All @@ -218,14 +79,13 @@ CircleStyleProps & {
};
```

其中，相关的图形样式参考 [`CircleStyleProps` 圆形图形样式](../shape/CircleStyleProps.zh.md)。
- [CircleStyleProps](/apis/shape/circle-style-props)

### ComboDisplayModelData.otherShapes
Combo 四周的边连入位置圆形图形（连接桩），anchorShapes 配置的是多个连接桩。

上面所有的 xxShape(s) 均为 G6 定义的规范 Combo 中可能存在的图形。自定义 Combo 中的其他图形应当定义和配置在 `otherShapes` 中。
### otherShapes

- **是否必须**: 否；
- **类型**:
**类型**：

```typescript
{
Expand All @@ -235,4 +95,6 @@ CircleStyleProps & {
}
```

其中，不同的图形样式参考[图形样式](../shape/BaseStyleProps.zh.md)目录下对应的图形类型文档。
> 其中，不同的图形样式参考[图形样式](/apis/shape/overview)目录下对应的图形类型文档。
上面所有的 xxShape(s) 均为 G6 定义的规范 Combo 中可能存在的图形。自定义 Combo 中的其他图形应当定义和配置在 `otherShapes` 中。
56 changes: 18 additions & 38 deletions packages/site/docs/apis/data/ComboModel.en.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ title: ComboModel
order: 8
---

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 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:

```typescript
interface ComboModel {
Expand All @@ -12,66 +12,46 @@ interface ComboModel {
}
```

## id
## id <Badge type="error">Required</Badge>

The unique ID of the combo. After the combo is created, the ID cannot be modified.

- **Required**: True;
- **Type**: `string|number`
**Type**: `string | number`

## data
## data <Badge type="error">Required</Badge>

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:
<embed src="../../common/DataAttrTips.en.md"></embed>

### ComboModelData.type
### 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`；
**Type**: `string`

### ComboModelData.visible
### visible

Whether the combo is displayed by default.

- **Required**: False;
- **Type**: `boolean`；
**Type**: `boolean`

### ComboModelData.color
### 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.
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 shape styles.

- **Required**: False;
- **Type**: `string`；
**Type**: `string`

### ComboModelData.label
### 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.
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 shape styles.

- **Required**: False;
- **Type**: `string`；
**Type**: `string`

### ComboModelData.icon
<embed src="../../common/DataIcon.en.md"></embed>

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
### parentId

The ID of the parent combo to which the combo belongs. `undefined` means it is a root.

- **Required**: False;
- **Type**: `string | number`；
**Type**: `string | number`
Loading

0 comments on commit 16af916

Please sign in to comment.