@fulate/ui 2.0.11 → 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 +127 -243
- package/dist/index.d.ts +2 -0
- package/dist/index.js +111 -2
- package/dist/line/serialization.d.ts +11 -0
- package/dist/line-tree/serialization.d.ts +2 -0
- package/dist/serialization.d.ts +4 -0
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -1,126 +1,60 @@
|
|
|
1
|
-
#
|
|
1
|
+
# `@fulate/ui`
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
不能在通知中再次改写正在通知的 placement/children。
|
|
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)。
|
|
7
6
|
|
|
8
|
-
##
|
|
9
|
-
|
|
10
|
-
`Bitmap`唯一拥有主线程当前frame,并向位图producer提供`renderPixelRatio = Viewport scale × DPR`。
|
|
11
|
-
producer保持authored-local布局;需要超采样时,在自己的backend中基于该倍率增加质量倍率和资源预算。
|
|
12
|
-
`paintBitmap()`仍把最终位图绘制到图元authored宽高,再由Layer应用Viewport与DPR。
|
|
13
|
-
|
|
14
|
-
`Bitmap`也唯一记录renderer最近收到的authored宽高与像素倍率。producer创建renderer时调用
|
|
15
|
-
`startFrameSurface(pixelRatio)`;需要同步尺寸时调用`claimFrameResize(pixelRatio)`,只有尺寸或倍率变化
|
|
16
|
-
且上一次请求的frame已经`presentBitmap()`时才返回`true`,producer据此发送一次自己的resize消息。
|
|
17
|
-
等待期间的变化在该frame绘制后按最新值发送,renderer同时最多处理一次待完成的尺寸请求。
|
|
18
|
-
|
|
19
|
-
Worker 的 `onFrame` 和 emitter 的 `emit` 调用把 bitmap 所有权交给接收方;接收方采用后发生异常,
|
|
20
|
-
发送方不再关闭该资源。跨 Worker 的原生 `postMessage` 成功后才完成跨 realm 转移;发送失败时仍持有
|
|
21
|
-
bitmap 的 host 负责释放并传播原异常。已经失效且尚未交付的 frame 由收到它的资源 owner 关闭。
|
|
22
|
-
|
|
23
|
-
位图、DPR和超采样质量都不改变逻辑坐标。鼠标与Worker返回的坐标保持authored-local,不经过
|
|
24
|
-
`Bitmap`的scale换算。
|
|
25
|
-
|
|
26
|
-
PNG 导出直接借用当前 bitmap,通过同一 `paintBitmap()` 绘制。导出不向 Worker 请求新帧,
|
|
27
|
-
也不接管 bitmap 的释放;尺寸与清晰度语义见 [PNG 导出](../core/docs/guides/png-export.md)。
|
|
28
|
-
|
|
29
|
-
## Image 尺寸与加载
|
|
30
|
-
|
|
31
|
-
`Image` 未提供尺寸时直接读取当前源的 `naturalWidth`/`naturalHeight`;显式
|
|
32
|
-
`width`/`height` 优先且保留 `0`。源的 intrinsic 尺寸变化进入同一 geometry/layout 提交,位图分辨率
|
|
33
|
-
升级只重绘,不改变逻辑尺寸。
|
|
34
|
-
|
|
35
|
-
`src` 与构造时提供的 `image` 使用同一加载路径;切换源、detach、重新进入和 unmount 都使旧处理
|
|
36
|
-
结果失效。晚到的旧 bitmap 会被释放,不覆盖当前源。
|
|
37
|
-
`Image` 的 PNG 导出复用当前已显示的 bitmap、半径裁剪与样式,不另行加载、解码或升级分辨率。
|
|
38
|
-
源加载尚未完成时,导出与普通绘制一样没有该图片内容。
|
|
39
|
-
当前 load/decode 直接以其 Promise identity 表示;位图尺寸从 `Bitmap` 所持有的资源读取,源的 intrinsic
|
|
40
|
-
尺寸单独保存,避免下采样结果改变布局尺寸。
|
|
41
|
-
|
|
42
|
-
## ScrollView 内容范围
|
|
43
|
-
|
|
44
|
-
`contentWidth/contentHeight` 构造值提供首次布局前的范围;首次布局后由直接子元素的 extent 替换。
|
|
45
|
-
子元素或后代的实际变化使范围失效;纯滚动复用该范围,继续更新必要的 child world matrix、clip 和
|
|
46
|
-
scrollbar 投影。内容缩小所需的 clamp 由 ScrollView 在下一次 Root RAF 的 R0 读取当前范围执行,停用时
|
|
47
|
-
释放待办。直接写入越界 offset 也在 R1 登记下一 R0 的归位;归位前恢复范围会取消该待办。
|
|
48
|
-
|
|
49
|
-
ScrollView 的内容范围和 max-size 由自身 R1 layout owner 计算;Ripple 的 owner 观察当前宿主的
|
|
50
|
-
transform commit,仅在尺寸真实改变时安装自己的 frame。换父或停用会释放旧宿主订阅。
|
|
51
|
-
离线 ScrollView/Ripple 在既有 Transform baseline capture 入口内稳定相关脏链,不请求 RAF。
|
|
52
|
-
|
|
53
|
-
## Workspace fit
|
|
7
|
+
## 路径图形
|
|
54
8
|
|
|
55
|
-
`
|
|
56
|
-
|
|
57
|
-
首个Canvas paint前直接安装最终Viewport,不播放动画。同一帧内连续发生的Root尺寸变化只按最终尺寸
|
|
58
|
-
执行一次无动画fit。两条路径都读取当前Root提供的实时可见区insets。
|
|
9
|
+
仅需绘制时使用 `@fulate/core` 的 `VectorPath`;需要编辑能力时使用 `@fulate/ui` 的
|
|
10
|
+
`EditorVectorPath`。
|
|
59
11
|
|
|
60
|
-
|
|
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`,直线或三次曲线 |
|
|
61
17
|
|
|
62
18
|
```ts
|
|
63
|
-
import {
|
|
64
|
-
|
|
65
|
-
await fitWorkspace(workspace, { padding: 0 });
|
|
66
|
-
```
|
|
67
|
-
|
|
68
|
-
显式调用不受`WorkspaceOption.fit`或`WorkspaceOption.fitOnResize`限制;传入的focus options会按原引用
|
|
69
|
-
直接交给Workspace所属Root的Viewport。用户触发的fit需要动画时由调用者显式传入`animate`。
|
|
70
|
-
|
|
71
|
-
通用场景路径从 `@fulate/core` 导入 VectorPath;编辑器使用 `@fulate/ui` 的 EditorVectorPath。
|
|
72
|
-
Polygon 继承 EditorVectorPath。VectorPathCommand、VectorPathGeometry 和基础 VectorPathOption 从 Core 导入。
|
|
73
|
-
|
|
74
|
-
`Line`、`Polygon` 和 `EditorVectorPath` 都只有一份 live canonical authored owner:
|
|
75
|
-
|
|
76
|
-
| 元素 | 普通创建输入 | live getter | topology |
|
|
77
|
-
| --- | --- | --- | --- |
|
|
78
|
-
| `Line` | `points: PointView[]` 或 `geometry` | `line.geometry` / `line.anchors` | manual subpath 或 orthogonal 端点、手调点与 margin |
|
|
79
|
-
| `Polygon` | `path: PointView[]` | `polygon.path.subpaths[0]` | 一个 closed、line-only subpath |
|
|
80
|
-
| `EditorVectorPath` | `path: VectorPathCommand[]` | `vector.path.subpaths` | ordered open/closed line/cubic subpaths |
|
|
19
|
+
import { Line } from "@fulate/ui";
|
|
81
20
|
|
|
82
|
-
普通输入只在入口解释一次。每个 canonical anchor record 直接保存 `anchorId`、原 `point` 引用,
|
|
83
|
-
并在存在 outgoing segment 时共置 `segmentId` 与 `line | cubic` 数据;普通 line segment 没有
|
|
84
|
-
独立 wrapper。Geometry resolver 让 `vertices` 和 `segmentShapes` 直接复用这些 records。
|
|
85
|
-
|
|
86
|
-
```ts
|
|
87
21
|
const line = new Line({
|
|
88
22
|
points: [{ x: 0, y: 0 }, { x: 80, y: 30 }]
|
|
89
23
|
});
|
|
90
|
-
|
|
91
|
-
const anchorId = line.headAnchor.anchorId;
|
|
92
|
-
line.setLocalPoint(anchorId, { x: 10, y: 5 });
|
|
24
|
+
line.setLocalPoint(line.headAnchor.anchorId, { x: 10, y: 5 });
|
|
93
25
|
```
|
|
94
26
|
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
即使内容相同也会被采用。point/control 等结构化值不做 caller-isolation clone;需要隔离时由
|
|
98
|
-
调用者在传入前复制。调用者在所有权移交后原地修改同一对象不会自动产生 commit、dirty、
|
|
99
|
-
History 或 frame。
|
|
27
|
+
坐标修改保留点和线段的 ID;插入只创建新增 ID。传入路径对象后不应原地修改,
|
|
28
|
+
应使用对应编辑方法或传入新对象。
|
|
100
29
|
|
|
101
|
-
|
|
30
|
+
正交线仍使用 `Line`:
|
|
102
31
|
|
|
103
32
|
```ts
|
|
33
|
+
import { Line, createOrthogonalLineGeometry } from "@fulate/ui";
|
|
34
|
+
|
|
104
35
|
const line = new Line({
|
|
105
|
-
geometry: createOrthogonalLineGeometry([{x: 0, y: 0}, {x: 180, y: 100}]),
|
|
106
|
-
text:
|
|
36
|
+
geometry: createOrthogonalLineGeometry([{ x: 0, y: 0 }, { x: 180, y: 100 }]),
|
|
37
|
+
text: "审核通过",
|
|
107
38
|
tailDecoration: "arrow"
|
|
108
39
|
});
|
|
109
40
|
```
|
|
110
41
|
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
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)。
|
|
119
52
|
|
|
120
|
-
|
|
53
|
+
程序化连接使用 `connectEndpoint(root, source, target)`,断开使用
|
|
54
|
+
`disconnectEndpoint(root, source)`。Line 首端是 output,尾端是 input;
|
|
55
|
+
方向不兼容、容量已满或目标不存在时不建立连接。
|
|
121
56
|
|
|
122
|
-
|
|
123
|
-
LineTree root/leaf endpoint只保存source-owned relation:
|
|
57
|
+
端点关系引用目标元素与端口:
|
|
124
58
|
|
|
125
59
|
```ts
|
|
126
60
|
interface EndpointRelation {
|
|
@@ -132,108 +66,55 @@ interface EndpointRelation {
|
|
|
132
66
|
}
|
|
133
67
|
```
|
|
134
68
|
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
`disconnectEndpoint(root, source)`;普通noop返回`void`且不创建结果状态机。
|
|
142
|
-
connect 只消费 Port 元数据;disconnect 省略 `localPosition`、Port 删除或 world-coordinate Point
|
|
143
|
-
writer 需要操作前已准备的几何。调用者在依赖变化后先 `await root.nextTick()`;authored-local writer
|
|
144
|
-
直接使用局部数据。`computePosition()` 同样消费已准备的几何,其 Promise 来自 Floating UI 计算。
|
|
145
|
-
Floating UI 的尺寸、偏移和 `middlewareData` 使用 world 空间;返回的 `x/y` 已转换为 floating 元素
|
|
146
|
-
父空间的 `left/top`,可直接传给 `setOptions()`,包括缩放、旋转和滚动父容器。
|
|
147
|
-
通用读取与等待合同见 [Core 阶段合同](../../docs/specs/core-runtime-phases.md#d3-读取与状态推进)。
|
|
148
|
-
|
|
149
|
-
Line首端/root endpoint的连接role是`output`,尾端/leaf是`input`;装饰不决定连接role。同步
|
|
150
|
-
`connectEndpoint()`从live source与target Port读取role、`direction`和对应capacity;方向不兼容、容量
|
|
151
|
-
已满或target Port不存在时保持noop。Tools picker复用同一规则,受阻Port不能降级成自由落点。
|
|
152
|
-
|
|
153
|
-
`Element.ports`是`false | true | readonly ConnectionPortDefinition[]`的唯一authored owner。构造时
|
|
154
|
-
省略等同`false`;`false`没有Port,`true`使用元素类型的默认schema,数组作为custom whole-value按
|
|
155
|
-
原引用采用,`[]`表示当前custom配置为空。patch省略`ports`保持当前值;不支持`null`。数组同引用
|
|
156
|
-
noop,不clone、freeze、normalize或deep-equal。
|
|
157
|
-
`Root.enablePorts`默认`false`并可通过`setEnablePorts()`切换;关闭时不绘制、发现或Snap Port,也不
|
|
158
|
-
允许`connectEndpoint()`新建relation。按已知Port ID解析和已有relation的target observer始终有效,
|
|
159
|
-
因此Line/LineTree继续跟随目标;显式Port删除/替换仍物化当前fallback并detach。完整开关边界见
|
|
160
|
-
[`path-line-core.md`](../../docs/specs/path-line-core.md#10-transformpointbinding-与-routing-边界)。
|
|
161
|
-
|
|
162
|
-
JSON、clipboard和History的独立输出复制所需数据;restore直接安装canonical geometry/path/topology、IDs和
|
|
163
|
-
source-owned relations。source与target一起复制时只重映射element key;只复制source时使用当前
|
|
164
|
-
resolved source-local fallback并删除外部relation;完整owner的subpath/anchor/segment/Port IDs保留。
|
|
69
|
+
`Line.relations` 补丁省略一端表示保持该端,显式 `undefined` 清除该端,关系对象建立或替换连接。
|
|
70
|
+
绑定后的端点随目标移动。关闭 Root 的 Ports 不会断开已有连接;删除端口会解除对应关系。
|
|
71
|
+
|
|
72
|
+
断开时未提供 `localPosition`,或操作需要当前世界坐标时,先 `await root.nextTick()`。
|
|
73
|
+
文件与剪贴板处理见[Tools IO 指南](../tools/README.md#原生场景与文件-io);完整连接规则见
|
|
74
|
+
[Path/Line 规范](../../docs/specs/path-line-core.md)。
|
|
165
75
|
|
|
166
76
|
## LineTree
|
|
167
77
|
|
|
168
|
-
`LineTree
|
|
169
|
-
|
|
170
|
-
SegmentId`引用这些points;非root branch用`parentSubpathId`表达同一owner内的唯一父分支。
|
|
171
|
-
当前branch只有straight/polyline,不保存kind或Orthogonal/cubic预留variant。
|
|
78
|
+
`LineTree` 把多个分支作为一个元素选择、移动、复制和删除。新增分支从父分支尾点出发,
|
|
79
|
+
同一尾点可创建多个同级分支:
|
|
172
80
|
|
|
173
81
|
```ts
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
]);
|
|
82
|
+
import { LineTree, createLineTreeTopology, addLineTreeBranchAtTail } from "@fulate/ui";
|
|
83
|
+
|
|
84
|
+
const topology = createLineTreeTopology([{ x: 0, y: 0 }, { x: 120, y: 0 }]);
|
|
178
85
|
const tree = new LineTree({ topology });
|
|
179
|
-
const root = topology.branches[0];
|
|
180
86
|
|
|
181
87
|
tree.replaceTopology(addLineTreeBranchAtTail(
|
|
182
88
|
tree.topology,
|
|
183
|
-
|
|
89
|
+
topology.branches[0].subpathId,
|
|
184
90
|
[{ x: 120, y: 80 }]
|
|
185
91
|
).topology);
|
|
186
92
|
```
|
|
187
93
|
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
changed records及必要外层数组。新增branch只复用parent branch的尾点;Editor交互允许任意branch
|
|
192
|
-
tail成为source,同一junction tail可重复产生sibling branches,但junction不绘制tail三角形。树干segment和中间anchor都不是branch source,也
|
|
193
|
-
不会因扩展操作被插入junction。
|
|
194
|
-
|
|
195
|
-
Line与LineTree的stroke和端点decoration在world空间按固定宽度绘制;自身visual bounds与render
|
|
196
|
-
coverage覆盖同一完整绘制范围,反向近零Transform也不会缩掉dirty coverage。固定world paint padding
|
|
197
|
-
不进入Line/LineTree的selection/resize frame或ancestor content bounds;单选、多选及Group均使用
|
|
198
|
-
effective path geometry计量线的尺寸。hover与active branch highlight复用同一polyline paint,箭头和线段保持同色。
|
|
199
|
-
|
|
200
|
-
Rectangle、Triangle及其他Shape省略`backgroundColor`/`borderColor`时读取当前Root的
|
|
201
|
-
`skin.shapeFill`/`skin.shapeStroke`;Line和LineTree branch省略`strokeColor`时读取
|
|
202
|
-
`skin.lineStroke`。显式值始终优先,Shape的显式`null`关闭绘制,显式字段清回`undefined`后立即重新
|
|
203
|
-
继承Skin。Skin改变只触发现有Root/Layer重绘,不改写element、branch topology或History。
|
|
204
|
-
|
|
205
|
-
LineTree整体resize把全部拓扑点按完整仿射写回 authored topology。随后Point编辑和L分支扩展在
|
|
206
|
-
同一owner change内保留当前world pose;包括反向scale在内,未编辑points保持world位置不变。
|
|
207
|
-
分支选择使用 Core 的 world 距离查询;共享 junction 在各分支 view 中借用同一个 world point。
|
|
208
|
-
仅修改分支颜色或装饰不重建路径 geometry;线宽更新 visual bounds,真实 points/vertices/graph 变化
|
|
209
|
-
才失效对应 geometry。
|
|
210
|
-
|
|
211
|
-
## Text 尺寸与显示
|
|
94
|
+
双击分支进入该分支的点编辑;删除父分支会删除其全部后代分支。
|
|
95
|
+
交互操作见 [Tools 指南](../tools/README.md#点编辑与画线),数据模型见
|
|
96
|
+
[Path/Line 规范](../../docs/specs/path-line-core.md)。
|
|
212
97
|
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
`overflow="visible"` 且不启用省略号;组件若需要 Web 控件式的填满、裁剪或省略,应显式传入对应属性。
|
|
98
|
+
Line 与 LineTree 的线宽和端点装饰按世界坐标绘制,元素自身缩放不缩放线宽。
|
|
99
|
+
选择框、缩放尺寸和 Group 内容范围使用路径几何,不计描边和箭头外扩。
|
|
100
|
+
省略填充、描边或线色时继承 [Root Skin](../core/docs/guides/layers-and-rendering.md#skin)。
|
|
217
101
|
|
|
218
|
-
|
|
219
|
-
`wordWrap={false}`、`overflow="visible"` 的文本被缩放后,取消选择再重新选择仍保持上一次 authored
|
|
220
|
-
尺寸,下一次缩放也从该尺寸继续。
|
|
102
|
+
## Text 尺寸与显示
|
|
221
103
|
|
|
222
|
-
|
|
223
|
-
该范围不改变布局盒或 selection/resize frame。
|
|
104
|
+
未提供 `width`/`height` 时,`Text` 使用文字自然尺寸;提供后作为布局盒。
|
|
224
105
|
|
|
225
|
-
|
|
226
|
-
|
|
106
|
+
| 选项 | 作用 | 默认值 |
|
|
107
|
+
| --- | --- | --- |
|
|
108
|
+
| `wordWrap` | 按布局宽度换行 | `false` |
|
|
109
|
+
| `ellipsis` | 将截断内容显示为省略号 | `false` |
|
|
110
|
+
| `overflow` | 控制内容裁剪 | `"visible"` |
|
|
227
111
|
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
属性或 History。字体加载与影响文字排版或视觉边界的 Skin 字段变化先捕获旧像素范围,再失效相应缓存
|
|
231
|
-
与祖先边界;颜色变化复用已有布局。Skin 的全层重绘同时覆盖读取 live Skin 的自定义 Shape。
|
|
112
|
+
三者可以独立组合。编辑器选择和缩放使用布局盒,即使文字绘制超出该盒,也不改变选择尺寸。
|
|
113
|
+
`Span` 使用 Yoga 计算后的尺寸约束文字。
|
|
232
114
|
|
|
233
115
|
### 原生 Canvas 文本 run
|
|
234
116
|
|
|
235
|
-
|
|
236
|
-
和字符间距语义测量一段文本,不需要复制或整理 style:
|
|
117
|
+
自定义 Shape 可使用与 Text 相同的字体和基线规则测量文本:
|
|
237
118
|
|
|
238
119
|
```ts
|
|
239
120
|
import { measureTextRun } from "@fulate/ui";
|
|
@@ -241,77 +122,78 @@ import { measureTextRun } from "@fulate/ui";
|
|
|
241
122
|
const metrics = measureTextRun(ctx, text, root.skin.text, 14, 500);
|
|
242
123
|
```
|
|
243
124
|
|
|
244
|
-
|
|
245
|
-
`
|
|
246
|
-
`
|
|
247
|
-
是同一行框内的规范 alphabetic baseline,因此不同字号的 run 可以直接对齐。空文本的 `width`
|
|
248
|
-
为 `0`,但仍测量一个空格以取得稳定字体度量。函数会把本次测量所需的文字状态写入 `ctx`,不会
|
|
249
|
-
调用 `save()` 或 `restore()`;Canvas 生命周期以及业务特有的文字顺序、对齐和绘制仍由 Shape
|
|
250
|
-
自己拥有。
|
|
125
|
+
返回 `font`、`width`、`lineHeight`、`drawY`、`alphabeticBaseline`、
|
|
126
|
+
`textBaseline` 和 `letterSpacing`。不同字号可按 `alphabeticBaseline` 对齐。
|
|
127
|
+
函数会修改 ctx 的文字状态,调用方负责 `save()`/`restore()` 和实际绘制。
|
|
251
128
|
|
|
252
129
|
### 组合型多行文本
|
|
253
130
|
|
|
254
|
-
|
|
255
|
-
共用同一份 hard-break、grapheme、`wordWrap`、`maxLines` 和 `ellipsis` 排版实现:
|
|
131
|
+
在非 Text 元素中绘制可换行文字时,使用 `TextBlock`:
|
|
256
132
|
|
|
257
133
|
```ts
|
|
258
|
-
import {
|
|
259
|
-
TextBlock,
|
|
260
|
-
getTextBlockVisualBounds,
|
|
261
|
-
paintTextBlock,
|
|
262
|
-
resolveTextStyle
|
|
263
|
-
} from "@fulate/ui";
|
|
134
|
+
import { TextBlock, getTextBlockVisualBounds, paintTextBlock, resolveTextStyle } from "@fulate/ui";
|
|
264
135
|
|
|
265
136
|
const style = resolveTextStyle(
|
|
266
|
-
{
|
|
267
|
-
fontSize: 14,
|
|
268
|
-
fontWeight: 500,
|
|
269
|
-
textAlign: "left",
|
|
270
|
-
textBaseline: "top",
|
|
271
|
-
verticalAlign: "top",
|
|
272
|
-
wordWrap: true
|
|
273
|
-
},
|
|
137
|
+
{ fontSize: 14, fontWeight: 500, textAlign: "left", textBaseline: "top", verticalAlign: "top", wordWrap: true },
|
|
274
138
|
root.skin.text
|
|
275
139
|
);
|
|
276
140
|
const block = new TextBlock();
|
|
277
141
|
const snapshot = block.sync({
|
|
278
|
-
text,
|
|
279
|
-
|
|
280
|
-
width: 120,
|
|
281
|
-
height: 80,
|
|
282
|
-
overflow: "visible",
|
|
283
|
-
wordWrap: true,
|
|
284
|
-
ellipsis: false
|
|
142
|
+
text, style, width: 120, height: 80,
|
|
143
|
+
overflow: "visible", wordWrap: true, ellipsis: false
|
|
285
144
|
});
|
|
286
145
|
|
|
287
146
|
paintTextBlock(ctx, snapshot, style, 120, 80);
|
|
288
147
|
const visualBounds = getTextBlockVisualBounds(snapshot, style, 120, 80);
|
|
289
148
|
```
|
|
290
149
|
|
|
291
|
-
`measure()
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
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`,可分别关闭。自动聚焦不播放动画,并会避开标尺等占用的可见区域。
|
|
297
173
|
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
174
|
+
手动聚焦:
|
|
175
|
+
|
|
176
|
+
```ts
|
|
177
|
+
import { fitWorkspace } from "@fulate/ui";
|
|
178
|
+
|
|
179
|
+
await fitWorkspace(workspace, { padding: 0 });
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
手动调用不受上述两个开关限制;需要动画时显式传入 `animate`。
|
|
183
|
+
|
|
184
|
+
## 浮层定位
|
|
185
|
+
|
|
186
|
+
`computePosition()` 基于当前几何计算位置,调用前先 `await root.nextTick()`。
|
|
187
|
+
返回的 `x/y` 已转换为浮层父空间的 `left/top`,可直接传给 `setOptions()`;
|
|
188
|
+
Floating UI 的尺寸、偏移与 `middlewareData` 使用世界坐标。
|
|
302
189
|
|
|
303
190
|
## Editor capabilities
|
|
304
191
|
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
Selection 的闭集策略使用公开枚举:
|
|
192
|
+
自定义元素通过 Selection、Transform、Snap、Point、Content capability 接入编辑器。
|
|
193
|
+
例如选择策略使用公开枚举:
|
|
308
194
|
|
|
309
195
|
```ts
|
|
310
|
-
import {
|
|
311
|
-
SelectionBehaviorMode,
|
|
312
|
-
SelectionDiveMode,
|
|
313
|
-
SelectionSnapMode
|
|
314
|
-
} from "@fulate/ui";
|
|
196
|
+
import { SelectionBehaviorMode, SelectionDiveMode, SelectionSnapMode } from "@fulate/ui";
|
|
315
197
|
|
|
316
198
|
const behavior = {
|
|
317
199
|
mode: SelectionBehaviorMode.OwnerDirect,
|
|
@@ -320,16 +202,18 @@ const behavior = {
|
|
|
320
202
|
};
|
|
321
203
|
```
|
|
322
204
|
|
|
323
|
-
`OwnerDirect`
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
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/index.d.ts
CHANGED
|
@@ -49,3 +49,5 @@ export type { LineDecoration, LineEndpointRelationPatch, LineEndpointUpdate, Lin
|
|
|
49
49
|
export * from "./line/geometry";
|
|
50
50
|
export * from "./line/orthogonal";
|
|
51
51
|
export { resolveOrthogonalEndpoint } from "./line/base";
|
|
52
|
+
export { elementV2Codecs } from "./serialization";
|
|
53
|
+
export type { LineV2 } from "./serialization";
|
package/dist/index.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { clearCache, layout, layoutNextLine, layoutNextLineRange, layoutWithLines, materializeLineRange, measureLineStats, measureNaturalWidth, prepareWithSegments } from "@chenglou/pretext";
|
|
2
|
-
import { ChangeImpact, CustomEvent, Element, ElementProperties, ElementTransform, SKIN_DEFAULTS, Shape, ShapeProperties, ShapeTransform, VectorPath, VectorPathProperties, VectorPathTransform, appendAuthoredLineAnchor, captureElementTransformReference, createAuthoredLineSubpath, createGeometrySnapshot, createLineSubpath, createPathLocalId, evaluatePathSegmentPoint, getAuthoredAnchorBounds, getAuthoredPathLayoutBounds, getElementConnectionPortPoint, insertAuthoredPathAnchor, isReparentTransformIntent, mergeOwnerPropertyChanges, removeAuthoredAnchor, replaceAuthoredAnchorPoint, replaceAuthoredCubicHandle, resolveAuthoredGeometryFramePatch, resolveAuthoredSubpath, resolveReferenceBoundsTranslation, resolveReferenceTransform, transformAuthoredSubpath } from "@fulate/core";
|
|
2
|
+
import { ChangeImpact, CustomEvent, Element, ElementProperties, ElementTransform, SKIN_DEFAULTS, Shape, ShapeProperties, ShapeTransform, VectorPath, VectorPathProperties, VectorPathTransform, appendAuthoredLineAnchor, captureElementTransformReference, coreElementV2Codecs, createAuthoredLineSubpath, createGeometrySnapshot, createLineSubpath, createPathLocalId, evaluatePathSegmentPoint, getAuthoredAnchorBounds, getAuthoredPathLayoutBounds, getElementConnectionPortPoint, insertAuthoredPathAnchor, isReparentTransformIntent, mergeOwnerPropertyChanges, removeAuthoredAnchor, replaceAuthoredAnchorPoint, replaceAuthoredCubicHandle, resolveAuthoredGeometryFramePatch, resolveAuthoredSubpath, resolveReferenceBoundsTranslation, resolveReferenceTransform, transformAuthoredSubpath } from "@fulate/core";
|
|
3
3
|
import { clamp, has, isFunction, isNil, isNull, isString, isUndefined, last } from "lodash-es";
|
|
4
4
|
import { Bound, Intersection, Matrix2D, createCanvasGradient, createPointView, isGradient, isPointWithinDistance, projectBounds, rectEdgePosition, transformPoint } from "@fulate/share";
|
|
5
5
|
import { computePosition as computePosition$1, flip, offset, shift } from "@floating-ui/core";
|
|
@@ -7364,4 +7364,113 @@ function applyLineTreeTopologyDelta(topology, delta, direction) {
|
|
|
7364
7364
|
};
|
|
7365
7365
|
}
|
|
7366
7366
|
//#endregion
|
|
7367
|
-
|
|
7367
|
+
//#region packages/ui/src/line/serialization.ts
|
|
7368
|
+
function encodeLine(element, context) {
|
|
7369
|
+
const line = element;
|
|
7370
|
+
const data = line.toJSON();
|
|
7371
|
+
if (!context || !line.headRelation && !line.tailRelation) return data;
|
|
7372
|
+
const vertices = line.getEffectiveLineVerticesView();
|
|
7373
|
+
let headPoint, tailPoint;
|
|
7374
|
+
const relations = { ...data.relations };
|
|
7375
|
+
for (const end of ["head", "tail"]) {
|
|
7376
|
+
const relation = line[end === "head" ? "headRelation" : "tailRelation"];
|
|
7377
|
+
if (!relation || context.sourceKeys.has(relation.target.elementKey)) continue;
|
|
7378
|
+
const point = end === "head" ? vertices[0].point : vertices[vertices.length - 1].point;
|
|
7379
|
+
const copied = {
|
|
7380
|
+
x: point.x,
|
|
7381
|
+
y: point.y
|
|
7382
|
+
};
|
|
7383
|
+
if (end === "head") headPoint = copied;
|
|
7384
|
+
else tailPoint = copied;
|
|
7385
|
+
delete relations[end];
|
|
7386
|
+
}
|
|
7387
|
+
const geometry = materializeEffectiveEndpointPoints(data.geometry, headPoint, tailPoint);
|
|
7388
|
+
if (geometry !== data.geometry) Object.assign(data, line.resolvePointGeometryPatch(geometry));
|
|
7389
|
+
if (relations.head || relations.tail) data.relations = relations;
|
|
7390
|
+
else delete data.relations;
|
|
7391
|
+
return data;
|
|
7392
|
+
}
|
|
7393
|
+
var lineCodec = {
|
|
7394
|
+
encode: encodeLine,
|
|
7395
|
+
decode(data, keyMap) {
|
|
7396
|
+
const { type, ...properties } = data;
|
|
7397
|
+
if (keyMap && properties.relations) {
|
|
7398
|
+
const remap = (relation) => relation && {
|
|
7399
|
+
...relation,
|
|
7400
|
+
target: {
|
|
7401
|
+
...relation.target,
|
|
7402
|
+
elementKey: keyMap.get(relation.target.elementKey)
|
|
7403
|
+
}
|
|
7404
|
+
};
|
|
7405
|
+
properties.relations = {
|
|
7406
|
+
head: remap(properties.relations.head),
|
|
7407
|
+
tail: remap(properties.relations.tail)
|
|
7408
|
+
};
|
|
7409
|
+
}
|
|
7410
|
+
return new Line(properties);
|
|
7411
|
+
}
|
|
7412
|
+
};
|
|
7413
|
+
//#endregion
|
|
7414
|
+
//#region packages/ui/src/line-tree/serialization.ts
|
|
7415
|
+
var lineTreeCodec = {
|
|
7416
|
+
encode(element, context) {
|
|
7417
|
+
const tree = element;
|
|
7418
|
+
const data = tree.toJSON();
|
|
7419
|
+
if (context) {
|
|
7420
|
+
const topology = data.topology;
|
|
7421
|
+
let changed = false;
|
|
7422
|
+
const points = topology.points.map((point) => {
|
|
7423
|
+
if (!point.relation || context.sourceKeys.has(point.relation.target.elementKey)) return point;
|
|
7424
|
+
changed = true;
|
|
7425
|
+
const { relation, ...anchor } = point;
|
|
7426
|
+
const effective = tree.transform.getResolvedPoint(point.anchorId).point;
|
|
7427
|
+
return {
|
|
7428
|
+
...anchor,
|
|
7429
|
+
point: {
|
|
7430
|
+
x: effective.x,
|
|
7431
|
+
y: effective.y
|
|
7432
|
+
}
|
|
7433
|
+
};
|
|
7434
|
+
});
|
|
7435
|
+
if (changed) Object.assign(data, tree.resolvePointTopologyPatch({
|
|
7436
|
+
...topology,
|
|
7437
|
+
points
|
|
7438
|
+
}));
|
|
7439
|
+
}
|
|
7440
|
+
return data;
|
|
7441
|
+
},
|
|
7442
|
+
decode({ type, ...properties }, keyMap) {
|
|
7443
|
+
if (keyMap) properties.topology = remapLineTreeRelations(properties.topology, keyMap);
|
|
7444
|
+
return new LineTree(properties);
|
|
7445
|
+
}
|
|
7446
|
+
};
|
|
7447
|
+
//#endregion
|
|
7448
|
+
//#region packages/ui/src/serialization.ts
|
|
7449
|
+
function codec(Constructor) {
|
|
7450
|
+
return {
|
|
7451
|
+
encode: (element) => element.toJSON(),
|
|
7452
|
+
decode: ({ type, ...properties }) => new Constructor(properties)
|
|
7453
|
+
};
|
|
7454
|
+
}
|
|
7455
|
+
function createCodecs() {
|
|
7456
|
+
return new Map([
|
|
7457
|
+
...coreElementV2Codecs,
|
|
7458
|
+
["rectangle", codec(Rectangle)],
|
|
7459
|
+
["circle", codec(Circle)],
|
|
7460
|
+
["triangle", codec(Triangle)],
|
|
7461
|
+
["polygon", codec(Polygon)],
|
|
7462
|
+
["vectorPath", codec(EditorVectorPath)],
|
|
7463
|
+
["text", codec(Text)],
|
|
7464
|
+
["image", codec(Image)],
|
|
7465
|
+
["workspace", codec(Workspace)],
|
|
7466
|
+
["group", codec(Group)],
|
|
7467
|
+
["scrollview", codec(ScrollView)],
|
|
7468
|
+
["line", lineCodec],
|
|
7469
|
+
["lineTree", lineTreeCodec],
|
|
7470
|
+
["ripple", codec(RippleOverlay)]
|
|
7471
|
+
]);
|
|
7472
|
+
}
|
|
7473
|
+
/** Compose extensions with this map at the application boundary; keys are exact DTO types. */
|
|
7474
|
+
var elementV2Codecs = /* @__PURE__ */ createCodecs();
|
|
7475
|
+
//#endregion
|
|
7476
|
+
export { BaseLine, Bitmap, Circle, CircleTransform, ContentEditingCapabilityToken, DEFAULT_LINE_TREE_BRANCH_STYLE, DEFAULT_ORTHOGONAL_MARGIN, EMPTY_LINE_TREE_TOPOLOGY, EditorElementProperties, EditorFrameFlush, EditorShapeProperties, EditorVectorPath, EditorVectorPathProperties, EditorVectorPathTransform, EndpointRelationIndex, Group, GroupTransform, Image, ImageProperties, Line, LineTransform, LineTree, LineTreeProperties, LineTreeTransform, PointEditingCapabilityToken, Polygon, PolygonTransform, Rectangle, RectangleProperties, RectangleTransform, RippleOverlay, SCROLLBAR_DEFAULTS, ScrollView, ScrollViewTransform, Scrollbars, SelectionBehaviorCapabilityToken, SelectionBehaviorMode, SelectionDiveMode, SelectionSnapMode, SnapSourceCapabilityToken, Text, TextBlock, TextProperties, TextTransform, TransformInteractionCapabilityToken, Triangle, TriangleTransform, WorkerSurfacePool, Workspace, WorkspaceProperties, addLineTreeBranchAtTail, applyLineTreeTopologyDelta, computePosition, connectEndpoint, connectionPortAccepts, createLineTreeTopology, createLineTreeTopologyDelta, createManualLineGeometry, createOrthogonalLineGeometry, defineEditorCapability, disconnectEndpoint, elementV2Codecs, fitWorkspace, flip, getEditorCapability, getEditorFrameFlush, getEndpointRelationIndex, getLineAnchors, getLineGeometryBounds, getLineTreeBranch, getLineTreeJunctionAnchorIds, getLineTreePoint, getLineTreePointReferenceCounts, getTextBlockVisualBounds, hasConnectionPortCapacity, hasLineCoordinateChange, hasLineGeometryChange, hasLineTreeTopologyChange, insertLineTreePoint, isEditorCapabilityHost, isEndpointRelationSource, materializeEffectiveEndpointPoints, measureTextRun, measureTextWidth, moveLineTreePoint, offset, paintTextBlock, quantizeOrthogonalDirection, remapLineTreeRelations, removeLineTreeBranch, removeLineTreePoint, replaceLineAnchorPoint, resolveConnectEndpointChange, resolveConnectionPortChanges, resolveDisconnectEndpointChanges, resolveGroupMemberBounds, resolveOrthogonalEndpoint, resolveOrthogonalWaypoint, resolveSelectionFrameBounds, resolveTextStyle, routeOrthogonal, shift, simplifyOrthogonalRoute, subscribeTextMeasurementChanges, transformLineGeometry, transformLineTreeTopology, updateLineTreeBranchStyle, workspaceFocusInsetsKey };
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
import type { ElementPayload, ElementV2Codec } from "@fulate/core";
|
|
2
|
+
import type { LineGeometry } from "./geometry";
|
|
3
|
+
import type { LineEndpointRelationPatch } from "./base";
|
|
4
|
+
export interface LineV2 extends ElementPayload {
|
|
5
|
+
readonly type: "line";
|
|
6
|
+
geometry: LineGeometry;
|
|
7
|
+
/** Horizontal label fixed at half the effective route length. */
|
|
8
|
+
text?: string;
|
|
9
|
+
relations?: LineEndpointRelationPatch;
|
|
10
|
+
}
|
|
11
|
+
export declare const lineCodec: ElementV2Codec;
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@fulate/ui",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "3.0.2",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"main": "./dist/index.js",
|
|
6
6
|
"types": "./dist/index.d.ts",
|
|
@@ -25,8 +25,8 @@
|
|
|
25
25
|
"dependencies": {
|
|
26
26
|
"@chenglou/pretext": "0.0.8",
|
|
27
27
|
"@floating-ui/core": "^1.8.0",
|
|
28
|
-
"@fulate/core": "
|
|
29
|
-
"@fulate/share": "
|
|
28
|
+
"@fulate/core": "3.0.2",
|
|
29
|
+
"@fulate/share": "3.0.2",
|
|
30
30
|
"@tweenjs/tween.js": "^25.0.0",
|
|
31
31
|
"lodash-es": "^4.17.22"
|
|
32
32
|
}
|