# DragSelectDoc

**Repository Path**: ilizan/DragSelect-Doc-Cn

## Basic Information

- **Project Name**: DragSelectDoc
- **Description**: 简单的javascript拖动选择选中插件DragSelect文档说明，类似 window 系统文件拖动选择效果
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 8
- **Created**: 2023-07-10
- **Last Updated**: 2023-07-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DragSelect 中文文档

# 介绍
简单的javascript拖动选择功能插件，类似 window 系统文件拖动选择效果，不依赖任何第三方项目

## Demo
[演示效果](https://ovsexia.gitee.io/dragselect-doc-cn/demo.html)

## 安装教程

### 1.CDN
`<script src="https://thibaultjanbeyer.github.io/DragSelect/ds.min.js"></script>`

### 2.npm
`npm install --save dragselect`

### 3.bower
`bower install --save dragselect`

### 4.将`ds.min.js`直接存放至你的网站空间


## 使用说明

### 1.一个最基础的实例，填写可被选中的元素

```
new DragSelect({
  selectables: document.getElementsByClassName('selectable-nodes')
});
```

### 2.在限定区域内生效，只能在选定的容器内部使用
```
new DragSelect({
  selectables: document.getElementsByClassName('selectable-nodes'),
  area: document.getElementById('area')
});
```

### 3.其他扩展，所有选项都是可选的，详情看参数和方法

```
var ds = new DragSelect({
  selectables: document.getElementsByClassName('selectable-nodes'), // 可被选中的元素节点
  selector: document.getElementById('rectangle'), // 可手动添加一个拖动选择框（译者：可用于修改拖动选择框的样式，需要手动添加 css 的 position:absolute 样式）
  area: document.getElementById('area'), // 拖动生效的区域，如果未提供，它将是整个网页文档
  customStyles: false,  // 如果设置为true，则默认情况下拖动选择框将不应用任何样式（绝对位置除外）
  multiSelectKeys: ['ctrlKey', 'shiftKey', 'metaKey'],  // 允许多选的特殊键，默认为 ctrl，shift，meta(Mac系统的专有键)
  multiSelectMode: false,  // 如果设置为true，则默认情况下将启用多选行为，而无需使用多选键，默认值：false
  autoScrollSpeed: 3,  // 选择时区域滚动的速度（如果有），单位是像素，设置为0以禁用自动滚动，默认值：1
  onDragStart: function(element) {}, // 用户点击该区域时触发此回调，在DragSelect函数代码运行之后执行，用于设置事件侦听器
  onDragMove: function(element) {}, // 用户拖动该区域时触发此回调，在DragSelect函数代码运行之后执行，用于设置事件侦听器   
  onElementSelect: function(element) {}, // 每次选择元素时触发的回调函数
  onElementUnselect: function(element) {}, // 每次取消选择元素时触发的回调函数
  callback: function(elements) {} // 用户释放鼠标后触发，返回所有被选定的元素节点
});
```

```
// 如果像我们一样将函数添加到变量中，则可以访问其所有函数
// 然后我们就可以先这样使用 start() 和 stop() 方法了
ds.getSelection();  // 返回所有被选定的元素节点
ds.addSelectables(document.getElementsByClassName('selectable-node'));  // 添加可以选择的元素，智能算法保证不会添加同个元素两次
ds.break();  // 在回调中使用以禁用即将执行的代码（译者：暂不知道有什么用）
ds.stop();  // 暂停功能
ds.start();  // 暂停后重启功能
// 还有更多内容，请参见文档中的“方法”部分
```

## 参数
### 所有选项都是可选的

| 参数 | 类型 | 用法 |
|--- |--- |--- |
|selectables |DOM elements (nodes) |可被选中的元素节点 |
|selector |single DOM element (node) |可手动添加一个拖动选择框（译者：可用于修改拖动选择框的样式，需要手动添加 css 的 position:absolute 样式） |
|area |single DOM element (node) |拖动生效的区域，如果未提供，它将是整个网页文档 |
|customStyles |boolean |如果设置为true，则默认情况下拖动选择框将不应用任何样式（绝对位置除外） |
|multiSelectKeys |array |允许切换到多选模式的按键，可选的值有有：ctrlKey，shiftKey，metaKey（Mac系统的专有键）和altKey，默认=['ctrlKey', 'shiftKey', 'metaKey']。如果要关闭功能，请提供一个空数组[] |
|multiSelectMode |boolean |每次选中新元素时不清空旧的选中元素，默认='false' |
|autoScrollSpeed |integer |选择时区域滚动的速度（如果有），单位是像素，设置为0以禁用自动滚动，默认值：1 |
|selectedClass |string |分配给选中项目的css类名称 |
|hoverClass |string |分配给鼠标悬停项目的css类名称（译者：并不是很理解这个的含义，估计用的不多） |
|selectorClass |string |拖动选择框的css类名称 |
|selectableClass |string |给区域内所有可选元素添加的css类名称 |
|onDragStartBegin |function |用户点击该区域时触发此回调，在DragSelect函数代码运行之前执行，用于设置事件侦听器 |
|onDragStart |function |用户点击该区域时触发此回调，在DragSelect函数代码运行之后执行，用于设置事件侦听器 |
|onDragMove |function |用户拖动该区域时触发此回调，在DragSelect函数代码运行之后执行，用于设置事件侦听器 |
|onElementSelect |function |每次选择元素时触发的回调函数 |
|onElementUnselect |function |每次取消选择元素时触发的回调函数 |
|callback |function |用户释放鼠标后触发，返回所有被选定的元素节点 |

## 方法
当函数保存到变量var foo = new DragSelect（）中时，您可以访问其所有内部函数。
还有更多其他的方法，您可以在官方的文档中找到所有内容，这里只列举最常用的：

| method | properties | usage |
|--- |--- |--- |
|stop |/ |暂停功能 |
|start |/ |暂停后重启功能 |
|break |/ |在回调中使用以禁用即将执行的代码（译者：暂不知道有什么用） |
|getSelection |/ |Returns all currently selected nodes |
|addSelection |DOM elements (nodes), Boolean (callback), Boolean (dontAddToSelectables) |adds one or multiple elements to the selection. If boolean is set to true: callback will be called afterwards. By default, it checks if all elements ere alos in the list of selectables and adds them if not (can be turned off by setting the last boolean to true) |
|removeSelection |DOM elements (nodes), Boolean (callback), Boolean (removeFromSelectables) |removes one or multiple elements to the selection. If boolean is set to true: callback will be called afterwards. If last bolean is set to true, it also removes them from the possible selectable nodes if they were. |
|toggleSelection |DOM elements (nodes), Boolean (callback), Boolean (special) |toggles one or multiple elements to the selection. If element is not in selection it will be added, if it is already selected, it will be removed. If boolean is set to true: callback will be called afterward. If last boolean is set to true, it also removes selected elements from possible selectable nodes & doesn’t add them to selectables if they are not. |
|setSelection |DOM elements (nodes), Boolean (callback), Boolean (dontAddToSelectables) |将选择内容设置为一个或多个元素。如果boolean设置为true：回调将在之后被调用。 默认情况下，它检查所有元素是否都在可选列表中，如果不存在则添加它们（可以通过将最后一个布尔值设置为true来关闭） |
|clearSelection |DOM elements (nodes), Boolean (callback) |从选择中删除所有元素。如果boolean设置为true：回调将在之后被调用。 |
|addSelectables |DOM elements (nodes), Boolean (addToSelection) |添加可以选择的元素。智能的算法可确保节点永远不会被添加两次。如果boolean设置为true：元素也将添加到当前选择中。 |
|removeSelectables |DOM elements (nodes), Boolean (removeFromSelection) |删除可以选择的元素。如果boolean设置为true：元素也将从当前选择中删除。 |
|getSelectables |/ |返回所有选中元素节点数组。 |
|setSelectables |DOM elements (nodes), Boolean (removeFromSelection), Boolean (addToSelection) |设置所有可以选择的元素。删除所有当前的可选择项，添加新设置的选项到选项列表。如果应该从选择中删除旧元素，则第一个布尔值为true。如果要将新元素添加到选择中，第二个布尔值为true。 |
|getInitialCursorPosition |/ |返回第一次单击时光标的x，y坐标 |
|getCurrentCursorPosition |/ |返回当前/上次注册的光标的x，y坐标 |
|getCursorPositionDifference |Boolean (usePreviousCursorDifference) |返回对象的初始和最后光标位置之间的x，y差。如果参数设置为true，则将x，y的差值返回到先前的选择 |
|getCursorPos |Event, Node (_area), Boolean (ignoreScroll) |Returns the cursor x, y coordinates *based on a click event object*. The click event object is required. By default, takes scroll and area into consideration. Area is this.area by default and can be fully ignored by setting the second argument explicitely to false. Scroll can be ignored by setting the third argument to true. |