Skip to content

Commit

Permalink
docs: update custom-element doc
Browse files Browse the repository at this point in the history
  • Loading branch information
@Aarebecca
Aarebecca committed Nov 29, 2024
1 parent 341066e commit 1c4c2d1
Show file tree
Hide file tree
Showing 2 changed files with 24 additions and 24 deletions.
30 changes: 14 additions & 16 deletions packages/site/docs/manual/custom-extension/element.en.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ Before starting to customize an element, you need to understand some important p

> Record<string, DisplayObject>
The mapping table of all graphics under the current element
The mapping table of all shapes under the current element

#### animateMap

Expand All @@ -29,18 +29,18 @@ The mapping table of all animations under the current element

#### upsert(key, Ctor, style, container)

Create or update graphics, and automatically destroy the graphics when the element is destroyed
Create or update shapes, and automatically destroy the shapes when the element is destroyed

```typescript
upsert(key: string, Ctor: { new (...args: any[]): DisplayObject }, style: Record<string, any>, container: DisplayObject);
```

| Parameter | Type | Description |
| --------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| key | string | The key of the graphic, that is, the corresponding key in `shapeMap`. Built-in keys include `'key'`, `'label'`, `'halo'`, `'icon'`, `'port'`, `'badge'` |
| Ctor | { new (...args: any[]): DisplayObject } | The constructor for the graphic class |
| style | Record<string, any> | The style of the graphic |
| container | DisplayObject | The container where the graphic is mounted |
| Parameter | Type | Description |
| --------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| key | string | The key of the shape, that is, the corresponding key in `shapeMap`. Built-in keys include `'key'`, `'label'`, `'halo'`, `'icon'`, `'port'`, `'badge'` <br/> The key should not use special symbols. Based on this value, it will be transformed into camelCase to call the `getXxxStyle` and `drawXxxShape` methods (see [Element Convention](#element-convention)) |
| Ctor | { new (...args: any[]): DisplayObject } | The constructor for the shape class |
| style | Record<string, any> | The style of the shape |
| container | DisplayObject | The container where the shape is mounted |

#### render(style, container)

Expand All @@ -65,17 +65,15 @@ The element provides the following hook functions, which can be overridden as ne

### Element Convention

- **Use Conventional Attributes**
- Obtain the size of the element through `this.getSize()`.

The currently agreed-upon element attributes include:
- **Adopt the paired way of `getXxxStyle` and `drawXxxShape` for shape drawing**

1. `size`: The size of the element
`getXxxStyle` is used to obtain the shape style, and `drawXxxShape` is used to draw the shape. The shape created through this way supports automatic execution of animations.

- **Use the `getXxxStyle` and `drawXxxShape` pairing method for graphic drawing**
> Among them, `Xxx` is the camelCase form of the key passed in when calling the [upsert](#methods) method.
`getXxxStyle` is used to obtain the graphic style, and `drawXxxShape` is used for drawing the graphic. Graphics created in this way support automatic animation execution.

- **The Graph context can be accessed via `attributes.context`**
- **The Graph context can be accessed through `this.context`**

## Custom Node

Expand Down Expand Up @@ -190,7 +188,7 @@ class CustomCircle extends CustomElement {
}
```

To implement graphical animation, you need to override the `animate` method to perform the animation operations on the `CustomCircle` onto the `Circle` graphic:
To implement graphical animation, you need to override the `animate` method to perform the animation operations on the `CustomCircle` onto the `Circle` shape:

```typescript
import type {} from '@antv/g';
Expand Down
18 changes: 10 additions & 8 deletions packages/site/docs/manual/custom-extension/element.zh.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -35,12 +35,12 @@ order: 0
upsert(key: string, Ctor: { new (...args: any[]): DisplayObject }, style: Record<string, any>, container: DisplayObject);
```

| 参数 | 类型 | 描述 |
| --------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| key | string | 图形的 key，即 `shapeMap` 中对应的 key。内置的 key 包括 `'key'` `'label'` `'halo'` `'icon'` `'port'` `'badge'` |
| Ctor | { new (...args: any[]): DisplayObject } | 图形类 |
| style | Record<string, any> | 图形样式 |
| container | DisplayObject | 挂载图形的容器 |
| 参数 | 类型 | 描述 |
| --------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| key | string | 图形的 key，即 `shapeMap` 中对应的 key。内置的 key 包括 `'key'` `'label'` `'halo'` `'icon'` `'port'` `'badge'`<br/> key 不应使用特殊符号，会基于该值转化为驼峰形式调用 `getXxxStyle` 和 `drawXxxShape` 方法（见[元素约定](#元素约定)） |
| Ctor | { new (...args: any[]): DisplayObject } | 图形类 |
| style | Record<string, any> | 图形样式 |
| container | DisplayObject | 挂载图形的容器 |

#### render(style, container)

Expand Down Expand Up @@ -69,13 +69,15 @@ render(style: Record<string, any>, container: Group): void;

目前约定的元素属性包括：

1. `size` 元素的尺寸
- 通过 `this.getSize()` 获取元素的尺寸

- **采用 `getXxxStyle` 和 `drawXxxShape` 配对的方式进行图形绘制**

`getXxxStyle` 用于获取图形样式，`drawXxxShape` 用于绘制图形。通过该方式创建的图形支持自动执行动画。

- **可通过 `attributes.context` 访问 Graph 上下文**
> 其中 `Xxx` 是调用 [upsert](#方法) 方法时传入的 key 的驼峰形式。
- **可通过 `this.context` 访问 Graph 上下文**

## 自定义节点

Expand Down

0 comments on commit 1c4c2d1

Please sign in to comment.