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

package/dist/2d/selection/snap-manager.d.ts

@@ -0,0 +1,130 @@
+import { Line2, type Box2 } from '@galacean/effects-math/es/extension/index';
+import { Vector2 } from '../math';
+import type { SnapConfig } from '../configs/types';
+import type { VFXItem } from '@galacean/effects';
+import type { GizmoOwner } from '../gizmo-owner';
+/** 位移吸附结果。 */
+export type TranslationSnapResult = {
+    /** x 方向吸附距离 */
+    x?: number;
+    /** y 方向吸附距离 */
+    y?: number;
+    /** x 方向点吸附信息 */
+    xPoints?: TranslationPointSnapTarget[];
+    /** y 方向点吸附信息 */
+    yPoints?: TranslationPointSnapTarget[];
+};
+/** 平移点吸附信息。 */
+export type TranslationPointSnapTarget = {
+    /** 包围盒点 */
+    point: Vector2;
+    /** 吸附点 */
+    targets: Vector2[];
+};
+/** 管理选区吸附目标、修正量和对齐提示。 */
+export declare class SnapManager {
+    /** 当前吸附结果。距离为未吸附位置减目标位置，调用方应减去该值。 */
+    result: TranslationSnapResult;
+    private readonly owner;
+    /** 吸附提示线集合。 */
+    private results;
+    /** 当前拖拽会话缓存的吸附目标。 */
+    private targetBoxes;
+    /** 本帧每轴选中的最近候选。 */
+    private axisSelections;
+    /** 本帧尚未施加吸附修正的选区包围盒。 */
+    private sourceBox;
+    /**
+     * @param owner Gizmo 宿主
+     */
+    constructor(owner: GizmoOwner);
+    /** 是否启用吸附。 */
+    get enabled(): boolean;
+    /** 当前吸附配置。 */
+    get config(): Readonly<SnapConfig>;
+    /**
+     * 缓存一次选区交互使用的吸附目标。
+     * @param items 场景元素
+     * @param selectedItems 当前选中元素
+     * @param containerSize 画布容器尺寸
+     */
+    cacheSnapTargetsForSelection(items: readonly VFXItem[], selectedItems: readonly VFXItem[], containerSize: Vector2): void;
+    /**
+     * 缓存视图空间中的吸附目标包围盒。
+     * @param boxes 吸附目标包围盒
+     */
+    cacheSnapTargetBoxes(boxes: readonly Box2[]): void;
+    /** 清空当前拖拽会话的吸附目标缓存。 */
+    clearCache(): void;
+    /** @returns 当前缓存的吸附目标包围盒。 */
+    getSnapTargetBoxes(): readonly Box2[];
+    /** @returns 当前吸附目标的角点和中心点。 */
+    getSnapTargetPoints(): Vector2[];
+    /**
+     * 包围盒位移吸附。每轴分别选择最近的边、中心或等距间隔候选。
+     * @param shift 本次原始偏移值
+     * @param box 当前已施加上一帧吸附修正的包围盒
+     * @param otherBoxes 吸附包围盒
+     * @param xEnabled 是否进行 x 轴吸附
+     * @param yEnabled 是否进行 y 轴吸附
+     */
+    prepareBox(shift: Vector2, box: Box2, otherBoxes?: readonly Box2[], xEnabled?: boolean, yEnabled?: boolean): void;
+    /**
+     * 点位移吸附。x/y 两轴独立选择最近目标。
+     * @param shift 本次原始偏移值
+     * @param point 当前已施加上一帧吸附修正的点
+     * @param otherPoints 吸附点集合
+     * @param xEnabled 是否进行 x 轴吸附
+     * @param yEnabled 是否进行 y 轴吸附
+     */
+    preparePoint(shift: Vector2, point: Vector2, otherPoints?: readonly Vector2[], xEnabled?: boolean, yEnabled?: boolean): void;
+    /** @returns 当前视图坐标系中的吸附提示线。 */
+    getSnappingVisualizations(): readonly Line2[];
+    /** 清空吸附修正量和提示，保留目标缓存。 */
+    clearSnappingVisualizations(): void;
+    /** 清空全部吸附状态。 */
+    reset(): void;
+    private update;
+    /** 判断元素自身或任一祖先是否属于当前选区。 */
+    private isSelectedOrDescendant;
+    /** 收集当前选区的全部祖先，避免容器成为自身内容的吸附目标。 */
+    private getAncestorIdSet;
+    /** 获取元素所在的最近吸附作用域；作用域元素自身属于外层。 */
+    private getNearestSnapScopeId;
+    /** 获取整个选区共同所在的最近吸附作用域。 */
+    private getCommonSnapScopeId;
+    /** 画板和动效容器都会隔离内外吸附候选。 */
+    private isSnapScopeItem;
+    /** 比较一个目标包围盒的 min / center / max 锚点。 */
+    private considerBoxAlignment;
+    /**
+     * 添加等距候选：在现有 gap 中居中，或在 gap 两端复制相同间距。
+     */
+    private considerGapSnaps;
+    /** 只保留阈值内最近的候选；同一修正量的命中全部合并用于渲染。 */
+    private considerAxisCandidate;
+    /** 将内部轴命中发布到兼容的 TranslationSnapResult。 */
+    private publishResult;
+    /** 生成贯穿选区和全部命中目标完整范围的对齐线，并标记参与边段的端点。 */
+    private appendAlignmentLines;
+    private appendSnapMarker;
+    /** 创建位于指定吸附轴和正交轴坐标上的点。 */
+    private createAxisPoint;
+    /** 把等距 gap 绘制为间距线。 */
+    private appendGapLines;
+    /** 构造两个相邻包围盒之间的 gap 提示。 */
+    private createGapSegment;
+    /** 把包围盒沿单轴移动到指定 min 坐标。 */
+    private moveBoxAlongAxis;
+    /** 判断两个包围盒在指定轴上的投影是否相交或相切。 */
+    private rangesOverlap;
+    private pointsEqual;
+    /** 合并共享同一屏幕坐标的吸附锚点。 */
+    private deduplicatePoints;
+    /** 排除被第三个目标占据的非相邻 gap。 */
+    private hasInterveningBox;
+    /** 去掉由多组等价命中生成的重复线段。 */
+    private deduplicateLines;
+    /** 清空本帧求解与渲染状态。 */
+    private clearFrameState;
+}

