@vvfx/sdk 0.1.13 → 0.1.14-alpha.1

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/index.d.cts CHANGED
@@ -1,8 +1,664 @@
1
1
  import * as _galacean_effects from '@galacean/effects';
2
- import { spec, math, Player } from '@galacean/effects';
2
+ import { spec, VFXItem, math, Player } from '@galacean/effects';
3
3
  export { generateGUID, spec } from '@galacean/effects';
4
4
  import { Point } from '@pixi/constants';
5
5
 
6
+ /**
7
+ * @description SDKItem 基础选项接口
8
+ * @description 支持扩展属性,允许添加任意额外属性
9
+ */
10
+ type SDKItemOptions = {
11
+ /**
12
+ * @description 元素ID
13
+ */
14
+ id: string;
15
+ /**
16
+ * @description 元素名称
17
+ */
18
+ name: string;
19
+ /**
20
+ * @description 父节点ID
21
+ */
22
+ parentId?: string;
23
+ /**
24
+ * @description 子元素ID列表
25
+ */
26
+ children?: string[];
27
+ /**
28
+ * @description 元素生命周期
29
+ */
30
+ duration?: number;
31
+ /**
32
+ * @description 元素生命周期延时
33
+ */
34
+ delay?: number;
35
+ /**
36
+ * @description 元素结束行为
37
+ */
38
+ endBehavior?: spec.EndBehavior;
39
+ /**
40
+ * @description 是否处于锁定状态
41
+ */
42
+ isLocked?: boolean;
43
+ /**
44
+ * @description 扩展属性存储(属性名 -> 属性值)
45
+ */
46
+ extensions?: Record<string, any>;
47
+ /**
48
+ * @description 允许任意额外属性(用于兼容旧代码)
49
+ */
50
+ [extraProp: string]: any;
51
+ };
52
+ /**
53
+ * @description Sprite SDKItem 选项
54
+ */
55
+ type SpriteItemOptions = SDKItemOptions & {
56
+ /**
57
+ * @description 元素属性
58
+ */
59
+ property?: Partial<SpriteFormProperty>;
60
+ };
61
+ /**
62
+ * @description Text SDKItem 选项
63
+ */
64
+ type TextItemOptions = SDKItemOptions & {
65
+ /**
66
+ * @description 元素属性
67
+ */
68
+ property?: Partial<TextFormProperty>;
69
+ };
70
+ /**
71
+ * @description Video SDKItem 选项
72
+ */
73
+ type VideoItemOptions = SDKItemOptions & {
74
+ /**
75
+ * @description 元素属性
76
+ */
77
+ property?: Partial<VideoFormProperty>;
78
+ };
79
+ /**
80
+ * @description Null SDKItem 选项(空节点/组)
81
+ */
82
+ type NullItemOptions = SDKItemOptions & {
83
+ /**
84
+ * @description 元素属性
85
+ */
86
+ property?: Partial<BaseFormProperty>;
87
+ };
88
+ /**
89
+ * @description Generator SDKItem 选项(资源生成器)
90
+ * @description 支持 image 和 video 两种生成器类型
91
+ * @description 复用 SpriteFormProperty 作为底层渲染
92
+ */
93
+ type GeneratorItemOptions = SDKItemOptions & {
94
+ /**
95
+ * @description 生成器类型
96
+ */
97
+ generatorType: GeneratorType;
98
+ /**
99
+ * @description 元素属性
100
+ */
101
+ property?: Partial<SpriteFormProperty>;
102
+ };
103
+ /**
104
+ * @description SDKItem 类型(独立于 spec.ItemType)
105
+ * @description 包含所有 SDK 层级的元素类型,包括虚拟类型如 generator
106
+ */
107
+ type SDKItemType = 'sprite' | 'text' | 'video' | 'null' | 'generator';
108
+
109
+ /**
110
+ * @description SDKItem 抽象基类
111
+ * @description 支持属性扩展,允许添加任意自定义属性
112
+ */
113
+ declare abstract class BaseItem {
114
+ /**
115
+ * @description 元素ID
116
+ */
117
+ id: string;
118
+ /**
119
+ * @description 元素名称
120
+ */
121
+ name: string;
122
+ /**
123
+ * @description 父节点ID
124
+ */
125
+ parentId?: string;
126
+ /**
127
+ * @description 子元素ID列表
128
+ */
129
+ children: string[];
130
+ /**
131
+ * @description 元素生命周期
132
+ */
133
+ duration: number;
134
+ /**
135
+ * @description 元素生命周期延时
136
+ */
137
+ delay: number;
138
+ /**
139
+ * @description 元素结束行为
140
+ */
141
+ endBehavior: spec.EndBehavior;
142
+ /**
143
+ * @description 是否处于锁定状态
144
+ */
145
+ isLocked: boolean;
146
+ /**
147
+ * @description 扩展属性存储(私有)
148
+ */
149
+ private _extensions;
150
+ /**
151
+ * @description 元素类型(由子类实现)
152
+ * @description 支持 spec.ItemType 或扩展的 SDKItemType(如 'video-generator')
153
+ */
154
+ abstract readonly type: spec.ItemType | SDKItemType;
155
+ /**
156
+ * @description 元素属性(由子类实现)
157
+ */
158
+ abstract readonly property: BaseFormProperty;
159
+ constructor(options: SDKItemOptions);
160
+ /**
161
+ * @description 设置扩展属性
162
+ * @param key 属性名
163
+ * @param value 属性值
164
+ */
165
+ setExtension(key: string, value: any): void;
166
+ /**
167
+ * @description 获取扩展属性
168
+ * @param key 属性名
169
+ * @returns 属性值
170
+ */
171
+ getExtension(key: string): any;
172
+ /**
173
+ * @description 检查是否存在指定扩展属性
174
+ * @param key 属性名
175
+ * @returns 是否存在
176
+ */
177
+ hasExtension(key: string): boolean;
178
+ /**
179
+ * @description 删除扩展属性
180
+ * @param key 属性名
181
+ * @returns 是否删除成功
182
+ */
183
+ deleteExtension(key: string): boolean;
184
+ /**
185
+ * @description 获取所有扩展属性的键名列表
186
+ * @returns 键名数组
187
+ */
188
+ getExtensionKeys(): string[];
189
+ /**
190
+ * @description 获取所有扩展属性
191
+ * @returns 扩展属性对象
192
+ */
193
+ getAllExtensions(): Record<string, any>;
194
+ /**
195
+ * @description 批量设置扩展属性
196
+ * @param extensions 扩展属性对象
197
+ */
198
+ setExtensions(extensions: Record<string, any>): void;
199
+ /**
200
+ * @description 清空所有扩展属性
201
+ */
202
+ clearExtensions(): void;
203
+ /**
204
+ * @description 转换为普通对象(用于序列化)
205
+ * @returns 普通对象
206
+ */
207
+ abstract toJSON(): Record<string, any>;
208
+ /**
209
+ * @description 转换为 CreateInfo(用于元素复制/导出)
210
+ * @param withParent 是否包含父节点ID
211
+ * @returns CreateInfo 对象
212
+ */
213
+ abstract toCreateInfo(withParent?: boolean): ItemCreateInfo;
214
+ /**
215
+ * @description 克隆 SDKItem
216
+ * @returns 新的 SDKItem 实例
217
+ */
218
+ abstract clone(): BaseItem;
219
+ /**
220
+ * @description 获取基础属性的 JSON 对象(子类可用)
221
+ * @protected
222
+ */
223
+ protected getBaseJSON(): Record<string, any>;
224
+ }
225
+ /**
226
+ * @description 类型守卫函数:检查对象是否是 BaseItem
227
+ * @param obj 要检查的对象
228
+ * @returns 是否是 BaseItem 实例
229
+ */
230
+ declare function isBaseItem(obj: any): obj is BaseItem;
231
+
232
+ /**
233
+ * @description 图片元素 SDKItem 类
234
+ * @description 支持属性扩展
235
+ */
236
+ declare class SpriteItem extends BaseItem {
237
+ /**
238
+ * @description 元素类型
239
+ */
240
+ readonly type = spec.ItemType.sprite;
241
+ /**
242
+ * @description 元素属性
243
+ */
244
+ property: SpriteFormProperty;
245
+ constructor(options: SpriteItemOptions);
246
+ /**
247
+ * @description 图片地址
248
+ */
249
+ get image(): string;
250
+ set image(value: string);
251
+ /**
252
+ * @description 位置
253
+ */
254
+ get position(): [number, number];
255
+ set position(value: [number, number]);
256
+ /**
257
+ * @description 大小
258
+ */
259
+ get size(): [number, number];
260
+ set size(value: [number, number]);
261
+ /**
262
+ * @description 旋转(二维旋转角度)
263
+ */
264
+ get rotation(): number;
265
+ set rotation(value: number);
266
+ /**
267
+ * @description 完整旋转(包含 x, y, z)
268
+ */
269
+ get fullRotation(): [number, number, number];
270
+ set fullRotation(value: [number, number, number]);
271
+ /**
272
+ * @description 可见性
273
+ */
274
+ get visible(): boolean;
275
+ set visible(value: boolean);
276
+ /**
277
+ * @description 是否正在编辑关键属性
278
+ */
279
+ get keyPropertyEditing(): boolean;
280
+ set keyPropertyEditing(value: boolean);
281
+ /**
282
+ * @description 转换为普通对象
283
+ */
284
+ toJSON(): Record<string, any>;
285
+ /**
286
+ * @description 转换为 CreateInfo
287
+ * @param withParent 是否包含父节点ID
288
+ */
289
+ toCreateInfo(withParent?: boolean): SpriteCreateInfo;
290
+ /**
291
+ * @description 克隆 SDKItem
292
+ */
293
+ clone(): SpriteItem;
294
+ /**
295
+ * @description 创建包含扩展属性的 CreateInfo
296
+ * @param withParent 是否包含父节点ID
297
+ * @param extraProps 额外的属性
298
+ */
299
+ toCreateInfoWithExtensions(withParent?: boolean, extraProps?: Record<string, any>): SpriteCreateInfo;
300
+ }
301
+ /**
302
+ * @description 类型守卫:检查是否是 SpriteItem
303
+ */
304
+ declare function isSpriteItem(obj: any): obj is SpriteItem;
305
+
306
+ /**
307
+ * @description 文本元素 SDKItem 类
308
+ * @description 支持属性扩展
309
+ */
310
+ declare class TextItem extends BaseItem {
311
+ /**
312
+ * @description 元素类型
313
+ */
314
+ readonly type = spec.ItemType.text;
315
+ /**
316
+ * @description 元素属性
317
+ */
318
+ property: TextFormProperty;
319
+ constructor(options: TextItemOptions);
320
+ /**
321
+ * @description 文本内容
322
+ */
323
+ get text(): string;
324
+ set text(value: string);
325
+ /**
326
+ * @description 字体名称
327
+ */
328
+ get fontFamily(): string;
329
+ set fontFamily(value: string);
330
+ /**
331
+ * @description 字号
332
+ */
333
+ get fontSize(): number;
334
+ set fontSize(value: number);
335
+ /**
336
+ * @description 字重
337
+ */
338
+ get fontWeight(): spec.TextWeight;
339
+ set fontWeight(value: spec.TextWeight);
340
+ /**
341
+ * @description 字体样式
342
+ */
343
+ get fontStyle(): spec.FontStyle;
344
+ set fontStyle(value: spec.FontStyle);
345
+ /**
346
+ * @description 文本对齐方式
347
+ */
348
+ get textAlign(): spec.TextAlignment;
349
+ set textAlign(value: spec.TextAlignment);
350
+ /**
351
+ * @description 文本颜色 [r, g, b, a]
352
+ */
353
+ get textColor(): [number, number, number, number];
354
+ set textColor(value: [number, number, number, number]);
355
+ /**
356
+ * @description 文本宽度
357
+ */
358
+ get textWidth(): number;
359
+ set textWidth(value: number);
360
+ /**
361
+ * @description 行高
362
+ */
363
+ get lineHeight(): number;
364
+ set lineHeight(value: number);
365
+ /**
366
+ * @description 文本高度
367
+ */
368
+ get textHeight(): number;
369
+ set textHeight(value: number);
370
+ /**
371
+ * @description 描边颜色
372
+ */
373
+ get outlineColor(): spec.vec4 | undefined;
374
+ set outlineColor(value: spec.vec4 | undefined);
375
+ /**
376
+ * @description 描边宽度
377
+ */
378
+ get outlineWidth(): number | undefined;
379
+ set outlineWidth(value: number | undefined);
380
+ /**
381
+ * @description 描边开关
382
+ */
383
+ get outlineEnabled(): boolean;
384
+ set outlineEnabled(value: boolean);
385
+ /**
386
+ * @description 位置
387
+ */
388
+ get position(): [number, number];
389
+ set position(value: [number, number]);
390
+ /**
391
+ * @description 旋转(二维旋转角度)
392
+ */
393
+ get rotation(): number;
394
+ set rotation(value: number);
395
+ /**
396
+ * @description 可见性
397
+ */
398
+ get visible(): boolean;
399
+ set visible(value: boolean);
400
+ /**
401
+ * @description 转换为普通对象
402
+ */
403
+ toJSON(): Record<string, any>;
404
+ /**
405
+ * @description 转换为 CreateInfo
406
+ * @param withParent 是否包含父节点ID
407
+ */
408
+ toCreateInfo(withParent?: boolean): TextCreateInfo;
409
+ /**
410
+ * @description 克隆 SDKItem
411
+ */
412
+ clone(): TextItem;
413
+ }
414
+ /**
415
+ * @description 类型守卫:检查是否是 TextItem
416
+ */
417
+ declare function isTextItem(obj: any): obj is TextItem;
418
+
419
+ /**
420
+ * @description 视频元素 SDKItem 类
421
+ * @description 支持属性扩展
422
+ */
423
+ declare class VideoItem extends BaseItem {
424
+ /**
425
+ * @description 元素类型
426
+ */
427
+ readonly type = spec.ItemType.video;
428
+ /**
429
+ * @description 元素属性
430
+ */
431
+ property: VideoFormProperty;
432
+ constructor(options: VideoItemOptions);
433
+ /**
434
+ * @description 视频地址
435
+ */
436
+ get video(): string;
437
+ set video(value: string);
438
+ /**
439
+ * @description 位置
440
+ */
441
+ get position(): [number, number];
442
+ set position(value: [number, number]);
443
+ /**
444
+ * @description 大小
445
+ */
446
+ get size(): [number, number];
447
+ set size(value: [number, number]);
448
+ /**
449
+ * @description 旋转(二维旋转角度)
450
+ */
451
+ get rotation(): number;
452
+ set rotation(value: number);
453
+ /**
454
+ * @description 完整旋转(包含 x, y, z)
455
+ */
456
+ get fullRotation(): [number, number, number];
457
+ set fullRotation(value: [number, number, number]);
458
+ /**
459
+ * @description 可见性
460
+ */
461
+ get visible(): boolean;
462
+ set visible(value: boolean);
463
+ /**
464
+ * @description 是否正在编辑关键属性
465
+ */
466
+ get keyPropertyEditing(): boolean;
467
+ set keyPropertyEditing(value: boolean);
468
+ /**
469
+ * @description 转换为普通对象
470
+ */
471
+ toJSON(): Record<string, any>;
472
+ /**
473
+ * @description 转换为 CreateInfo
474
+ * @param withParent 是否包含父节点ID
475
+ */
476
+ toCreateInfo(withParent?: boolean): VideoCreateInfo;
477
+ /**
478
+ * @description 克隆 SDKItem
479
+ */
480
+ clone(): VideoItem;
481
+ }
482
+ /**
483
+ * @description 类型守卫:检查是否是 VideoItem
484
+ */
485
+ declare function isVideoItem(obj: any): obj is VideoItem;
486
+
487
+ /**
488
+ * @description 空节点/组 SDKItem 类
489
+ * @description 支持属性扩展
490
+ */
491
+ declare class NullItem extends BaseItem {
492
+ /**
493
+ * @description 元素类型
494
+ */
495
+ readonly type = spec.ItemType.null;
496
+ /**
497
+ * @description 元素属性
498
+ */
499
+ property: BaseFormProperty;
500
+ constructor(options: NullItemOptions);
501
+ /**
502
+ * @description 位置
503
+ */
504
+ get position(): [number, number];
505
+ set position(value: [number, number]);
506
+ /**
507
+ * @description 大小
508
+ */
509
+ get size(): [number, number];
510
+ set size(value: [number, number]);
511
+ /**
512
+ * @description 旋转(二维旋转角度)
513
+ */
514
+ get rotation(): number;
515
+ set rotation(value: number);
516
+ /**
517
+ * @description 完整旋转(包含 x, y, z)
518
+ */
519
+ get fullRotation(): [number, number, number];
520
+ set fullRotation(value: [number, number, number]);
521
+ /**
522
+ * @description 可见性
523
+ */
524
+ get visible(): boolean;
525
+ set visible(value: boolean);
526
+ /**
527
+ * @description 是否正在编辑关键属性
528
+ */
529
+ get keyPropertyEditing(): boolean;
530
+ set keyPropertyEditing(value: boolean);
531
+ /**
532
+ * @description 计算缩放(基于子元素)
533
+ */
534
+ get scaleForCreateInfo(): [number, number];
535
+ /**
536
+ * @description 设置缩放(存储在扩展属性中)
537
+ */
538
+ set scaleForCreateInfo(value: [number, number]);
539
+ /**
540
+ * @description 转换为普通对象
541
+ */
542
+ toJSON(): Record<string, any>;
543
+ /**
544
+ * @description 转换为 CreateInfo
545
+ * @param withParent 是否包含父节点ID
546
+ */
547
+ toCreateInfo(withParent?: boolean): NullCreateInfo;
548
+ /**
549
+ * @description 克隆 SDKItem
550
+ */
551
+ clone(): NullItem;
552
+ }
553
+ /**
554
+ * @description 类型守卫:检查是否是 NullItem
555
+ */
556
+ declare function isNullItem(obj: any): obj is NullItem;
557
+
558
+ /**
559
+ * @description 资源生成器元素 SDKItem 类
560
+ * @description 支持 image 和 video 两种生成器类型
561
+ * @description 在 Player 中以透明 SpriteItem 形式渲染
562
+ * @description 支持属性扩展,可转换为 SpriteItem 或 VideoItem
563
+ */
564
+ declare class GeneratorItem extends BaseItem {
565
+ /**
566
+ * @description 元素类型(独立类型,不属于 spec.ItemType)
567
+ */
568
+ readonly type: SDKItemType;
569
+ /**
570
+ * @description 生成器类型
571
+ */
572
+ generatorType: GeneratorType;
573
+ /**
574
+ * @description 元素属性
575
+ */
576
+ property: SpriteFormProperty;
577
+ constructor(options: GeneratorItemOptions);
578
+ /**
579
+ * @description 图片地址(生成器返回空)
580
+ */
581
+ get image(): string;
582
+ set image(_value: string);
583
+ /**
584
+ * @description 位置
585
+ */
586
+ get position(): [number, number];
587
+ set position(value: [number, number]);
588
+ /**
589
+ * @description 大小
590
+ */
591
+ get size(): [number, number];
592
+ set size(value: [number, number]);
593
+ /**
594
+ * @description 旋转(二维旋转角度)
595
+ */
596
+ get rotation(): number;
597
+ set rotation(value: number);
598
+ /**
599
+ * @description 完整旋转(包含 x, y, z)
600
+ */
601
+ get fullRotation(): [number, number, number];
602
+ set fullRotation(value: [number, number, number]);
603
+ /**
604
+ * @description 可见性
605
+ */
606
+ get visible(): boolean;
607
+ set visible(value: boolean);
608
+ /**
609
+ * @description 是否正在编辑关键属性
610
+ */
611
+ get keyPropertyEditing(): boolean;
612
+ set keyPropertyEditing(value: boolean);
613
+ /**
614
+ * @description 转换为普通对象
615
+ */
616
+ toJSON(): Record<string, any>;
617
+ /**
618
+ * @description 转换为 GeneratorCreateInfo
619
+ * @param withParent 是否包含父节点ID
620
+ */
621
+ toCreateInfo(withParent?: boolean): GeneratorCreateInfo;
622
+ /**
623
+ * @description 转换为 VideoCreateInfo(用于转换为视频元素)
624
+ * @param videoUrl 视频资源地址
625
+ * @param withParent 是否包含父节点ID
626
+ */
627
+ toVideoCreateInfo(videoUrl: string, withParent?: boolean): VideoCreateInfo;
628
+ /**
629
+ * @description 转换为 SpriteCreateInfo(用于转换为图片元素)
630
+ * @param imageUrl 图片资源地址
631
+ * @param withParent 是否包含父节点ID
632
+ */
633
+ toSpriteCreateInfo(imageUrl: string, withParent?: boolean): SpriteCreateInfo;
634
+ /**
635
+ * @description 克隆 SDKItem
636
+ */
637
+ clone(): GeneratorItem;
638
+ }
639
+
640
+ /**
641
+ * @description 根据 item type 创建对应的 SDKItem 实例
642
+ * @param type 元素类型
643
+ * @param options SDKItem 选项
644
+ * @returns SDKItem 实例
645
+ */
646
+ declare function createSDKItem(type: spec.ItemType, options: SDKItemOptions): BaseItem;
647
+ /**
648
+ * @description 从 Player Item 创建 SDKItem
649
+ * @param playerItem VFXItem
650
+ * @param parentId 父节点ID
651
+ * @param property 属性对象
652
+ * @param generatorType 生成器类型(如果是生成器元素)
653
+ * @returns SDKItem 实例
654
+ */
655
+ declare function createSDKItemFromPlayerItem(playerItem: VFXItem, parentId: string | undefined, property: Record<string, any>, generatorType?: GeneratorType): BaseItem;
656
+ /**
657
+ * @description SDKItem 类型联合
658
+ * @description 用于替换原来的 SDKItem type
659
+ */
660
+ type SDKItem$1 = SpriteItem | TextItem | VideoItem | NullItem | GeneratorItem;
661
+
6
662
  type ViewItemTypedProperty = {
7
663
  [K in keyof PageFormTypeAndPropertyReference]: {
8
664
  /**
@@ -1342,7 +1998,6 @@ declare class SDK {
1342
1998
  private initExporter;
1343
1999
  private initSDK;
1344
2000
  run(param: SDKInputParam): Promise<void>;
1345
- getPageData(): PageData;
1346
2001
  getActiveItems(): string[];
1347
2002
  setPreSelectedItem(id: string): void;
1348
2003
  getPreSelectedItem(): string;
@@ -1381,7 +2036,7 @@ declare class SDK {
1381
2036
  * @param progress 播放进度 0-100
1382
2037
  */
1383
2038
  setPlayProgress(progress: number): Promise<void>;
1384
- getViewItems(): ViewItem[];
2039
+ getSDKItems(): SDKItem$1[];
1385
2040
  setPlayState(playState: 'play' | 'pause'): Promise<void>;
1386
2041
  /**
1387
2042
  * @description 获取场景预览图
@@ -1567,7 +2222,48 @@ declare class SDK {
1567
2222
  */
1568
2223
  exportJSON(idInfo?: number | number[]): spec.JSONScene[];
1569
2224
  getViewBoxById(id: string): Box2;
1570
- getViewItemById(id: string): ViewItem | undefined;
2225
+ getSDKItemById(id: string): SDKItem$1 | undefined;
2226
+ /**
2227
+ * @description 批量设置元素扩展属性
2228
+ * @param id 元素ID
2229
+ * @param extensions 扩展属性对象(支持同时设置多个)
2230
+ * @returns 是否设置成功
2231
+ */
2232
+ setItemExtensions(id: string, extensions: Record<string, any>): boolean;
2233
+ /**
2234
+ * @description 批量获取元素扩展属性
2235
+ * @param id 元素ID
2236
+ * @param keys 扩展属性名称列表(不传则返回所有扩展属性)
2237
+ * @returns 扩展属性对象
2238
+ */
2239
+ getItemExtensions(id: string, keys?: string[]): Record<string, any> | undefined;
2240
+ /**
2241
+ * @description 获取单个元素扩展属性
2242
+ * @param id 元素ID
2243
+ * @param key 扩展属性名称
2244
+ * @returns 扩展属性值
2245
+ */
2246
+ getItemExtension(id: string, key: string): any;
2247
+ /**
2248
+ * @description 删除元素扩展属性(支持批量删除)
2249
+ * @param id 元素ID
2250
+ * @param keys 扩展属性名称列表
2251
+ * @returns 是否删除成功
2252
+ */
2253
+ deleteItemExtensions(id: string, keys: string[]): boolean;
2254
+ /**
2255
+ * @description 检查元素是否有指定扩展属性
2256
+ * @param id 元素ID
2257
+ * @param key 扩展属性名称
2258
+ * @returns 是否存在
2259
+ */
2260
+ hasItemExtension(id: string, key: string): boolean;
2261
+ /**
2262
+ * @description 获取元素所有扩展属性的键名列表
2263
+ * @param id 元素ID
2264
+ * @returns 键名数组
2265
+ */
2266
+ getItemExtensionKeys(id: string): string[] | undefined;
1571
2267
  getViewProperty(id: number): ViewProperty | undefined;
1572
2268
  pageMove(shift: [number, number]): void;
1573
2269
  pageZoom(shift: number, center?: [number, number]): void;
@@ -1619,9 +2315,57 @@ declare class SDK {
1619
2315
  setInteractType(type: GestureHandlerInteractType): void;
1620
2316
  makeItemAlign(type: AlignType, ids?: string[]): void;
1621
2317
  makeItemDistribute(type: DistributeType, ids?: string[]): void;
1622
- createVideoGenerator(createInfo: VideoGeneratorCreateInfo): void;
2318
+ /**
2319
+ * @description 创建生成器元素
2320
+ * @param createInfo 生成器创建信息
2321
+ * @returns 生成器元素ID
2322
+ */
2323
+ createGenerator(createInfo: GeneratorCreateInfo): string;
2324
+ /**
2325
+ * @description 创建视频生成器元素
2326
+ * @param createInfo 视频生成器创建信息
2327
+ * @returns 视频生成器元素ID
2328
+ * @deprecated 使用 createGenerator 替代
2329
+ */
2330
+ createVideoGenerator(createInfo: GeneratorCreateInfo): string;
2331
+ /**
2332
+ * @description 设置生成器资源,将生成器转换为对应的元素
2333
+ * @param id 生成器元素ID
2334
+ * @param resourceUrl 资源地址
2335
+ * @returns 新的元素ID
2336
+ */
2337
+ setGeneratorResource(id: string, resourceUrl: string): Promise<string>;
2338
+ /**
2339
+ * @description 设置生成器资源(使用 GeneratorResource 对象)
2340
+ * @param resource 生成器资源信息
2341
+ */
2342
+ setGeneratorResourceFromObject(resource: GeneratorResource): void;
2343
+ /**
2344
+ * @description 将视频生成器转换为视频元素
2345
+ * @param id 视频生成器元素ID
2346
+ * @param videoUrl 视频资源地址
2347
+ * @returns 新的视频元素ID
2348
+ * @deprecated 使用 setGeneratorResource 替代
2349
+ */
2350
+ convertVideoGeneratorToVideo(id: string, videoUrl: string): Promise<string>;
2351
+ /**
2352
+ * @description 设置视频生成器资源
2353
+ * @param resource 视频生成器资源信息
2354
+ * @deprecated 使用 setGeneratorResource 替代
2355
+ */
1623
2356
  setVideoGeneratorResource(resource: VideoGeneratorResource): void;
1624
- createSpriteGenerator(createInfo: SpriteGeneratorCreateInfo): void;
2357
+ /**
2358
+ * @description 创建图层生成器元素
2359
+ * @param createInfo 图层生成器创建信息
2360
+ * @returns 图层生成器元素ID
2361
+ * @deprecated 使用 createGenerator 替代
2362
+ */
2363
+ createSpriteGenerator(createInfo: GeneratorCreateInfo): string;
2364
+ /**
2365
+ * @description 设置图层生成器资源
2366
+ * @param resource 图层生成器资源信息
2367
+ * @deprecated 使用 setGeneratorResource 替代
2368
+ */
1625
2369
  setSpriteGeneratorResource(resource: SpriteGeneratorResource): void;
1626
2370
  setItemLockState(id: string, state: boolean): void;
1627
2371
  getItemLockState(id: string): void;
@@ -1635,7 +2379,9 @@ type BaseFormProperty = {
1635
2379
  position: [number, number];
1636
2380
  rotation: [number, number, number];
1637
2381
  size: [number, number];
2382
+ scale: [number, number];
1638
2383
  visible: boolean;
2384
+ isLocked?: boolean;
1639
2385
  keyPropertyEditing: boolean;
1640
2386
  };
1641
2387
  type SpriteFormProperty = BaseFormProperty & {
@@ -1765,7 +2511,7 @@ type PageData = {
1765
2511
  /**
1766
2512
  * @description 元素数据
1767
2513
  */
1768
- items: ViewItem[];
2514
+ items: SDKItem[];
1769
2515
  /**
1770
2516
  * @description 视图当前时间
1771
2517
  */
@@ -1936,42 +2682,12 @@ type ActiveData = {
1936
2682
  };
1937
2683
  /**
1938
2684
  * @description 视图元素
2685
+ * @description 注意:SDKItem 现在已从类实现中导入,见 view-item/index.ts
2686
+ * @description SDKItem 现在是类实例而非普通对象,支持属性扩展
2687
+ * @description 保持类型兼容性:新 SDKItem 类拥有与旧类型相同的属性
1939
2688
  */
1940
- type ViewItem = {
1941
- /**
1942
- * @description 元素ID
1943
- */
1944
- id: string;
1945
- /**
1946
- * @description 元素名称
1947
- */
1948
- name: string;
1949
- /**
1950
- * @description 元素父节点ID
1951
- */
1952
- parentId?: string;
1953
- /**
1954
- * @description 子元素
1955
- */
1956
- children: string[];
1957
- /**
1958
- * @description 元素生命周期
1959
- */
1960
- duration: number;
1961
- /**
1962
- * @description 元素生命周期延时
1963
- */
1964
- delay: number;
1965
- /**
1966
- * @description 元素结束行为
1967
- */
1968
- endBehavior: spec.EndBehavior;
1969
- /**
1970
- * @description 是否处于锁定状态
1971
- */
1972
- isLocked?: boolean;
1973
- } & ViewItemTypedProperty;
1974
- type SDKBackgroundType = 'color' | 'image' | 'chess-board';
2689
+ type SDKItem = SDKItem$1;
2690
+ type SDKBackgroundType = 'color' | 'image' | 'chess-board' | 'dot-board';
1975
2691
  /**
1976
2692
  * @description 图层创建信息
1977
2693
  */
@@ -2009,6 +2725,10 @@ type SpriteCreateInfo = {
2009
2725
  * @description 图层元素二维位置
2010
2726
  */
2011
2727
  position: spec.vec2;
2728
+ /**
2729
+ * @description 扩展属性
2730
+ */
2731
+ extensions?: Record<string, any>;
2012
2732
  };
2013
2733
  /**
2014
2734
  * @description 空节点创建信息
@@ -2043,6 +2763,10 @@ type NullCreateInfo = {
2043
2763
  * @description 空节点位移
2044
2764
  */
2045
2765
  position?: spec.vec2;
2766
+ /**
2767
+ * @description 扩展属性
2768
+ */
2769
+ extensions?: Record<string, any>;
2046
2770
  };
2047
2771
  /**
2048
2772
  * @description 文本创建信息
@@ -2125,6 +2849,10 @@ type TextCreateInfo = {
2125
2849
  * @description 字体文件地址
2126
2850
  */
2127
2851
  url?: string;
2852
+ /**
2853
+ * @description 扩展属性
2854
+ */
2855
+ extensions?: Record<string, any>;
2128
2856
  };
2129
2857
  /**
2130
2858
  * @description 视频创建信息
@@ -2179,100 +2907,117 @@ type VideoCreateInfo = {
2179
2907
  * @description 音量
2180
2908
  */
2181
2909
  volume?: number;
2910
+ /**
2911
+ * @description 扩展属性
2912
+ */
2913
+ extensions?: Record<string, any>;
2182
2914
  };
2183
2915
  /**
2184
- * @description 视频生成器创建信息
2916
+ * @description 生成器类型
2917
+ */
2918
+ type GeneratorType = 'image' | 'video';
2919
+ /**
2920
+ * @description 生成器创建信息
2185
2921
  */
2186
- type VideoGeneratorCreateInfo = {
2922
+ type GeneratorCreateInfo = {
2187
2923
  /**
2188
- * @description 类型 - 视频生成器
2924
+ * @description 元素类型 - 生成器
2189
2925
  */
2190
- type: 'video-generator';
2926
+ type: 'generator';
2191
2927
  /**
2192
- * @description 视频名称
2193
- */
2928
+ * @description 生成器类型
2929
+ */
2930
+ generatorType: GeneratorType;
2931
+ /**
2932
+ * @description 元素名称
2933
+ */
2194
2934
  name?: string;
2195
2935
  /**
2196
2936
  * @description 元素id
2197
2937
  */
2198
2938
  id?: string;
2199
2939
  /**
2200
- * @description 视频生成器大小
2940
+ * @description 父元素id
2941
+ */
2942
+ parentId?: string;
2943
+ /**
2944
+ * @description 生成器大小
2201
2945
  */
2202
2946
  size: spec.vec2;
2203
2947
  /**
2204
- * @description 视频生成器位置
2948
+ * @description 生成器位置
2205
2949
  */
2206
2950
  position: spec.vec2;
2951
+ /**
2952
+ * @description 旋转角度
2953
+ */
2954
+ rotation?: number;
2955
+ /**
2956
+ * @description 缩放
2957
+ */
2958
+ scale?: spec.vec2;
2959
+ /**
2960
+ * @description 扩展属性
2961
+ */
2962
+ extensions?: Record<string, any>;
2207
2963
  };
2208
2964
  /**
2209
- * @description 视频生成器资源信息
2965
+ * @description 生成器资源信息
2210
2966
  */
2211
- type VideoGeneratorResource = {
2967
+ type SpriteGeneratorResource = {
2212
2968
  /**
2213
2969
  * @description 资源地址
2214
2970
  */
2215
2971
  url: string;
2216
2972
  /**
2217
- * @description 视频尺寸
2973
+ * @description 资源尺寸
2218
2974
  */
2219
2975
  size?: spec.vec2;
2220
2976
  /**
2221
- * @description 是否静音
2977
+ * @description 目标生成器元素 ID(必填)
2222
2978
  */
2223
- muted?: boolean;
2979
+ itemId: string;
2224
2980
  /**
2225
- * @description 是否为透明视频
2981
+ * @description 扩展属性
2226
2982
  */
2227
- transparent?: boolean;
2983
+ extensions?: Record<string, any>;
2984
+ };
2985
+ type VideoGeneratorResource = {
2228
2986
  /**
2229
- * @description 播放速率
2230
- */
2231
- playbackRate?: number;
2987
+ * @description 资源地址
2988
+ */
2989
+ url: string;
2232
2990
  /**
2233
- * @description 音量
2991
+ * @description 资源尺寸
2234
2992
  */
2235
- volume?: number;
2236
- };
2237
- /**
2238
- * @description 图层生成器创建信息
2239
- */
2240
- type SpriteGeneratorCreateInfo = {
2993
+ size?: spec.vec2;
2241
2994
  /**
2242
- * @description 类型 - 图层生成器
2995
+ * @description 是否静音(仅用于视频)
2243
2996
  */
2244
- type: 'sprite-generator';
2245
- /**
2246
- * @description 图层名称
2247
- */
2248
- name?: string;
2997
+ muted?: boolean;
2249
2998
  /**
2250
- * @description 元素id
2999
+ * @description 是否为透明视频(仅用于视频)
2251
3000
  */
2252
- id?: string;
3001
+ transparent?: boolean;
2253
3002
  /**
2254
- * @description 图层生成器大小
3003
+ * @description 播放速率(仅用于视频)
2255
3004
  */
2256
- size: spec.vec2;
3005
+ playbackRate?: number;
2257
3006
  /**
2258
- * @description 图层生成器位置
3007
+ * @description 音量(仅用于视频)
2259
3008
  */
2260
- position: spec.vec2;
2261
- };
2262
- /**
2263
- * @description 图层生成器资源信息
2264
- */
2265
- type SpriteGeneratorResource = {
3009
+ volume?: number;
2266
3010
  /**
2267
- * @description 资源地址
3011
+ * @description 目标生成器元素 ID(必填)
2268
3012
  */
2269
- url: string;
3013
+ itemId: string;
2270
3014
  /**
2271
- * @description 图层尺寸
3015
+ * @description 扩展属性
2272
3016
  */
2273
- size?: spec.vec2;
3017
+ extensions?: Record<string, any>;
2274
3018
  };
2275
- type ItemCreateInfo = NullCreateInfo | SpriteCreateInfo | TextCreateInfo | VideoCreateInfo | SpriteGeneratorCreateInfo | VideoGeneratorCreateInfo;
3019
+ type GeneratorResource = SpriteGeneratorResource | VideoGeneratorResource;
3020
+ type ItemCreateInfo = NullCreateInfo | SpriteCreateInfo | TextCreateInfo | VideoCreateInfo | GeneratorCreateInfo;
2276
3021
  /**
2277
3022
  * @description 场景创建信息
2278
3023
  */
@@ -2314,4 +3059,4 @@ type ViewportFitShiftParam = {
2314
3059
  bottom?: number;
2315
3060
  };
2316
3061
 
2317
- export { type ActiveData, type BaseFormProperty, Box2, type CreateOperation, type DeleteOperation, type GizmoType, type ItemCreateInfo, ItemOrderAction, type NullCreateInfo, type Operation, type PageData, type PageFormTypedProperty, type PageProperty, SDK, type SDKEvents, type SDKInputParam, type SDKOptions, type SetItemPropertyValueParam, type SpecificPageFormProps, type SpriteCreateInfo, type SpriteFormProperty, type TextCreateInfo, type TextFormProperty, type UpdateOperation, Vector2, type VideoCreateInfo, type VideoFormProperty, type ViewItem, type ViewItemTypedProperty, type ViewParam, type ViewProperty };
3062
+ export { type ActiveData, type BaseFormProperty, BaseItem, Box2, type CreateOperation, type DeleteOperation, type GizmoType, type ItemCreateInfo, ItemOrderAction, type NullCreateInfo, NullItem, type NullItemOptions, type Operation, type PageData, type PageFormTypedProperty, type PageProperty, SDK, type SDKEvents, type SDKInputParam, type SDKItem$1 as SDKItem, type SDKItemOptions, type SDKOptions, type SetItemPropertyValueParam, type SpecificPageFormProps, type SpriteCreateInfo, type SpriteFormProperty, SpriteItem, type SpriteItemOptions, type TextCreateInfo, type TextFormProperty, TextItem, type TextItemOptions, type UpdateOperation, Vector2, type VideoCreateInfo, type VideoFormProperty, VideoItem, type VideoItemOptions, type ViewItemTypedProperty, type ViewParam, type ViewProperty, createSDKItem, createSDKItemFromPlayerItem, isBaseItem, isNullItem, isSpriteItem, isTextItem, isVideoItem };