Draggabilly中文文档

Draggabilly中文文档

根据Draggabilly官方文档翻译，由于英文水平有限，部分内容可能有误。本文档只翻译了主要的选项配置等，想了解更多请查看官方文档。

js拖拽插件

1.0版本支持ie8+和多点触控
2.0版本支持ie10+和多点触控

github地址

安装

获取源码打包文件

• draggabilly.pkgd.min.js 压缩版
• draggabilly.pkgd.js 未压缩版

包管理工具

使用npm安装：npm install draggabilly
使用Bower安装：bower install draggabilly

CDN

通过cdn直接链接到Draggabilly文件

<!-- 1.0版本 -->
<script src="//cdnjs.cloudflare.com/ajax/libs/draggabilly/1.2.4/draggabilly.pkgd.min.js"></script>
<!-- 或者 -->
<script src="//cdnjs.cloudflare.com/ajax/libs/draggabilly/1.2.4/draggabilly.pkgd.js"></script>

<!-- 2.0版本 -->
<script src="https://unpkg.com/draggabilly@2/dist/draggabilly.pkgd.min.js"></script>
<!-- 或者 -->
<script src="https://unpkg.com/draggabilly@2/dist/draggabilly.pkgd.js"></script>

使用

初始化draggabilly为一个jQuery插件

var $draggable = $('.draggable').draggabilly({
  // 选项（配置）...
})

使用原生js初始化

var elem = document.querySelector('.draggable');
var draggie = new Draggabilly( elem, {
  // 选项...
});

// 或者直接将元素作为第一个参数
var draggie = new Draggabilly( '.draggable', {
  // 选项...
});

// 如果你有多个.draggable元素
// 首先获取所有的拖拽元素
var draggableElems = document.querySelectorAll('.draggable');
// 设置一个数组用来存放初始化后的所有拖拽元素
var draggies = []
// 初始化
for ( var i=0, len = draggableElems.length; i < len; i++ ) {
  var draggableElem = draggableElems[i];
  var draggie = new Draggabilly( draggableElem, {
    // 选项...
  });
  draggies.push( draggie );
}

相关的class
- .is-pointer-down 当用户鼠标第一次点击（或触摸）时添加
- .is-dragging 当元素开始拖拽时添加

选项（配置）

axis

类型： 字符串（String）
值： ‘x’ 或者 ‘y’

axis: 'x'

元素允许在水平或垂直方向上拖动，默认是水平垂直均可

containment

类型：元素、选择器字符串 或 布尔值

containment: '.container'

包含元素边界的移动。如果true，容器将是父元素。

grid

类型： 数组（Array）
值： [ x, y ]

grid: [ 20, 20 ]

网格式移动元素，每x和y像素移动元素

handle

类型： 选择器字符串

handle: '.handle'

指定拖动交互开始的元素。
句柄（操作器）是有用的，当你不想所有的内部元素被用于拖动，如输入和表单。

事件

使用jquery标准事件.on()、.off()、和.one().，事件里面的this指向当前拖拽的元素。

// jQuery
function listener(/* 参数 */) {
  // 获取拖拽元素实例
  var draggie = $(this).data('draggabilly');
  console.log( 'eventName happened', draggie.position.x, draggie.position.y );
}
// 绑定事件监听
$draggable.on( 'eventName', listener );
// 移除事件监听
$draggable.off( 'eventName', listener );
// 只触发一次事件监听。注意是one不是on
$draggable.one( 'eventName', function() {
  console.log('eventName happened just once');
});

使用原生js绑定事件.on()、.off()、和.once()，在事件里this指向当前拖拽的元素。

// 原生JS
function listener(/* 参数 */) {
  console.log( 'eventName happened', this.position.x, this.position.y );
}
// 绑定事件监听
draggie.on( 'eventName', listener );
// 移除事件监听
draggie.off( 'eventName', listener );
// 只触发一次事件监听。注意是once不是one或者on
draggie.once( 'eventName', function() {
  console.log('eventName happened just once');
});

dragStart

拖动开始移动前触发，当移动小于2像素时表现为点击。

