fabric-texture/dist/modes/skew.class.d.ts

This JavaScript library enables fast and efficient image distortion transformations using Canvas 2D.

import { fabric } from 'fabric';
import type { FabricTexture } from '../fabric-texture.class';
import type { Texture } from '../texture.class';
import BaseMode from './base.class';
/**
 * 贴图变形区域的顶点类型枚举
 *
 * 用于标识变形区域四个角的位置。
 *
 * @enum {string}
 */
export declare enum VertexType {
    /** 左上角顶点 */
    TOP_LEFT = "tl",
    /** 右上角顶点 */
    TOP_RIGHT = "tr",
    /** 左下角顶点 */
    BOTTOM_LEFT = "bl",
    /** 右下角顶点 */
    BOTTOM_RIGHT = "br"
}
/**
 * 倾斜模式配置
 */
interface SkewOptions {
    /**
     * 是否启用空白区域拖拽调整功能
     *
     * 启用后：
     * - 可以在画布空白处拖拽来调整变形区域
     * - 最小拖拽区域为 50x50 像素
     *
     * @default true
     */
    enableDragResize?: boolean;
}
/**
 * 倾斜变形模式类
 *
 * 提供图像的倾斜变形功能，通过四个边的拖拽控制点实现自由倾斜效果。
 *
 * 主要特性：
 * - 四边独立控制：每条边都有独立的拖拽控制点
 * - 智能吸附：拖拽时自动吸附到合适的倾斜角度
 * - 实时预览：拖拽过程中实时显示变形效果
 * - 防止变形过度：内置边界检查机制
 *
 * 交互方式：
 * - 拖拽边缘控制点：调整单边倾斜角度
 * - 空白处拖拽：快速调整整体大小
 * - 支持撤销/重做
 *
 * @example
 * ```typescript
 * // 1. 基础用法
 * const canvas = new fabric.Canvas('canvas');
 * const fabricTexture = new FabricTexture(canvas);
 *
 * // 创建倾斜模式并应用到图像
 * const skew = new Skew('#FF0000');  // 使用红色主题
 * fabricTexture.enterEditing(image, null, skew);
 *
 * // 2. 自定义拖拽图标样式
 * const skew = new Skew()
 *   .setStyleSetters({
 *     dragIcon: (icon) => {
 *       icon.set({ opacity: 0.8 });
 *       return icon;
 *     }
 *   });
 *
 * // 3. 隐藏原始对象（可选）
 * image.set({ visible: false });
 * canvas.renderAll();
 * ```
 *
 * @remarks 原始对象默认保持可见，需要手动隐藏
 *
 * @see
 * - {@link BaseMode} 变形模式基类
 * - {@link FabricTexture} 主要功能类
 */
