Teal TealUI

拖动web/draggable

允许元素跟随指针移动。

基本用法
事件
局部拖动
自动滚屏
方向
区域
步长
返回原地
吸附
代理
API
全局
Draggable 类

基本用法

<div id="box" class="doc-box" style="cursor: move"></div>
<script>
    import draggable from "web/draggable";

    draggable(box);
</script>

事件

拖动过程会依次触发以下事件:

  1. onDragStart:拖动开始事件。
  2. onDragMove:拖动移动事件。
  3. onDragEnd:拖动结束事件。

通过事件函数的第一参数 e.pageXe.pageY 获取的鼠标位置。 通过事件函数的第二参数 s.offsetXs.offsetY 获取拖动的距离。

<div id="box1" class="doc-box" style="cursor: move"></div>
<script>
    import draggable from "web/draggable";

    draggable(box1, {
        onDragStart(){ 
            box1.className += " doc-box-green"; 
        },
        onDragMove(e, s){ 
            box1.innerHTML = s.offsetX.toFixed(0) + "," + s.offsetY.toFixed(0); 
        },
        onDragEnd(){ 
            box1.innerHTML = "";
            box1.className = "doc-box"; 
        }
    });
</script>

局部拖动

如果不希望点击元素任意位置都能开始拖动:

<div id="box_handle" class="doc-box"><button id="box_handle_body" style="cursor: move">点我拖动</button></div>
<script>
    import draggable from "web/draggable";

    draggable(box_handle_body, {
        proxy: box_handle
    });
</script>
<div id="box_cancel" class="doc-box" style="cursor: move"><button id="box_cancel_body" style="cursor: default;">点外拖动</button></div> <script> import draggable from "web/draggable"; draggable(box_cancel, { cancel(e) { return e.target === box_cancel_body; } }); </script>

自动滚屏

允许拖动时更改滚动条位置。

<div id="box_scroll" class="doc-box" style="cursor: move"></div>
<script>
    import draggable from "web/draggable";

    draggable(box_scroll, {
        onDragMove(e, s) {
            s.autoScroll();
        }
    });
</script>

方向

限制拖动的方向。

<div id="box_direction_horizontal" class="doc-box" style="cursor: e-resize"></div>
<script>
    import * as dom from "web/dom";
    import draggable from "web/draggable";

    draggable(box_direction_horizontal, {
        onDragMove(e, s) {
            s.direction("horizontal");
        }
    });
</script>
<div id="box_direction_vertial" class="doc-box" style="cursor: n-resize"></div> <script> import * as dom from "web/dom"; import draggable from "web/draggable"; draggable(box_direction_vertial, { onDragMove(e, s) { s.direction("vertical"); } }); </script>

区域

限制拖动的范围。

<div id="box_limit" class="doc-box" style="cursor: move"></div>
<script>
    import * as dom from "web/dom";
    import draggable from "web/draggable";

    draggable(box_limit, {
        onDragMove(e, s) {
            s.limit(__root__);
        }
    });
</script>

步长

拖动到一定距离后才移动位置。

<div id="box_step" class="doc-box" style="cursor: move"></div>
<script>
    import draggable from "web/draggable";

    draggable(box_step, {
        onDragMove(e, s) {
            s.step(50);
        }
    });
</script>

返回原地

拖动结束后返回原地。

<div id="box_revert" class="doc-box" style="cursor: move"></div>
<script>
    import draggable from "web/draggable";

    draggable(box_revert, {
        onDragEnd(e, s) {
            s.revert();
        }
    });
</script>

吸附

允许拖动时吸附指定的位置。

<div id="box_snap" class="doc-box" style="cursor: move"></div>
<div id="box_snap_target" class="doc-box doc-box-large doc-box-blue"></div>
<script>
    import draggable from "web/draggable";

    draggable(box_snap, {
        onDragMove(e, s) {
            s.snap(box_snap_target);
        }
    });
</script>

代理

允许拖动时创建移动代理元素。

