@galacean/effects-plugin-editor-gizmo 2.10.4 → 2.11.0-alpha.1

package/dist/2d/gizmo-type.d.ts

@@ -0,0 +1,37 @@
+/** 内置 Gizmo 的稳定类型标识。 */
+export declare enum GizmoType {
+    /** 空类型。 */
+    NULL = "null",
+    /** 视口平移工具。 */
+    HAND = "hand",
+    /** 选区切换工具。 */
+    CHANGE_SELECTION = "change-selection",
+    /** 选区移动工具。 */
+    MOVE_SELECTION = "move-selection",
+    /** 框选工具。 */
+    BOX_SELECTION = "box-selection",
+    /** 点击与拖拽仲裁工具。 */
+    CLICK_DRAG_MULTIPLEX = "click-drag-multiplex",
+    /** 角点旋转工具。 */
+    CORNER_ROTATION = "corner-rotation",
+    /** 选区缩放工具。 */
+    RESIZE_SELECTION = "resize-selection",
+    /** 视口覆盖层。 */
+    VIEWPORT_OVERLAY = "viewport-overlay",
+    /** 图片裁切工具。 */
+    IMAGE_CUT = "image-cut",
+    /** 文本编辑工具。 */
+    TEXT = "text",
+    /** 蒙版编辑工具。 */
+    MASK = "mask",
+    /** 加载状态工具。 */
+    LOADING = "loading",
+    /** 图片扩边工具。 */
+    IMAGE_EXPAND = "image-expand",
+    /** 精准文字编辑工具。 */
+    SPRITE_TEXT_EDIT = "sprite-text-edit",
+    /** 媒体图标工具。 */
+    ICON = "icon",
+    /** 元素创建工具。 */
+    ITEM_CREATE = "item-create"
+}

package/dist/2d/gizmo.d.ts

@@ -0,0 +1,60 @@
+import type { InputEventKey, InputEventMouseButton, InputEventMouseMotion } from '@galacean/effects';
+import type { Control } from '@galacean/effects-plugin-gui';
+import type { GizmoOwner } from './gizmo-owner';
+/** 定义 Gizmo 的绘制、鼠标和键盘交互生命周期。 */
+export declare abstract class Gizmo {
+    /** Gizmo 类型标识（子类必须实现）。 */
+    abstract readonly type: string;
+    /** Gizmo 共享状态的宿主契约。 */
+    protected readonly _owner: GizmoOwner;
+    /**
+     * 创建 Gizmo。
+     * @param owner 宿主契约
+     */
+    constructor(owner: GizmoOwner);
+    /** 释放资源。子类可覆盖清理。 */
+    dispose(): void;
+    /** 在每帧更新时同步内部渲染状态。 */
+    onUpdate(): void;
+    /** 在输入候选仲裁前更新命中状态。 */
+    prepareForDispatch(): void;
+    /** @returns 是否需要越过拖拽阈值后才接收拖拽事件。 */
+    requiresDragThreshold(): boolean;
+    /**
+     * 绘制 Gizmo 视觉元素。
+     * @param _control 绘制控制器
+     */
+    draw(_control: Control): void;
+    /**
+     * 处理鼠标按下并按需接管交互会话。
+     * @param _event 鼠标按下事件
+     */
+    onMouseDown(_event: InputEventMouseButton): void;
+    /**
+     * 处理鼠标抬起并结束交互会话。
+     * @param _event 鼠标抬起事件
+     */
+    onMouseUp(_event: InputEventMouseButton): void;
+    /**
+     * 处理无按键状态的鼠标移动。
+     * @param _event 鼠标移动事件
+     */
+    onMouseMove(_event: InputEventMouseMotion): void;
+    /**
+     * 处理越过距离阈值后的鼠标拖拽。
+     * @param _event 鼠标拖拽事件
+     */
+    onMouseDrag(_event: InputEventMouseMotion): void;
+    /** 处理鼠标离开并清理悬停状态。 */
+    onMouseLeave(): void;
+    /**
+     * 处理键盘按下。
+     * @param _event 键盘按下事件
+     */
+    onKeyDown(_event: InputEventKey): void;
+    /**
+     * 处理键盘抬起。
+     * @param _event 键盘抬起事件
+     */
+    onKeyUp(_event: InputEventKey): void;
+}