package/dist/2d/text/index.d.ts

@@ -0,0 +1,2 @@
+export { TextEditSession } from './text-edit-session';
+export type { TextEditActivation } from './text-edit-session';

package/dist/2d/text/text-caret-mapper.d.ts

@@ -0,0 +1,61 @@
+/** 视图坐标点。 */
+export type ViewPoint = {
+    /** X 坐标。 */
+    x: number;
+    /** Y 坐标。 */
+    y: number;
+};
+/** 文本插入点计算所需的 DOM 布局样式。 */
+export type TextCaretLayout = {
+    /** 文本框左坐标。 */
+    left: number;
+    /** 文本框上坐标。 */
+    top: number;
+    /** 文本框宽度。 */
+    width: number;
+    /** 文本框高度。 */
+    height: number;
+    /** 文本框旋转弧度。 */
+    rotation: number;
+    /** 文本内容。 */
+    text: string;
+    /** 字体。 */
+    fontFamily: string;
+    /** 字号。 */
+    fontSize: number;
+    /** 字重。 */
+    fontWeight: string | number;
+    /** 字间距。 */
+    letterSpacing: number;
+    /** 行高。 */
+    lineHeight: number;
+    /** 文本对齐方式。 */
+    textAlign: 'left' | 'center' | 'right';
+    /** 是否保持单词完整换行。 */
+    keepWordIntact: boolean;
+};
+/** 使用浏览器文本布局将视图坐标映射为文本插入点。 */
+export declare class TextCaretMapper {
+    private layout;
+    private layoutKey;
+    private caretPositions;
+    /** 清除当前布局。 */
+    reset(): void;
+    /**
+     * 同步文本框样式并按需重新测量插入点。
+     * @param style 文本框布局样式
+     */
+    sync(style: TextCaretLayout): void;
+    /**
+     * 查找最接近视图坐标的文本插入点。
+     * @param point 视图坐标
+     * @returns 文本偏移；布局尚未同步时返回 undefined
+     */
+    resolve(point: ViewPoint): number | undefined;
+    /**
+     * 使用离屏 DOM 测量全部文本插入点。
+     * @param style 文本框布局样式
+     * @returns 插入点位置列表
+     */
+    private measureCaretPositions;
+}

