fabric-warpvas/dist/modes/warp.class.d.ts

This JavaScript library helps you efficiently build image warping tools on Fabric.js

import { FabricObject, Line } from 'fabric/es';
import { Warpvas } from 'warpvas';
import type { FabricWarpvas } from '../core/fabric-warpvas.class';
import BaseMode, { BaseOptions } from './base.class';
/**
 * 变形区域的顶点类型枚举
 *
 * 用于标识变形区域四个角的位置。
 *
 * @enum {string}
 */
export declare enum VertexType {
    /** 左上角顶点 */
    TOP_LEFT = "tl",
    /** 右上角顶点 */
    TOP_RIGHT = "tr",
    /** 左下角顶点 */
    BOTTOM_LEFT = "bl",
    /** 右下角顶点 */
    BOTTOM_RIGHT = "br"
}
/**
 * 变形模式可自定义对象类型
 */
type WarpObjects = {
    /**
     * 可配置顶点控制点的方法
     * @param object - 默认的控制点对象
     * @returns 作为顶点控制点对象的fabric元素对象，可使用默认对象以外的新对象
     */
    control: (object: FabricObject) => FabricObject;
    /**
     * 可配置扭曲控制点的方法
     * @param object - 默认的控制点对象
     * @returns 作为扭曲控制点对象的fabric元素对象，可使用默认对象以外的新对象
     */
    curveControl: (object: FabricObject) => FabricObject;
    /**
     * 可配置插入控制点的方法
     * @param object - 默认的控制点对象
     * @returns 作为插入控制点对象的fabric元素对象，可使用默认对象以外的新对象
     */
    insertControl: (object: FabricObject) => FabricObject;
    /**
     * 可配置顶点控制点与扭曲控制点之间连线样式的方法
     * @param line - 连线对象
     */
    line: (line: Line) => void;
};
/**
 * 变形模式配置
 */
type WarpOptions = BaseOptions<{
    /**
     * 是否启用网格分割功能
     *
     * 启用后：
     * - 可以点击变形图像实现内部添加新的分割点
     * - 可以选中内部分割点并点击 Delete/Backspace 键删除
     * - 适用于需要更精细变形控制的场景
     *
     * @default true
     */
    enableGridSplit?: boolean;
    /**
     * 是否启用移动约束按键，默认禁用（None）
     *
     * 启用后：
     * - 移动控点时按键限制移动方向为水平或垂直
     * - 移动方向取决于拖拽距离较大的方向
     *
     * @default 'None' 表示禁用移动约束
     */
    enableConstraintKey?: string | 'none';
}>;
/**
 * 扭曲变形模式类
 *
 * 提供图像的扭曲变形功能。
 *
 * 交互说明：
 * 1. 拖动交互点实现扭曲点的变换，支持框选
 * 2. 点击内部区域，会出现临时交互点
 * 3. 拖动临时交互点实现整体移动
 * 4. 点击临时交互点实现变形区域分割
 * 5. 选中交互点后点击Delete实现扭曲点的删除（PS：四个原始对角交互点无法被删除）
 * 6. 按住设置按键限制控制点拖动只向水平或垂直方向移动（当 enableConstraintKey 设置为具体按键时生效）
 *

 * @example
 * ```typescript
 * import { fabric } from 'fabric';
 * import { FabricWarpvas } from 'fabric-warpvas';
 * import Warp from 'fabric-warpvas/modes/warp';
 *
 * // 创建 fabricWarpvas 实例
 * const canvas = new fabric.Canvas('canvas');
 * const fabricWarpvas = new FabricWarpvas(canvas);
 *
 * // 创建扭曲模式
 * const warp = new Warp({ themeColor: '#FF0000' });  // 交互元素使用红色主题色
 *
 * // 自定义模式中的控制点样式
 * warp.registerStyleSetter('control', (control) => {
 *     control.set({
 *       radius: 10,
 *       fill: 'blue',
 *       stroke: 'white'
 *     });
 *     return control;
 * });
 *
 * // 进入变形态
 * fabricWarpvas.enterEditing(image, null, warp);
 * ```
 *
 * @remarks 原始对象默认保持可见，需要手动隐藏
 *
 * @see
 * - {@link BaseMode} 变形模式基类
 * - {@link FabricWarpvas} 主要功能类
 */