package/dist/2d/gizmos/box-selection-gizmo.d.ts

@@ -0,0 +1,67 @@
+import { type InputEventMouseButton, type InputEventMouseMotion } from '@galacean/effects';
+import type { Control } from '@galacean/effects-plugin-gui';
+import { Gizmo } from '../gizmo';
+import type { GizmoOwner } from '../gizmo-owner';
+import type { SelectionPreviewConfig } from '../configs/types';
+/** 通过拖拽矩形更新选区并绘制框选区域。 */
+export declare class BoxSelectionGizmo extends Gizmo {
+    private readonly deferToHitTarget;
+    readonly type = "box-selection";
+    private readonly overlay;
+    private readonly cursorPoint;
+    private readonly startPoint;
+    private isBoxSelecting;
+    private mouseGrabbed;
+    /**
+     * 创建框选交互。
+     * @param owner Gizmo 宿主。
+     * @param deferToHitTarget 命中已有对象时是否将交互让给其他候选。
+     */
+    constructor(owner: GizmoOwner, deferToHitTarget?: boolean);
+    /** 框选预览配置。 */
+    get config(): Readonly<SelectionPreviewConfig>;
+    /** 当前选区。 */
+    private get selection();
+    /**
+     * 忽略尚未进入拖拽阶段的移动事件。
+     * @param _event 鼠标移动事件。
+     */
+    onMouseMove(_event: InputEventMouseMotion): void;
+    /**
+     * 更新已开始的框选交互。
+     * @param event 鼠标拖拽事件。
+     */
+    onMouseDrag(event: InputEventMouseMotion): void;
+    /**
+     * 在空白区域按下主键时开始框选。
+     * @param event 鼠标按下事件。
+     */
+    onMouseDown(event: InputEventMouseButton): void;
+    /**
+     * 结束框选并提交选择变更。
+     * @param event 鼠标抬起事件。
+     */
+    onMouseUp(event: InputEventMouseButton): void;
+    /**
+     * 绘制当前框选区域。
+     * @param control 绘制控制器。
+     */
+    draw(control: Control): void;
+    /**
+     * 根据当前指针更新框选区域与候选选区。
+     * @param event 鼠标拖拽事件。
+     */
+    private updateGrab;
+    /**
+     * 在选区发生变化时提交操作事件。
+     * @param force 是否强制提交。
+     */
+    private emitMouseUpIfChanged;
+    /**
+     * 判断两个 ID 列表是否按顺序相等。
+     * @param left 左侧 ID 列表。
+     * @param right 右侧 ID 列表。
+     * @returns 是否相等。
+     */
+    private sameIds;
+}

package/dist/2d/gizmos/change-selection-gizmo.d.ts

@@ -0,0 +1,45 @@
+import { Gizmo } from '../gizmo';
+import { type InputEventMouseButton, type InputEventMouseMotion } from '@galacean/effects';
+/** 处理单击、双击和右键选择，并协调与拖拽候选的选择时机。 */
+export declare class ChangeSelectionGizmo extends Gizmo {
+    readonly type = "change-selection";
+    private session;
+    private hoverItemId;
+    /**
+     * 更新悬停目标。
+     * @param event 鼠标移动事件。
+     */
+    onMouseMove(event: InputEventMouseMotion): void;
+    /**
+     * 忽略拖拽阶段的悬停更新。
+     * @param _event 鼠标拖拽事件。
+     */
+    onMouseDrag(_event: InputEventMouseMotion): void;
+    /**
+     * 根据鼠标按键和命中结果开始选择交互。
+     * @param event 鼠标按下事件。
+     */
+    onMouseDown(event: InputEventMouseButton): void;
+    /**
+     * 完成或取消当前选择交互。
+     * @param event 鼠标抬起事件。
+     */
+    onMouseUp(event: InputEventMouseButton): void;
+    /** 释放选择交互状态。 */
+    dispose(): void;
+    /**
+     * 解析按下阶段应提交的选区。
+     * @param event 鼠标按下事件。
+     * @param session 当前按下会话。
+     * @returns 立即提交的选中项 ID；需要延迟或保持选区时返回 undefined。
+     */
+    private resolvePressSelection;
+    /**
+     * 根据右键命中结果更新上下文选区。
+     * @param event 鼠标按下事件。
+     * @returns 选区是否发生变化。
+     */
+    private resolveContextSelection;
+    /** 清除当前按下会话。 */
+    private resetSession;
+}

