Skip to content

Commit

Permalink
docs: optimize docs (#3703)
Browse files Browse the repository at this point in the history 
* docs: optimize connector docs

* docs: optimize docs for node-anchor

* docs: add demo for edge anchor

* docs: add demo for connection point

* docs: add demo for attrs

* docs: add demos for filter

* docs: add demos for port layout

* docs: add demos for port label layout
  • Loading branch information
@NewByVector
NewByVector authored Jun 26, 2023
1 parent 6e8422e commit ef5388e
Show file tree
Hide file tree
Showing 100 changed files with 7,339 additions and 437 deletions.
4 changes: 2 additions & 2 deletions sites/x6-sites/.dumirc.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -233,8 +233,8 @@ export default defineConfig({
{
slug: 'api/registry',
title: {
zh: '注册',
en: 'Registry',
zh: '扩展',
en: 'Extension',
},
order: 4,
},
Expand Down
2 changes: 1 addition & 1 deletion sites/x6-sites/docs/api/mvc/model.zh.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
title: Model
title: 模型
order: 1
redirect_from:
- /zh/docs
Expand Down
44 changes: 3 additions & 41 deletions sites/x6-sites/docs/api/mvc/view.zh.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
title: View
title: 视图
order: 7
redirect_from:
- /zh/docs
Expand Down Expand Up @@ -111,45 +111,7 @@ const graph = new Graph({
| container | Element | ✓ | 文本标签容器。 |
| selectors | Markup.Selectors | ✓ | 文本标签 Markup 渲染后的选择器键值对。 |

例如，我们可以在标签上渲染任何想要的元素。

```tsx
const graph = new Graph({
container: this.container,
onEdgeLabelRendered(args) {
const { label, container, selectors } = args
const data = label.data

if (data) {
// 在 Label 容器中渲染一个 foreignObject 来承载 HTML 元素和 React 组件
const content = this.appendForeignObject(container)

if (data === 1) {
// 渲染一个 Div 元素
const txt = document.createTextNode('text node')
content.style.border = '1px solid #f0f0f0'
content.style.borderRadius = '4px'
content.appendChild(txt)
} else if (data === 2) {
// 渲染一个 HTML 按钮
const btn = document.createElement('button')
btn.appendChild(document.createTextNode('HTML Button'))
btn.style.height = '30px'
btn.style.lineHeight = '1'
btn.addEventListener('click', () => {
alert('clicked')
})
content.appendChild(btn)
} else if (data === 3) {
// 渲染一个 Atnd 的按钮
ReactDOM.render(<Button size="small">Antd Button</Button>, content)
}
}
},
})
```

我们也可以在定义 Label 的 Markup 时添加 `<foreignObject>` 元素来支持 HTML 和 React 的渲染能力。
我们可以在定义 Label 的 Markup 时添加 `<foreignObject>` 元素来支持 HTML 和 React 的渲染能力。

```tsx
const graph = new Graph({
Expand All @@ -171,7 +133,7 @@ const graph = new Graph({
### createCellView

```ts
;(this: Graph, cell: Cell) => CellView | null | undefined
(this: Graph, cell: Cell) => CellView | null | undefined
```

自定义元素的视图，可以返回一个 `CellView`，会替换默认的视图，如果返回 `null`，则不会渲染，如果返回 `undefined`，会按照默认方式渲染。
Expand Down
66 changes: 46 additions & 20 deletions sites/x6-sites/docs/api/registry/attr.zh.md
View file
Original file line number Diff line number Diff line change
@@ -1,25 +1,51 @@
---
title: Attr
order: 11
title: 属性
order: 13
redirect_from:
- /zh/docs
- /zh/docs/api
- /zh/docs/api/registry
---

我们在 `Attr` 命名空间中提供了注册和管理特殊属性的方法，以及所有特殊属性的定义。
X6 提供了非常多的内置属性以及自定义属性方式。

## presets

我们在 `Registry.Attr.presets` 命名空间下挂载了所有特殊属性的定义。
## 内置属性

### ref

指向一个元素的 CSS 选择器，指代的元素是那些以 `ref` 开头的属性的参照元素。
指向一个元素的选择器，指向的元素作为参考元素。

```typescript
graph.addNode({
...,
markup: [
{
tagName: 'rect',
selector: 'body,'
},
{
tagName: 'rect',
selector: 'custom,'
}
],
attrs: {
body: {
width: 100,
height: 50,
},
// custom 元素的长度和宽度是 body 的一半
custom: {
ref: 'body',
refWidth: 0.5,
refHeight: 0.5,
}
}
})
```

### refX

设置元素 `x` 坐标，目标 `x` 坐标相对于 [`ref`](#ref) 指代的参照元素的左上角 `x` 坐标（参照 `x` 坐标）
设置元素 `x` 坐标，目标 `x` 坐标相对于 [`ref`](#ref) 指代的元素的左上角 `x` 坐标。

- 当其值在 `[0, 1]` 之间或为百分比（如 `50%`）时，表示目标 `x` 坐标是参照 `x` 坐标相对于参照元素宽度百分比的相对偏移量。例如 `refX: 0.5` 表示，目标 `x` 坐标在参照 `x` 坐标基础上，向右偏移参照宽度的 `50%`。
- 当其值 `<0` 或 `>1` 时，表示目标 `x` 坐标是参照 `x` 坐标的绝对偏移量。例如 `refX: 20` 表示，目标 `x` 坐标在参照 `x` 坐标基础上，向右偏移 `20px`。
Expand Down Expand Up @@ -79,7 +105,7 @@ redirect_from:
- 当其值 `<0` 或 `>1` 时，表示元素的宽度在参照宽度的基础上减少或增加多少。例如 `refWidth: 20` 表示元素比相对元素宽 `20px`。

:::warning{title=注意}
需要注意的是，该属性只适用于那些支持宽度 `width` 和高度 `height` 的元素，如 `<rect>` 元素。
该属性只适用于那些支持宽度 `width` 和高度 `height` 的元素，如 `<rect>` 元素。
:::

### refWidth2
Expand All @@ -103,7 +129,7 @@ redirect_from:
- 当其值 `<0` 或 `>1` 时，表示元素的高度在参照高度的基础上减少或增加多少。例如 `refHeight: 20` 表示元素比相对元素高 `20px`。

:::warning{title=注意}
需要注意的是，该属性只适用于那些支持宽度 `width` 和高度 `height` 的元素，如 `<rect>` 元素。
该属性只适用于那些支持宽度 `width` 和高度 `height` 的元素，如 `<rect>` 元素。
:::

### refHeight2
Expand All @@ -127,7 +153,7 @@ redirect_from:
- 当其值 `<0` 或 `>1` 时，表示元素的 `cx` 是在参照宽度的基础上减少或增加多少。例如 `refCx: 20` 表示元素中心 `x` 坐标位于参照宽度加 `20px` 处。

:::warning{title=注意}
需要注意的是，该属性只适用于那些支持 `cx` 和 `cy` 属性的元素，如 `<ellipse>` 元素。
该属性只适用于那些支持 `cx` 和 `cy` 属性的元素，如 `<ellipse>` 元素。
:::

### refCy
Expand All @@ -138,7 +164,7 @@ redirect_from:
- 当其值 `<0` 或 `>1` 时，表示元素的 `cy` 是在参照宽度的基础上减少或增加多少。例如 `refCy: 20` 表示元素中心 `y` 坐标位于参照高度加 `20px` 处。

:::warning{title=注意}
需要注意的是，该属性只适用于那些支持 `cx` 和 `cy` 属性的元素，如 `<ellipse>` 元素。
该属性只适用于那些支持 `cx` 和 `cy` 属性的元素，如 `<ellipse>` 元素。
:::

### refRx
Expand All @@ -149,7 +175,7 @@ redirect_from:
- 当其值 `<0` 或 `>1` 时，表示元素的 `rx` 是在参照宽度的基础上减少或增加多少。例如 `refRx: 20` 表示元素的 `rx` 是参照宽度加 `20px`。

:::warning{title=注意}
需要注意的是，该属性只适用于那些支持 `rx` 和 `ry` 属性的元素，如 `<rect>` 元素。
该属性只适用于那些支持 `rx` 和 `ry` 属性的元素，如 `<rect>` 元素。
:::

### refRy
Expand All @@ -160,7 +186,7 @@ redirect_from:
- 当其值 `<0` 或 `>1` 时，表示元素的 `ry` 是在参照宽度的基础上减少或增加多少。例如 `refRy: 20` 表示元素的 `ry` 是参照高度加 `20px`。

:::warning{title=注意}
需要注意的是，该属性只适用于那些支持 `rx` 和 `ry` 属性的元素，如 `<rect>` 元素。
该属性只适用于那些支持 `rx` 和 `ry` 属性的元素，如 `<rect>` 元素。
:::

### refRCircumscribed
Expand All @@ -171,7 +197,7 @@ redirect_from:
- 当其值 `<0` 或 `>1` 时，表示 `r` 是在参照长度的基础上减少或增加多少。例如 `refRCircumscribed: 20` 表示 `r` 是参照长度加 `20px`。

:::warning{title=注意}
需要注意的是，该属性只适用于那些支持 `r` 属性的元素，如 `<rect>` 元素。
该属性只适用于那些支持 `r` 属性的元素，如 `<rect>` 元素。
:::

### refRInscribed
Expand All @@ -184,7 +210,7 @@ _简称_：**`refR`**
- 当其值 `<0` 或 `>1` 时，表示 `r` 是在参照长度的基础上减少或增加多少。例如 `refRInscribed: 20` 表示 `r` 是参照长度加 `20px`。

:::warning{title=注意}
需要注意的是，该属性只适用于那些支持 `r` 属性的元素，如 `<rect>` 元素。
该属性只适用于那些支持 `r` 属性的元素，如 `<rect>` 元素。
:::

### refDKeepOffset
Expand Down Expand Up @@ -356,7 +382,7 @@ console.log(view.findOne('polygon').getAttribute('points'))
- `'middle'` 目标元素的中心与 `y` 对齐。
- `'bottom'` 目标元素与的底部与 `y` 对齐。

<!-- <iframe src="/demos/api/registry/attr/x-align"></iframe> -->
<code id="attrs-x-align" src="@/src/api/attrs/x-align/index.tsx"></code>

### fill

Expand Down Expand Up @@ -434,7 +460,7 @@ textWrap: {
}
```

<!-- <iframe src="/demos/api/registry/attr/text-wrap"></iframe> -->
<code id="attrs-text-wrap" src="@/src/api/attrs/text-wrap/index.tsx"></code>

### textPath

Expand All @@ -456,7 +482,7 @@ textWrap: {
- `'middle'` 目标元素的中心与 `y` 对齐。
- `'bottom'` 目标元素与的底部与 `y` 对齐。

<!-- <iframe src="/demos/api/registry/attr/text-anchor"></iframe> -->
<code id="attrs-text-anchor" src="@/src/api/attrs/text-anchor/index.tsx"></code>

### connection

Expand Down Expand Up @@ -570,7 +596,7 @@ edge.attr('connection/sourceMarker', {
适用于所有 `<path>` 元素，在路径的终点添加一个 SVG 元素（如终点箭头），并自动旋转该元素，使其与根据路径方向保持一致。了解更多详情请参考[这篇教程](/api/model/marker)。

:::warning{title=注意}
需要注意的是，该元素初始时就被旋转了 `180` 度，在此基础上再自动调整旋转角度，并与路径的方向保持一致。例如，对于一个水平的直线，我们为其起点指定了一个向左的箭头，我们也可以为其重点指定相同的箭头，这个箭头会自动指向右侧（自动旋转了 `180` 度）。
该元素初始时就被旋转了 `180` 度，在此基础上再自动调整旋转角度，并与路径的方向保持一致。例如，对于一个水平的直线，我们为其起点指定了一个向左的箭头，我们也可以为其重点指定相同的箭头，这个箭头会自动指向右侧（自动旋转了 `180` 度）。
:::

### vertexMarker
Expand Down
77 changes: 37 additions & 40 deletions sites/x6-sites/docs/api/registry/connection-point.zh.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
title: ConnectionPoint
title: 连接点
order: 10
redirect_from:
- /zh/docs
Expand All @@ -9,17 +9,17 @@ redirect_from:

连接点 ConnectionPoint 与锚点 [Anchor](/zh/docs/api/registry/node-anchor) 共同确定了边的起点或终点。

- 起点：从第一个路径点或目标节点的中心（没有路径点时）画一条参考线到源节点的锚点，然后根据 [connectionPoint](/zh/docs/api/model/edge#source-和-target) 指定的交点计算方法，计算参考线与图形的交点，该交点就是边的起点。
- 终点：从最后一个路径点或源节点的中心（没有路径点时）画一条参考线到目标节点的锚点，然后根据 [connectionPoint](/zh/docs/api/model/edge#source-和-target) 指定的交点计算方法，计算参考线与图形的交点，该交点就是边的终点。
- 起点：从第一个路径点或目标节点的中心（没有路径点时）画一条参考线到源节点的锚点，然后根据 `connectionPoint` 指定的交点计算方法，计算参考线与图形的交点，该交点就是边的起点。
- 终点：从最后一个路径点或源节点的中心（没有路径点时）画一条参考线到目标节点的锚点，然后根据 `connectionPoint` 指定的交点计算方法，计算参考线与图形的交点，该交点就是边的终点。

我们在 `Registry.ConnectionPoint.presets` 命名空间中提供了以下几种连接点计算方法。
X6 内置了以下几种连接点计算方法。

- [boundary](#boundary) 默认值，与链接图形的边框的交点。
- [bbox](#bbox) 与链接元素的包围盒的交点。
- [rect](#rect) 与链接元素的旋转后的矩形区域的交点。
- [anchor](#anchor) 使用锚点作为连接点。

<!-- <iframe src="/demos/api/registry/connection-point/playground"></iframe> -->
<code id="connection-point" src="@/src/api/connection-point/playground/index.tsx"></code>

可以在创建边时指定连接点：

Expand Down Expand Up @@ -80,51 +80,51 @@ new Graph({
})
```

## presets
## 内置连接点

### boundary

自动识别链接图形的边框，并计算参照点与锚点（Anchor）形成的直线与边框的交点。如 `<ellipse>` 元素将被识别为椭圆，并求椭圆与直线的交点，求得的交点为边的连接点。不能识别的元素（`text`、`<path>` 等）使用图形的包围盒代替，这与使用 `'bbox'` 求得的连接点一样。

支持的参数如下表：

| 参数名 | 参数类型 | 是否必选 | 默认值 | 参数说明 |
| --- | --- | :-: | --- | --- |
| offset | number \| Point.PointLike | 否 | `0` | 连接点的偏移量。 |
| stroked | boolean | 否 | `true` | 是否考虑图形的边框宽度。 |
| insideout | boolean | 否 | `true` | 当参考线位于图形内部且没有交点时，是否延长参考线求交点，默认为 `true`。 |
| extrapolate | boolean | 否 | `false` | 当参考线位于图形外部且没有交点时，是否延长参考线求交点，延长后也可能没有交点，默认为 `false`。此参数的优先级高于 `sticky`。 |
| sticky | boolean | 否 | `false` | 当参考线位于图形外部且没有交点时，是否使用边框上离参考线最最近的点作为交点，默认为 `false`。 |
| precision | number | 否 | `2` | 交点计算的精度。 |
| selector | string | 否 | `undefined` | 选择器，用于标识一个元素，使用该元素的边框来计算交点。默认使用节点中第一个不在 `<g>` 元素内的子元素。 |
| 参数名 | 参数类型 | 是否必选 | 默认值 | 参数说明 |
|-------------|---------------------------|:-------:|-------------|--------------------------------------------------------------------------------------------------------------------|
| offset | number \| Point.PointLike | 否 | `0` | 连接点的偏移量。 |
| stroked | boolean | 否 | `true` | 是否考虑图形的边框宽度。 |
| insideout | boolean | 否 | `true` | 当参考线位于图形内部且没有交点时，是否延长参考线求交点，默认为 `true`。 |
| extrapolate | boolean | 否 | `false` | 当参考线位于图形外部且没有交点时，是否延长参考线求交点，延长后也可能没有交点，默认为 `false`。此参数的优先级高于 `sticky`。 |
| sticky | boolean | 否 | `false` | 当参考线位于图形外部且没有交点时，是否使用边框上离参考线最最近的点作为交点，默认为 `false`。 |
| precision | number | 否 | `2` | 交点计算的精度。 |
| selector | string | 否 | `undefined` | 选择器，用于标识一个元素，使用该元素的边框来计算交点。默认使用节点中第一个不在 `<g>` 元素内的子元素。 |

### anchor

将锚点作为连接点，支持如下参数：

| 参数名 | 参数类型 | 是否必选 | 默认值 | 参数说明 |
| ------ | ------------------------- | :------: | ------ | ---------------- |
| 参数名 | 参数类型 | 是否必选 | 默认值 | 参数说明 |
|--------|---------------------------|:-------:|--------|-------------|
| offset | number \| Point.PointLike | 否 | `0` | 连接点的偏移量。 |

### bbox

图形的包围盒与参考线的交点，支持如下参数：

| 参数名 | 参数类型 | 是否必选 | 默认值 | 参数说明 |
| --- | --- | :-: | --- | --- |
| offset | number \| Point.PointLike | 否 | `0` | 连接点的偏移量。 |
| stroked | boolean | 否 | `false` | 是否考虑图形的边框宽度。 |
| 参数名 | 参数类型 | 是否必选 | 默认值 | 参数说明 |
|---------|---------------------------|:-------:|---------|---------------------|
| offset | number \| Point.PointLike | 否 | `0` | 连接点的偏移量。 |
| stroked | boolean | 否 | `false` | 是否考虑图形的边框宽度。 |

### rect

图形旋转后的矩形区域与参考线的交点，支持如下参数：

| 参数名 | 参数类型 | 是否必选 | 默认值 | 参数说明 |
| --- | --- | :-: | --- | --- |
| offset | number \| Point.PointLike | 否 | `0` | 连接点的偏移量。 |
| stroked | boolean | 否 | `false` | 是否考虑图形的边框宽度。 |
| 参数名 | 参数类型 | 是否必选 | 默认值 | 参数说明 |
|---------|---------------------------|:-------:|---------|---------------------|
| offset | number \| Point.PointLike | 否 | `0` | 连接点的偏移量。 |
| stroked | boolean | 否 | `false` | 是否考虑图形的边框宽度。 |

## registry
## 自定义连接点

连接点定义是一个具有如下签名的函数，返回连接点。

Expand All @@ -137,28 +137,25 @@ export type Definition<T> = (
) => Point
```
| 参数名 | 参数类型 | 参数说明 |
| -------- | ---------- | -------------------- |
| 参数名 | 参数类型 | 参数说明 |
|----------|------------|-------------------|
| line | Line | 参考线。 |
| nodeView | NodeView | 连接的节点视图。 |
| magnet | SVGElement | 连接的节点上的元素。 |
| args | T | 参数。 |
并在 `Registry.ConnectionPoint.registry` 对象上提供了 [`register`](#register) 和 [`unregister`](#unregister) 两个方法来注册和取消注册连接点定义，同时也将这两个方法分别挂载为 Graph 上的两个静态方法 `Graph.registerConnectionPoint` 和 `Graph.unregisterConnectionPoint`。
### register
完成连接点定义后，我们先注册连接点：
```ts
register(entities: { [name: string]: Definition }, force?: boolean): void
register(name: string, entity: Definition, force?: boolean): Definition
Graph.registerConnectionPoint('custom-connection-point', ...)
```
注册连连接点定义。
### unregister
注册以后我们就可以通过连接点名称来使用：
```ts
unregister(name: string): Definition | null
```
取消注册连接点定义。
new Graph({
connecting: {
connectionPoint: 'custom-connection-point'
},
})
```
Loading

0 comments on commit ef5388e

Please sign in to comment.