declare class Skew extends BaseMode<{
    /**
     * 可配置拖动图标样式的方法
     * @param object - 默认的拖动图标对象
     * @returns 作为拖动图标对象的fabric元素对象，可使用默认对象以外的新对象
     */
    dragIcon: (object: fabric.Group) => fabric.Object;
}> {
    /**
     * 变形模式的唯一标识名称
     */
    name: string;
    /**
     * 模式配置
     */
    options: Required<SkewOptions>;
    /**
     * 样式设置器集合
     *
     * 用于自定义倾斜变形模式中各种元素的样式：
     * - texture: 配置变形后的贴图样式
     * - path: 配置网格边界线的样式
     * - dragIcon: 配置拖拽控制点的样式
     *
     * @example
     * ```typescript
     * skew.setStyleSetters({
     *   // 自定义拖拽图标样式
     *   dragIcon: (icon) => {
     *     icon.set({
     *       opacity: 0.8,
     *       scaleX: 1.2,
     *       scaleY: 1.2
     *     });
     *     return icon;
     *   }
     * });
     * ```
     *
     * @protected 仅供子类访问和修改
     */
    protected _styleSetters: {
        texture: () => void;
        path: () => void;
        dragIcon: (object: fabric.Group) => fabric.Group;
    };
    /**
     * 控制点映射表
     *
     * 存储控制点与其相关数据的映射关系，包括：
     * - curve: 控制点所在的贝塞尔曲线
     * - rowIndex: 控制点所在的网格行索引
     * - colIndex: 控制点所在的网格列索引
     * - vertexTypes: 控制点影响的顶点类型数组
     *
     * @internal 仅供内部使用
     */
    private _objectControlMap;
    /**
     * 构造函数
     *
     * 创建一个倾斜变形模式实例。
     *
     * @param themeColor - 主题色，用于控制点的背景色，默认为 THEME_COLOR
     * @param subThemeColor - 副主题色，用于辅助元素的颜色，默认为 SUB_THEME_COLOR
     */
    constructor(themeColor?: string, subThemeColor?: string, options?: SkewOptions);
    /**
     * 创建拖拽控制图标
     *
     * 创建一个双向箭头的拖拽控制图标，用于调整倾斜角度。图标包含：
     * - 圆角矩形背景
     * - 双向箭头图标
     * - 自适应旋转
     *
     * 样式特点：
     * - 背景：46x18 像素，圆角 10px
     * - 箭头：白色填充
     * - 边框：2px 白色描边
     * - 缩放：整体缩放到 0.8 倍
     * - 定位：居中对齐
     *
     * @param themeColor - 控制图标的背景颜色
     * @returns {fabric.Group} 返回组合的 Fabric 对象
     *
     * @example
     * ```typescript
     * // 创建一个红色背景的控制图标
     * const icon = Skew.createDragIcon('#FF0000');
     * canvas.add(icon);
     * ```
     */
    static createDragIcon(themeColor: string): fabric.Group;
    /**
     * 执行倾斜变形的网格分割算法
     *
     * 根据贴图的网格线计算所有交点坐标，生成变形后的网格点阵。
     *
     * 算法步骤：
     * 1. 遍历网格的行和列
     * 2. 计算每个网格单元的垂直和水平线段
     * 3. 计算所有线段的交点坐标
     * 4. 生成最终的分割点数组
     *
     * @param texture - 需要进行倾斜变形的贴图对象
     * @returns {Coord[][][]} 返回三维数组，表示网格的分割点坐标：
     * - 第一维：行索引
     * - 第二维：列索引
     * - 第三维：点的坐标 {x, y}
     *
     * @example
     * ```typescript
     * const points = Skew.execute(texture);
     * // points[0][0][0] 表示左上角第一个分割点的坐标
     * ```
     */
    static execute(texture: Texture): Coord[][][];
    /**
     * 获取所有控制点对象
     *
     * 返回当前倾斜变形模式中的所有控制点对象。用于：
     * - 批量修改控制点样式
     * - 控制点的显示/隐藏
     * - 获取控制点位置信息
     *
     * @returns {fabric.Object[]} 所有控制点对象的数组
     */
    get controlObjects(): fabric.Object[];
    /**
     * 执行倾斜变形计算
     *
     * 代理方法，调用静态方法 {@link Skew.execute} 进行实际的倾斜变形计算。
     *
     * @param texture - 需要进行倾斜变形的贴图对象
     * @returns 返回计算后的网格分割点坐标数组
     * @see {@link Skew.execute} 具体实现细节
     */
    execute(texture: Texture): Coord[][][];
    /**
     * 渲染倾斜变形的交互界面
     *
     * 在画布上创建并管理倾斜变形的交互控制界面。主要功能：
     *
     * 1. 控制点管理
     * - 为每条边创建双向箭头控制点
     * - 自动计算控制点位置和角度
     * - 保持控制点始终在最上层
     *
     * 2. 交互功能
     * - 拖拽边缘控制点：调整单边倾斜角度
     * - 空白处拖拽：快速调整整体大小
     * - 智能吸附：自动对齐到水平或垂直位置
     *
     * 3. 数据同步
     * - 实时更新贴图顶点坐标
     * - 自动记录可撤销的操作历史
     * - 防止无效的变形操作
     *
     * @param fabricTexture - FabricTexture 实例
     * @returns {Function} 返回清理函数，用于移除所有控制点和事件监听器
     *
     * @example
     * ```typescript
     * // 进入倾斜编辑模式
     * const cleanup = skew.dirtyRender(fabricTexture);
     *
     * // 退出编辑模式时清理
     * cleanup();
     * ```
     *
     * @remarks
     * 1. 控制点样式可通过 setStyleSetters 自定义
     * 2. 拖拽区域小于 50x50 像素时不会触发变形
     * 3. 变形操作会自动记录到历史栈中
     */
    dirtyRender(fabricTexture: FabricTexture): (() => void) | undefined;
}
export default Skew;