package/dist/2d/text/text-edit-session.d.ts

@@ -0,0 +1,169 @@
+import { EventEmitter, type VFXItem } from '@galacean/effects';
+import type { Box2 } from '@galacean/effects-math/es/extension/index';
+import type { GizmoOwner } from '../gizmo-owner';
+import { type Matrix3 } from '../math';
+import { type ViewPoint } from './text-caret-mapper';
+/** 文本编辑进入后选中全文或仅聚焦输入框。 */
+export type TextEditActivation = 'select' | 'focus';
+/** 文本编辑投影结果。 */
+export type TextResult = TextValidResult | TextEmptyResult;
+/** 有效文本编辑投影。 */
+export type TextValidResult = {
+    /** 结果类型。 */
+    type: 'valid';
+    /** 文本视图包围盒。 */
+    box: Box2;
+    /** 文本局部 Box2 到视图的变换。 */
+    transform: Matrix3;
+};
+/** 空文本编辑投影。 */
+export type TextEmptyResult = {
+    /** 结果类型。 */
+    type: 'empty';
+};
+/** 文本 Gizmo 的交互状态。 */
+export type TextInteractionParam = {
+    /** 当前交互类型。 */
+    type: 'none' | 'edit';
+    /** 文本框激活方式。 */
+    textareaType?: TextEditActivation;
+};
+/** 文本输入事件参数。 */
+export type TextInputPayload = {
+    /** 文本元素 ID。 */
+    itemId: string;
+    /** 输入后的文本。 */
+    text: string;
+    /** 当前字体。 */
+    fontFamily: string;
+};
+/** 文本编辑会话事件参数。 */
+type TextEditSessionEvents = {
+    /** 文本输入事件。 */
+    textInput: [TextInputPayload];
+};
+/** 管理行内文本编辑的 textarea、选区和画布投影。 */
+export declare class TextEditSession extends EventEmitter<TextEditSessionEvents> {
+    /** 文本编辑使用的 DOM 输入框。 */
+    readonly textAreaElement: HTMLTextAreaElement;
+    /** 当前文本交互状态。 */
+    interactionParam: TextInteractionParam;
+    private readonly owner;
+    private _editingItem;
+    private readonly attachedProjections;
+    private disposed;
+    private selectionStart;
+    private selectionEnd;
+    private pointerSelection;
+    private readonly caretMapper;
+    /** 画布接管拖选期间使用的无焦点选区预览。 */
+    private readonly pointerSelectionPreviewElement;
+    private readonly removeTextAreaStyle;
+    private readonly removeTextSelectionStyle;
+    private readonly removePointerSelectionPreviewStyle;
+    /**
+     * 将 DOM 输入同步到文本组件并发出输入事件。
+     * @param event DOM 输入事件。
+     */
+    private readonly handleInput;
+    /**
+     * 隔离输入框键盘事件。
+     * @param event DOM 键盘事件。
+     */
+    private readonly handleKeyDown;
+    /**
+     * 在新的指针选择开始前折叠原 DOM 选区。
+     * @param event DOM 鼠标事件。
+     */
+    private readonly handleMouseDown;
+    /**
+     * 阻止浏览器原生文本拖放。
+     * @param event DOM 拖拽事件。
+     */
+    private readonly handleDragStart;
+    /**
+     * @param owner Gizmo 宿主
+     */
+    constructor(owner: GizmoOwner);
+    /** 当前正在编辑的文本元素。 */
+    get editingItem(): VFXItem | undefined;
+    /** 是否存在正在编辑的文本元素。 */
+    get isEditing(): boolean;
+    /**
+     * 选中当前编辑文本的全部内容，并将焦点交给输入框。
+     *
+     * 输入框尚未完成首次画布投影时会先保存全文选区，待投影打开后恢复。
+     * @returns 当前存在可编辑文本时返回 true
+     */
+    selectAllText(): boolean;
+    /**
+     * 使用当前单选文本元素开始编辑。
+     * @param textareaType 文本框激活方式
+     * @returns 是否成功开始编辑
+     */
+    beginFromCurrentSelection(textareaType: TextEditActivation): boolean;
+    /**
+     * 将当前会话切换到另一个文本元素。
+     * @param item 新的文本元素
+     * @param textareaType 文本框激活方式
+     * @returns 是否切换成功
+     */
+    retarget(item: VFXItem, textareaType?: TextEditActivation): boolean;
+    /**
+     * 开始使用画布指针拖拽选择文本。
+     * @param point 选择起点
+     */
+    beginPointerSelection(point: ViewPoint): void;
+    /**
+     * 更新指针拖拽选择终点。
+     * @param point 当前指针位置
+     */
+    updatePointerSelection(point: ViewPoint): void;
+    /**
+     * 完成指针拖拽选择。
+     * @param point 最终指针位置
+     */
+    finishPointerSelection(point: ViewPoint): void;
+    /** 取消指针拖拽选择。 */
+    cancelPointerSelection(): void;
+    /**
+     * 挂接一个画布文本投影。
+     * @param projection 投影实例
+     */
+    attachProjection(projection: object): void;
+    /**
+     * 脱离一个画布文本投影。
+     * @param projection 投影实例
+     */
+    detachProjection(projection: object): void;
+    /** 结束编辑并释放 DOM 资源和事件监听器。 */
+    dispose(): void;
+    /**
+     * 将 textarea 的位置和排版同步到画布文本投影。
+     * @param result 当前文本投影结果
+     * @param viewScale 视口缩放
+     */
+    syncTextArea(result: TextResult, viewScale: number): void;
+    /** 保存当前 DOM 文本选区。 */
+    private saveSelectionRange;
+    /** 隐藏输入框并停止监听输入。 */
+    private hideTextArea;
+    /**
+     * 同步插入点布局并应用待处理的指针选区。
+     * @param style 文本插入点布局
+     */
+    private syncPointerLayout;
+    /** @returns 是否成功将指针选区应用到 DOM 输入框。 */
+    private applyPointerSelection;
+    /** 绘制画布指针拖选对应的文字高亮。 */
+    private renderPointerSelectionPreview;
+    /** 隐藏画布指针拖选预览。 */
+    private hidePointerSelectionPreview;
+    /**
+     * 将 Effects 文本对齐转换为 CSS 对齐值。
+     * @param textAlign Effects 文本对齐
+     * @returns CSS 文本对齐值
+     */
+    private getTextAlign;
+}
+export {};

