@xiaohaih/drag/dist/index.d.ts

拖拽插件, 可通过指令或函数调用来拖拽元素移动

/** 添加元素类名 */
export declare function addElementClass(el: Element, classNames: string | undefined): void;

/** 事件坐标 */
export declare interface Axis {
    /** 鼠标坐标 */
    x: number;
    /** 鼠标坐标 */
    y: number;
    /** 按下时鼠标距离节点原点的距离 + 父节点距离屏幕原点的距离(会加上滚动距离) */
    pageX: number;
    /** 按下时鼠标距离节点原点的距离 + 父节点距离屏幕原点的距离(会加上滚动距离) */
    pageY: number;
}

/**
 * 设置拖拽范围(true: 不超出父级大小, false: 可以超出父级大小)
 */
export declare function BoundaryLimit(): PluginOption;

export declare interface BoundaryLimitOption {
    /** 是否启用 */
    enable?: boolean;
    /**
     * 设置拖拽范围(true: 不超出父级大小, false: 可以超出父级大小)
     * @default true
     */
    boundaryLimit?: boolean;
}

/**
 * 设定拖拽方向
 */
export declare function Direction(): PluginOption;

export declare interface DirectionOption {
    /** 是否启用 */
    enable?: boolean;
    /**
     * 设定拖拽方向
     * @default x
     */
    orient?: 'x' | 'y';
}

/** 传递的元素类型 */
export declare type DOM = DOMSingle | NodeListOf<Element> | HTMLCollectionOf<Element> | DOMSingle[];

export declare type DOMSingle = string | HTMLElement | Element | ((parent: HTMLElement | Document) => HTMLElement | HTMLElement[] | Element | NodeListOf<Element> | HTMLCollectionOf<Element> | undefined | null);

export declare const downEventName: string;

/** 拖拽语法糖, 初始化时使用所有插件 */
export declare function drag(option?: DragCoreOption): DragCore;

/** 元素拖拽 */
export declare class DragCore {
    option: Omit<DragCoreOption, RequiredKeys_2> & Required<Pick<DragCoreOption, RequiredKeys_2>>;
    /** 应用的插件 */
    plugins: PluginOption[];
    /** 拖拽的节点信息 */
    operationDom: Omit<EventOption, 'native'>[];
    /** 启用状态 */
    status: boolean;
    /** 元素比例, 当缩放时, 此处会记录缩放比例[宽度百分比, 高度百分比] */
    ratio: [widthRatio: number, heightRatio: number];
    constructor(option?: DragCoreOption);
    /** 更新参数 */
    updateOption(option: Partial<Omit<DragCoreOption, 'disabled'>>): this;
    /** 启用拖拽 */
    enabled(): this;
    /** 禁用拖拽 */
    disabled(): this;
    brokerDoms: HTMLElement[];
    /** 格式化代理元素 */
    formatBrokerDom(): void;
    /** 增加代理元素监听的相关事件 */
    addEventListenerForBrokerDoms(): void;
    /** 移除代理元素监听的相关事件 */
    removeEventListenerForBrokerDoms(): void;
    /** 格式化拖拽元素 */
    formatDom(): this;
    /** 增加元素监听的相关事件 */
    addEventsListener(): void;
    /** 移除元素监听的相关事件 */
    removeEventsListener(): void;
    /** 代理元素的按下事件 */
    addEventListenerForBrokerDom(ev: TouchEvent | MouseEvent): void;
    _cursorTouch: string;
    isTouching: boolean;
    /** 开始拖拽 - 基于事件 */
    touchstart(ev: TouchEvent | MouseEvent): void;
    /** 拖拽开始 */
    down(info: Omit<EventOption, 'native'>, axis: Axis, ev?: MouseEvent | TouchEvent): void;
    /** 拖拽中 */
    move(info: Omit<EventOption, 'native'>, axis: Axis, ev?: MouseEvent | TouchEvent): void;
    /** 拖拽结束 */
    up(info: Omit<EventOption, 'native'>, axis: Axis, ev?: MouseEvent | TouchEvent): void;
    /** 设置坐标 */
    setPosition(pseudoInfo: Omit<EventOption, 'native'>, dom: HTMLElement): void;
    /** 获取事件传递的信息 */
    getCustomEvent(info: this['operationDom'][number], ev?: TouchEvent | MouseEvent): this["operationDom"][number] & {
        native: TouchEvent | MouseEvent | undefined;
    };
    _cursor: string;
    isEntering: boolean;
    /** 鼠标移入事件 */
    mouseenter(ev: TouchEvent | MouseEvent): void;
    /** 鼠标离开事件 */
    mouseleave(ev: TouchEvent | MouseEvent): void;
    /** 事件集合 */
    events: Record<string, [cb: (...args: any) => void, once?: boolean][]>;
    /** 在特定时机收集新增的事件 */
    eventsScope: Record<string, [cb: (...args: any) => void, once?: boolean][]>[];
    /**
     * 监听事件
     * @param {DragCoreEventsNames} eventName 事件名称
     * @param {DragCoreEvents[DragCoreEventsNames]} callback 事件回调
     * @param {boolean} [once] 是否仅监听一次
     */
    on<EventName extends DragCoreEventsNames>(eventName: EventName, callback: DragCoreEvents[EventName], once?: boolean): this;
    /** 一次性监听事件 */
    once<EventName extends DragCoreEventsNames>(eventName: EventName, callback: DragCoreEvents[EventName]): this;
    /** 重新绑定指定事件集合内的事件 */
    rebindEvents(eventsObj: DragCore['events'] | undefined): void;
    /** 移除监听事件 */
    off<EventName extends DragCoreEventsNames>(eventName: EventName, callback?: DragCoreEvents[EventName]): this;
    /** 触发监听事件 */
    emit<EventName extends DragCoreEventsNames>(eventName: EventName, ...args: Parameters<DragCoreEvents[EventName]>): this;
    /** 收集新增的事件 */
    getFragmentEvents(): {
        get: () => Record<string, [cb: (...args: any) => void, once?: boolean | undefined][]>;
        run: () => void;
        stop: () => void;
    };
    /** 销毁指定事件 */
    disposeEvents(events: PluginOption['events'] | undefined): void;
    /**
     * 注册插件 插件默认不会执行, 只在 run 方法后运行
     */
    use(option: () => PluginOption): this;
    /** 移除插件 */
    unuse(name: string | number): this;
    /** 销毁实例 */
    destroyed(): void;
    /** 获取元素的比例 */
    static getRatioByElement(dom: HTMLElement): [number, number];
}

