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

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

import type { fabric } from 'fabric';
import type { FabricTexture } from '../fabric-texture.class';
import type { Texture } from '../texture.class';
import { AbstractMode } from '../abstract-mode.class';
/**
 * 默认主题色
 *
 * 决定交互控件的颜色
 *
 * @default '#44A08D' 清新绿色
 */
export declare const THEME_COLOR = "#44A08D";
/**
 * 默认副主题色
 *
 * 决定交互控件交互时的变化色，应与主题色形成合适的搭配
 *
 * @default '#324346' 深灰绿色
 */
export declare const SUB_THEME_COLOR = "#324346";
/**
 * 交互元素的样式配置器类型
 *
 * 用于自定义变形模式中各种交互元素的样式。
 *
 * @template T - 扩展的样式设置器类型，默认为空的对象方法映射
 *
 * @example
 * ```typescript
 * // 基础用法
 * const mode = new BaseMode();
 * mode.setStyleSetters({
 *   // 自定义贴图样式
 *   texture: (image) => {
 *     image.set({
 *       opacity: 0.8,
 *       shadow: new fabric.Shadow({ blur: 10, color: 'rgba(0,0,0,0.3)' })
 *     });
 *   },
 *   // 自定义边界线样式
 *   path: (path) => {
 *     path.set({
 *       strokeDashArray: [5, 5],  // 虚线效果
 *       strokeWidth: 3
 *     });
 *   }
 * });
 * ```
 */
export type BaseStyleSetters<T = Record<string, (...rgs: any[]) => fabric.Object>> = T & {
    /**
     * 配置变形后贴图的样式
     *
     * @param image - fabric.Image 实例，代表变形后的贴图对象
     */
    texture: (image: fabric.Image) => void;
    /**
     * 配置网格边界线的样式
     *
     * @param path - fabric.Path 实例，代表网格的边界线
     */
    path: (path: fabric.Path) => void;
};
/**
 * 变形模式的基础实现类
 *
 * 提供了变形模式的基础功能实现，包括：
 * - 配置默认的变形分割策略
 * - 主题色系管理
 * - 基础渲染逻辑，仅显示变形贴图和边界线
 *
 * @template T - 扩展的样式设置器类型，用于添加自定义的样式配置方法以支持对自定义变形模式内部的元素样式添加配置
 *
 * @remarks
 * 1. 这是一个抽象基类，通常用作其他具体模式的父类，而不直接使用
 * 2. 可以通过继承此类来创建自定义的变形模式
 * 3. 支持通过泛型扩展样式设置器的类型
 */
declare class BaseMode<T> extends AbstractMode {
    /**
     * 变形模式的唯一标识名称
     *
     * 用于在分割策略中标识当前模式，为自定义标识，每个模式都应该有唯一的名称
     *
     * @default 'Base'
     */
    name: string;
    /**
     * 主题色
     *
     * 决定交互控件的颜色
     *
     * @default THEME_COLOR ('#44A08D')
     * @see THEME_COLOR 默认主题色常量
     */
    themeColor: string;
    /**
     * 副主题色
     *
     * 决定交互控件交互时的变化色，应与主题色形成合适的搭配
     *
     * @default SUB_THEME_COLOR ('#324346')
     * @see SUB_THEME_COLOR 默认副主题色常量
     */
    subThemeColor: string;
    /**
     * 样式设置器集合
     *
     * 用于自定义变形模式中各种元素的样式，包括：
     * - texture: 变形后的贴图样式
     * - path: 网格边界线的样式
     * - 其他通过泛型 T 扩展的自定义样式设置器
     *
     * @example
     * ```typescript
     * mode.setStyleSetters({
     *   texture: (image) => {
     *     image.set({ opacity: 0.8 });
     *   }
     * });
     * ```
     *
     * @protected 仅供子类访问和修改
     */
    protected _styleSetters: BaseStyleSetters<T>;
    /**
     * 创建变形模式实例
     *
     * 初始化一个基础变形模式，可以通过参数自定义主题色系。
     *
     * @param themeColor - 主题色，用于渲染网格边界线等主要交互元素
     * @param subThemeColor - 副主题色，用于渲染次要界面元素和交互状态
     *
     * @remarks 建议选择对比度适中的颜色组合，以确保良好的可视性
     */
    constructor(themeColor?: string, subThemeColor?: string);
    /**
     * 配置变形模式中各元素的样式
     *
     * 通过样式设置器自定义变形模式中各种元素的外观，支持：
     * - 变形后的贴图样式
     * - 网格边界线样式
     * - 通过泛型扩展的自定义元素样式
     *
     * @param styleSetters - 样式设置器配置对象
     * @returns 当前实例，支持链式调用
     *
     * @example
     * ```typescript
     * mode.setStyleSetters({
     *   texture: (image) => {
     *     image.set({ opacity: 0.8 });
     *   }
     * });
     * ```
     *
     * @remarks
     * 1. 新的样式设置会与现有设置合并，而不是完全替换
     * 2. 对于同名设置器，新的会覆盖旧的
     * 3. 样式会在下一次渲染时生效
     */
    setStyleSetters(styleSetters: Partial<BaseStyleSetters>): this;
    /**
     * 执行变形分割策略
     *
     * 基类中返回空数组，需要在子类中实现具体的分割逻辑。
     *
     * @param texture - 变形贴图实例，包含原始图像和变形配置
     * @returns 返回三维数组，表示网格的分割点坐标：
     * - 第一维：行
     * - 第二维：列
     * - 第三维：分割点坐标
     *
     * @virtual 此方法应在子类中重写
     */
    execute(texture: Texture): Coord[][][];
    /**
     * 渲染变形效果到画布
     *
     * 将变形后的贴图和网格边界线渲染到 Fabric.js 画布上。
     *
     * @param fabricTexture - Fabric 变形工具实例，包含画布和变形状态
     * @returns 清理函数，用于移除渲染的元素
     *
     * @example
     * ```typescript
     * class CustomMode extends BaseMode {
     *   render(fabricTexture: FabricTexture) {
     *     // 调用基类渲染方法
     *     const cleanup = super.render(fabricTexture);
     *
     *     // 添加自定义渲染逻辑
     *     const customElements = this.renderCustomElements();
     *
     *     // 返回组合的清理函数
     *     return () => {
     *       cleanup();
     *       this.cleanupCustomElements(customElements);
     *     };
     *   }
     * }
     * ```
     *
     * @remarks
     * 1. 返回的清理函数会在下次渲染前或离开编辑模式时自动调用
     * 2. 子类可以通过 super.render() 复用基类的渲染逻辑
     * 3. 渲染的元素样式可通过 setStyleSetters 配置
     */
    render(fabricTexture: FabricTexture): (() => void) | undefined;
}
export default BaseMode;