package/dist/2d/viewport/coordinates.d.ts

@@ -0,0 +1,89 @@
+import type { VFXItem } from '@galacean/effects';
+import type { Euler } from '../math';
+import { Matrix4, Vector2, Vector3 } from '../math';
+import { Plane } from '@galacean/effects-math/es/extension/index';
+/**
+ * 将世界坐标转换为视图坐标。
+ * @param point 世界坐标
+ * @param item 播放器元素
+ * @param containerSize 视图容器大小
+ * @returns 视图坐标
+ */
+export declare function projectPoint(point: Vector3, item: VFXItem, containerSize: Vector2): Vector2;
+/**
+ * 视图坐标转 NDC 标准化坐标（范围 [-1, 1]）。
+ * @param point 视图坐标
+ * @param containerSize 视图容器大小
+ * @returns NDC 坐标
+ */
+export declare function viewPositionToNDC(point: Vector2, containerSize: Vector2): Vector2;
+/**
+ * 视图大小转 NDC 视图大小。
+ * @param viewSize 视图大小
+ * @param containerSize 视图容器大小
+ * @returns NDC 视图大小
+ */
+export declare function viewSizeToNDC(viewSize: Vector2, containerSize: Vector2): Vector2;
+/**
+ * NDC 大小转视图大小。
+ * @param ndcSize NDC 大小
+ * @param containerSize 视图容器大小
+ * @returns 视图大小
+ */
+export declare function ndcSizeToViewSize(ndcSize: Vector2, containerSize: Vector2): Vector2;
+/**
+ * 视图坐标转世界坐标（经 NDC 构造射线并与交互平面求交）。
+ * @param viewPoint 视图坐标
+ * @param cameraInfo 相机信息
+ * @param plane 交互平面
+ * @param containerSize 视图容器大小
+ * @returns 世界坐标
+ */
+export declare function viewPositionToWorld(viewPoint: Vector2, cameraInfo: {
+    position: Vector3;
+    matrix: Matrix4;
+}, plane: Plane, containerSize: Vector2): Vector3 | undefined;
+/**
+ * 视图尺寸对应的世界尺寸（经射线碰撞换算）。
+ * @param viewSize 视图尺寸
+ * @param containerSize 容器尺寸
+ * @param item 播放器元素
+ * @param cameraInfo 相机位置与逆视投影矩阵
+ * @param plane 交互平面
+ * @returns 世界尺寸
+ */
+export declare function viewSizeToWorld(viewSize: Vector2, containerSize: Vector2, item: VFXItem, cameraInfo: {
+    position: Vector3;
+    matrix: Matrix4;
+}, plane: Plane): Vector3;
+/**
+ * 世界尺寸转视图尺寸。
+ * @param worldSize 世界尺寸
+ * @param containerSize 视图容器大小
+ * @param item 播放器元素
+ * @returns 视图尺寸
+ */
+export declare function worldSizeToViewSize(worldSize: Vector2, containerSize: Vector2, item: VFXItem): Vector2;
+/**
+ * 视图尺寸转像素尺寸。
+ * @param viewSize 视图尺寸
+ * @param viewportScale 视口缩放
+ * @returns 像素尺寸
+ */
+export declare function viewSizeToPixel(viewSize: Vector2, viewportScale: number): Vector2;
+/**
+ * 视图坐标转像素坐标。
+ * @param viewPosition 视图坐标（像素，左上原点）
+ * @param containerSize 视图容器大小
+ * @param viewportScale 视口缩放
+ * @param viewportTranslation NDC 单位的视口平移
+ * @returns 像素坐标
+ */
+export declare function viewPositionToPixel(viewPosition: Vector2, containerSize: Vector2, viewportScale: number, viewportTranslation: Vector2): Vector2;
+/**
+ * 构造交互平面。
+ * @param position 平面位置
+ * @param rotation 平面旋转
+ * @returns 交互平面
+ */
+export declare function createInteractionPlane(position: Vector3, rotation: Euler): Plane;

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