export declare function dragCore(option: DragCoreOption): DragCore;

/** 元素拖拽的事件 */
export declare interface DragCoreEvents {
    /** 开始拖拽前触发 */
    beforeStart: (option: EventOption, ins: DragCore) => void;
    /** 开始拖拽后触发 */
    start: (option: EventOption, ins: DragCore) => void;
    /** 开始移动前触发 */
    beforeMove: (option: EventOption, ins: DragCore) => void;
    /** 开始移动后触发 */
    move: (option: EventOption, ins: DragCore) => void;
    /** 结束拖拽前触发 */
    beforeEnd: (option: EventOption, ins: DragCore) => void;
    /** 结束拖拽后触发 */
    end: (option: EventOption, ins: DragCore) => void;
    /** 坐标更新前的回调事件 - 可直接修改坐标值来覆盖实际坐标(不支持异步修改) */
    axisBeforeUpdate: (option: Omit<EventOption, 'native'>, ins: DragCore) => void;
    /** 坐标更新后的回调事件 */
    axisUpdated: (option: Omit<EventOption, 'native'>, ins: DragCore) => void;
}

/** 元素拖拽的事件名称 */
export declare type DragCoreEventsNames = keyof DragCoreEvents;

/** 元素拖拽的配置项 */
export declare interface DragCoreOption {
    /** 范围限制配置项 */
    boundaryLimitOptions?: BoundaryLimitOption;
    /** 方向限制配置项 */
    directionOptions?: DirectionOption;
    /** 吸边配置项 */
    snapOptions?: SnapOption;
    /** 滚动配置项 */
    scrollingOptions?: ScrollingOption;
    /** 虚影跟随配置项 */
    shadowFollowOptions?: ShadowFollowOption;
    /** 事件代理 - 当拖拽元素懒加载或会动态更新时, 可将事件挂载到其祖先上 */
    eventProxy?: DOM;
    /** 拖拽元素 */
    target?: DOM;
    /** 拖拽元素句柄, 不传取拖拽元素本身 */
    handle?: DOM;
    /** 拖拽时只应用虚拟坐标, 元素坐标不更新 */
    virtualAxis?: boolean;
    /** 激活时的类名(按下至抬起前) */
    classActive?: string;
    /** 激活的类名(只要按下便会一直设置, 直到选择了其它拖拽元素) */
    classActivated?: string;
    /** 拖拽时的类名 */
    classMoving?: string;
    /**
     * 鼠标移上时的指针形状
     * @default move
     */
    cursorOver?: string;
    /** 鼠标离开时的指针形状, 默认还原 */
    cursorOut?: string;
    /** 按下时的指针形状 */
    cursorDown?: string;
    /** 抬起时的指针形状, 默认还原 */
    cursorUp?: string;
    /**
     * 拖拽时的指针形状
     * @default move
     */
    cursorMoving?: string;
    /** 初始化时是否禁用 */
    disabled?: boolean;
    /** 根据状态获取指针形状 */
    getCursor?: (type: 'over' | 'out' | 'down' | 'up' | 'moving', option: Omit<EventOption, 'native'>, ins: DragCore, getCursor: (type: 'over' | 'out' | 'down' | 'up' | 'moving', option: Omit<EventOption, 'native'>, ins: DragCore) => string | undefined | null) => string | undefined | null;
    /** 设置指针形状 */
    setCursor?: (value?: string | null) => void;
    /** 开始拖拽前触发 */
    onTouchStart?: (option: EventOption, ins: DragCore) => void;
    /** 开始拖拽后触发 */
    onTouchStarted?: (option: EventOption, ins: DragCore) => void;
    /** 开始移动前触发 */
    onTouchMove?: (option: EventOption, ins: DragCore) => void;
    /** 开始移动后触发 */
    onTouchMoved?: (option: EventOption, ins: DragCore) => void;
    /** 结束拖拽前触发 */
    onTouchEnd?: (option: EventOption, ins: DragCore) => void;
    /** 结束拖拽后触发 */
    onTouchEnded?: (option: EventOption, ins: DragCore) => void;
    /** 坐标更新前的回调事件 - 可直接修改坐标值来覆盖实际坐标(不支持异步修改) */
    onAxisBeforeUpdate?: (option: Omit<EventOption, 'native'>, ins: DragCore) => void;
    /** 坐标更新后的回调事件 */
    onAxisUpdated?: (option: Omit<EventOption, 'native'>, ins: DragCore) => void;
}

