# @bluecateng/smooth-reorder 中文文档

规范地址：https://npmcn.com/package/%40bluecateng/smooth-reorder/

版本：2\.2\.1
npm 元数据更新时间：2026-10-29T21:57:20.455Z
中文译文更新时间：2026-11-08T08:22:17.422Z
软件包许可：ISC

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40bluecateng/smooth-reorder
原文对照：https://npmcn.com/package/%40bluecateng/smooth-reorder/?lang=original
项目主页：https://github.com/bluecatengineering/pelagos-packages#readme
源码仓库：https://github.com/bluecatengineering/pelagos-packages

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：12.8 kB，5 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2020-05-19T20:47:31.754Z
- 最新版本发布：2026-10-29T21:57:20.072Z
- 近 30 天下载量：3408（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 3 个）

## 中文简介

香草JS的平滑列表重排顺序

## 安装

```sh
npm install @bluecateng/smooth-reorder
```

也可以使用：`pnpm add @bluecateng/smooth-reorder`、`yarn add @bluecateng/smooth-reorder`、`bun add @bluecateng/smooth-reorder`

## README

# @ bluecateng/ smooth- 重排 [![GitHub license](https://img.shields.io/badge/license-ISC-blue.svg)](https://github.com/bluecatengineering/pelagos-packages/blob/master/LICENSE) [![npm version](https://img.shields.io/npm/v/@bluecateng/smooth-reorder.svg?style=flat)](https://www.npmjs.com/package/@bluecateng/smooth-reorder)

允许鼠标拖曳或键盘只使用香草 JS 重排列表的顺序 . 在可能情况下随CSS过渡或随同 [@bluecateng/nano-spring (英语)](https://www.npmjs.com/package/@bluecateng/nano-spring)所以感觉更自然. 这些回调允许对无障碍进行反馈.

文章 [4 可访问拖放/排序列表的主要模式](https://medium.com/salesforce-ux/4-major-patterns-for-accessible-drag-and-drop-1d43f64ebf09#0303) 在中文本中有一个如何实施无障碍的实例.

压缩前大小:4,102字节.

# 安装

```bash
npm i -S @bluecateng/smooth-reorder
```

# 示例

```js
import reorder from '@bluecateng/smooth-reorder';

const container = document.querySelector('#test');
reorder(container, {
    onStart: (element, position) => console.log(`Started moving element ${element} from ${position}`),
    onMove: (element, position) => console.log(`Element ${element} will move to ${position}`),
    onMoveEnd: (element, position) => console.log(`Element ${element} is now at ${position}`),
    onFinish: (element) => console.log(`Element ${element} moved`),
    onCancel: (element) => console.log(`Element ${element} move cancelled`),
});
```

该 CSS 必须添加到页面中 :

```css
.draggable {
    cursor: move;
    cursor: grab;
    touch-action: none;
}
.dragging {
    z-index: 1000;
}
.placeholder {
    opacity: 0;
}
.clone {
    position: absolute;
    left: 0;
    top: 0;
    will-change: transform;
}
```

## 选项

| 选项 | 说明 | 默认 |
| --- | --- | --- |
| `horizontal` | 列表是否为水平 . | `false` |
| `selector` | 用于元素重排的 CSS 选择器 . | `.draggable` |
| `handleSelector` | 重排手柄的 CSS 选择器 . | `selector` |
| `focusSelector` | CSS选择器,用于元素聚焦. | `handleSelector` |
| `duration` | 按动画的毫秒计算, `0` 关闭它. | `200` |
| `onStart` | 重排时调用 . |  |
| `onMove` | 当用户要求用键盘移动元素时调用(可选). |  |
| `onMoveEnd` | 在 DOM 中移动元素后调用( 可选) . |  |
| `onFinish` | 当元素被丢弃时调用 . |  |
| `onCancel` | 重排取消时调用 . |  |

如果用户喜欢减少运动(`prefers-reduced-motion: reduce`)动画被禁用,与 设置 `duration` 改为 `0`。 。 。 .

## 生命周期

键盘重排:焦点元素上的空间会抓住它,箭头键会移动它,空间会放下它并取消"逃生".

1.  `onStart(element, index)` 当元素被抓住时立即调用.
2.  每个箭头键调用 `onMove(element, index)` 随即,随索引 元素将拥有。 兄弟姐妹们 然后用 CSS 转换幻灯片, DOM 是 **没有** 更改直到动画结束.
3.  当动画结束( W)`duration` + 5 ms) 元素在 DOM 中被移动 `onMoveEnd(element, index)` 与实际索引一起调用。 这是发布消息的正确地点.
4.  空间呼叫 `onFinish(element)`; 逃逸电话 `onCancel(element)` 在元素被移动回它的后 原地处地. 如果动画正在运行, 按下同时键( 包括放下和取消) 将被排入队列 并按每部动画的收尾顺序处理,所以 `onFinish` 财务报告和审定财务报表 `onCancel` 总是看到最后的DOM.

指针重排通话顺序 `onMoveEnd` 当占位符改变位置时,和 `onFinish` 曾经拖走 部队已进入最后位置. `onStart` 财务报告和审定财务报表 `onMove` 不要求指针.

## 国家属性

容器有属性 `data-reorder-state` 带有其中之一的值,可用于造型或 用于测试,以了解何时可以安全地继续:

-   `idle`: 没有重新排序元素 .
-   `grabbed`: 元素被抓取或拖取, 没有动画运行 .
-   `moving`:移动动画正在运行.

当函数被 `reorder` 名为.

## 产出

![Output](https://raw.githubusercontent.com/bluecatengineering/pelagos-packages/master/packages/smooth-reorder/example.gif)

## 常见问题

### @bluecateng/smooth-reorder 是什么？

香草JS的平滑列表重排顺序

### 如何安装 @bluecateng/smooth-reorder？

在项目目录运行 npm install @bluecateng/smooth-reorder，或使用 pnpm add / yarn add / bun add。

### @bluecateng/smooth-reorder 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @bluecateng/smooth-reorder 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @bluecateng/smooth-reorder 可以商用吗？

@bluecateng/smooth-reorder 使用 ISC 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @bluecateng/smooth-reorder 的下载量有多少？

根据 npm 官方下载统计，@bluecateng/smooth-reorder 在 2026/10/09 – 2026/11/07 这 30 天内被下载 3,408 次，日均约 114 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @bluecateng/smooth-reorder 还在维护吗？

最新版本 2\.2\.1 发布于 2026/10/30（9 天前）；至今共发布 10 个版本，其中过去 12 个月发布了 3 个；首次发布于 2020/05/20。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。