declare class Warp extends BaseMode<WarpObjects, WarpOptions> {
    /**
     * 变形模式的唯一标识名称
     */
    name: string;
    /**
     * 模式配置
     */
    options: Required<WarpOptions>;
    /**
     * 控制点位置映射表
     *
     * 存储控制点与其位置信息的映射关系：
     * - 键：由 "行-列" 组成的字符串，如 "0-1" 表示第0行第1列
     * - 值：{@link Control} 类型的控制点数据结构
     */
    private _positionControlMap;
    /**
     * 当前激活的插入控制点
     *
     * 用于临时存储当前正在交互的插入点对象。
     * 当用户点击贴图内部时创建，确认插入或取消时清除。
     */
    private _insertControlObject;
    /**
     * 创建扭曲变形模式实例
     *
     * 初始化一个新的扭曲变形模式。
     */
    constructor(options?: Partial<WarpOptions>);
    /**
     * 计算贴图的分割点坐标
     *
     * 根据贴图的网格曲线计算分割点的位置坐标。该方法会：
     * 1. 遍历所有网格单元
     * 2. 计算横向和纵向曲线的交点
     * 3. 生成用于变形的控制点网格
     *
     * @param warpvas - 需要进行变形的贴图对象
     * @returns {Coord[][][]} 返回三维数组：
     * - 第一维：行索引
     * - 第二维：列索引
     * - 第三维：分割点坐标 {x, y}
     */
    static execute(warpvas: Warpvas): Coord[][][];
    /**
     * 获取所有顶点控制点
     *
     * 返回所有用于控制贴图顶点的主控制点对象列表。
     * 这些控制点位于贴图的四个角和边缘分割点位置。
     *
     * @returns {FabricObject[]} 顶点控制点对象数组
     */
    get controlObjects(): FabricObject[];
    /**
     * 获取所有曲线控制点
     *
     * 返回所有用于调整曲线形状的次要控制点对象列表。
     * 这些控制点位于边缘曲线的中间位置，用于调整曲线的弯曲程度。
     *
     * @returns {FabricObject[]} 曲线控制点对象数组
     */
    get subControlObjects(): FabricObject[];
    /**
     * 获取当前激活的插入控制点
     *
     * 返回当前正在交互的插入点对象。
     * 当用户点击贴图内部时会创建此控制点，
     * 用户可以通过点击它来在该位置添加新的分割点。
     *
     * @returns {FabricObject | null} 插入控制点对象，如果不存在则返回 null
     */
    get insertControlObject(): FabricObject | null;
    /**
     * 获取所有控制点连接线
     *
     * 返回所有连接主控制点和曲线控制点的线段对象列表。
     * 这些线段用于可视化控制点之间的关系。
     *
     * @returns {Line[]} 连接线对象数组
     */
    get lineObjects(): Line[];
    /**
     * 执行扭曲变形计算
     *
     * 代理方法，调用静态方法 {@link Warp.execute} 进行实际的扭曲变形计算。
     *
     * @param warpvas - 需要进行扭曲变形的贴图对象
     * @returns 返回计算后的网格分割点坐标数组
     *
     * @see {@link Warp.execute} 具体实现细节
     */
    execute(warpvas: Warpvas): Coord[][][];
    /**
     * 在脏渲染后执行的钩子，用于渲染变形的交互元素
     *
     * @param fabricWarpvas - FabricWarpvas 实例，提供操作接口
     * @returns 清理函数，用于移除所有控制元素和事件监听
     *
     * @example
     * ```typescript
     * // 进入交互会自动调用
     * const cleanup = warp.dirtyRender(fabricWarpvas);
     *
     * // 退出交互时清理
     * cleanup();
     * ```
     */
    dirtyRender(fabricWarpvas: FabricWarpvas): (() => void) | undefined;
    /**
     * 创建变形模式默认的顶点控制点对象
     *
     * 创建一个圆形的控制点，用于作为顶点控制点提供拖拽变形的功能。
     *
     * @returns {fabric.Circle} 返回 Fabric.js 圆形对象
     */
    private _createDefaultControl;
    /**
     * 创建变形模式默认的曲线控制点
     *
     * 创建一个矩形的控制点，用于调整边界曲线形状，显示在曲线的中间位置。
     *
     * @returns {fabric.Rect} 返回 Fabric.js 矩形对象
     */
    private _createDefaultCurveControl;
    /**
     * 创建变形模式默认的中间临时点对象
     *
     * 创建一个圆形的控制点，用于标识可插入新控制点位置的指示器，点击后在该位置添加新的分割点，
     * 另外也可作为整体拓展的控制点。
     *
     * @returns {fabric.Circle} 返回 Fabric.js 圆形对象
     */
    private _createDefaultInsertControl;
}
export default Warp;