export declare interface EventOption {
    /** 节点 */
    target: HTMLElement;
    /** 拖拽句柄 */
    handle: HTMLElement;
    /** 是否处于拖拽中 */
    dragging: boolean;
    /** 事件对象 */
    native?: TouchEvent | MouseEvent;
    /** 鼠标坐标值 x */
    clientX: number;
    /** 鼠标坐标值 y */
    clientY: number;
    /** 元素起始的坐标值 x */
    initialX: number;
    /** 元素起始的坐标值 y */
    initialY: number;
    /** 按下时鼠标距离节点原点的距离 + 父节点距离屏幕原点的距离(会加上滚动距离) */
    pageX: number;
    /** 按下时鼠标距离节点原点的距离 + 父节点距离屏幕原点的距离(会加上滚动距离) */
    pageY: number;
    /** 按下时鼠标距离节点原点的距离 + 父节点距离屏幕原点的距离 */
    offsetX: number;
    /** 按下时鼠标距离节点原点的距离 + 父节点距离屏幕原点的距离 */
    offsetY: number;
    /** 按下时鼠标距离节点原点的距离 */
    offsetInsetX: number;
    /** 按下时鼠标距离节点原点的距离 */
    offsetInsetY: number;
    /** 按下时元素的 margin-left 值 */
    ml: number;
    /** 按下时元素的 margin-top 值 */
    mt: number;
    /** 元素实时的坐标值 x */
    x: number;
    /** 元素实时的坐标值 y */
    y: number;
    setPosition: (axis: Partial<Record<'x' | 'y', number>>, dom: HTMLElement) => void;
}

/**
 * 模拟元素的 getBoundingClientRect
 * @param {HTMLElement} dom
 * @param {string} sizeReference 元素大小的参考值
 */
export declare function getBoundingClientRect(dom: HTMLElement, sizeReference: 'offset' | 'scroll' | 'client'): {
    left: number;
    right: number;
    top: number;
    bottom: number;
    x: number;
    y: number;
    width: number;
    height: number;
};

/** 获取元素的样式表 */
export declare function getElementStyle(el: Element, pseudoElt?: string | null): CSSStyleDeclaration;

/** 获取插件的启用状态 */
export declare function getEnableStatus(opt?: {
    enable?: boolean;
}): boolean;

/** 获取事件的坐标信息 */
export declare function getEvent(ev: TouchEvent | MouseEvent): Touch | MouseEvent;

/** 判断是否是手机 */
export declare function getMobilePlatStatus(): boolean;

/** 获取 dom 的定位父级 */
export declare function getParent(dom: HTMLElement): HTMLElement;

/** 获取 dom 的大小 */
export declare function getSize(dom: HTMLElement): {
    width: number;
    height: number;
};