package/dist/2d/gizmos/click-drag-multiplex-gizmo.d.ts

@@ -0,0 +1,95 @@
+import { Gizmo } from '../gizmo';
+import type { GizmoOwner } from '../gizmo-owner';
+import { InputEventMouseButton, type InputEventMouseMotion } from '@galacean/effects';
+import type { Control } from '@galacean/effects-plugin-gui';
+/** 点击与拖拽候选的仲裁配置。 */
+export type ClickDragMultiplexOptions = {
+    /** 点击阶段的候选列表。 */
+    clickCandidates: Gizmo[];
+    /** 拖拽阶段的候选列表。 */
+    dragCandidates: Gizmo[];
+    /** 标准快捷键按下时优先尝试的拖拽候选。 */
+    auxiliaryBehavior?: Gizmo;
+};
+/** 在同一指针序列中延迟仲裁点击与拖拽候选。 */
+export declare class ClickDragMultiplexGizmo extends Gizmo {
+    readonly type = "click-drag-multiplex";
+    /** 点击阶段的候选列表。 */
+    private readonly clickCandidateList;
+    /** 拖拽阶段的候选列表。 */
+    private readonly dragCandidateList;
+    /** 标准快捷键对应的辅助拖拽候选。 */
+    private readonly auxiliaryBehaviorGizmo;
+    /** 供拖拽候选重放的按下事件快照。 */
+    private downSnapshot;
+    /** 当前拖拽候选胜者。 */
+    private dragWinner;
+    /** 当前点击候选胜者。 */
+    private clickWinner;
+    /**
+     * 创建点击与拖拽仲裁器。
+     * @param owner Gizmo 宿主。
+     * @param options 候选配置。
+     */
+    constructor(owner: GizmoOwner, options: ClickDragMultiplexOptions);
+    /** @returns 点击候选的只读列表。 */
+    clickCandidates(): readonly Gizmo[];
+    /** @returns 拖拽候选的只读列表。 */
+    dragCandidates(): readonly Gizmo[];
+    /** @returns 标准快捷键对应的辅助拖拽候选。 */
+    auxiliaryBehavior(): Gizmo | undefined;
+    /**
+     * 将按下事件交给点击候选并保存事件快照。
+     * @param event 鼠标按下事件。
+     */
+    onMouseDown(event: InputEventMouseButton): void;
+    /**
+     * 将悬停移动事件广播给点击候选。
+     * @param event 鼠标移动事件。
+     */
+    onMouseMove(event: InputEventMouseMotion): void;
+    /**
+     * 解析拖拽胜者并将事件转发给它。
+     * @param event 鼠标拖拽事件。
+     */
+    onMouseDrag(event: InputEventMouseMotion): void;
+    /**
+     * 将抬起事件交给当前胜者。
+     * @param event 鼠标抬起事件。
+     */
+    onMouseUp(event: InputEventMouseButton): void;
+    /** 将每帧更新转发给点击和拖拽候选。 */
+    onUpdate(): void;
+    /**
+     * 按候选优先级绘制所有子 Gizmo。
+     * @param control 绘制控制器。
+     */
+    draw(control: Control): void;
+    /** 释放所有子 Gizmo 和交互快照。 */
+    dispose(): void;
+    /**
+     * 顺序派发按下事件并返回首个接受者。
+     * @param candidates 候选列表。
+     * @param event 鼠标按下事件。
+     * @returns 接受事件的候选。
+     */
+    private invokeMouseDown;
+    /**
+     * 向候选重放按下事件以尝试建立拖拽会话。
+     * @param candidate 待尝试的候选。
+     * @returns 接受事件的拖拽候选。
+     */
+    private resolveDragCandidate;
+    /** @returns 所有受托管的子 Gizmo。 */
+    private allChildren;
+    /** 清除当前点击与拖拽胜者。 */
+    private clearWinners;
+    /**
+     * 调用候选的指定鼠标阶段。
+     * @param candidate 目标候选。
+     * @param event 鼠标事件。
+     * @param phase 事件阶段。
+     * @returns 候选是否接受事件。
+     */
+    private invoke;
+}