@@ -0,0 +1,108 @@
+import { InputEventMouseMotion, type InputEventKey, type InputEventMouseButton, type Engine } from '@galacean/effects';
+import { Control } from '@galacean/effects-plugin-gui';
+import { Vector2 } from '../math';
+/** 维护画布输入状态并将绘制和交互事件转发给 Gizmo 层。 */
+export declare class GizmoViewport extends Control {
+    /** 鼠标进入回调。 */
+    onMouseEnterCallback: ((location: Vector2) => void) | null;
+    /** 鼠标悬停移动回调。 */
+    onMouseMoveCallback: ((event: InputEventMouseMotion) => void) | null;
+    /** 鼠标拖拽回调。 */
+    onMouseDragCallback: ((event: InputEventMouseMotion) => void) | null;
+    /** 鼠标离开回调。 */
+    onMouseLeaveCallback: (() => void) | null;
+    /** 鼠标滚轮回调。 */
+    onMouseWheelCallback: ((event: InputEventMouseButton) => void) | null;
+    /** 鼠标按下回调。 */
+    onMouseDownCallback: ((event: InputEventMouseButton) => void) | null;
+    /** 鼠标抬起回调。 */
+    onMouseUpCallback: ((event: InputEventMouseButton) => void) | null;
+    /** 键盘按下回调。 */
+    onKeyDownCallback: ((event: InputEventKey) => void) | null;
+    /** 键盘抬起回调。 */
+    onKeyUpCallback: ((event: InputEventKey) => void) | null;
+    /** 每帧更新回调。 */
+    onUpdateCallback: (() => void) | null;
+    /** 绘制回调。 */
+    drawCallBack: (() => void) | null;
+    private readonly mousePosition;
+    private readonly globalMousePosition;
+    private readonly dragStart;
+    private mouseInside;
+    private mouseButtonMask;
+    private dragThresholdState;
+    private shiftPressed;
+    private altPressed;
+    private metaPressed;
+    private ctrlPressed;
+    /**
+     * @param engine Effects 引擎实例
+     */
+    constructor(engine: Engine);
+    /**
+     * 在每帧更新时触发 Gizmo 更新回调。
+     * @param _deltaTime 帧间隔
+     */
+    update(_deltaTime: number): void;
+    /** 触发 Gizmo 绘制回调。 */
+    draw(): void;
+    /**
+     * 记录鼠标进入位置并转发事件。
+     * @param location 鼠标本地坐标
+     */
+    onMouseEnter(location: Vector2): void;
+    /**
+     * 更新输入状态，并按按键状态分发移动或拖拽事件。
+     * @param event 鼠标移动事件
+     */
+    onMouseMove(event: InputEventMouseMotion): void;
+    /** 记录鼠标离开并转发事件。 */
+    onMouseLeave(): void;
+    /**
+     * 更新输入状态并转发滚轮事件。
+     * @param event 鼠标滚轮事件
+     */
+    onMouseWheel(event: InputEventMouseButton): void;
+    /**
+     * 开始按键会话并记录拖拽起点。
+     * @param event 鼠标按下事件
+     */
+    onMouseDown(event: InputEventMouseButton): void;
+    /**
+     * 结束按键会话并重置拖拽阈值。
+     * @param event 鼠标抬起事件
+     */
+    onMouseUp(event: InputEventMouseButton): void;
+    /**
+     * 更新修饰键状态并转发键盘按下事件。
+     * @param event 键盘按下事件
+     */
+    onKeyDown(event: InputEventKey): void;
+    /**
+     * 更新修饰键状态并转发键盘抬起事件。
+     * @param event 键盘抬起事件
+     */
+    onKeyUp(event: InputEventKey): void;
+    /** @returns 当前鼠标本地坐标。 */
+    getMousePosition(): Vector2;
+    /** @returns 鼠标是否位于控件内。 */
+    isMouseInside(): boolean;
+    /** @returns 当前是否有鼠标按钮按下。 */
+    isMouseButtonPressed(): boolean;
+    /** @returns 当前按键会话是否已越过拖拽阈值。 */
+    hasCrossedDragThreshold(): boolean;
+    /** @returns 使用当前输入快照创建的鼠标移动事件。 */
+    createMouseEventAtCurrentPosition(): InputEventMouseMotion;
+    /** 释放回调和输入状态。 */
+    onDestroy(): void;
+    /**
+     * 记录鼠标位置与修饰键状态。
+     * @param event 鼠标事件
+     */
+    private recordMouseInput;
+    /**
+     * 记录修饰键状态。
+     * @param event 带修饰键的输入事件
+     */
+    private recordModifiers;
+}