export declare function getType(val: any): string;

export declare type InsetShadowFollowOption = Omit<ShadowFollowOption, RequiredKeys> & Required<Pick<ShadowFollowOption, RequiredKeys>>;

export declare function isFunction(val: any): val is Record<any, any>;

export declare const isMobile: boolean;

export declare function isObject(val: any): val is Record<any, any>;

export declare function isString(val: any): val is Record<any, any>;

/** 匹配 dom 树中的某个元素 */
export declare function matchForDomTree(dom: HTMLElement, matchDom: HTMLElement, breakDom?: HTMLElement): HTMLElement | null;

export declare const moveEventName: string;

/**
 * 解析 dom
 * @param {DOM} val 待解析的参数
 * @param {HTMLElement} parent 为字符串时, 限制查找的父节点
 */
export declare function parseDOM<T extends HTMLElement[] | undefined>(val: DOM | undefined | null, parent: HTMLElement | Document, def?: T): HTMLElement[] | T;

/** 插件选项 */
export declare interface PluginOption {
    /** 插件名称 */
    name: string;
    /** 排序序号 */
    sort?: number;
    /** 内部监听的事件(异步监听的事件未收集, 需插件内部主动解除) - 供拖拽内部使用 */
    events?: Record<string, [cb: (...args: any[]) => void, once?: boolean][]>;
    /** 安装插件时调用的方法 */
    install: (ins: DragCore) => void;
    /** 卸载插件时调用的方法 */
    uninstall?: (ins: DragCore) => void;
}

/** 删除元素类名 */
export declare function removeElementClass(el: Element, classNames: string | undefined): void;

declare type RequiredKeys = 'createDom' | 'append' | 'setDomAttrs';

declare type RequiredKeys_2 = 'setCursor' | 'getCursor' | 'cursorOver' | 'cursorMoving';

/**
 * 鼠标位于边缘时, 自动滚动
 */
export declare function Scrolling(): PluginOption;

export declare interface ScrollingOption {
    /** 是否启用 */
    enable?: boolean;
    /**
     * 滚动容器
     * @default 默认取元素的父级定位元素
     */
    container?: HTMLElement | ((opt: EventOption) => HTMLElement);
    /**
     * 靠近边缘时触发滚动的阈值
     * @default 20
     */
    threshold?: number;
    /**
     * 滚动速度
     * @default 10
     */
    speed?: number;
    /**
     * 执行滚动的定时器时长
     * @default 100
     */
    scrollMs?: number;
    /** 滚动配置项(浏览器滚动的配置项) */
    scrollOption?: ScrollOptions;
}

/**
 * 跟随鼠标移动的影子 dom
 */
export declare function ShadowFollow(): PluginOption;

export declare interface ShadowFollowOption {
    /** 是否启用 */
    enable?: boolean;
    /** 是否为固定定位元素 */
    fixed?: boolean;
    /** 创建跟随元素, 默认克隆拖拽元素 */
    createDom?: (option: InsetShadowFollowOption, opt: EventOption) => HTMLElement | Node;
    /**
     * 将克隆元素添加到页面中
     * @default Function 默认添加到拖拽元素的父级
     */
    append?: (dom: HTMLElement | Node, opt: EventOption) => void;
    /**
     * 设置元素默认属性(外部传递了 createDom 该属性不生效, 需手动处理)
     * @default 默认设置不透明度, 不响应事件, 定位等样式
     */
    setDomAttrs?: (dom: HTMLElement | Node, option: InsetShadowFollowOption, opt: EventOption) => void;
    /** 设置克隆元素的类名(外部传递了 createDom 该属性不生效, 需手动处理) */
    class?: string;
    /** 设置克隆元素的样式(外部传递了 createDom 该属性不生效, 需手动处理) */
    style?: Partial<CSSStyleDeclaration>;
}

/**
 * 设置贴边效果
 */
export declare function Snap(): PluginOption;

export declare interface SnapOption {
    /** 是否开启边缘吸附效果, 未开启时, 以下配置项皆不生效 */
    enable?: boolean;
    /**
     * 吸附阈值
     * @default 10
     */
    threshold?: number;
    /** 吸附方向 @default both */
    orient?: 'x' | 'y' | 'both';
    /** 是否强制边缘吸附效果 */
    forceSnap?: boolean;
    /**
     * 是否强制边缘吸附效果(x: 水平方向吸附, y: 垂直方向吸附, left, right, top, bottom)
     * @default x
     */
    forceSnapOrient?: 'left' | 'right' | 'top' | 'bottom' | 'x' | 'y';
}

export declare const upEventName: string;

export { }