@fulate/ui 1.0.19 → 3.0.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +130 -177
- package/dist/circle.d.ts +2 -1
- package/dist/connection/commands.d.ts +3 -3
- package/dist/connection/types.d.ts +5 -1
- package/dist/connection-port-decoration.d.ts +18 -2
- package/dist/editor/capability.d.ts +37 -6
- package/dist/editor/frame-flush.d.ts +3 -4
- package/dist/editor/properties.d.ts +31 -0
- package/dist/editor/shape-capability.d.ts +13 -0
- package/dist/editor/shape.d.ts +16 -19
- package/dist/editor/transform.d.ts +1 -3
- package/dist/editor-vector-path.d.ts +70 -0
- package/dist/floating.d.ts +12 -2
- package/dist/group.d.ts +17 -8
- package/dist/image.d.ts +16 -19
- package/dist/index.d.ts +15 -6
- package/dist/index.js +2757 -1555
- package/dist/line/base.d.ts +64 -27
- package/dist/line/geometry.d.ts +28 -0
- package/dist/line/index.d.ts +2 -0
- package/dist/line/label.d.ts +58 -0
- package/dist/line/orthogonal.d.ts +23 -0
- package/dist/line/serialization.d.ts +11 -0
- package/dist/line/straight.d.ts +7 -3
- package/dist/line-tree/history-delta.d.ts +2 -0
- package/dist/line-tree/index.d.ts +15 -8
- package/dist/line-tree/serialization.d.ts +2 -0
- package/dist/line-tree/transform.d.ts +1 -0
- package/dist/line-tree/types.d.ts +3 -2
- package/dist/polygon.d.ts +19 -38
- package/dist/rectangle.d.ts +5 -4
- package/dist/ripple.d.ts +18 -4
- package/dist/scrollbars.d.ts +36 -0
- package/dist/scrollview.d.ts +27 -21
- package/dist/serialization.d.ts +4 -0
- package/dist/text/block.d.ts +5 -1
- package/dist/text/editing.d.ts +54 -12
- package/dist/text/index.d.ts +22 -20
- package/dist/text/layout.d.ts +8 -2
- package/dist/text/paint.d.ts +3 -2
- package/dist/text/style.d.ts +4 -0
- package/dist/triangle.d.ts +10 -5
- package/dist/worker-surface-worker.d.ts +4 -1
- package/dist/worker-surface-worker.js +11 -8
- package/dist/worker-surface.d.ts +1 -0
- package/dist/workspace.d.ts +3 -3
- package/package.json +33 -33
- package/dist/authored-path.d.ts +0 -28
- package/dist/vector-path.d.ts +0 -58
package/README.md
CHANGED
|
@@ -1,77 +1,60 @@
|
|
|
1
|
-
#
|
|
1
|
+
# `@fulate/ui`
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
producer保持authored-local布局;需要超采样时,在自己的backend中基于该倍率增加质量倍率和资源预算。
|
|
7
|
-
`paintBitmap()`仍把最终位图绘制到图元authored宽高,再由Layer应用Viewport与DPR。
|
|
3
|
+
提供 Rectangle、Circle、Triangle、Text、Image、Line、LineTree、Polygon、EditorVectorPath、
|
|
4
|
+
Group、ScrollView 和 Workspace。场景创建见 [Core 快速开始](../core/docs/guides/getting-started.md),
|
|
5
|
+
通用属性见[属性指南](../core/docs/guides/elements-and-properties.md)。
|
|
8
6
|
|
|
9
|
-
|
|
10
|
-
`startFrameSurface(pixelRatio)`;需要同步尺寸时调用`claimFrameResize(pixelRatio)`,只有尺寸或倍率变化
|
|
11
|
-
且上一次请求的frame已经`presentBitmap()`时才返回`true`,producer据此发送一次自己的resize消息。
|
|
12
|
-
等待期间的变化在该frame绘制后按最新值发送,renderer同时最多处理一次待完成的尺寸请求。
|
|
7
|
+
## 路径图形
|
|
13
8
|
|
|
14
|
-
|
|
15
|
-
`
|
|
16
|
-
|
|
17
|
-
## Image 尺寸与加载
|
|
9
|
+
仅需绘制时使用 `@fulate/core` 的 `VectorPath`;需要编辑能力时使用 `@fulate/ui` 的
|
|
10
|
+
`EditorVectorPath`。
|
|
18
11
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
`
|
|
24
|
-
结果失效。晚到的旧 bitmap 会被释放,不覆盖当前源。
|
|
25
|
-
|
|
26
|
-
## Workspace fit
|
|
27
|
-
|
|
28
|
-
`WorkspaceOption.fit`控制首次进入Root时的自动聚焦,`WorkspaceOption.fitOnResize`控制Root尺寸
|
|
29
|
-
变化后的自动重新聚焦;两者默认都是`true`,也可以独立关闭。首次fit在Workspace的初始几何提交后、
|
|
30
|
-
首个Canvas paint前直接安装最终Viewport,不播放动画。同一帧内连续发生的Root尺寸变化只按最终尺寸
|
|
31
|
-
执行一次无动画fit。两条路径都读取当前Root提供的实时可见区insets。
|
|
32
|
-
|
|
33
|
-
编辑器按钮、导入完成等外部流程直接调用同一公开函数,不复制Workspace bounds或Viewport focus规则:
|
|
12
|
+
| 元素 | 创建输入 | 读取路径 |
|
|
13
|
+
| --- | --- | --- |
|
|
14
|
+
| `Line` | `points: PointView[]` 或 `geometry` | `line.geometry` / `line.anchors` |
|
|
15
|
+
| `Polygon` | `path: PointView[]` | `polygon.path.subpaths[0]`,闭合直线 |
|
|
16
|
+
| `EditorVectorPath` | `path: VectorPathCommand[]` 或 `VectorPathGeometry` | `vector.path.subpaths`,直线或三次曲线 |
|
|
34
17
|
|
|
35
18
|
```ts
|
|
36
|
-
import {
|
|
19
|
+
import { Line } from "@fulate/ui";
|
|
37
20
|
|
|
38
|
-
|
|
21
|
+
const line = new Line({
|
|
22
|
+
points: [{ x: 0, y: 0 }, { x: 80, y: 30 }]
|
|
23
|
+
});
|
|
24
|
+
line.setLocalPoint(line.headAnchor.anchorId, { x: 10, y: 5 });
|
|
39
25
|
```
|
|
40
26
|
|
|
41
|
-
|
|
42
|
-
|
|
27
|
+
坐标修改保留点和线段的 ID;插入只创建新增 ID。传入路径对象后不应原地修改,
|
|
28
|
+
应使用对应编辑方法或传入新对象。
|
|
43
29
|
|
|
44
|
-
`Line
|
|
45
|
-
|
|
46
|
-
| 元素 | 普通创建输入 | live getter | topology |
|
|
47
|
-
| --- | --- | --- | --- |
|
|
48
|
-
| `Line` | `path: PointView[]` | `line.path` | 一个 open、line-only subpath |
|
|
49
|
-
| `Polygon` | `contour: PointView[]` | `polygon.contour` | 一个 closed、line-only subpath |
|
|
50
|
-
| `VectorPath` | `path: VectorPathCommand[]` | `vector.path.subpaths` | ordered open/closed line/cubic subpaths |
|
|
51
|
-
|
|
52
|
-
普通输入只在入口解释一次。每个 canonical anchor record 直接保存 `anchorId`、原 `point` 引用,
|
|
53
|
-
并在存在 outgoing segment 时共置 `segmentId` 与 `line | cubic` 数据;普通 line segment 没有
|
|
54
|
-
独立 wrapper。Geometry resolver 让 `vertices` 和 `segmentShapes` 直接复用这些 records。
|
|
30
|
+
正交线仍使用 `Line`:
|
|
55
31
|
|
|
56
32
|
```ts
|
|
33
|
+
import { Line, createOrthogonalLineGeometry } from "@fulate/ui";
|
|
34
|
+
|
|
57
35
|
const line = new Line({
|
|
58
|
-
|
|
36
|
+
geometry: createOrthogonalLineGeometry([{ x: 0, y: 0 }, { x: 180, y: 100 }]),
|
|
37
|
+
text: "审核通过",
|
|
38
|
+
tailDecoration: "arrow"
|
|
59
39
|
});
|
|
60
|
-
|
|
61
|
-
const anchorId = line.headAnchor.anchorId;
|
|
62
|
-
line.setLocalPoint(anchorId, { x: 10, y: 5 });
|
|
63
40
|
```
|
|
64
41
|
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
42
|
+
单击正交线显示端点和折段控制点。拖动绑定端点会断开该端,靠近可连接点后松手可重连;
|
|
43
|
+
两端均未绑定时可从线体或标签拖动整线。正交点编辑不参与场景轴对齐。
|
|
44
|
+
|
|
45
|
+
双击正交线或标签编辑文字,Esc 或点击外部结束;也可调用 `line.setOptions({ text: "新文字" })`。
|
|
46
|
+
文字水平显示在路线长度中点,空字符串隐藏标签,手调点与文字均可保存。
|
|
47
|
+
|
|
48
|
+
## 端口连接
|
|
49
|
+
|
|
50
|
+
为 Root 开启 `enablePorts: true`,并为目标元素设置 `ports: true` 或自定义端口数组。
|
|
51
|
+
默认值、方向和容量配置见 [Ports](../core/docs/guides/elements-and-properties.md#ports)。
|
|
70
52
|
|
|
71
|
-
|
|
53
|
+
程序化连接使用 `connectEndpoint(root, source, target)`,断开使用
|
|
54
|
+
`disconnectEndpoint(root, source)`。Line 首端是 output,尾端是 input;
|
|
55
|
+
方向不兼容、容量已满或目标不存在时不建立连接。
|
|
72
56
|
|
|
73
|
-
|
|
74
|
-
LineTree root/leaf endpoint只保存source-owned relation:
|
|
57
|
+
端点关系引用目标元素与端口:
|
|
75
58
|
|
|
76
59
|
```ts
|
|
77
60
|
interface EndpointRelation {
|
|
@@ -83,88 +66,55 @@ interface EndpointRelation {
|
|
|
83
66
|
}
|
|
84
67
|
```
|
|
85
68
|
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
`EndpointRelationIndex`精确dirty dependents,不反写source authored值或History。
|
|
69
|
+
`Line.relations` 补丁省略一端表示保持该端,显式 `undefined` 清除该端,关系对象建立或替换连接。
|
|
70
|
+
绑定后的端点随目标移动。关闭 Root 的 Ports 不会断开已有连接;删除端口会解除对应关系。
|
|
89
71
|
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
Line首端/root endpoint的连接role是`output`,尾端/leaf是`input`;装饰不决定连接role。同步
|
|
95
|
-
`connectEndpoint()`从live source与target Port读取role、`direction`和对应capacity;方向不兼容、容量
|
|
96
|
-
已满或target Port不存在时保持noop。Tools picker复用同一规则,受阻Port不能降级成自由落点。
|
|
97
|
-
|
|
98
|
-
`Element.ports`是`false | true | readonly ConnectionPortDefinition[]`的唯一authored owner。构造时
|
|
99
|
-
省略等同`false`;`false`没有Port,`true`使用元素类型的默认schema,数组作为custom whole-value按
|
|
100
|
-
原引用采用,`[]`表示当前custom配置为空。patch省略`ports`保持当前值;不支持`null`。数组同引用
|
|
101
|
-
noop,不clone、freeze、normalize或deep-equal。
|
|
102
|
-
`Root.enablePorts`默认`false`并可通过`setEnablePorts()`切换;关闭时不绘制、发现或Snap Port,也不
|
|
103
|
-
允许`connectEndpoint()`新建relation。按已知Port ID解析和已有relation的target observer始终有效,
|
|
104
|
-
因此Line/LineTree继续跟随目标;显式Port删除/替换仍物化当前fallback并detach。完整开关边界见
|
|
105
|
-
[`path-line-core.md`](../../docs/specs/path-line-core.md#10-transformpointbinding-与-routing-边界)。
|
|
106
|
-
|
|
107
|
-
JSON、clipboard和History的独立输出复制所需数据;restore直接安装canonical path/topology、IDs和
|
|
108
|
-
source-owned relations。source与target一起复制时只重映射element key;只复制source时使用当前
|
|
109
|
-
resolved source-local fallback并删除外部relation;完整owner的subpath/anchor/segment/Port IDs保留。
|
|
72
|
+
断开时未提供 `localPosition`,或操作需要当前世界坐标时,先 `await root.nextTick()`。
|
|
73
|
+
文件与剪贴板处理见[Tools IO 指南](../tools/README.md#原生场景与文件-io);完整连接规则见
|
|
74
|
+
[Path/Line 规范](../../docs/specs/path-line-core.md)。
|
|
110
75
|
|
|
111
76
|
## LineTree
|
|
112
77
|
|
|
113
|
-
`LineTree
|
|
114
|
-
|
|
115
|
-
SegmentId`引用这些points;非root branch用`parentSubpathId`表达同一owner内的唯一父分支。
|
|
116
|
-
当前branch只有straight/polyline,不保存kind或Orthogonal/cubic预留variant。
|
|
78
|
+
`LineTree` 把多个分支作为一个元素选择、移动、复制和删除。新增分支从父分支尾点出发,
|
|
79
|
+
同一尾点可创建多个同级分支:
|
|
117
80
|
|
|
118
81
|
```ts
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
]);
|
|
82
|
+
import { LineTree, createLineTreeTopology, addLineTreeBranchAtTail } from "@fulate/ui";
|
|
83
|
+
|
|
84
|
+
const topology = createLineTreeTopology([{ x: 0, y: 0 }, { x: 120, y: 0 }]);
|
|
123
85
|
const tree = new LineTree({ topology });
|
|
124
|
-
const root = topology.branches[0];
|
|
125
86
|
|
|
126
87
|
tree.replaceTopology(addLineTreeBranchAtTail(
|
|
127
88
|
tree.topology,
|
|
128
|
-
|
|
89
|
+
topology.branches[0].subpathId,
|
|
129
90
|
[{ x: 120, y: 80 }]
|
|
130
91
|
).topology);
|
|
131
92
|
```
|
|
132
93
|
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
changed records及必要外层数组。新增branch只复用parent branch的尾点;Editor交互允许任意branch
|
|
137
|
-
tail成为source,同一junction tail可重复产生sibling branches,但junction不绘制tail三角形。树干segment和中间anchor都不是branch source,也
|
|
138
|
-
不会因扩展操作被插入junction。
|
|
139
|
-
|
|
140
|
-
Line与LineTree的stroke和端点decoration在world空间按固定宽度绘制;自身visual bounds与render
|
|
141
|
-
coverage覆盖同一完整绘制范围,反向近零Transform也不会缩掉dirty coverage。固定world paint padding
|
|
142
|
-
不贡献ancestor content bounds;Group selection、resize与snap只消费Line/LineTree的effective path
|
|
143
|
-
geometry。hover与active branch highlight复用同一polyline paint,箭头和线段保持同色。
|
|
144
|
-
|
|
145
|
-
Rectangle、Triangle及其他Shape省略`backgroundColor`/`borderColor`时读取当前Root的
|
|
146
|
-
`skin.shapeFill`/`skin.shapeStroke`;Line和LineTree branch省略`strokeColor`时读取
|
|
147
|
-
`skin.lineStroke`。显式值始终优先,Shape的显式`null`关闭绘制,显式字段清回`undefined`后立即重新
|
|
148
|
-
继承Skin。Skin改变只触发现有Root/Layer重绘,不改写element、branch topology或History。
|
|
94
|
+
双击分支进入该分支的点编辑;删除父分支会删除其全部后代分支。
|
|
95
|
+
交互操作见 [Tools 指南](../tools/README.md#点编辑与画线),数据模型见
|
|
96
|
+
[Path/Line 规范](../../docs/specs/path-line-core.md)。
|
|
149
97
|
|
|
150
|
-
LineTree
|
|
151
|
-
|
|
98
|
+
Line 与 LineTree 的线宽和端点装饰按世界坐标绘制,元素自身缩放不缩放线宽。
|
|
99
|
+
选择框、缩放尺寸和 Group 内容范围使用路径几何,不计描边和箭头外扩。
|
|
100
|
+
省略填充、描边或线色时继承 [Root Skin](../core/docs/guides/layers-and-rendering.md#skin)。
|
|
152
101
|
|
|
153
102
|
## Text 尺寸与显示
|
|
154
103
|
|
|
155
|
-
|
|
156
|
-
`wordWrap` 只控制是否按布局宽度换行,`ellipsis` 只控制是否把被截断内容绘制为 `…`,`overflow`
|
|
157
|
-
只控制是否裁剪绘制内容,三个选项可以独立组合。Text 默认使用 intrinsic 尺寸、`wordWrap=false`、
|
|
158
|
-
`overflow="visible"` 且不启用省略号;组件若需要 Web 控件式的填满、裁剪或省略,应显式传入对应属性。
|
|
104
|
+
未提供 `width`/`height` 时,`Text` 使用文字自然尺寸;提供后作为布局盒。
|
|
159
105
|
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
106
|
+
| 选项 | 作用 | 默认值 |
|
|
107
|
+
| --- | --- | --- |
|
|
108
|
+
| `wordWrap` | 按布局宽度换行 | `false` |
|
|
109
|
+
| `ellipsis` | 将截断内容显示为省略号 | `false` |
|
|
110
|
+
| `overflow` | 控制内容裁剪 | `"visible"` |
|
|
111
|
+
|
|
112
|
+
三者可以独立组合。编辑器选择和缩放使用布局盒,即使文字绘制超出该盒,也不改变选择尺寸。
|
|
113
|
+
`Span` 使用 Yoga 计算后的尺寸约束文字。
|
|
163
114
|
|
|
164
115
|
### 原生 Canvas 文本 run
|
|
165
116
|
|
|
166
|
-
|
|
167
|
-
和字符间距语义测量一段文本,不需要复制或整理 style:
|
|
117
|
+
自定义 Shape 可使用与 Text 相同的字体和基线规则测量文本:
|
|
168
118
|
|
|
169
119
|
```ts
|
|
170
120
|
import { measureTextRun } from "@fulate/ui";
|
|
@@ -172,77 +122,78 @@ import { measureTextRun } from "@fulate/ui";
|
|
|
172
122
|
const metrics = measureTextRun(ctx, text, root.skin.text, 14, 500);
|
|
173
123
|
```
|
|
174
124
|
|
|
175
|
-
|
|
176
|
-
`
|
|
177
|
-
`
|
|
178
|
-
是同一行框内的规范 alphabetic baseline,因此不同字号的 run 可以直接对齐。空文本的 `width`
|
|
179
|
-
为 `0`,但仍测量一个空格以取得稳定字体度量。函数会把本次测量所需的文字状态写入 `ctx`,不会
|
|
180
|
-
调用 `save()` 或 `restore()`;Canvas 生命周期以及业务特有的文字顺序、对齐和绘制仍由 Shape
|
|
181
|
-
自己拥有。
|
|
125
|
+
返回 `font`、`width`、`lineHeight`、`drawY`、`alphabeticBaseline`、
|
|
126
|
+
`textBaseline` 和 `letterSpacing`。不同字号可按 `alphabeticBaseline` 对齐。
|
|
127
|
+
函数会修改 ctx 的文字状态,调用方负责 `save()`/`restore()` 和实际绘制。
|
|
182
128
|
|
|
183
129
|
### 组合型多行文本
|
|
184
130
|
|
|
185
|
-
|
|
186
|
-
共用同一份 hard-break、grapheme、`wordWrap`、`maxLines` 和 `ellipsis` 排版实现:
|
|
131
|
+
在非 Text 元素中绘制可换行文字时,使用 `TextBlock`:
|
|
187
132
|
|
|
188
133
|
```ts
|
|
189
|
-
import {
|
|
190
|
-
TextBlock,
|
|
191
|
-
getTextBlockVisualBounds,
|
|
192
|
-
paintTextBlock,
|
|
193
|
-
resolveTextStyle
|
|
194
|
-
} from "@fulate/ui";
|
|
134
|
+
import { TextBlock, getTextBlockVisualBounds, paintTextBlock, resolveTextStyle } from "@fulate/ui";
|
|
195
135
|
|
|
196
136
|
const style = resolveTextStyle(
|
|
197
|
-
{
|
|
198
|
-
fontSize: 14,
|
|
199
|
-
fontWeight: 500,
|
|
200
|
-
textAlign: "left",
|
|
201
|
-
textBaseline: "top",
|
|
202
|
-
verticalAlign: "top",
|
|
203
|
-
wordWrap: true
|
|
204
|
-
},
|
|
137
|
+
{ fontSize: 14, fontWeight: 500, textAlign: "left", textBaseline: "top", verticalAlign: "top", wordWrap: true },
|
|
205
138
|
root.skin.text
|
|
206
139
|
);
|
|
207
140
|
const block = new TextBlock();
|
|
208
141
|
const snapshot = block.sync({
|
|
209
|
-
text,
|
|
210
|
-
|
|
211
|
-
width: 120,
|
|
212
|
-
height: 80,
|
|
213
|
-
overflow: "visible",
|
|
214
|
-
wordWrap: true,
|
|
215
|
-
ellipsis: false
|
|
142
|
+
text, style, width: 120, height: 80,
|
|
143
|
+
overflow: "visible", wordWrap: true, ellipsis: false
|
|
216
144
|
});
|
|
217
145
|
|
|
218
146
|
paintTextBlock(ctx, snapshot, style, 120, 80);
|
|
219
147
|
const visualBounds = getTextBlockVisualBounds(snapshot, style, 120, 80);
|
|
220
148
|
```
|
|
221
149
|
|
|
222
|
-
`measure()
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
150
|
+
预先测量使用 `measure()`;最终尺寸确定后调用 `sync()`,将结果用于绘制和视觉边界。
|
|
151
|
+
调用方负责 Canvas 变换、裁剪和状态恢复,`overflow: "hidden"` 也需要自行安装 clip。
|
|
152
|
+
|
|
153
|
+
输入或 Skin 变化时调用 `invalidate()`。需要响应字体加载时订阅
|
|
154
|
+
`subscribeTextMeasurementChanges()`,销毁时调用返回的取消函数。
|
|
155
|
+
|
|
156
|
+
## Image 尺寸与加载
|
|
157
|
+
|
|
158
|
+
`Image` 未指定尺寸时使用源的 `naturalWidth`/`naturalHeight`;显式宽高优先,`0` 也有效。
|
|
159
|
+
更换源后,旧加载结果不会覆盖新图片。
|
|
160
|
+
|
|
161
|
+
PNG 导出使用当前显示的位图与样式,不等待加载或解码;图片未加载完成时,导出中没有该图片内容。
|
|
162
|
+
详见 [PNG 导出](../core/docs/guides/png-export.md)。
|
|
163
|
+
|
|
164
|
+
## ScrollView 内容范围
|
|
165
|
+
|
|
166
|
+
`contentWidth`/`contentHeight` 构造值提供首次布局前的范围;首次布局后由子元素范围决定,
|
|
167
|
+
内容变化会更新范围。内容缩小或写入越界 offset 后,在后续帧将滚动位置限制到有效范围。
|
|
168
|
+
|
|
169
|
+
## Workspace fit
|
|
170
|
+
|
|
171
|
+
`fit` 控制首次进入 Root 时自动聚焦,`fitOnResize` 控制 Root 尺寸变化后重新聚焦,两者默认
|
|
172
|
+
`true`,可分别关闭。自动聚焦不播放动画,并会避开标尺等占用的可见区域。
|
|
173
|
+
|
|
174
|
+
手动聚焦:
|
|
175
|
+
|
|
176
|
+
```ts
|
|
177
|
+
import { fitWorkspace } from "@fulate/ui";
|
|
178
|
+
|
|
179
|
+
await fitWorkspace(workspace, { padding: 0 });
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
手动调用不受上述两个开关限制;需要动画时显式传入 `animate`。
|
|
183
|
+
|
|
184
|
+
## 浮层定位
|
|
228
185
|
|
|
229
|
-
`
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
`TextBlock` 的内部实现,也不要为同一段文字另建一套换行或测量器。
|
|
186
|
+
`computePosition()` 基于当前几何计算位置,调用前先 `await root.nextTick()`。
|
|
187
|
+
返回的 `x/y` 已转换为浮层父空间的 `left/top`,可直接传给 `setOptions()`;
|
|
188
|
+
Floating UI 的尺寸、偏移与 `middlewareData` 使用世界坐标。
|
|
233
189
|
|
|
234
190
|
## Editor capabilities
|
|
235
191
|
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
Selection 的闭集策略使用公开枚举:
|
|
192
|
+
自定义元素通过 Selection、Transform、Snap、Point、Content capability 接入编辑器。
|
|
193
|
+
例如选择策略使用公开枚举:
|
|
239
194
|
|
|
240
195
|
```ts
|
|
241
|
-
import {
|
|
242
|
-
SelectionBehaviorMode,
|
|
243
|
-
SelectionDiveMode,
|
|
244
|
-
SelectionSnapMode
|
|
245
|
-
} from "@fulate/ui";
|
|
196
|
+
import { SelectionBehaviorMode, SelectionDiveMode, SelectionSnapMode } from "@fulate/ui";
|
|
246
197
|
|
|
247
198
|
const behavior = {
|
|
248
199
|
mode: SelectionBehaviorMode.OwnerDirect,
|
|
@@ -251,16 +202,18 @@ const behavior = {
|
|
|
251
202
|
};
|
|
252
203
|
```
|
|
253
204
|
|
|
254
|
-
`OwnerDirect`
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
205
|
+
`OwnerDirect` 适合直接拖动且不显示单选框的对象;Group 使用 `DirectChild` 下钻,
|
|
206
|
+
普通图形使用 `Standard`。完整接口见[编辑器规范](../../docs/specs/editor-interaction.md)。
|
|
207
|
+
|
|
208
|
+
`selectable: false` 禁止交互选择进入该元素分支;程序化 `Select.select()` 仍由调用方决定,
|
|
209
|
+
修改该属性也不会自动清除已有选择。
|
|
210
|
+
|
|
211
|
+
## Bitmap surface
|
|
212
|
+
|
|
213
|
+
自定义位图元素继承 `Bitmap`,通过 `presentBitmap()` 交付新帧;交付后由 Bitmap 负责替换和释放资源。
|
|
214
|
+
`renderPixelRatio` 为 `Viewport scale × DPR`,位图分辨率不改变局部逻辑坐标。
|
|
215
|
+
|
|
216
|
+
创建渲染 surface 时调用 `startFrameSurface(pixelRatio)`;后续仅在
|
|
217
|
+
`claimFrameResize(pixelRatio)` 返回 `true` 时发送 resize。前一帧到达前不会再次放行尺寸请求。
|
|
218
|
+
|
|
219
|
+
Worker 接入与资源生命周期见 [Worker-backed bitmap 扩展](../core/docs/guides/extending-core.md#worker-backed-bitmap-扩展)。
|
package/dist/circle.d.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { type EditorShapeOption } from "./editor/properties";
|
|
1
2
|
import { type PointView } from "@fulate/share";
|
|
2
3
|
import type { Edge } from "@fulate/share";
|
|
3
4
|
import { type GeometrySnapshot } from "@fulate/core";
|
|
@@ -13,7 +14,7 @@ export declare class CircleTransform<E extends Circle = Circle> extends EditorSh
|
|
|
13
14
|
}
|
|
14
15
|
export declare class Circle extends EditorShape {
|
|
15
16
|
readonly type = "circle";
|
|
16
|
-
constructor(options?:
|
|
17
|
+
constructor(options?: EditorShapeOption);
|
|
17
18
|
protected buildPath(ctx: CanvasRenderingContext2D): void;
|
|
18
19
|
getEdgePosition(edge: Edge, ratio: number): {
|
|
19
20
|
pos: PointView;
|
|
@@ -1,13 +1,13 @@
|
|
|
1
1
|
import { Element, type AnchorId, type ConnectionPortDefinition, type ConnectionPortRef, type OwnerPropertyChange, type Root } from "@fulate/core";
|
|
2
2
|
import type { PointView } from "@fulate/share";
|
|
3
3
|
import { type EndpointConnectionRole, type EndpointRef } from "./types";
|
|
4
|
-
/**
|
|
4
|
+
/** R0:按 endpoint role、Port direction 与当前 capacity 建立 Binding。 */
|
|
5
5
|
export declare function connectEndpoint(root: Root, source: EndpointRef, target: ConnectionPortRef): void;
|
|
6
|
-
/**
|
|
6
|
+
/** R0:删除普通 Binding;省略 localPosition 时读取已准备的 resolved 位置。 */
|
|
7
7
|
export declare function disconnectEndpoint(root: Root, source: EndpointRef, options?: {
|
|
8
8
|
readonly localPosition?: PointView;
|
|
9
9
|
}): void;
|
|
10
|
-
/** @internal 从调用时 live scene
|
|
10
|
+
/** @internal 从调用时 live scene 纯计算一次 owner change;resolver 不提交场景或推进阶段。 */
|
|
11
11
|
export declare function resolveConnectEndpointChange(root: Root, source: EndpointRef, target: ConnectionPortRef): OwnerPropertyChange | null;
|
|
12
12
|
/** @internal 按 source owner 合并多个 detach 为每 owner 一个 final change。 */
|
|
13
13
|
export declare function resolveDisconnectEndpointChanges(root: Root, sources: readonly EndpointRef[], localPositions?: ReadonlyMap<AnchorId, PointView>, patches?: ReadonlyMap<Element, Readonly<Record<string, unknown>>>): OwnerPropertyChange[];
|
|
@@ -22,7 +22,11 @@ export interface EndpointRelationBinding {
|
|
|
22
22
|
export interface BindableEndpoint {
|
|
23
23
|
readonly ref: EndpointRef;
|
|
24
24
|
}
|
|
25
|
-
/**
|
|
25
|
+
/**
|
|
26
|
+
* Standalone Line 与 LineTree 共用的 source-owned relation 接缝。
|
|
27
|
+
* 查询与 resolver 只消费当前 canonical 输入,可填所属纯计算缓存;不得提交场景、
|
|
28
|
+
* 改变结构/交互或推进运行阶段。resolver 返回的 typed effect 由调用者同步提交一次。
|
|
29
|
+
*/
|
|
26
30
|
export interface EndpointRelationSource {
|
|
27
31
|
getBindableEndpoints(): readonly BindableEndpoint[];
|
|
28
32
|
getEndpointRole(anchorId: AnchorId): EndpointConnectionRole | null;
|
|
@@ -1,26 +1,42 @@
|
|
|
1
|
+
import { type PaintContext } from "@fulate/core";
|
|
1
2
|
import { type ResolvedConnectionPortSlot, type Root, type Shape } from "@fulate/core";
|
|
2
3
|
import { Bound } from "@fulate/share";
|
|
3
4
|
type ConnectionPortDecorationHost = Shape & {
|
|
4
5
|
getResolvedConnectionPortSlots(): readonly ResolvedConnectionPortSlot[];
|
|
5
6
|
};
|
|
6
|
-
/**
|
|
7
|
+
/** UI Shape 内部的非节点 Port 绘制、文字布局和 visual bounds 组合。 */
|
|
7
8
|
export declare class ConnectionPortDecoration {
|
|
8
9
|
private readonly host;
|
|
10
|
+
static isEnabled(host: ConnectionPortDecorationHost): boolean;
|
|
11
|
+
static create(host: ConnectionPortDecorationHost): ConnectionPortDecoration;
|
|
12
|
+
static syncPorts(host: ConnectionPortDecorationHost, decoration: ConnectionPortDecoration | null): ConnectionPortDecoration;
|
|
13
|
+
static activateForRoot(root: Root | null, decoration: ConnectionPortDecoration | null): ConnectionPortDecoration;
|
|
14
|
+
paintWithHost(paint: PaintContext): void;
|
|
9
15
|
private slotSource;
|
|
10
16
|
private entries;
|
|
11
17
|
private activeRoot;
|
|
12
18
|
private skinTextCommitRemove;
|
|
13
19
|
private measurementRemove;
|
|
20
|
+
private placementMatrixA;
|
|
21
|
+
private placementMatrixB;
|
|
22
|
+
private placementMatrixC;
|
|
23
|
+
private placementMatrixD;
|
|
24
|
+
private placementMatrixE;
|
|
25
|
+
private placementMatrixF;
|
|
14
26
|
constructor(host: ConnectionPortDecorationHost);
|
|
15
27
|
activate(root: Root): void;
|
|
16
28
|
deactivate(): void;
|
|
17
29
|
invalidateSource(): void;
|
|
18
|
-
paint(
|
|
30
|
+
paint(paint: PaintContext): void;
|
|
19
31
|
getWorldBounds(): Bound | null;
|
|
20
32
|
private getEntries;
|
|
21
33
|
private resolveLabelPlacement;
|
|
34
|
+
private updatePlacementMatrix;
|
|
35
|
+
/** Bounds 与 paint 借用同一次 slot/font/world-matrix 定位结果。 */
|
|
36
|
+
private getLabelPlacement;
|
|
22
37
|
private getStyle;
|
|
23
38
|
private buildUprightMatrix;
|
|
39
|
+
private readonly handleSkinTextChanged;
|
|
24
40
|
private readonly handleTextMeasurementChanged;
|
|
25
41
|
private invalidateTextLayout;
|
|
26
42
|
}
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { Element, type AnchorId, type ElementTransformBaseline, type OwnerPropertyChange, type ReparentTransformIntent, type SegmentId, type StablePathTargetRef, type SubpathId, type TransformIntent } from "@fulate/core";
|
|
1
|
+
import { Element, type AnchorId, type GeometrySnapshot, type ElementTransformBaseline, type OwnerPropertyChange, type OriginX, type OriginY, type ReparentTransformIntent, type SegmentId, type StablePathTargetRef, type SubpathId, type TransformIntent } from "@fulate/core";
|
|
2
2
|
import type { PointView, Rect } from "@fulate/share";
|
|
3
3
|
import type { EndpointRef } from "../connection/types";
|
|
4
4
|
declare const capabilityType: unique symbol;
|
|
@@ -6,7 +6,7 @@ declare const capabilityType: unique symbol;
|
|
|
6
6
|
export interface EditorCapabilityToken<T> {
|
|
7
7
|
readonly [capabilityType]?: T;
|
|
8
8
|
}
|
|
9
|
-
/**
|
|
9
|
+
/** 纯查询能力;可填本 owner 的计算缓存,不改变场景、选择或运行阶段。 */
|
|
10
10
|
export interface EditorCapabilityHost {
|
|
11
11
|
getEditorCapability<T>(token: EditorCapabilityToken<T>): T | undefined;
|
|
12
12
|
}
|
|
@@ -48,21 +48,33 @@ export interface TransformInteractionPolicy {
|
|
|
48
48
|
readonly rotationPivot: "center-only" | "adjustable";
|
|
49
49
|
}
|
|
50
50
|
export interface TransformInteractionCapability<Owned = unknown> {
|
|
51
|
+
readonly rotationPivotX: OriginX;
|
|
52
|
+
readonly rotationPivotY: OriginY;
|
|
51
53
|
getTransformPolicy(): TransformInteractionPolicy;
|
|
52
|
-
/** Optional
|
|
54
|
+
/** Optional local bounds used by the editor frame (authored/layout or effective geometry). */
|
|
53
55
|
getSelectionFrameBounds?(): Readonly<Rect> | null;
|
|
54
|
-
/**
|
|
56
|
+
/** R0: capture the prepared geometry reference and current authored state. */
|
|
55
57
|
captureTransformBaseline(bakeGeometry: boolean): ElementTransformBaseline<Owned>;
|
|
56
58
|
/**
|
|
57
59
|
* Resolves every owner change for this transform. Composite owners may return
|
|
58
60
|
* multiple child changes; the editor commits the complete result in one batch.
|
|
61
|
+
* Pure calculation: do not mutate scene/interaction state or advance a phase.
|
|
59
62
|
*/
|
|
60
63
|
resolveTransformChange(baseline: Readonly<ElementTransformBaseline<Owned>>, intent: Readonly<TransformIntent | ReparentTransformIntent>): readonly OwnerPropertyChange[];
|
|
61
64
|
}
|
|
62
65
|
export interface SnapSourceCapability {
|
|
66
|
+
/** Borrow the committed world projection until its geometry/matrix inputs change. */
|
|
63
67
|
getWorldSnapPointsView(): readonly PointView[];
|
|
64
68
|
}
|
|
65
|
-
export type PointEditTarget =
|
|
69
|
+
export type PointEditTarget = {
|
|
70
|
+
readonly kind: "route-segment";
|
|
71
|
+
readonly snapshot: GeometrySnapshot;
|
|
72
|
+
readonly index: number;
|
|
73
|
+
} | {
|
|
74
|
+
readonly kind: "orthogonal-segment";
|
|
75
|
+
readonly from: AnchorId;
|
|
76
|
+
readonly to: AnchorId;
|
|
77
|
+
} | StablePathTargetRef | {
|
|
66
78
|
readonly kind: "handle";
|
|
67
79
|
readonly segmentId: SegmentId;
|
|
68
80
|
readonly role: "cubic-control-1" | "cubic-control-2";
|
|
@@ -75,6 +87,13 @@ export type PointEditingScope = {
|
|
|
75
87
|
readonly subpathId: SubpathId;
|
|
76
88
|
};
|
|
77
89
|
export type PointControlDescriptor = {
|
|
90
|
+
readonly kind: "move-segment";
|
|
91
|
+
readonly target: Extract<PointEditTarget, {
|
|
92
|
+
kind: "route-segment" | "orthogonal-segment";
|
|
93
|
+
}>;
|
|
94
|
+
readonly local: PointView;
|
|
95
|
+
readonly axis: "x" | "y";
|
|
96
|
+
} | {
|
|
78
97
|
readonly kind: "anchor";
|
|
79
98
|
readonly target: Extract<PointEditTarget, {
|
|
80
99
|
readonly kind: "anchor";
|
|
@@ -101,6 +120,14 @@ export type PointControlDescriptor = {
|
|
|
101
120
|
readonly anchorLocal: PointView;
|
|
102
121
|
};
|
|
103
122
|
export type PointEditRequest = {
|
|
123
|
+
readonly kind: "move-segment";
|
|
124
|
+
readonly target: Extract<PointEditTarget, {
|
|
125
|
+
kind: "route-segment" | "orthogonal-segment";
|
|
126
|
+
}>;
|
|
127
|
+
readonly world: PointView;
|
|
128
|
+
/** World distance for collapsing a short neighboring orthogonal fold. */
|
|
129
|
+
readonly mergeTolerance: number;
|
|
130
|
+
} | {
|
|
104
131
|
readonly kind: "move-anchor";
|
|
105
132
|
readonly anchorId: AnchorId;
|
|
106
133
|
readonly local: PointView;
|
|
@@ -132,9 +159,12 @@ export type PointOwnerEdit = {
|
|
|
132
159
|
readonly source: EndpointRef;
|
|
133
160
|
readonly local: PointView;
|
|
134
161
|
};
|
|
162
|
+
/** Pure scope/control/effect computation from current canonical and prepared geometry. */
|
|
135
163
|
export interface PointEditingCapability {
|
|
136
164
|
resolvePointScope(worldPoint: PointView, current?: PointEditingScope): PointEditingScope | null;
|
|
137
165
|
hasPointScope(scope: PointEditingScope): boolean;
|
|
166
|
+
/** Tests authored target existence independently of the visible control projection. */
|
|
167
|
+
hasPointTarget(scope: PointEditingScope, target: PointEditTarget): boolean;
|
|
138
168
|
getPointControls(scope: PointEditingScope): readonly PointControlDescriptor[];
|
|
139
169
|
getPointScopeOutline(scope: PointEditingScope): readonly PointView[] | null;
|
|
140
170
|
resolvePointEdit(request: PointEditRequest): PointOwnerEdit | null;
|
|
@@ -148,8 +178,9 @@ export interface ContentEditingCapability {
|
|
|
148
178
|
}
|
|
149
179
|
export interface ContentEditingSession {
|
|
150
180
|
readonly ownerKey: string;
|
|
181
|
+
/** Pure text effect; submit/History ownership remains with the consumer. */
|
|
151
182
|
resolveTextChange(value: string): OwnerPropertyChange | null;
|
|
152
|
-
/**
|
|
183
|
+
/** 只释放本 session 的 DOM/listeners;不得再次触发 consumer.finish()。 */
|
|
153
184
|
close(): void;
|
|
154
185
|
}
|
|
155
186
|
export declare const SelectionBehaviorCapabilityToken: EditorCapabilityToken<SelectionBehaviorCapability>;
|
|
@@ -1,17 +1,18 @@
|
|
|
1
1
|
import { type Root, type RootFrameParticipant } from "@fulate/core";
|
|
2
2
|
import type { PointView } from "@fulate/share";
|
|
3
3
|
export interface EditorAuthoredGesture {
|
|
4
|
+
/** R0: consume the latest accepted intent and synchronously commit its typed effects. */
|
|
4
5
|
consumeLatestIntent(): void;
|
|
5
6
|
}
|
|
6
7
|
export interface EditorOverlayClient {
|
|
7
8
|
hasPendingOverlayWork(): boolean;
|
|
9
|
+
/** R2: consume stable geometry and replace only the interaction projection. */
|
|
8
10
|
flushOverlayProjection(): void;
|
|
9
|
-
hasPendingCompletionWork(): boolean;
|
|
10
|
-
flushCompletionWork(): void;
|
|
11
11
|
resolveCursor(point: PointView | undefined, contentCursor: string): string;
|
|
12
12
|
}
|
|
13
13
|
export interface EditorSpatialClient {
|
|
14
14
|
hasPendingSpatialWork(): boolean;
|
|
15
|
+
/** R2: update the owner's projection from the committed scene and geometry. */
|
|
15
16
|
flushSpatialProjection(): void;
|
|
16
17
|
}
|
|
17
18
|
/** @internal Root 生命周期内唯一的 Editor mutation/spatial/overlay participant。 */
|
|
@@ -31,8 +32,6 @@ export declare class EditorFrameFlush implements RootFrameParticipant {
|
|
|
31
32
|
flushSpatialProjection(): void;
|
|
32
33
|
hasPendingOverlayWork(): boolean;
|
|
33
34
|
flushOverlayProjection(): void;
|
|
34
|
-
hasPendingCompletionWork(): boolean;
|
|
35
|
-
flushCompletionWork(): void;
|
|
36
35
|
resolveCursor(point: PointView | undefined, contentCursor: string): string;
|
|
37
36
|
}
|
|
38
37
|
/** 取得并在需要时安装当前 Root 唯一的 Editor FrameFlush。 */
|