// jQuery
$draggable.on( 'dragStart', function( event, pointer ) {...})
// 原生JS
draggie.on( 'dragStart', function( event, pointer ) {...})

• event - 类型: 事件 - 原生的mousedown或touchstart事件
• pointer - 类型: 鼠标事件（MouseEvent）或触控事件（Touch）对象 - 这个事件对象有.pageX和.pageY

dragMove

当元素移动时触发。

// jQuery
$draggable.on( 'dragMove', function( event, pointer, moveVector ) {...})
// 原生JS
draggie.on( 'dragMove', function( event, pointer, moveVector ) {...})

• event - 类型: 事件 - 原生的mousemove或者touchmove事件
• pointer - 类型: 鼠标事件（MouseEvent）或触控事件（Touch）对象 - 事件对象有.pageX和.pageY
• moveVector - 类型: 对象 - 当前位置离初始位置的位移 { x: 20, y: -30 }

dragEnd

当元素停止移动时触发。

// jQuery
$draggable.on( 'dragEnd', function( event, pointer ) {...})
// 原生JS
draggie.on( 'dragEnd', function( event, pointer ) {...})

• event - 类型: 事件 - the original mouseup or touchend event
• pointer - 类型: 鼠标事件（MouseEvent）或触控事件（Touch）对象 - 事件对象有.pageX和.pageY

pointerDown

当用户指针按下（鼠标、触摸）时触发。

// jQuery
$draggable.on( 'pointerDown', function( event, pointer ) {...})
// 原生JS
draggie.on( 'pointerDown', function( event, pointer ) {...})

• event - 类型: 事件 - the original mouseup or touchend event
• pointer - 类型: 鼠标事件（MouseEvent）或触控事件（Touch）对象 - 事件对象有.pageX和.pageY

pointerMove

当用户的指针移动时触发。

// jQuery
$draggable.on( 'pointerMove', function( event, pointer, moveVector ) {...})
// 原生JS
draggie.on( 'pointerMove', function( event, pointer, moveVector ) {...})

• event - 类型: 事件 - 原生的mousemove或者touchmove事件
• pointer - 类型: 鼠标事件（MouseEvent）或触控事件（Touch）对象 - 事件对象有.pageX和.pageY
• moveVector - 类型: 对象 - 当前位置离初始位置的位移 { x: 20, y: -30 }

pointerUp

当用户指针离开元素时触发。

// jQuery
$draggable.on( 'pointerUp', function( event, pointer ) {...})
// 原生JS
draggie.on( 'pointerUp', function( event, pointer ) {...})

• event - 类型: 事件 - the original mouseup or touchend event
• pointer - 类型: 鼠标事件（MouseEvent）或触控事件（Touch）对象 - 事件对象有.pageX和.pageY

staticClick

用户的指针压下并没有开始拖动。
单击事件很难拖动界面检测，因为他们是当用户的鼠标触发。draggabilly的staticclick事件解决了，因为它被触发时，用户没有拖。

// jQuery
$draggable.on( 'staticClick', function( event, pointer ) {...})
// 原生JS
draggie.on( 'staticClick', function( event, pointer ) {...})

• event - 类型: 事件 - the original mouseup or touchend event
• pointer - 类型: 鼠标事件（MouseEvent）或触控事件（Touch）对象 - 事件对象有.pageX和.pageY

方法

disable

// jQuery
$draggable.draggabilly('disable')
// vanilla JS
draggie.disable()

enable

// jQuery
$draggable.draggabilly('enable')
// vanilla JS
draggie.enable()

destroy

// jQuery
$draggable.draggabilly('destroy')
// vanilla JS
draggie.destroy()

jQuery.fn.data(‘draggabilly’)

从一个jQuery对象得到draggabilly实例。draggabilly实例访问draggabilly有用的属性。

var draggie = $('.draggable').data('draggabilly')
// access Draggabilly properties
console.log( 'draggie at ' + draggie.position.x + ', ' + draggie.position.y )

Properties（属性）

position

{ x: 20, y: -30 }

• x 整数
• y 整数