<div id="box_proxy" class="doc-box" style="cursor: move"></div>
<script>
    import draggable from "web/draggable";
    import * as dom from "web/dom";

    draggable(box_proxy, {
        onDragStart(e, s) {
            // 创建代理元素。
            s.proxy = s.elem.parentNode.appendChild(document.createElement(s.elem.tagName));
            s.proxy.className = s.elem.className;
            s.proxy.innerHTML = s.elem.innerHTML;
            s.proxy.style.position = "absolute";
            s.proxy.style.zIndex = 1000000;
            s.proxy.style.opacity = 0.5;
            dom.setRect(s.proxy, getRect(s.elem));
        },
        onDragEnd(e, s) {
            // 设置实际元素的位置。
            dom.setRect(s.elem, getRect(s.proxy));

            // 删除代理元素。
            s.proxy.parentNode.removeChild(s.proxy);
            s.proxy = s.elem;
        }
    });
</script>

API

全局

函数 描述
draggable(elem, ...)(elem:HTMLElement, options?:Partial<Draggable>):Draggable

设置指定的元素可拖动。

参数 类型 描述 默认值
elem* HTMLElement
options Partial<Draggable>

返回值

类型:Draggable

返回一个拖动对象。

设置指定的元素可拖动。

Draggable 类

继承自:Movable

表示一个可拖动对象。

字段 类型 描述 继承自
proxy : HTMLElement

实际移动的元素。

HTMLElement

实际移动的元素。

onDragStart : (e: MouseEvent, sender: Draggable) => boolean | void

拖动开始事件。

function

拖动开始事件。

onDragMove : (e: MouseEvent, sender: Draggable) => boolean | void

拖动移动事件。

function

拖动移动事件。

onDragEnd : (e: MouseEvent, sender: Draggable) => void

拖动结束事件。

function

拖动结束事件。

onDragCancel : (e: MouseEvent, sender: Draggable) => void

拖动取消事件。

function

拖动取消事件。

startClientX : number

开始拖动时拖动元素的水平偏移距离(单位:像素)。

number

开始拖动时拖动元素的水平偏移距离(单位:像素)。

startClientY : number

开始拖动时拖动元素的垂直偏移距离(单位:像素)。

number

开始拖动时拖动元素的垂直偏移距离(单位:像素)。

endClientX : number

当前拖动元素的水平偏移距离(单位:像素)。

number

当前拖动元素的水平偏移距离(单位:像素)。

endClientY : number

当前拖动元素的垂直偏移距离(单位:像素)。

number

当前拖动元素的垂直偏移距离(单位:像素)。

delay : number = 500

(已覆盖)从指针按下到触发移动事件的等待毫秒数。如果为 -1 则忽略指针按下不动的操作。

继承自

Movable

number

(已覆盖)从指针按下到触发移动事件的等待毫秒数。如果为 -1 则忽略指针按下不动的操作。

Movable
elem : HTMLElement

移动的元素。

继承自

Movable

HTMLElement

移动的元素。

Movable
distance : number = 3

允许触发移动事件的最小指针移动距离(单位:像素)。当移动距离小于这个值时忽略移动操作。

继承自

Movable

number

允许触发移动事件的最小指针移动距离(单位:像素)。当移动距离小于这个值时忽略移动操作。

Movable
startX : number

获取开始移动的水平坐标(单位:像素)。

继承自

Movable

number

获取开始移动的水平坐标(单位:像素)。

Movable
startY : number

获取开始移动的垂直坐标(单位:像素)。

继承自

Movable

number

获取开始移动的垂直坐标(单位:像素)。

Movable
endX : number

获取当前的水平坐标(单位:像素)。

继承自

Movable

number

获取当前的水平坐标(单位:像素)。

Movable
endY : number

获取当前的垂直坐标(单位:像素)。

继承自

Movable

number

获取当前的垂直坐标(单位:像素)。

Movable
offsetX : number

(只读)获取移动的水平距离(单位:像素)。

继承自

Movable

number

(只读)获取移动的水平距离(单位:像素)。

Movable
offsetY : number

(只读)获取移动的垂直距离(单位:像素)。

继承自

Movable

