Skip to content

Commit

Permalink
docs: update api docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@Aarebecca
Aarebecca committed Dec 1, 2023
1 parent 16af916 commit 95091af
Show file tree
Hide file tree
Showing 66 changed files with 735 additions and 1,045 deletions.
19 changes: 13 additions & 6 deletions packages/site/.dumirc.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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,
},
Expand Down
90 changes: 17 additions & 73 deletions packages/site/docs/apis/data/ComboDisplayModel.en.md
View file
Original file line number Diff line number Diff line change
@@ -1,22 +1,11 @@
---
title: ComboDisplayModel
order: 12
order: 11
---

ComboDisplayModel（Combo Display/Rendering Data） is the result of mapping the ComboModel (inner model) through the mapper configuration specified on the graph instance ([specification.combo](../graph/Specification.en.md#combo)), and is only consumed for internal rendering. You won't consume it anywhere else. The data type inherits the ComboModel data type [ComboModel](./ComboModel.en.md) from the internal data flow and is extended as follows:
ComboDisplayModel (the rendering data of Combo) is the result of [data mapping](./DataIntro.en.md#mappers) of [ComboModel](./ComboModel.en.md), which can only be accessed by G6.

```typescript
interface ComboDisplayModel {
id: string | number;
data: ComboDisplayModelData; // extends ComboModelData
}
```

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

The unique ID of the Combo. The ID cannot be modified once the Combo is created.

**Type**: `string | number`
<embed src="../../common/DataID.en.md"></embed>

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

Expand All @@ -26,75 +15,30 @@ The data in ComboDisplayModelData is the result of mapping the ComboModel data t

<embed src="../../common/LodLevels.en.md"></embed>

### animates

Configuration of shape animations when the node appears, disappears, shows, hides, or updates. Supports sequential execution of multiple animations (order). [Animation Demo](/en/examples/scatter/changePosition/#itemAnimates).

**Type**: `IAnimates`

<embed src="../../common/IAnimates.en.md"></embed>
<embed src="../../common/DataAnimates.en.md"></embed>

### keyShape

The style configuration of the key shape of the Combo. The key shape of the Combo represents its primary form and is also used to calculate the incoming position of edges.

**Type**: `ShapeStyle`, and the configuration options for different key shapes are different. For example, the key shape of `'circle-combo'` is `'circle'` (refer to [Circle Shape Style](/en/apis/shape/circle-style-props)), and the key shape of `'rect-combo'` is `'rect'` (refer to [Rect Shape Style](/en/apis/shape/rect-style-props)).

### haloShape

In the built-in Combo and themes, `haloShape` refers to the halo effect displayed around the key shape (`keyShape`) of the Combo in the `active` state (usually triggered when the mouse hovers) and `selected` state (usually triggered when selected). In the logic of the built-in Combo, the type and color of the `haloShape` follow the key shape (`keyShape`).

**Type**: `ShapeStyle`, where the type of haloShape follows the key shape (keyShape). The configuration options for different key shapes are different. For example, the key shape of `'circle-combo'` is `'circle'` (refer to [Circle Shape Style](/en/apis/shape/circle-style-props)), and the key shape of `'rect-combo'` is `'rect'` (refer to [Rect Shape Style](/en/apis/shape/rect-style-props)).

<embed src="../../common/LabelShape.en.md"></embed>

### labelBackgroundShape

The background shape of the text in the Combo, which is a rectangle. If not set, it will not be displayed. Setting it as `{}` will use the default style in the theme to display the text background shape.

**Type**:

```typescript
ShapeStyle & {
padding?: number | number[]; // The padding distance between the text and the background rectangle in all directions
};
```

The related shape style can be referred to as RectStyleProps [RectStyleProps](/en/apis/shape/rect-style-props).

<embed src="../../common/BadgeShapes.en.md"></embed>
**Type**: `ShapeStyle`

### anchorShapes
The style configuration of the key shape of the Combo

The circular shapes (anchor shapes) at the four sides of the Combo represent the entry points for connections. The anchorShapes configuration specifies multiple anchor shapes.
> The key shape of `'circle-combo'` is ['circle'](/apis/shape/circle-style-props); the key shape of `'rect-combo'` is ['rect'](/apis/shape/rect-style-props).
**Type**:
<embed src="../../common/DataHaloShape.en.md"></embed>

```typescript
// The outer layer configures the style of all anchor shapes (circles), with lower priority than the individual anchor shape configurations.
CircleStyleProps & {
// Individual anchor shape configurations, with higher priority than the outer CircleStyleProps.
[key: number]: CircleStyleProps & {
// The position of the anchor shape, can be configured as a string or a number array representing the percentage position relative to the bounding box of the key shape (keyShape). For example, [0.5, 1] means it is located at the right center of the key shape.
position?: 'top' | 'left' | 'bottom' | 'right' | [number, number];
};
};
```
<embed src="../../common/DataLabelShape.en.md"></embed>

The style of the anchor shapes can be referred to as [CircleStyleProps](/en/apis/shape/circle-style-props).
<embed src="../../common/DataLabelBackgroundShape.en.md"></embed>

### otherShapes
<embed src="../../common/DataBadgeShapes.en.md"></embed>

The xxShape(s) mentioned above are the predefined shapes in the G6 Combo specification. Other custom shapes in the Combo should be defined and configured in `otherShapes`.
<embed src="../../common/DataAnchorShapes.en.md"></embed>

**Type**:
<embed src="../../common/DataOtherShapes.en.md"></embed>

```typescript
{
// The key is the shape id, in the format of xxShape
// The value is the shape style configuration (which varies depending on the shape, see the relevant documentation for each shape), as well as the animation of the shape
[shapeId: string]: ShapeStyleProps;
}
```
:::info
The following attributes are inherited from [ComboModel](./ComboModel.en.md)
:::

The style configurations for different shapes can be referred to in the corresponding documentation under the [Shape Style](/en/apis/shape/overview) directory.
<embed src="../../common/ComboUserModel.en.md"></embed>
92 changes: 18 additions & 74 deletions packages/site/docs/apis/data/ComboDisplayModel.zh.md
View file
Original file line number Diff line number Diff line change
@@ -1,100 +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
}
```

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

**类型**：`string | number`

Combo 的唯一 ID，Combo 创建后，ID 不可被修改。
<embed src="../../common/DataID.zh.md"></embed>

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

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

<embed src="../../common/DataAttrTips.zh.md"></embed>

<embed src="../../common/LodLevels.zh.md"></embed>

### animates

**类型**：`IAnimates`

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

<embed src="../../common/IAnimates.zh.md"></embed>
<embed src="../../common/DataAnimates.zh.md"></embed>

### keyShape

**类型**：`ShapeStyle`，根据不同的主图形，图形样式配置项不同。例如

Combo 主图形的样式配置。Combo 的主图形表达了 Combo 的主要形状。还用于计算边的连入位置。 `'circle-combo'` 的主图形是 `'circle'` 参考 [CircleStyleProps](/apis/shape/circle-style-props)；`'rect-combo'` 的主图形是 `'rect'` 参考 [RectStyleProps](/apis/shape/rect-style-props)

### haloShape

**类型**：`ShapeStyle`，`haloShape`

在内置的 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)

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

### labelBackgroundShape

**类型**：

```typescript
ShapeStyle & {
padding?: number | number[]; // 文本距离背景矩形四周的留白距离
};
```

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

<embed src="../../common/BadgeShapes.zh.md"></embed>
**类型**：`ShapeStyle`

### anchorShapes
主图形的样式配置

**类型**：
> `'circle-combo'` 的主图形是 ['circle'](/apis/shape/circle-style-props)；`'rect-combo'` 的主图形是 ['rect'](/apis/shape/rect-style-props)
```typescript
// 外层可配置对所有连接桩（圆形）的样式，优先级低于单独的连接桩配置
CircleStyleProps & {
// 单独的连接桩图形配置，优先级高于外层的 CircleStyleProps
[key: number]: CircleStyleProps & {
// 该连接桩的位置，可配置字符串或数字数组表示相对于主图形 (keyShape) 包围盒的百分比位置，例如 [0.5, 1] 表示位于主图形的右侧中间
position?: 'top' | 'left' | 'bottom' | 'right' | [number, number];
};
};
```
<embed src="../../common/DataHaloShape.zh.md"></embed>

- [CircleStyleProps](/apis/shape/circle-style-props)
<embed src="../../common/DataLabelShape.zh.md"></embed>

Combo 四周的边连入位置圆形图形（连接桩），anchorShapes 配置的是多个连接桩。
<embed src="../../common/DataLabelBackgroundShape.zh.md"></embed>

### otherShapes
<embed src="../../common/DataBadgeShapes.zh.md"></embed>

**类型**：
<embed src="../../common/DataAnchorShapes.zh.md"></embed>

```typescript
{
// key 为图形 id，规范格式为 xxShape
// value 为图形样式配置（不同图形配置不同，见图形相关文档），以及图形的动画
[shapeId: string]: ShapeStyleProps;
}
```
<embed src="../../common/DataOtherShapes.zh.md"></embed>

> 其中，不同的图形样式参考[图形样式](/apis/shape/overview)目录下对应的图形类型文档。
:::info{title=提示}
下列属性继承自 [ComboModel](./ComboModel.zh.md)
:::

上面所有的 xxShape(s) 均为 G6 定义的规范 Combo 中可能存在的图形。自定义 Combo 中的其他图形应当定义和配置在 `otherShapes` 中。
<embed src="../../common/ComboUserModel.zh.md"></embed>
51 changes: 4 additions & 47 deletions packages/site/docs/apis/data/ComboModel.en.md
View file
Original file line number Diff line number Diff line change
@@ -1,57 +1,14 @@
---
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). This is the data you consume anywhere later.

```typescript
interface ComboModel {
id: string | number;
data: ComboModelData; // = ComboModelData
}
```

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

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

**Type**: `string | number`
<embed src="../../common/DataID.en.md"></embed>

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

<embed src="../../common/DataAttrTips.en.md"></embed>

### 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'`.

**Type**: `string`

### visible

Whether the combo is displayed by default.

**Type**: `boolean`

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

**Type**: `string`

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

**Type**: `string`

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

### parentId

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

**Type**: `string | number`
<embed src="../../common/ComboUserModel.en.md"></embed>
51 changes: 4 additions & 47 deletions packages/site/docs/apis/data/ComboModel.zh.md
View file
Original file line number Diff line number Diff line change
@@ -1,57 +1,14 @@
---
title: ComboModel 内部数据
order: 8
order: 10
---

ComboModel 为内部流转的 combo 数据，由 ComboUserModel 经过皮质在图实例上的 transforms 计算而得。后续您在任意地方消费的都是这一份数据。每一项 Combo 的类型继承自 [ComboUserModel](./ComboUserModel.zh.md)，扩展后定义如下：
ComboModel 为内部流转的 combo 数据，由 [ComboUserModel](./ComboUserModel.zh.md) 经过[数据转换](./DataIntro.zh.md#transforms-数据转换)后得到。后续您在任意地方消费的都是这一份数据。

```typescript
interface ComboModel {
id: string | number;
data: ComboModelData; // = ComboModelData
}
```

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

节点的唯一 ID，节点创建后，ID 不可被修改。

**类型**：`string | number`
<embed src="../../common/DataID.zh.md"></embed>

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

InnerModelData 中的数据已经是 UserModelData 通过 Graph 实例的一系列 transform 函数生成的结果，业务数据可能已经被转换、过滤、合并。

<embed src="../../common/DataAttrTips.zh.md"></embed>

### type

Combo 的渲染类型，可以是已经注册到图类上的 Combo 类型，内置并默认注册的有 `'circle-combo'`，`'rect-combo'`。默认为 `'circle-combo'`。

**类型**： `string`

### visible

Combo 是否默认展示出来。

**类型**： `boolean`

### color

该 Combo 的主图形（keyShape）的主题色，值为十六进制字符串。为方便简单配置而提供，更多的样式配置应当在 Graph 实例的 Combo mapper 中配置 keyShape 以及各种图形的图形样式。

**类型**： `string`

### label

Combo `labelShape` 的文本内容。为方便简单配置而提供，更多的样式配置应当在 Graph 实例的 Combo mapper 中配置 `labelShape` 的 `text` 值或其他图形样式。

**类型**： `string`

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

### parentId

在有 Combo 的图上表示该 Combo 所属的父亲 Combo 的 id。`undefined` 表示当前 Combo 是一个根。

**类型**： `string | number`
<embed src="../../common/ComboUserModel.zh.md"></embed>
Loading

0 comments on commit 95091af

Please sign in to comment.