@fulate/core 1.0.19 → 2.0.11
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/dist/event.d.ts +62 -37
- package/dist/export-png.d.ts +22 -0
- package/dist/geometry/authored.d.ts +4 -2
- package/dist/geometry/common.d.ts +15 -6
- package/dist/geometry/index.d.ts +6 -1
- package/dist/geometry/path.d.ts +41 -0
- package/dist/index.d.ts +16 -9
- package/dist/index.js +1828 -1457
- package/dist/layer/index.d.ts +33 -32
- package/dist/mutation/change-batch.d.ts +5 -5
- package/dist/node/element-transform-geometry.d.ts +1 -3
- package/dist/node/element-transform.d.ts +80 -42
- package/dist/node/element.d.ts +89 -72
- package/dist/node/node.d.ts +59 -27
- package/dist/node/properties.d.ts +18 -28
- package/dist/node/reference-transform.d.ts +6 -2
- package/dist/node/shape.d.ts +9 -8
- package/dist/node/vector-path.d.ts +34 -0
- package/dist/paint-context.d.ts +30 -0
- package/dist/root/frame-runtime.d.ts +43 -33
- package/dist/root/hit-test.d.ts +2 -4
- package/dist/root/index.d.ts +21 -31
- package/dist/root/input-controller.d.ts +34 -6
- package/dist/root/scene-registry.d.ts +17 -7
- package/dist/root/viewport.d.ts +20 -7
- package/dist/skin.d.ts +1 -1
- package/dist/utils/connection-port.d.ts +1 -8
- package/package.json +30 -30
package/dist/node/element.d.ts
CHANGED
|
@@ -1,18 +1,20 @@
|
|
|
1
|
+
import { type PaintContext } from "../paint-context";
|
|
2
|
+
import { type PNGExportOptions, type PNGExportResult } from "../export-png";
|
|
1
3
|
import type { Edge, PointView, Rect } from "@fulate/share";
|
|
2
4
|
import { type EventOptionKey, type FulateEvent } from "../event";
|
|
3
5
|
import { Node } from "./node";
|
|
4
6
|
import { ElementTransform, type ElementTransformClass } from "./element-transform";
|
|
5
7
|
import { ChangeImpact, TransformProperties, type PropertyChanges, type PreparedPropertyUpdate, type TransformableOptions } from "./properties";
|
|
6
8
|
import { Tween } from "@tweenjs/tween.js";
|
|
7
|
-
import type { ConnectionPortConfiguration, ConnectionPortGeometry,
|
|
9
|
+
import type { ConnectionPortConfiguration, ConnectionPortGeometry, ResolvedConnectionPort, ResolvedConnectionPortSlot } from "../utils/connection-port";
|
|
8
10
|
import type { Root } from "../root";
|
|
9
11
|
import type { Layer } from "../layer";
|
|
10
12
|
import type { OwnerPropertyChange } from "../mutation/change-batch";
|
|
11
13
|
type ElementEventOptions<T> = {
|
|
12
|
-
[K in EventOptionKey]?: (this: T, event: FulateEvent<T>) => any;
|
|
14
|
+
[K in EventOptionKey]?: (this: T, event: FulateEvent<K extends `on${string}Capture` ? AnyElement : T>) => any;
|
|
13
15
|
};
|
|
14
16
|
/** 任意 Properties 和 Options 的 Element。 */
|
|
15
|
-
export type AnyElement = Element<any, any, any>;
|
|
17
|
+
export type AnyElement = Element<any, any, any, any>;
|
|
16
18
|
/** 所有 Element 共用的构造选项。 */
|
|
17
19
|
export interface BaseElementOption<T = Element> extends TransformableOptions, ElementEventOptions<T> {
|
|
18
20
|
/** hover 时写入 Root 容器的 CSS cursor。 */
|
|
@@ -32,32 +34,27 @@ export interface BaseElementOption<T = Element> extends TransformableOptions, El
|
|
|
32
34
|
/** 初始 children。 */
|
|
33
35
|
children?: readonly AnyElement[];
|
|
34
36
|
}
|
|
35
|
-
/** `setOptions()`
|
|
37
|
+
/** `setOptions()` 接受的 configured 属性补丁。 */
|
|
36
38
|
export type ElementOptionPatch<O extends BaseElementOption<any> = BaseElementOption> = Partial<Omit<O, "key" | "children">>;
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
}[keyof O];
|
|
40
|
-
/** Element 的可序列化属性和递归 children。 */
|
|
41
|
-
export type ElementJSON<O extends BaseElementOption<any> = BaseElementOption<any>> = Omit<O, "children" | "key" | "type" | EventHandlerKey<O>> & {
|
|
42
|
-
/** 构造时确定并由 serializer 显式写出的节点 key。 */
|
|
39
|
+
/** One element's independent authored payload. Scene codecs own child recursion. */
|
|
40
|
+
export interface ElementPayload {
|
|
43
41
|
readonly key: string;
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
children?: ElementJSON[];
|
|
48
|
-
};
|
|
42
|
+
readonly type: string;
|
|
43
|
+
[property: string]: unknown;
|
|
44
|
+
}
|
|
49
45
|
/** @internal Core publisher 在零写入阶段完成的 owner commit 数据。 */
|
|
50
46
|
export interface PreparedElementPropertyCommit {
|
|
51
47
|
readonly update: PreparedPropertyUpdate;
|
|
52
48
|
readonly impact: ChangeImpact;
|
|
53
|
-
readonly previousVisualBounds: Readonly<import("@fulate/share").BoundingBox> | null | undefined;
|
|
54
49
|
}
|
|
55
50
|
export { ChangeImpact } from "./properties";
|
|
56
51
|
/** `animate()` 的 Tween 选项。 */
|
|
57
52
|
export interface AnimateOptions<T = any> {
|
|
58
53
|
/** 持续时间,单位为毫秒,默认 `300`。 */
|
|
59
54
|
duration?: number;
|
|
60
|
-
/**
|
|
55
|
+
/**
|
|
56
|
+
* 只根据进度返回缓动结果;不提交场景或改变动画任务。
|
|
57
|
+
*/
|
|
61
58
|
easing?: (amount: number) => number;
|
|
62
59
|
/** 延迟时间,单位为毫秒,默认 `0`。 */
|
|
63
60
|
delay?: number;
|
|
@@ -65,12 +62,19 @@ export interface AnimateOptions<T = any> {
|
|
|
65
62
|
repeat?: number;
|
|
66
63
|
/** 重复时是否反向播放,默认 `false`。 */
|
|
67
64
|
yoyo?: boolean;
|
|
68
|
-
/**
|
|
65
|
+
/**
|
|
66
|
+
* 动画正常完成后的 R0 业务回调,可从当前状态发起下一合法操作。
|
|
67
|
+
*/
|
|
69
68
|
onComplete?: (v: T) => void;
|
|
70
|
-
/**
|
|
69
|
+
/**
|
|
70
|
+
* 每次配置属性提交后的 R0 业务回调,可按动画 API 停止/完成当前任务。
|
|
71
|
+
*/
|
|
71
72
|
onUpdate?: (v: T) => void;
|
|
72
73
|
}
|
|
73
|
-
|
|
74
|
+
type RuntimePropertyKeys<Patch> = {
|
|
75
|
+
[K in keyof Patch]-?: [Required<Patch>[K]] extends [never] ? never : K;
|
|
76
|
+
}[keyof Patch];
|
|
77
|
+
/** 从允许的属性输入中选出可动画的数值与颜色字段,保留显式禁用字段的 never 约束。 */
|
|
74
78
|
export type AnimateTarget<O> = {
|
|
75
79
|
[K in keyof O as K extends "key" ? never : NonNullable<O[K]> extends number ? K : K extends string ? Lowercase<K> extends `${string}color${string}` ? K : never : never]?: NonNullable<O[K]> extends number ? Extract<O[K], number> : O[K];
|
|
76
80
|
};
|
|
@@ -98,8 +102,8 @@ export declare class ElementProperties extends TransformProperties {
|
|
|
98
102
|
/** @internal 合并显示、输入和事件属性的提交影响。 */
|
|
99
103
|
getImpact(changes: PropertyChanges): ChangeImpact;
|
|
100
104
|
}
|
|
101
|
-
/**
|
|
102
|
-
export declare class Element<P extends ElementProperties = ElementProperties, O extends BaseElementOption<any> = BaseElementOption<any>, Patch extends object = ElementOptionPatch<O
|
|
105
|
+
/** 可变换、可绘制、可命中并支持事件和动画的场景节点。属性 writer 在 R0 安装输入。 */
|
|
106
|
+
export declare class Element<P extends ElementProperties = ElementProperties, O extends BaseElementOption<any> = BaseElementOption<any>, Patch extends object = ElementOptionPatch<O>, RuntimePatch extends object = Patch> extends Node<P, AnyElement> {
|
|
103
107
|
readonly type: string;
|
|
104
108
|
/** 当前 Element 唯一的变换与几何运行时。 */
|
|
105
109
|
readonly transform: ElementTransform<this>;
|
|
@@ -135,22 +139,12 @@ export declare class Element<P extends ElementProperties = ElementProperties, O
|
|
|
135
139
|
get originX(): import("./properties").OriginX;
|
|
136
140
|
/** y 方向变换原点。 */
|
|
137
141
|
get originY(): import("./properties").OriginY;
|
|
138
|
-
/** Editor 旋转中心的 x 轴位置。 */
|
|
139
|
-
get rotationPivotX(): import("./properties").OriginX;
|
|
140
|
-
/** Editor 旋转中心的 y 轴位置。 */
|
|
141
|
-
get rotationPivotY(): import("./properties").OriginY;
|
|
142
142
|
/** 当前已解析宽度。 */
|
|
143
143
|
get width(): number;
|
|
144
144
|
/** 当前已解析高度。 */
|
|
145
145
|
get height(): number;
|
|
146
|
-
/** 未指定宽度时是否匹配 parent 宽度。 */
|
|
147
|
-
get fitWidth(): boolean;
|
|
148
|
-
/** 未指定高度时是否匹配 parent 高度。 */
|
|
149
|
-
get fitHeight(): boolean;
|
|
150
146
|
/** 当前采用的 Port whole-value;`true` 使用默认 schema。 */
|
|
151
147
|
get ports(): ConnectionPortConfiguration;
|
|
152
|
-
/** @internal 订阅实际 Ports authored commit;返回同一 observer 的注销函数。 */
|
|
153
|
-
observePortsCommit(observer: (element: Element) => void): () => void;
|
|
154
148
|
/**
|
|
155
149
|
* 采用 Port whole-value;数组由 Core 直接采用原引用。
|
|
156
150
|
* @param value `false`、`true` 或 custom definitions。
|
|
@@ -163,10 +157,6 @@ export declare class Element<P extends ElementProperties = ElementProperties, O
|
|
|
163
157
|
restorePropertySnapshot(snapshot: Record<string, unknown>): this;
|
|
164
158
|
/** 首次创建动画时才安装的未结束任务集合。 */
|
|
165
159
|
private activeAnimations?;
|
|
166
|
-
/** 首次出现 `on*` handler 时才安装的监听 wrapper 映射。 */
|
|
167
|
-
private optionEventWrappers?;
|
|
168
|
-
/** 只在真实 dependent 存在时创建的内部 Ports commit observers。 */
|
|
169
|
-
private portsCommitObservers?;
|
|
170
160
|
private connectionPortProjectionReady;
|
|
171
161
|
private connectionPortProjectionSource;
|
|
172
162
|
private connectionPortProjectionRevision;
|
|
@@ -174,76 +164,99 @@ export declare class Element<P extends ElementProperties = ElementProperties, O
|
|
|
174
164
|
private connectionPortSlots;
|
|
175
165
|
/** 创建带显示、输入、锚点和可选 children 的元素。 */
|
|
176
166
|
constructor(options?: NoInfer<O>, properties?: P, Transform?: ElementTransformClass);
|
|
177
|
-
/** raw parent link
|
|
178
|
-
protected
|
|
179
|
-
/** raw
|
|
180
|
-
|
|
181
|
-
/** raw children
|
|
182
|
-
protected
|
|
167
|
+
/** raw parent link 安装后登记当前路径的 transform 失效。 */
|
|
168
|
+
protected onParentInstalled(_previousParent?: Node): void;
|
|
169
|
+
/** @internal raw placement 改变前保留当前场景中的旧贡献。 */
|
|
170
|
+
captureBeforeDetach(): void;
|
|
171
|
+
/** raw children 安装后同步 Transform 派生输入与 dirty。 */
|
|
172
|
+
protected onChildrenInstalled(): void;
|
|
183
173
|
/** 激活时将未结束动画接入当前 Root。 */
|
|
184
174
|
protected onActivate(root: Root | null, layer: Layer | null): void;
|
|
185
175
|
/** 停用时从 Root 解除动画并结束未恢复的会话。 */
|
|
186
176
|
protected onDeactivate(root: Root | null, layer: Layer | null): void;
|
|
187
177
|
/** 卸载时停止当前元素的全部动画。 */
|
|
188
178
|
protected onUnmount(): void;
|
|
189
|
-
/**
|
|
179
|
+
/**
|
|
180
|
+
* 从最终 typed patch 纯计算不可省略的语义转换;每次提交只解释一次。
|
|
181
|
+
* 此时 live state 尚未安装最终值;不能在解释中提交属性、改树或调用应用。
|
|
182
|
+
*/
|
|
190
183
|
protected resolveOptions(options: Patch): Patch;
|
|
191
184
|
/**
|
|
192
185
|
* 创建只借用 typed patch 的 owner effect;batch 合并完成前不解析或复制值。
|
|
193
186
|
*/
|
|
194
187
|
protected createPropertyChange(options: Patch): OwnerPropertyChange;
|
|
195
|
-
/** @internal 在 live write 前一次完成 changed-key diff
|
|
188
|
+
/** @internal 在 live write 前一次完成 changed-key diff 和 impact。 */
|
|
196
189
|
preparePropertyCommit(patch: Record<string, unknown>): PreparedElementPropertyCommit | null;
|
|
197
190
|
/** 把 source/effective changed-key delta finalize 为 direct/batch 共用记录。 */
|
|
198
191
|
private finalizePropertyUpdate;
|
|
199
|
-
/** @internal
|
|
192
|
+
/** @internal 全部 final delta 已确定、任何字段与结构链接安装前捕获一次旧贡献。 */
|
|
193
|
+
capturePropertyCommit(commit: PreparedElementPropertyCommit): void;
|
|
194
|
+
/** @internal 无 callback 地安装 source/effective fields。 */
|
|
200
195
|
installPropertyCommit(commit: PreparedElementPropertyCommit): void;
|
|
201
|
-
/** @internal 在全部 owner/tree 安装后同步 option event
|
|
196
|
+
/** @internal 在全部 owner/tree 安装后同步 option event listener。 */
|
|
202
197
|
syncPropertyCommitEvents(commit: PreparedElementPropertyCommit): void;
|
|
203
198
|
/** @internal 在全部 owner/tree 安装及 lifecycle 后运行 owner hook。 */
|
|
204
199
|
runPropertyCommitHook(commit: PreparedElementPropertyCommit): void;
|
|
205
|
-
/** @internal 在 owner hook 后通知依赖实际 Ports commit 的框架消费者。 */
|
|
206
|
-
notifyPortsCommit(commit: PreparedElementPropertyCommit): void;
|
|
207
200
|
/** @internal 在内部 publication 完成后派发 authored `portschange`。 */
|
|
208
201
|
dispatchPortsChange(commit: PreparedElementPropertyCommit): void;
|
|
209
|
-
/** @internal
|
|
210
|
-
|
|
202
|
+
/** @internal 全部字段与链接安装后,先同步派生输入并登记失效;此轮不运行应用回调。 */
|
|
203
|
+
invalidatePropertyCommit(commit: PreparedElementPropertyCommit, publishRootImpact?: boolean): boolean;
|
|
211
204
|
/** 应用一份 direct configured/runtime update 并完成一次成功路径 publication。 */
|
|
212
205
|
private commitPreparedProperty;
|
|
213
|
-
|
|
206
|
+
/** Configured entry shared by setOptions, Port replacement and snapshot restore. */
|
|
207
|
+
protected commitConfiguredOptions(options: Patch): void;
|
|
214
208
|
private prepareRuntimeCommit;
|
|
215
|
-
/**
|
|
209
|
+
/** 将实际 changed keys 同步到事件层,复用提交已有的修改前值。 */
|
|
216
210
|
private syncOptionEvents;
|
|
217
|
-
/**
|
|
211
|
+
/**
|
|
212
|
+
* @internal 同步属性所依赖的本地缓存、原生布局输入和订阅。
|
|
213
|
+
* 所有 owner 完成本轮安装后才运行各自的变更 hooks;本接缝不得推进阶段或派发应用回调。
|
|
214
|
+
*/
|
|
215
|
+
protected onPropertiesInstalled(_current: P, _changes: PropertyChanges): void;
|
|
216
|
+
/**
|
|
217
|
+
* R0 消费已安装的 effective 变化,处理本 owner 的领域状态与资源。
|
|
218
|
+
* 需要当前几何时可显式准备;真实领域应用事件按其独立合同执行。
|
|
219
|
+
*/
|
|
218
220
|
protected onPropertiesChanged(_current: P, _changes: PropertyChanges): void;
|
|
219
221
|
/**
|
|
220
222
|
* 作者配置实际变化后的扩展点,在 effective 属性 hook 之后运行。
|
|
221
223
|
* runtime 遮罩不阻止此通知;runtime-only 更新和相同配置不触发。
|
|
222
224
|
* changedKeys 只包含本次实际改变的 configured 字段;通过 configured reader 读取当前值。
|
|
223
|
-
* direct、batch 和 History replay
|
|
225
|
+
* direct、batch 和 History replay 使用同一阶段;可在此更新自身当前数据的 runtime 显示。
|
|
224
226
|
*/
|
|
225
227
|
protected onConfiguredPropertiesChanged?(changedKeys: readonly string[]): void;
|
|
226
228
|
/** 把非 geometry impact 路由到绘制、Layer 顺序和 hover 队列。 */
|
|
227
229
|
private invalidate;
|
|
228
|
-
/**
|
|
230
|
+
/** 返回 local children 裁剪区域。null 表示当前没有裁剪,包括空几何。 */
|
|
229
231
|
getChildClipRect(): Readonly<Rect> | null;
|
|
230
232
|
/** 判断 local 点是否通过当前元素绘制 children 时使用的裁剪。 */
|
|
231
233
|
containsChildClipPoint(point: PointView): boolean;
|
|
232
234
|
/** 将当前元素绘制到给定上下文。 */
|
|
233
|
-
paint(
|
|
235
|
+
paint(paint: PaintContext): void;
|
|
234
236
|
/** 按当前 Layer 提交状态绘制可见 children。 */
|
|
235
|
-
protected paintChildren(
|
|
236
|
-
/**
|
|
237
|
-
protected
|
|
237
|
+
protected paintChildren(paint: PaintContext): void;
|
|
238
|
+
/** 同步内容接缝;Element 内容自行选择 local/world 变换,Shape 已建立 local 变换。 */
|
|
239
|
+
protected paintContent?(paint: PaintContext): void;
|
|
240
|
+
/**
|
|
241
|
+
* 导出当前活动子树;等待已有几何工作,复用当前内容与 bitmap,不等待资源加载或 Worker 新帧。
|
|
242
|
+
* 默认倍率 1、padding 0;未激活、不可见或无绘制区域返回 undefined。
|
|
243
|
+
* signal 取消和绘制/编码错误原样传播。已绘入 Canvas 的像素不再依赖 live 生命周期。
|
|
244
|
+
*/
|
|
245
|
+
exportPNG(options?: PNGExportOptions): Promise<PNGExportResult | undefined>;
|
|
246
|
+
/** @internal 仅应用祖先对子树的裁剪/样式;不绘制祖先或兄弟。 */
|
|
247
|
+
protected applyExportAncestor(paint: PaintContext): void;
|
|
248
|
+
/** @internal 在已准备几何和资源上同步绘制;不交接屏幕像素责任。 */
|
|
249
|
+
paintExport(paint: PaintContext): void;
|
|
238
250
|
/** 使用当前元素的矩形边界裁剪 children。 */
|
|
239
251
|
protected applyChildClip(ctx: CanvasRenderingContext2D): void;
|
|
240
252
|
/** 绘制默认 hover 轮廓。 */
|
|
241
253
|
paintHover(ctx: CanvasRenderingContext2D, scale: number): void;
|
|
242
254
|
/**
|
|
243
|
-
* @internal 把与 `paintHover()`
|
|
244
|
-
*
|
|
255
|
+
* @internal 把与 `paintHover()` 等价的世界坐标轮廓追加到调用方提供的 path。
|
|
256
|
+
* 本方法只追加轮廓;调用方负责合并路径并在 Viewport 变换下统一描边。
|
|
257
|
+
* 返回 `false` 时保持 path 不变,由调用方改用 `paintHover()` 独立绘制。
|
|
245
258
|
*/
|
|
246
|
-
traceHoverOutline(_ctx:
|
|
259
|
+
traceHoverOutline(_ctx: CanvasPath, _scale: number): boolean;
|
|
247
260
|
/** 从当前 live owner 直接解析一次可连接 Ports。 */
|
|
248
261
|
getConnectionPorts(): readonly ResolvedConnectionPort[];
|
|
249
262
|
private resolveCurrentConnectionPortProjection;
|
|
@@ -251,8 +264,10 @@ export declare class Element<P extends ElementProperties = ElementProperties, O
|
|
|
251
264
|
getConnectionPort(portId: string): ResolvedConnectionPort | undefined;
|
|
252
265
|
/** @internal 只解释显式 Port replacement 的 IDs;patch 是同批最终 owner fields。 */
|
|
253
266
|
resolveConnectionPortIds(ports: ConnectionPortConfiguration, patch?: Readonly<Record<string, unknown>>): readonly string[];
|
|
254
|
-
/**
|
|
255
|
-
protected
|
|
267
|
+
/** 列出类型自有的默认 Port IDs;patch 是同批最终 owner fields。 */
|
|
268
|
+
protected getDefaultConnectionPortIds(_patch?: Readonly<Record<string, unknown>>): readonly string[];
|
|
269
|
+
/** 从 live geometry 纯计算一个默认 Port;不存在的 ID 返回 undefined。 */
|
|
270
|
+
protected getDefaultConnectionPortGeometry(portId: string): Pick<ResolvedConnectionPort, "localPosition" | "localNormal"> | undefined;
|
|
256
271
|
/** 返回 custom Ports 的当前 decoration slots。 @internal */
|
|
257
272
|
getResolvedConnectionPortSlots(): readonly ResolvedConnectionPortSlot[];
|
|
258
273
|
/**
|
|
@@ -268,14 +283,14 @@ export declare class Element<P extends ElementProperties = ElementProperties, O
|
|
|
268
283
|
* 读取包含默认值的 configured 结果,不读取 runtime 覆盖;保留 null/undefined。
|
|
269
284
|
* cells 可复用;借用值不得原地修改并期待自动提交,需要独立值时由 caller 复制。
|
|
270
285
|
*/
|
|
271
|
-
static readConfiguredPropertyValues(owner:
|
|
286
|
+
static readConfiguredPropertyValues(owner: AnyElement, targets: ReadonlyMap<string, {
|
|
272
287
|
value: unknown;
|
|
273
288
|
}>): void;
|
|
274
289
|
/**
|
|
275
290
|
* 借用当前字段的 configured/default 值,忽略 runtime 覆盖,保留 null/undefined。
|
|
276
291
|
* 返回结构化原引用,不表示该字段是否曾被显式配置;需要独立值时由 caller 复制。
|
|
277
292
|
*/
|
|
278
|
-
static getConfiguredPropertyValue(owner:
|
|
293
|
+
static getConfiguredPropertyValue(owner: AnyElement, key: string): unknown;
|
|
279
294
|
/**
|
|
280
295
|
* 提交需要持久化的配置属性补丁。
|
|
281
296
|
* @param options 要修改的属性;省略时不修改,字段为 `undefined` 时恢复默认值。
|
|
@@ -287,27 +302,29 @@ export declare class Element<P extends ElementProperties = ElementProperties, O
|
|
|
287
302
|
* @param patch 字段省略时保持现有覆盖;字段为 `undefined` 时清除该字段覆盖。
|
|
288
303
|
* 结构化字段与 configured writer 一样按原引用采用。
|
|
289
304
|
*/
|
|
290
|
-
setRuntimeOptions(patch:
|
|
305
|
+
setRuntimeOptions(patch: RuntimePatch): this;
|
|
291
306
|
/** 显式清除指定或全部运行态属性覆盖。 */
|
|
292
|
-
clearRuntimeOptions<Key extends
|
|
307
|
+
clearRuntimeOptions<Key extends RuntimePropertyKeys<RuntimePatch>>(keys?: readonly Key[]): this;
|
|
293
308
|
/**
|
|
294
309
|
* 在当前 Root 动画组中补间数值和颜色属性。
|
|
295
310
|
* @param to 动画结束时的属性值。
|
|
296
311
|
* 结构化 target 会保留并在更新时采用同一引用,不生成调用方隔离快照。
|
|
297
312
|
* @param options 时长、缓动、重复和回调;省略时使用默认配置。
|
|
298
313
|
*/
|
|
299
|
-
animate(to: AnimateTarget<
|
|
314
|
+
animate(to: AnimateTarget<RuntimePatch>, options?: AnimateOptions<this>): Promise<void> & {
|
|
300
315
|
/** 当前动画使用的底层 Tween。 */
|
|
301
316
|
tween: Tween<any>;
|
|
302
317
|
};
|
|
303
318
|
/** 停止并清除当前元素的全部动画。 */
|
|
304
319
|
stopAnimations(): void;
|
|
305
|
-
/**
|
|
320
|
+
/** 将调用开始时的动画推进到结束状态;完成回调新建的动画继续正常运行。 */
|
|
306
321
|
finishAnimations(): void;
|
|
307
322
|
/** 暂停当前元素的全部动画。 */
|
|
308
323
|
pauseAnimations(): void;
|
|
309
324
|
/** 恢复当前元素的全部动画。 */
|
|
310
325
|
resumeAnimations(): void;
|
|
311
|
-
/**
|
|
312
|
-
|
|
326
|
+
/** The authored children included by scene serialization and clipboard. */
|
|
327
|
+
getPersistentChildren(): readonly AnyElement[];
|
|
328
|
+
/** Return this owner's independent authored payload, excluding events and children. */
|
|
329
|
+
toJSON(): ElementPayload;
|
|
313
330
|
}
|
package/dist/node/node.d.ts
CHANGED
|
@@ -7,6 +7,8 @@ export interface NodeCreationOptions {
|
|
|
7
7
|
/** 场景内唯一 key;省略时由 Core 自动生成。 */
|
|
8
8
|
readonly key?: string;
|
|
9
9
|
}
|
|
10
|
+
/** Node 与离线场景 producer 共用的唯一 key 生成器。 */
|
|
11
|
+
export declare function generateNodeKey(): string;
|
|
10
12
|
/**
|
|
11
13
|
* @internal 按同一棵树的 preorder 比较两个节点;祖先排在后代之前。只沿两条 parent 链走到
|
|
12
14
|
* 最近公共祖先,比较其下两个 child 的 sibling 标签。
|
|
@@ -23,14 +25,29 @@ export declare enum NodeLifecycleEvent {
|
|
|
23
25
|
/** 完成不可逆卸载。 */
|
|
24
26
|
Unmounted = "unmounted"
|
|
25
27
|
}
|
|
26
|
-
|
|
28
|
+
declare module "../event" {
|
|
29
|
+
interface FulateEventMap {
|
|
30
|
+
mounted: CustomEvent<{
|
|
31
|
+
target: Node;
|
|
32
|
+
}>;
|
|
33
|
+
activated: CustomEvent<{
|
|
34
|
+
target: Node;
|
|
35
|
+
}>;
|
|
36
|
+
deactivated: CustomEvent<{
|
|
37
|
+
target: Node;
|
|
38
|
+
}>;
|
|
39
|
+
unmounted: CustomEvent<{
|
|
40
|
+
target: Node;
|
|
41
|
+
}>;
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
/** 提供场景树所有权、生命周期、key 索引和上下文继承。结构与生命周期入口在 R0 执行。 */
|
|
27
45
|
export declare class Node<P extends NodeProperties = NodeProperties, Child extends Node<any, any> = Node<any, any>> extends EventEmitter {
|
|
28
|
-
#private;
|
|
29
46
|
/** 序列化使用的节点类型。 */
|
|
30
47
|
readonly type: string;
|
|
31
|
-
/**
|
|
32
|
-
|
|
33
|
-
/**
|
|
48
|
+
/** Root 场景索引使用的构造期只读节点 key。 */
|
|
49
|
+
readonly key: string;
|
|
50
|
+
/** 当前由节点拥有的唯一属性状态,字段读取 effective 值。 */
|
|
34
51
|
protected readonly propertyState: P;
|
|
35
52
|
/** 当前属性的只读视图。 */
|
|
36
53
|
get properties(): Readonly<P>;
|
|
@@ -40,8 +57,8 @@ export declare class Node<P extends NodeProperties = NodeProperties, Child exten
|
|
|
40
57
|
private childNodes;
|
|
41
58
|
/** 当前稳定生命周期状态。 */
|
|
42
59
|
private lifecycleState;
|
|
43
|
-
/**
|
|
44
|
-
private
|
|
60
|
+
/** 不可逆卸载已开始,children 和资源清理尚未完成。 */
|
|
61
|
+
private unmounting;
|
|
45
62
|
/** 按结构顺序排列的只读 children 快照。 */
|
|
46
63
|
get children(): readonly Child[];
|
|
47
64
|
/** 下一个 sibling;只读使用,通过树操作维护。 */
|
|
@@ -83,23 +100,33 @@ export declare class Node<P extends NodeProperties = NodeProperties, Child exten
|
|
|
83
100
|
private linkChild;
|
|
84
101
|
/** 解除结构所有权、sibling、上下文和事件冒泡关系。 */
|
|
85
102
|
private unlinkFromParent;
|
|
86
|
-
/**
|
|
103
|
+
/** @internal 结构安装前由具有绘制贡献的节点保存旧范围。 */
|
|
104
|
+
captureBeforeDetach(): void;
|
|
105
|
+
/** @internal 所有 raw links 安装后同步本地派生输入;不得推进阶段或调用应用回调。 */
|
|
106
|
+
protected onParentInstalled(_previousParent?: Node): void;
|
|
107
|
+
/** @internal 所有 raw links 安装后同步 children 派生输入和 dirty。 */
|
|
108
|
+
protected onChildrenInstalled(): void;
|
|
109
|
+
/**
|
|
110
|
+
* R0 消费已安装的 parent 与派生输入,维护所属依赖、订阅和失效。
|
|
111
|
+
* 可显式准备几何后读取;不得在此同步重新挂载当前节点。
|
|
112
|
+
*/
|
|
87
113
|
protected onParentChanged(_previousParent?: Node): void;
|
|
88
|
-
/**
|
|
114
|
+
/**
|
|
115
|
+
* R0 消费已安装的 children,维护所属依赖;构造期 children 不触发。
|
|
116
|
+
* 可显式准备几何后读取;不得同步改写正在通知的 children/placement。
|
|
117
|
+
*/
|
|
89
118
|
protected onChildrenChanged(): void;
|
|
90
|
-
/**
|
|
91
|
-
protected onStructureDirty(): void;
|
|
92
|
-
/** 在 children 提交后通知扩展点、Root 和 dirty 路径。 */
|
|
119
|
+
/** 在全部结构输入安装后运行结构通知并发布变化。 */
|
|
93
120
|
private markStructureDirty;
|
|
94
121
|
/**
|
|
95
|
-
* 向 Root 发布已安装的 placement
|
|
96
|
-
*
|
|
122
|
+
* 向 Root 发布已安装的 placement 变化。稳定生命周期事件可能建立新的关系,
|
|
123
|
+
* Root 按每个节点当前的 parent 与 lifecycle 消费实际变化。
|
|
97
124
|
*/
|
|
98
125
|
private publishStructureChange;
|
|
99
126
|
/** 安装一次最终 children,并在当前提交仍有效时发布结构变化。 */
|
|
100
127
|
private commitChildren;
|
|
101
128
|
/**
|
|
102
|
-
* 同步本次进入与离开节点的 lifecycle
|
|
129
|
+
* 同步本次进入与离开节点的 lifecycle。稳定生命周期事件可发起下一结构操作,因此每个节点都按
|
|
103
130
|
* 自己与当前 owner 的实时 parent 和 lifecycle 判断,不因 children 被新提交替换而遗漏其余节点。
|
|
104
131
|
*/
|
|
105
132
|
private syncCommittedLifecycles;
|
|
@@ -107,17 +134,24 @@ export declare class Node<P extends NodeProperties = NodeProperties, Child exten
|
|
|
107
134
|
detachBatchParent(): void;
|
|
108
135
|
/** @internal 接收 trusted batch 转移所有权的最终 children 与其变化窗口。 */
|
|
109
136
|
installBatchChildren(children: readonly Node[], start: number, end: number): void;
|
|
110
|
-
/** @internal 完整安装后的 parent
|
|
137
|
+
/** @internal 完整安装后的 parent 通知;先前稳定生命周期事件已改写归属时跳过旧结果。 */
|
|
111
138
|
notifyBatchParentChanged(previousParent: Node | undefined, expectedParent: Node | undefined): void;
|
|
112
139
|
/** @internal 按当前 parent 同步最终 lifecycle context。 */
|
|
113
140
|
syncPlacementLifecycle(): void;
|
|
114
|
-
/** @internal
|
|
115
|
-
|
|
141
|
+
/** @internal 全部字段和 raw links 安装后同步结构派生输入。 */
|
|
142
|
+
installBatchStructureInputs(): void;
|
|
143
|
+
/**
|
|
144
|
+
* @internal raw links 已改变后,在任何可重入回调前移交旧 Layer 的空间与像素责任。
|
|
145
|
+
* 活动上下文仍由 lifecycle owner 完成;新 Layer 在激活后接收新的绘制贡献。
|
|
146
|
+
*/
|
|
147
|
+
releasePreviousLayer(): void;
|
|
148
|
+
/** @internal 全部 raw links 安装后同步 placement 派生输入。 */
|
|
149
|
+
installBatchParentInput(previousParent: Node | undefined): void;
|
|
116
150
|
/** @internal raw links 与 placement lifecycle 同步完成后运行结构 hook。 */
|
|
117
151
|
runBatchStructureHook(): void;
|
|
118
152
|
/** 从当前 owner 移除一个直接 child,可选择同时停用它。 */
|
|
119
153
|
private removeOwnChild;
|
|
120
|
-
/** 构造期采用 children
|
|
154
|
+
/** 构造期采用 children;停用期间稳定事件已建立的新归属不再由旧输入接管。 */
|
|
121
155
|
private adoptIncoming;
|
|
122
156
|
/** 统一实现 append/prepend/before/after 的移动和插入事务。 */
|
|
123
157
|
private insertAt;
|
|
@@ -139,7 +173,7 @@ export declare class Node<P extends NodeProperties = NodeProperties, Child exten
|
|
|
139
173
|
after(...nodes: Node[]): this;
|
|
140
174
|
/** 移除但不卸载指定 children,使其仍可复用。 */
|
|
141
175
|
removeChild(...children: Child[]): this;
|
|
142
|
-
/**
|
|
176
|
+
/** 按当前状态执行生命周期操作;终态不再接收操作。 */
|
|
143
177
|
private transitionLifecycle;
|
|
144
178
|
/** 执行首次初始化和 Mounted 事件。 */
|
|
145
179
|
private mountNode;
|
|
@@ -147,26 +181,24 @@ export declare class Node<P extends NodeProperties = NodeProperties, Child exten
|
|
|
147
181
|
private canBeActivatedByOwner;
|
|
148
182
|
/** 首次挂载并在 owner 允许时激活当前子树;已卸载节点不可恢复。 */
|
|
149
183
|
mount(): void;
|
|
150
|
-
/**
|
|
184
|
+
/** 初始化自身资源和自有渲染 children;不得再次转换当前 Node 的生命周期。 */
|
|
151
185
|
protected onMount(): void;
|
|
152
186
|
/** 建立 Root/Layer 上下文、注册 key,并递归激活 children。 */
|
|
153
187
|
private activateNode;
|
|
154
|
-
/**
|
|
188
|
+
/** 激活自身资源、订阅和自有渲染输出;不得再次转换当前 Node 的生命周期或改写 host 归属。 */
|
|
155
189
|
protected onActivate(_activeRoot: Root | null, _layer: Layer | null): void;
|
|
156
190
|
/** 清理输入、key、Layer 空间项、children 和派生类 active 状态。 */
|
|
157
191
|
private leaveActiveContext;
|
|
158
192
|
/** 离开 active 上下文并派发 Deactivated。 */
|
|
159
193
|
private deactivateNode;
|
|
160
|
-
/**
|
|
194
|
+
/** 释放本节点活动资源和自有渲染输出;不得再次转换当前 Node 的生命周期。 */
|
|
161
195
|
protected onDeactivate(_activeRoot: Root | null, _layer: Layer | null): void;
|
|
162
|
-
/** children
|
|
196
|
+
/** children 卸载前释放自身资源;不得转移待卸载 children 或再次转换当前 Node 生命周期。 */
|
|
163
197
|
protected onBeforeUnmount(): void;
|
|
164
198
|
/** 释放派生 owner 前调用;不得再次转换当前 Node 的生命周期。 */
|
|
165
199
|
protected onUnmount(): void;
|
|
166
|
-
/**
|
|
200
|
+
/** 递归执行不可逆卸载,并释放本节点的结构、上下文和监听器。 */
|
|
167
201
|
private unmountNode;
|
|
168
|
-
/** 只在本节点存在监听器时创建同步生命周期事件。 */
|
|
169
|
-
private dispatchLifecycleEvent;
|
|
170
202
|
/** 不可逆卸载当前子树并清理监听器;重复调用不执行额外工作。 */
|
|
171
203
|
unmount(): void;
|
|
172
204
|
/** 在当前节点上下文中提供值。 */
|
|
@@ -1,6 +1,5 @@
|
|
|
1
1
|
import type { NodeCreationOptions } from "./node";
|
|
2
2
|
declare const CONFIGURED_STATE: unique symbol;
|
|
3
|
-
declare const RUNTIME_OVERRIDE_STATE: unique symbol;
|
|
4
3
|
/** x 方向变换原点;数值 `0` 为中心,`-0.5/0.5` 为左右边。 */
|
|
5
4
|
export type OriginX = "center" | "left" | "right" | number;
|
|
6
5
|
/** y 方向变换原点;数值 `0` 为中心,`-0.5/0.5` 为上下边。 */
|
|
@@ -33,18 +32,17 @@ export type PropertyChanges = ReadonlyMap<string, unknown>;
|
|
|
33
32
|
export type PropertyUpdates = ReadonlyMap<string, unknown>;
|
|
34
33
|
/** Node 持有的属性状态,并提供显式独立快照。 */
|
|
35
34
|
export declare class NodeProperties {
|
|
35
|
+
/** runtime 覆盖期间保存 configured 值,own-key 同时表示覆盖存在。 */
|
|
36
36
|
[CONFIGURED_STATE]: Record<string, unknown> | null;
|
|
37
|
-
[RUNTIME_OVERRIDE_STATE]: Record<string, unknown> | null;
|
|
38
37
|
/** 返回可独立修改的完整属性快照。 */
|
|
39
38
|
snapshot(): Record<string, unknown>;
|
|
40
39
|
/** 返回省略默认值和函数的可序列化属性。 */
|
|
41
40
|
toJSON(): Record<string, unknown>;
|
|
42
|
-
/**
|
|
41
|
+
/**
|
|
42
|
+
* 从安装前的当前 Properties、before changes 与最终 effective updates 纯计算提交影响。
|
|
43
|
+
* 扩展只返回影响位,不提交属性、结构或应用回调。
|
|
44
|
+
*/
|
|
43
45
|
getImpact(_changes: PropertyChanges, _updates?: PropertyUpdates): ChangeImpact;
|
|
44
|
-
/** 读取把 runtime 字段还原为 configured 后的当前作者值。 */
|
|
45
|
-
private configuredValue;
|
|
46
|
-
/** 返回把 runtime 字段还原为 configured 后的独立完整值。 */
|
|
47
|
-
private configuredValues;
|
|
48
46
|
}
|
|
49
47
|
/** @internal 借用单个字段当前的 configured source 值。 */
|
|
50
48
|
export declare function getConfiguredPropertyValue(properties: NodeProperties, key: string): any;
|
|
@@ -68,7 +66,6 @@ export interface PreparedPropertyField {
|
|
|
68
66
|
readonly sourceChanged: boolean;
|
|
69
67
|
readonly beforeValue: unknown;
|
|
70
68
|
readonly afterValue: unknown;
|
|
71
|
-
readonly valueChanged: boolean;
|
|
72
69
|
readonly installValue: boolean;
|
|
73
70
|
}
|
|
74
71
|
/** @internal direct 与 trusted batch 共用的最小 owner property delta。 */
|
|
@@ -78,13 +75,22 @@ export interface PreparedPropertyUpdate {
|
|
|
78
75
|
readonly changes: PropertyChanges;
|
|
79
76
|
readonly updates: PropertyUpdates;
|
|
80
77
|
}
|
|
81
|
-
/**
|
|
78
|
+
/**
|
|
79
|
+
* @internal 只计算 configured merge/reset 的 final delta,不安装或复制完整 Properties。
|
|
80
|
+
*/
|
|
82
81
|
export declare function prepareConfiguredPropertyUpdate(properties: NodeProperties, patch: Record<string, unknown>): PreparedPropertyUpdate;
|
|
83
|
-
/**
|
|
82
|
+
/**
|
|
83
|
+
* @internal 只计算 runtime merge 与 own-undefined clear 的 final delta,不安装状态。
|
|
84
|
+
*/
|
|
84
85
|
export declare function prepareRuntimePropertyUpdate(properties: NodeProperties, patch: Record<string, unknown>): PreparedPropertyUpdate;
|
|
85
|
-
/**
|
|
86
|
+
/**
|
|
87
|
+
* @internal 把指定或全部 runtime keys 解释为同一 clear delta,不安装状态。
|
|
88
|
+
*/
|
|
86
89
|
export declare function prepareRuntimePropertyClear(properties: NodeProperties, keys?: readonly PropertyKey[]): PreparedPropertyUpdate;
|
|
87
|
-
/**
|
|
90
|
+
/**
|
|
91
|
+
* @internal 由完整 R0 writer 安装已经 finalize 的 source/effective fields。
|
|
92
|
+
* hook、dirty 与 History 交由同一提交管线在必要字段安装后处理。
|
|
93
|
+
*/
|
|
88
94
|
export declare function installPropertyUpdate(properties: NodeProperties, update: PreparedPropertyUpdate): void;
|
|
89
95
|
/** Element 的作者变换和尺寸选项。 */
|
|
90
96
|
export interface TransformableOptions extends NodeCreationOptions {
|
|
@@ -106,18 +112,10 @@ export interface TransformableOptions extends NodeCreationOptions {
|
|
|
106
112
|
originX?: OriginX;
|
|
107
113
|
/** y 方向变换原点,默认 `center`。 */
|
|
108
114
|
originY?: OriginY;
|
|
109
|
-
/** Editor 旋转中心的 x 轴位置,默认 `center`。 */
|
|
110
|
-
rotationPivotX?: OriginX;
|
|
111
|
-
/** Editor 旋转中心的 y 轴位置,默认 `center`。 */
|
|
112
|
-
rotationPivotY?: OriginY;
|
|
113
115
|
/** x 轴错切角度,单位为度,默认 `0`。 */
|
|
114
116
|
skewX?: number;
|
|
115
117
|
/** y 轴错切角度,单位为度,默认 `0`。 */
|
|
116
118
|
skewY?: number;
|
|
117
|
-
/** 未指定宽度时是否匹配 parent 宽度。 */
|
|
118
|
-
fitWidth?: boolean;
|
|
119
|
-
/** 未指定高度时是否匹配 parent 高度。 */
|
|
120
|
-
fitHeight?: boolean;
|
|
121
119
|
}
|
|
122
120
|
/** Element 的作者变换属性状态。 */
|
|
123
121
|
export declare class TransformProperties extends NodeProperties {
|
|
@@ -139,18 +137,10 @@ export declare class TransformProperties extends NodeProperties {
|
|
|
139
137
|
originX: OriginX;
|
|
140
138
|
/** y 方向变换原点。 */
|
|
141
139
|
originY: OriginY;
|
|
142
|
-
/** Editor 旋转中心的 x 轴位置。 */
|
|
143
|
-
rotationPivotX: OriginX;
|
|
144
|
-
/** Editor 旋转中心的 y 轴位置。 */
|
|
145
|
-
rotationPivotY: OriginY;
|
|
146
140
|
/** x 轴错切角度,单位为度。 */
|
|
147
141
|
skewX: number;
|
|
148
142
|
/** y 轴错切角度,单位为度。 */
|
|
149
143
|
skewY: number;
|
|
150
|
-
/** 未指定宽度时是否匹配 parent 宽度。 */
|
|
151
|
-
fitWidth: boolean;
|
|
152
|
-
/** 未指定高度时是否匹配 parent 高度。 */
|
|
153
|
-
fitHeight: boolean;
|
|
154
144
|
/** 创建带声明默认值的作者变换属性。 */
|
|
155
145
|
constructor(options?: TransformableOptions);
|
|
156
146
|
/** @internal 将尺寸和标量变换变化映射为几何影响。 */
|
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
import { type PointView, type ReadonlyMatrix2D, type Rect } from "@fulate/share";
|
|
2
|
-
import type
|
|
2
|
+
import { Element, type ElementOptionPatch } from "./element";
|
|
3
3
|
import { type OriginX, type OriginY } from "./properties";
|
|
4
|
+
/** @internal 捕获已准备的场景几何和当前 authored 状态;离线对象独立计算变换。 */
|
|
5
|
+
export declare function captureElementTransformReference(owner: Element, writeMode: ReferenceTransformBaseline["writeMode"]): ReferenceTransformBaseline;
|
|
4
6
|
/** 交互开始时直接借用的作者 frame 标量。 */
|
|
5
7
|
export interface ReferenceTransformFrame {
|
|
6
8
|
readonly left: number;
|
|
@@ -54,13 +56,15 @@ export interface ReferenceTransformTarget {
|
|
|
54
56
|
export interface ReferenceTransformResolution {
|
|
55
57
|
readonly framePatch: Readonly<ElementOptionPatch>;
|
|
56
58
|
readonly authoredLocalDelta: ReadonlyMatrix2D;
|
|
59
|
+
/** authoredLocalDelta 后用于求 frame 的 reference AABB,由 resolver 直接交付。 */
|
|
60
|
+
readonly authoredReferenceBounds: Readonly<Rect>;
|
|
57
61
|
}
|
|
58
62
|
/**
|
|
59
63
|
* 用 owner 已算出的精确 authored bounds 修正 bake frame 的位置。
|
|
60
64
|
* AABB 经过旋转/错切后不能由原 bounds 四角精确推出;owner 在生成
|
|
61
65
|
* 新几何后把真实 bounds 交回这里,保持 frame world matrix 与目标一致。
|
|
62
66
|
*/
|
|
63
|
-
export declare function resolveAuthoredGeometryFramePatch(baseline: Readonly<Pick<ReferenceTransformBaseline, "
|
|
67
|
+
export declare function resolveAuthoredGeometryFramePatch(baseline: Readonly<Pick<ReferenceTransformBaseline, "frame">>, resolution: Readonly<ReferenceTransformResolution>, authoredBounds: Readonly<Rect>): Readonly<ElementOptionPatch>;
|
|
64
68
|
/** @internal reference bounds 改变时修正 origin 位移,保留给定最终 frame 的仿射。 */
|
|
65
69
|
export declare function resolveReferenceBoundsTranslation(frame: Readonly<ElementOptionPatch>, before: Readonly<Rect>, after: Readonly<Rect>): Readonly<Pick<ElementOptionPatch, "left" | "top">>;
|
|
66
70
|
/** 判断变换意图是否包含跨父级重挂载所需的目标父级矩阵。 */
|