number

(只读)获取移动的垂直距离(单位:像素)。

Movable
方法 描述 继承自
autoScroll(...)(scrollable?:Element | Document, padding?:number, offset?:number):void

自动滚动屏幕。

参数 类型 描述 默认值
scrollable Element | Document
padding number
offset number

返回值

类型:void

自动滚动屏幕。

direction(value)(value:string):void

限制拖动的方向。

参数 类型 描述 默认值
value* "vertical" | "horizontal"

返回值

类型:void

限制拖动的方向。

limit(container, ...)(container:Element | Document | Rect, padding?:number):void

限制只能在指定区域内拖动。

参数 类型 描述 默认值
container* Element | Document | Rect
padding number 0

返回值

类型:void

限制只能在指定区域内拖动。

step(value)(value:number):void

设置拖动的步长。

参数 类型 描述 默认值
value* number

返回值

类型:void

设置拖动的步长。

revert(...)(callback?:function, duration?:number):void

还原位置。

参数 类型 描述 默认值
callback () => void
duration number

返回值

类型:void

还原位置。

snap(target, ...)(target:Element | Document | Rect, padding?:number, distance?:number, position?:string):number

使当前元素吸附于目标位置。

参数 类型 描述 默认值
target* Element | Document | Rect
padding number 0
distance number 15
position "both" | "inside" | "outside" "both"

返回值

类型:number

如果未吸附成功则返回 0,如果水平吸附成功则返回 1,如果垂直吸附成功则返回 2,如果都吸附成功则返回 3。

使当前元素吸附于目标位置。

moveStart(e)(e:MouseEvent):boolean

触发拖动开始事件。

参数 类型 描述 默认值
e* MouseEvent

返回值

类型:boolean

如果返回 false 则忽略本次拖动。

继承自

Movable

(已覆盖)触发拖动开始事件。

Movable
move(e)(e:MouseEvent):boolean

触发拖动移动事件。

参数 类型 描述 默认值
e* MouseEvent

返回值

类型:boolean

继承自

Movable

(已覆盖)触发拖动移动事件。

Movable
moveEnd(e)(e:MouseEvent):void

触发拖动结束事件。

参数 类型 描述 默认值
e* MouseEvent

返回值

类型:void

继承自

Movable

(已覆盖)触发拖动结束事件。

Movable
cancel(e)(e:MouseEvent):boolean

判断是否取消指定事件引发的移动效果。

参数 类型 描述 默认值
e* MouseEvent

返回值

类型:boolean

如果返回 true 则取消移动,否则允许开始移动。

说明

默认地,如果是点击输入域则取消移动。

继承自

Movable

判断是否取消指定事件引发的移动效果。

Movable
enable()():void

启用移动效果。

返回值

类型:void

继承自

Movable

启用移动效果。

Movable
disable()():void

禁用移动效果。

返回值

类型:void

继承自

Movable

禁用移动效果。

Movable
handlePointerDown(e)(e:MouseEvent):void

(保护的)处理指针按下事件。

参数 类型 描述 默认值
e* MouseEvent

返回值

类型:void

继承自

Movable

(保护的)处理指针按下事件。

Movable
handlePointerMove(e)(e:MouseEvent):void

(保护的)处理指针移动事件。

参数 类型 描述 默认值
e* MouseEvent

返回值

类型:void

继承自

Movable

(保护的)处理指针移动事件。

Movable
handlePointerUp(e)(e:MouseEvent):void

(保护的)处理指针松开事件。

参数 类型 描述 默认值
e* MouseEvent

返回值

类型:void

继承自

Movable

(保护的)处理指针松开事件。

Movable
init(e)(e:MouseEvent):void

(保护的)进入移动状态。

参数 类型 描述 默认值
e* MouseEvent

返回值

类型:void

继承自

Movable

(保护的)进入移动状态。

Movable
uninit(e)(e:MouseEvent):void

(保护的)退出移动状态。

参数 类型 描述 默认值
e* MouseEvent

返回值

类型:void

继承自

Movable

(保护的)退出移动状态。

Movable