package/dist/2d/gizmos/corner-rotation-gizmo.d.ts

@@ -0,0 +1,101 @@
+import { type InputEventMouseButton, type InputEventMouseMotion, type VFXItem } from '@galacean/effects';
+import { type GestureCursorResult } from '../cursor';
+import { Gizmo } from '../gizmo';
+import type { GizmoOwner } from '../gizmo-owner';
+import { GizmoType } from '../gizmo-type';
+import { Vector2 } from '../math';
+import type { ResizeSelectionGizmo } from './resize-selection-gizmo';
+/** 通过选框角点命中区域旋转选中对象。 */
+export declare class CornerRotationGizmo extends Gizmo {
+    private readonly resizeSelection;
+    readonly type: GizmoType;
+    cursorResult: GestureCursorResult;
+    /** 当前指针的视图坐标；拖拽期间按 Control 本地坐标增量推进。 */
+    cursorPoint: Vector2;
+    /** 上一帧指针的 Control 本地坐标。 */
+    lastPoint: Vector2;
+    /** 单次旋转会话累计的 z 轴角度，用于保持旋转光标朝向连续。 */
+    rotationAngle: number;
+    private rotationActive;
+    private anchor;
+    private interactiveDirection;
+    /** 未吸附的累计拖拽角，独立于已应用角度，避免逐帧取整丢失小幅移动。 */
+    private rawRotationAngle;
+    /** pointer down 时选区节点的公共世界角度，用于吸附最终朝向而非单次拖拽增量。 */
+    private initialSelectionAngle;
+    /** pointer down 时冻结的旋转对象，避免拖拽中途换目标。 */
+    private rotationItems;
+    /**
+     * 创建共享选框几何的角旋转交互。
+     * @param owner Gizmo 宿主。
+     * @param resizeSelection 提供选框几何的缩放 Gizmo。
+     */
+    constructor(owner: GizmoOwner, resizeSelection: ResizeSelectionGizmo);
+    /** 当前选中的对象。 */
+    get selectedItems(): VFXItem[];
+    /**
+     * 更新角旋转悬停或正在进行的旋转。
+     * @param event 鼠标移动事件。
+     */
+    onMouseMove(event: InputEventMouseMotion): void;
+    /**
+     * 继续当前角旋转交互。
+     * @param event 鼠标拖拽事件。
+     */
+    onMouseDrag(event: InputEventMouseMotion): void;
+    /**
+     * 在角旋转命中区域按下主键时开始旋转。
+     * @param event 鼠标按下事件。
+     */
+    onMouseDown(event: InputEventMouseButton): void;
+    /**
+     * 结束旋转并提交结果。
+     * @param event 鼠标抬起事件。
+     */
+    onMouseUp(event: InputEventMouseButton): void;
+    /** 清除离开视口后的旋转悬停状态。 */
+    onMouseLeave(): void;
+    /** @returns 当前选区是否支持旋转。 */
+    private isApplicableSelection;
+    /**
+     * 根据指针增量更新累计旋转角度。
+     * @param event 鼠标拖拽事件。
+     * @returns 是否处理了旋转。
+     */
+    private updateRotationDrag;
+    /**
+     * 应用累计旋转角，并在 Shift 按下时吸附角度。
+     * @param event 鼠标拖拽事件。
+     */
+    private applyRotation;
+    /** 重置旋转交互状态。 */
+    private resetOperation;
+    /**
+     * 查找指针命中的角旋转区域。
+     * @param point 指针视口坐标。
+     * @returns 角旋转命中结果。
+     */
+    private findRotationHit;
+    /** @returns 选框在视口中的局部坐标轴。 */
+    private boxLocalAxes;
+    /**
+     * 获取 Shift 吸附使用的初始绝对角度。
+     * 角度来自节点变换，不从选框或子元素包围盒反推；
+     * 多选节点没有公共角度时使用 0°。
+     * @returns 当前选区在视图平面内的初始角度（度）。
+     */
+    private resolveInitialSelectionAngle;
+    /**
+     * 刷新指定位置的旋转悬停状态。
+     * @param point 指针视口坐标。
+     * @returns 角旋转命中结果。
+     */
+    private refreshHover;
+    /**
+     * 更新旋转光标。
+     * @param angle 旋转方向的弧度值。
+     */
+    private setRotationCursor;
+    /** 清除旋转悬停状态。 */
+    private clearHover;
+}