package/dist/2d/viewport/index.d.ts

@@ -0,0 +1,6 @@
+export * from './coordinates';
+export * from './viewport-operations';
+export * from './viewport-utils';
+export * from './viewport-navigation-controller';
+export { getViewportTranslationRange } from './viewport-range';
+export type { ViewportNavigationRange } from './types';

package/dist/2d/viewport/types.d.ts

@@ -0,0 +1,11 @@
+import type { Vector2 } from '../math';
+import type { Box2 } from '@galacean/effects-math/es/extension/index';
+/** 视口导航的缩放与平移边界。未提供的平移边界表示不设限。 */
+export type ViewportNavigationRange = {
+    minScale?: number;
+    maxScale?: number;
+    minTranslation?: Vector2;
+    maxTranslation?: Vector2;
+    /** 相对视口中心、scale=1 时的内容边界；提供时按当前缩放动态计算平移范围。 */
+    translationBounds?: Box2;
+};

package/dist/2d/viewport/viewport-navigation-controller.d.ts

@@ -0,0 +1,110 @@
+import { EventEmitter, type InputEventMouseButton } from '@galacean/effects';
+import { Vector2 } from '../math';
+import type { ViewportNavigationRange } from './types';
+import type { ViewportNavigationConfig } from '../configs/types';
+import type { GizmoOwner } from '../gizmo-owner';
+/** 视口平移或缩放后的相机快照。 */
+export type ViewportParam = {
+    /** 视口缩放。 */
+    scale: number;
+    /** 视口平移。 */
+    translation: Vector2;
+    /** 本次变换中心。 */
+    center: Vector2;
+};
+/** 视口导航操作来源。 */
+export type ViewportNavigationSource = 'hand-pan' | 'wheel-pan' | 'wheel-zoom' | 'pinch-zoom';
+/** 带操作来源的视口变更快照。 */
+export type ViewportNavigationChange = ViewportParam & {
+    /** 触发视口变更的操作。 */
+    source: ViewportNavigationSource;
+};
+/** 视口导航控制器事件参数。 */
+export type ViewportNavigationEvents = {
+    /** 视口变更事件。 */
+    change: [ViewportNavigationChange];
+};
+/** 统一处理手形工具和滚轮触发的视口平移与缩放。 */
+export declare class ViewportNavigationController extends EventEmitter<ViewportNavigationEvents> {
+    private readonly owner;
+    private minScale;
+    private maxScale;
+    private minTranslation;
+    private maxTranslation;
+    private translationBounds?;
+    /**
+     * @param owner Gizmo 宿主
+     */
+    constructor(owner: GizmoOwner);
+    /** 当前视口导航配置。 */
+    get config(): Readonly<ViewportNavigationConfig>;
+    /** 当前 Effects 引擎。 */
+    private get engine();
+    /**
+     * 设置允许的视口缩放范围。
+     * @param minScale 最小缩放
+     * @param maxScale 最大缩放
+     */
+    setScaleRange(minScale: number, maxScale: number): void;
+    /**
+     * 设置视口缩放和平移范围。
+     * @param range 视口边界；未提供的缩放边界保留当前值，未提供的平移边界表示不设限
+     */
+    setViewportRange(range: ViewportNavigationRange): void;
+    /** 恢复默认视口范围。 */
+    resetViewportRange(): void;
+    /** 当前视口范围快照。 */
+    get viewportRange(): ViewportNavigationRange;
+    /**
+     * 根据滚轮来源和修饰键执行平移或缩放。
+     * @param event 滚轮事件
+     * @param _pointerCaptured 指针是否已被捕获
+     * @returns 视口是否发生变化
+     */
+    handleWheel(event: InputEventMouseButton, _pointerCaptured: boolean): boolean;
+    /**
+     * 按视图像素增量平移视口。
+     * @param delta 视图像素位移
+     * @param center 操作中心
+     * @param source 操作来源
+     * @returns 视口是否发生变化
+     */
+    panByViewDelta(delta: Vector2, center: Vector2, source: 'hand-pan' | 'wheel-pan'): boolean;
+    /**
+     * 按倍率缩放视口。
+     * @param factor 缩放倍率
+     * @param center 缩放中心
+     * @param source 操作来源
+     * @returns 视口是否发生变化
+     */
+    zoomByFactor(factor: number, center: Vector2, source: 'wheel-zoom' | 'pinch-zoom'): boolean;
+    /** 释放事件监听器。 */
+    dispose(): void;
+    /**
+     * 根据显式配置和修饰键确定导航模式。
+     * @param event 滚轮事件
+     * @returns 滚轮导航模式
+     */
+    private classifyWheel;
+    /**
+     * 将方向型滚轮事件转换为视图位移。
+     * @param event 滚轮事件
+     * @returns 视图位移
+     */
+    private normalizeWheel;
+    /**
+     * 发出当前视口快照。
+     * @param center 操作中心
+     * @param source 操作来源
+     */
+    private emitChange;
+    /** @returns 当前画布容器尺寸。 */
+    private containerSize;
+    /** 将当前相机平移收敛到范围内。 */
+    private clampCurrentTranslation;
+    /** 将当前相机缩放和平移收敛到范围内。 */
+    private clampCurrentViewport;
+    private isTranslationRangeValid;
+    /** @returns 是否存在可操作的画布容器和相机。 */
+    private hasViewport;
+}