fabric-texture
Version:
This JavaScript library enables fast and efficient image distortion transformations using Canvas 2D.
381 lines (379 loc) • 12.4 kB
TypeScript
import { fabric } from 'fabric';
import type { Texture } from '../texture.class';
import type { FabricTexture } from '../fabric-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 WarpOptions {
/**
* 是否启用 Shift 键移动约束
*
* 启用后：
* - 移动控点时按住 Shift 键可限制移动方向为水平或垂直
* - 移动方向取决于拖拽距离较大的方向
*
* @default true
*/
enableShiftConstraint?: boolean;
/**
* 是否启用网格分割功能
*
* 启用后：
* - 可以点击贴图内部添加新的分割点
* - 可以选中内部分割点并点击 Delete/Backspace 键删除
* - 分割点将把贴图区域划分为更小的可控制区域
* - 适用于需要更精细变形控制的场景
*
* @default true
*/
enableGridSplit?: boolean;
}
/**
* 扭曲变形模式类
*
* 提供图像的扭曲变形功能，通过以下方式实现自由扭曲效果：
*
* 核心功能：
* - 顶点控制：四个角点可自由拖拽
* - 曲线控制：边缘曲线可通过中间控制点调整
* - 网格分割：支持在任意位置添加新的控制点
* - 实时预览：所有操作都能即时查看效果
* - 样式定制：支持自定义控件元素样式
*
* 交互方式：
* 1. 顶点拖拽：移动四个角点改变整体形状
* 2. 曲线调整：选中顶点后显示曲线控制点，拖拽改变曲线形状
* 3. 网格分割：
* - 点击图像内部显示分割点
* - 点击分割点在该位置添加新控制点
* - 选中控制点按Delete键删除
* 4. 整体移动：拖拽分割点可整体移动图像
*
* @example
* ```typescript
* // 1. 基础用法
* const canvas = new fabric.Canvas('canvas');
* const fabricTexture = new FabricTexture(canvas);
*
* // 创建扭曲模式并应用到图像
* const warp = new Warp('#FF0000'); // 使用红色主题
* fabricTexture.enterEditing(image, null, warp);
*
* // 2. 自定义拖拽图标样式
* const warp = new Warp()
* .setStyleSetters({
* control: (point) => {
* point.set({ radius: 10 });
* return point;
* },
* });
*
* // 3. 隐藏原始对象（可选）
* image.set({ visible: false });
* canvas.renderAll();
* ```
*
* @remarks 原始对象默认保持可见，需要手动隐藏
*
* @see
* - {@link BaseMode} 变形模式基类
* - {@link FabricTexture} 主要功能类
*/
declare class Warp extends BaseMode<{
/**
* 可配置顶点控制点的方法
* @param object - 默认的控制点对象
* @returns 作为顶点控制点对象的fabric元素对象，可使用默认对象以外的新对象
*/
control: (object: fabric.Object) => fabric.Object;
/**
* 可配置扭曲控制点的方法
* @param object - 默认的控制点对象
* @returns 作为扭曲控制点对象的fabric元素对象，可使用默认对象以外的新对象
*/
curveControl: (object: fabric.Object) => fabric.Object;
/**
* 可配置插入控制点的方法
* @param object - 默认的控制点对象
* @returns 作为插入控制点对象的fabric元素对象，可使用默认对象以外的新对象
*/
insertControl: (object: fabric.Object) => fabric.Object;
/**
* 可配置顶点控制点与扭曲控制点之间连线样式的方法
* @param line - 连线对象
*/
line: (line: fabric.Line) => void;
}> {
/**
* 变形模式的唯一标识名称
*/
name: string;
/**
* 模式配置
*/
options: Required<WarpOptions>;
/**
* 样式设置器集合
*
* 用于自定义扭曲变形模式中各种元素的样式：
* - texture: 配置变形后的贴图样式
* - path: 配置网格边界线的样式
* - control: 配置顶点控制点的样式
* - curveControl: 配置曲线控制点的样式
* - insertControl: 配置插入点的样式
* - line: 配置控制点连接线的样式
*
* @example
* ```typescript
* warp.setStyleSetters({
* // 自定义顶点控制点样式
* control: (point) => {
* point.set({
* radius: 10,
* fill: 'red',
* opacity: 0.8
* });
* return point;
* },
* // 自定义连接线样式
* line: (line) => {
* line.set({
* stroke: '#999',
* strokeDashArray: [5, 5]
* });
* }
* });
* ```
*
* @protected 仅供子类访问和修改
*/
protected _styleSetters: {
texture: () => void;
path: () => void;
control: (control: fabric.Object) => fabric.Object;
curveControl: (control: fabric.Object) => fabric.Object;
insertControl: (control: fabric.Object) => fabric.Object;
line: (line: fabric.Line) => void;
};
/**
* 控制点位置映射表
*
* 存储控制点与其位置信息的映射关系：
* - 键：由 "行-列" 组成的字符串，如 "0-1" 表示第0行第1列
* - 值：{@link Control} 类型的控制点数据结构
*
* @private 仅供内部使用
*/
private _positionControlMap;
/**
* 当前激活的插入控制点
*
* 用于临时存储当前正在交互的插入点对象。
* 当用户点击贴图内部时创建，确认插入或取消时清除。
*
* @private 仅供内部使用
*/
private _insertControlObject;
/**
* 创建扭曲变形模式实例
*
* 初始化一个新的扭曲变形模式，设置主题色和交互色。
*
* @param themeColor - 主题色，用于控制点的默认颜色，默认为 THEME_COLOR
* @param subThemeColor - 交互色，用于控制点被选中时的颜色，默认为 SUB_THEME_COLOR
*/
constructor(themeColor?: string, subThemeColor?: string, options?: WarpOptions);
/**
* 创建顶点控制点
*
* 创建用于拖拽变形的主要控制点，显示在贴图的四个角和边缘分割点位置。
*
* 控制点样式：
* - 形状：圆形
* - 大小：7px 半径
* - 颜色：主题色填充，白色描边
* - 交互：可拖拽，无控制框和边框
*
* @param themeColor - 控制点的填充颜色
* @returns {fabric.Circle} 返回 Fabric.js 圆形对象
*
* @example
* ```typescript
* const control = Warp.createDefaultControl('#FF0000');
* canvas.add(control);
* ```
*/
static createDefaultControl(themeColor: string): fabric.Circle;
/**
* 创建曲线控制点
*
* 创建用于调整曲线形状的次要控制点，显示在边缘曲线的中间位置。
*
* 控制点样式：
* - 形状：圆角矩形
* - 大小：6x6 像素
* - 颜色：白色填充，灰色描边
* - 特性：默认隐藏，选中主控制点时显示
* - 交互：可拖拽，无控制框和边框
*
* @returns {fabric.Rect} 返回 Fabric.js 矩形对象
*
* @example
* ```typescript
* const curveControl = Warp.createDefaultCurveControl();
* canvas.add(curveControl);
* ```
*/
static createDefaultCurveControl(): fabric.Rect;
/**
* 创建插入点控制点
*
* 创建用于标识可插入新控制点位置的指示器，点击后在该位置添加新的分割点。
*
* 控制点样式：
* - 形状：圆形
* - 大小：5px 半径
* - 颜色：半透明白色填充，主题色描边
* - 特性：不可选中，仅用于视觉提示
* - 交互：无法直接拖拽
*
* @param themeColor - 控制点的描边颜色
* @returns {fabric.Circle} 返回 Fabric.js 圆形对象
*
* @example
* ```typescript
* const insertPoint = Warp.createDefaultInsertControl('#FF0000');
* canvas.add(insertPoint);
* ```
*/
static createDefaultInsertControl(themeColor: string): fabric.Circle;
/**
* 计算贴图的分割点坐标
*
* 根据贴图的网格曲线计算分割点的位置坐标。该方法会：
* 1. 遍历所有网格单元
* 2. 计算横向和纵向曲线的交点
* 3. 生成用于变形的控制点网格
*
* @param texture - 需要计算分割点的贴图对象
* @returns {Coord[][][]} 返回三维数组：
* - 第一维：行索引
* - 第二维：列索引
* - 第三维：分割点坐标 {x, y}
*
* @example
* ```typescript
* const splitPoints = Warp.execute(texture);
* // splitPoints 结构示例：
* // [
* // [ // 第一行
* // [ // 第一列
* // {x: 10, y: 20}, // 分割点1
* // {x: 30, y: 40} // 分割点2
* // ]
* // ]
* // ]
* ```
*/
static execute(texture: Texture): Coord[][][];
/**
* 获取所有顶点控制点
*
* 返回所有用于控制贴图顶点的主控制点对象列表。
* 这些控制点位于贴图的四个角和边缘分割点位置。
*
* @returns {fabric.Object[]} 顶点控制点对象数组
*/
get controlObjects(): fabric.Object[];
/**
* 获取所有曲线控制点
*
* 返回所有用于调整曲线形状的次要控制点对象列表。
* 这些控制点位于边缘曲线的中间位置，用于调整曲线的弯曲程度。
*
* @returns {fabric.Object[]} 曲线控制点对象数组
*/
get subControlObjects(): fabric.Object[];
/**
* 获取当前激活的插入控制点
*
* 返回当前正在交互的插入点对象。
* 当用户点击贴图内部时会创建此控制点，
* 用户可以通过点击它来在该位置添加新的分割点。
*
* @returns {fabric.Object | null} 插入控制点对象，如果不存在则返回 null
*/
get insertControlObject(): fabric.Object | null;
/**
* 获取所有控制点连接线
*
* 返回所有连接主控制点和曲线控制点的线段对象列表。
* 这些线段用于可视化控制点之间的关系。
*
* @returns {fabric.Line[]} 连接线对象数组
*/
get lineObjects(): fabric.Line[];
/**
* 执行扭曲变形计算
*
* 代理方法，调用静态方法 {@link Warp.execute} 进行实际的扭曲变形计算。
*
* @param texture - 需要进行扭曲变形的贴图对象
* @returns 返回计算后的网格分割点坐标数组
* @see {@link Warp.execute} 具体实现细节
*/
execute(texture: Texture): Coord[][][];
/**
* 渲染变形控制界面
*
* 在画布上创建和管理所有交互控制元素，包括：
*
* 1. 控制点系统
* - 主控制点：用于控制顶点位置
* - 曲线控制点：用于调整曲线形状
* - 连接线：显示控制点之间的关系
*
* 2. 交互行为
* - 拖拽控制点：调整形状
* - 选中/取消选中：显示/隐藏相关控制点
* - 点击内部：添加新的分割点
* - 按Delete键：删除选中的控制点
*
* 3. 视觉反馈
* - 控制点层级：主控制点 > 曲线控制点 > 连接线
* - 选中状态：使用副主题色标识
* - 实时预览：所有操作即时生效
*
* @param fabricTexture - FabricTexture 实例对象
* @returns {() => void} 清理函数，用于移除所有控制元素和事件监听
*
* @example
* ```typescript
* // 进入编辑模式时会自动调用
* const cleanup = warp.dirtyRender(fabricTexture);
*
* // 退出编辑模式时清理
* cleanup();
* ```
*/
dirtyRender(fabricTexture: FabricTexture): (() => void) | undefined;
}
export default Warp;