package/dist/2d/gizmos/enter-edit-mode-gizmo.d.ts

@@ -0,0 +1,11 @@
+import { type InputEventMouseButton } from '@galacean/effects';
+import { Gizmo } from '../gizmo';
+/** 识别可编辑元素的双击，并进入对应的编辑模式。 */
+export declare class EnterEditModeGizmo extends Gizmo {
+    readonly type = "enter-edit-mode";
+    /**
+     * 双击当前选中的文本或动效元素时进入对应编辑模式。
+     * @param event 鼠标按下事件
+     */
+    onMouseDown(event: InputEventMouseButton): void;
+}

package/dist/2d/gizmos/hand-gizmo.d.ts

@@ -0,0 +1,67 @@
+import { Gizmo } from '../gizmo';
+import { type GestureCursorResult } from '../cursor';
+import { type InputEventKey, type InputEventMouseButton, type InputEventMouseMotion } from '@galacean/effects';
+/** 通过中键或抓手模式拖拽平移视口。 */
+export declare class HandGizmo extends Gizmo {
+    readonly type = "hand";
+    /** 空格按下时下一次左键拖拽应平移视口。 */
+    private panKeyPressed;
+    /** 当前拖拽会话态（NONE 未建立 / PAN 平移拖拽中）。 */
+    private dragType;
+    /** 上一帧鼠标位置（拖拽平移增量计算用）。 */
+    private lastPoint;
+    /** 当前抓手交互对应的光标。 */
+    get cursorResult(): GestureCursorResult;
+    /** @returns 是否正在平移或等待空格拖拽。 */
+    isPanning(): boolean;
+    /**
+     * 处理空格键按下并进入待平移状态。
+     * @param event 键盘按下事件。
+     */
+    onKeyDown(event: InputEventKey): void;
+    /**
+     * 处理空格键抬起并退出待平移状态。
+     * @param event 键盘抬起事件。
+     */
+    onKeyUp(event: InputEventKey): void;
+    /**
+     * 根据触发键开始视口平移。
+     * @param event 鼠标按下事件。
+     */
+    onMouseDown(event: InputEventMouseButton): void;
+    /**
+     * 更新悬停阶段的视口平移。
+     * @param event 鼠标移动事件。
+     */
+    onMouseMove(event: InputEventMouseMotion): void;
+    /**
+     * 更新拖拽阶段的视口平移。
+     * @param event 鼠标拖拽事件。
+     */
+    onMouseDrag(event: InputEventMouseMotion): void;
+    /**
+     * 结束视口平移。
+     * @param event 鼠标抬起事件。
+     */
+    onMouseUp(event: InputEventMouseButton): void;
+    /** 释放视口平移状态。 */
+    dispose(): void;
+    /**
+     * 处理指针移动并更新光标。
+     * @param event 鼠标移动事件。
+     */
+    private handlePointerMove;
+    /**
+     * 进入视口平移会话。
+     * @param event 鼠标按下事件。
+     */
+    private beginPan;
+    /**
+     * 将鼠标位移应用到视口。
+     * @param event 鼠标移动事件。
+     * @returns 视口是否发生变化。
+     */
+    private pan;
+    /** @returns 结束前是否存在平移会话。 */
+    private endPan;
+}

package/dist/2d/gizmos/icon-gizmo.d.ts

