Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: optimize docs #3703

Merged
merged 8 commits into from
Jun 26, 2023
Merged

docs: optimize docs #3703

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
ab1a44e
docs: optimize connector docs
NewByVector Jun 23, 2023
7d379ca
docs: optimize docs for node-anchor
NewByVector Jun 23, 2023
b728b82
docs: add demo for edge anchor
NewByVector Jun 23, 2023
7bf036b
docs: add demo for connection point
NewByVector Jun 24, 2023
5c37bc4
docs: add demo for attrs
NewByVector Jun 24, 2023
fb084c2
docs: add demos for filter
NewByVector Jun 26, 2023
96fd489
docs: add demos for port layout
NewByVector Jun 26, 2023
7544a4a
docs: add demos for port label layout
NewByVector Jun 26, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions sites/x6-sites/.dumirc.ts
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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