@@ -0,0 +1,107 @@
+import { type InputEventMouseButton, type InputEventMouseMotion } from '@galacean/effects';
+import type { Control } from '@galacean/effects-plugin-gui';
+import { Gizmo } from '../gizmo';
+import type { GizmoOwner } from '../gizmo-owner';
+import { GizmoType } from '../gizmo-type';
+import { type GestureCursorResult } from '../cursor';
+import { Box2 } from '@galacean/effects-math/es/extension/index';
+import { Vector2 } from '../math';
+import type { IconConfig } from '../configs/types';
+/** 辅助渲染 Icon 类型。 */
+export declare enum IconType {
+    /** 视频播放 Icon */
+    VIDEO_PLAY = "video-play",
+    /** 视频生成器 Icon */
+    VIDEO_GENERATOR = "video-generator",
+    /** 图片生成器 Icon */
+    IMAGE_GENERATOR = "image-generator"
+}
+/** 元素辅助 Icon 结果。 */
+export type IconResult = {
+    /** 选中元素 Id */
+    id: string;
+    /** Icon 类型 */
+    type: IconType;
+    /** 包围盒信息 */
+    box: Box2;
+};
+/** 元素辅助 Icon 交互参数。 */
+export type IconInteractionParam = {
+    /** 鼠标悬停的视频元素 ID */
+    hoverVideoId?: string;
+};
+/** 渲染元素辅助 Icon（视频播放按钮、生成器图标等）。 */
+export declare class IconGizmo extends Gizmo {
+    type: GizmoType;
+    results: IconResult[];
+    interactionParam: IconInteractionParam;
+    /** 光标结果（GestureCursorResult） */
+    cursorResult: GestureCursorResult;
+    private configOff?;
+    /** 图标纹理缓存，按 IconType 懒加载。 */
+    private iconTextures;
+    /** 图标纹理加载中的 Promise，避免重复发起加载。 */
+    private iconTexturePromises;
+    /**
+     * 创建元素辅助图标 Gizmo。
+     * @param owner Gizmo 宿主。
+     */
+    constructor(owner: GizmoOwner);
+    /** 当前图标配置。 */
+    get config(): Readonly<IconConfig>;
+    /**
+     * 更新视频播放图标的悬停状态与光标。
+     * @param event 鼠标移动事件。
+     */
+    onMouseMove(event: InputEventMouseMotion): void;
+    /** 清除离开交互层后的图标悬停状态。 */
+    onMouseLeave(): void;
+    /**
+     * 点击视频播放图标时发送播放事件。
+     * @param event 鼠标按下事件。
+     */
+    onMouseDown(event: InputEventMouseButton): void;
+    /** 根据当前指针与图标结果刷新光标。 */
+    refreshCursorResult(): void;
+    /**
+     * 更新悬停视频 ID 与图标结果。
+     * @param mouse 鼠标位置。
+     */
+    refreshVideoIconId(mouse: Vector2): void;
+    /** 刷新所有待绘制的元素辅助图标。 */
+    onUpdate(): void;
+    /**
+     * 绘制视频播放与生成器图标。
+     * @param control 绘制控制器。
+     */
+    draw(control: Control): void;
+    /** 释放配置监听器。 */
+    dispose(): void;
+    /**
+     * 在图标 URL 变化时清除对应纹理缓存。
+     * @param change 图标配置变更。
+     */
+    private onConfigChange;
+    /** 刷新视频播放与生成器图标的绘制结果。 */
+    private refreshResults;
+    /**
+     * 按 IconType 取得图标 URL。
+     * @param type 图标类型
+     * @returns 对应图标 URL，无匹配时返回空字符串
+     */
+    private getIconUrl;
+    /**
+     * 获取图标纹理（懒加载）。命中且未销毁则直接返回；否则发起一次异步加载并返回
+     * undefined（本帧跳过该图标，加载完成后由持续渲染循环自动重绘）。
+     * @param type 图标类型
+     * @param engine effects 引擎实例（取自 control）
+     * @returns 命中且未销毁的缓存纹理；未命中且发起异步加载时返回 undefined
+     */
+    private getIconTexture;
+    /**
+     * 查找鼠标命中的最上层视频对象。
+     * @param mouse 鼠标位置。
+     * @returns 命中视频对象的 ID。
+     */
+    private computeHoverVideoId;
+}