useSortable

类别

@Integrations

导出体积

486 B

依赖包

@vueuse/integrations

上次更改

2 months ago

sortable 的封装。

要了解可以传递的选项的更多信息，请参阅 Sortable 文档中的 Sortable.options。

WARNING

目前，useSortable 仅实现了单个列表的拖放排序。

示例

源码 playground (beta)

[{"id":1,"name":"a"},{"id":2,"name":"b"},{"id":3,"name":"c"}]

Available in the @vueuse/integrations add-on.

安装

bash

npm i sortablejs@^1

使用方法

使用模板引用

vue

<script setup lang="ts">
import { useSortable
 } from '@vueuse/integrations/useSortable'
import { shallowRef
, useTemplateRef
 } from 'vue'

const el
 = useTemplateRef
('el')
const list
 = shallowRef
([{ id
: 1, name
: 'a' }, { id
: 2, name
: 'b' }, { id
: 3, name
: 'c' }])

useSortable
(el
, list
)
</script>

<template>
  <div
 ref
="el
">
    <div
 v-for="item
 in list
" :key
="item
.id
">
      {{ item
.name
 }}
    </div
>
  </div
>
</template>

使用指定的选择器操作

vue

<script setup lang="ts">
import { useSortable
 } from '@vueuse/integrations/useSortable'
import { shallowRef
, useTemplateRef
 } from 'vue'

const el
 = useTemplateRef
('el')
const list
 = shallowRef
([{ id
: 1, name
: 'a' }, { id
: 2, name
: 'b' }, { id
: 3, name
: 'c' }])

const animation
 = 200

const { option
 } = useSortable
(el
, list
, {
  handle
: '.handle',
  // 或者设置 option
  // animation
})

// 你可以使用 option 方法设置和获取 Sortable 的选项
option
('animation', animation
)
// option('animation') // 200
</script>

<template>
  <div
 ref
="el
">
    <div
 v-for="item
 in list
" :key
="item
.id
">
      <span
>{{ item
.name
 }}</span
>
      <span
 class
="handle">*</span
>
    </div
>
  </div
>
</template>

使用选择器获取根元素

vue

<script setup lang="ts">
import { useSortable
 } from '@vueuse/integrations/useSortable'
import { shallowRef
 } from 'vue'

const list
 = shallowRef
([{ id
: 1, name
: 'a' }, { id
: 2, name
: 'b' }, { id
: 3, name
: 'c' }])

useSortable
('#dv', list
)
</script>

<template>
  <div
 id
="dv">
    <div
 v-for="item
 in list
" :key
="item
.id
">
      <span
>{{ item
.name
 }}</span
>
    </div
>
  </div
>
</template>

使用组件

vue

<script setup lang="ts">
import { UseSortable
 } from '@vueuse/integrations/useSortable/component'
import { shallowRef
 } from 'vue'

const list
 = shallowRef
([
  { id
: 1, name
: 'a' },
  { id
: 2, name
: 'b' },
  { id
: 3, name
: 'c' },
])
</script>

<template>
  <
UseSortable
 
v-model
=
"
list
"
 
as
=
"
ol
"
 
:options
=
"
{ 
animation
: 150 }
"
>

    <li
 v-for="item
 in list
" :key
="item
.id
">
      {{ item
.name
 }}
    </li
>
  </UseSortable>
</template>

你也可以从作用域插槽中访问辅助函数，如 start、stop 和 option：

vue

<template>
  <UseSortable v-slot="{ stop
, start
 }" v-model
="list">
    <button
 @click
="stop
()">
      停止排序
    </button
>
    <button
 @click
="start
()">
      开始排序
    </button
>
    <div
 v-for="item
 in list" :key
="item
.id">
      {{ item
.name }}
    </div
>
  </UseSortable>
</template>

返回值

属性	说明
`start`	初始化 Sortable 实例（挂载时自动调用）
`stop`	销毁 Sortable 实例
`option`	运行时获取或设置 Sortable 选项

const { start
, stop
, option
 } = useSortable(el, list)

// 停止排序
stop
()

// 重新启动排序
start
()

// 获取/设置选项
option
('animation', 200) // 设置
const animation
 = option
('animation') // 获取

监听元素变化

使用 watchElement 选项，在元素变化时自动重新初始化 Sortable（适用于带 v-if 的场景）。

import { useSortable
 } from '@vueuse/integrations/useSortable'

useSortable
(el, list, {
  watchElement
: true, // 元素变化时自动重新初始化
})

自定义更新处理函数

如果你想要自己处理 onUpdate，可以传递 onUpdate 参数，我们还提供了一个移动项目位置的函数。

import { moveArrayElement
, useSortable
 } from '@vueuse/integrations/useSortable'

useSortable
(el, list, {
  onUpdate
: (e
) => {
    // 做一些事情
    moveArrayElement
(list, e
.oldIndex
, e
.newIndex
, e
)
    // 由于 moveArrayElement 在微任务中执行，需要等待下一次 tick 才能保证完成
    nextTick
(() => {
      /* 做一些事情 */
    })
  }
})

辅助函数

以下辅助函数也被导出：

函数	说明
`moveArrayElement(list, from, to, event?)`	在数组中将元素从一个索引移动到另一个索引
`insertNodeAt(parent, element, index)`	在指定索引处插入 DOM 节点
`removeNode(node)`	从父节点中删除 DOM 节点

类型声明

显示类型声明

export interface UseSortableReturn {
  /**
   * 启动可排序实例
   */
  start
: () => void
  /**
   * 销毁可排序实例
   */
  stop
: () => void
  /**
   * 选项的获取器/设置器
   * @param name Sortable.Options 的属性名称。
   * @param value 一个值。
   */
  option
: (<K
 extends keyof Sortable.Options
>(
    name
: K
,
    value
: Sortable.Options
[K
],
  ) => void) &
    (<K
 extends keyof Sortable.Options
>(name
: K
) => Sortable.Options
[K
])
}
export interface UseSortableOptions extends Options, ConfigurableDocument {
  /**
   * Watch the element reference for changes and automatically reinitialize Sortable
   * when the element changes.
   *
   * When `false` (default), Sortable is only initialized once on mount.
   * You must manually call `start()` if the element reference changes.
   *
   * When `true`, automatically watches the element reference and reinitializes
   * Sortable whenever it changes (e.g., conditional rendering with v-if).
   *
   * @default false
   */
  watchElement
?: boolean
}
export declare function useSortable
<T
>(
  selector
: string,
  list
: MaybeRef
<T
[]>,
  options
?: UseSortableOptions,
): UseSortableReturn
export declare function useSortable
<T
>(
  el
: MaybeRefOrGetter
<MaybeElement
>,
  list
: MaybeRef
<T
[]>,
  options
?: UseSortableOptions,
): UseSortableReturn
/**
 * Inserts a element into the DOM at a given index.
 * @param parentElement
 * @param element
 * @param {number} index
 * @see https://github.com/Alfred-Skyblue/vue-draggable-plus/blob/a3829222095e1949bf2c9a20979d7b5930e66f14/src/utils/index.ts#L81C1-L94C2
 */
export declare function insertNodeAt
(
  parentElement
: Element,
  element
: Element,
  index
: number,
): void
/**
 * Removes a node from the DOM.
 * @param {Node} node
 * @see https://github.com/Alfred-Skyblue/vue-draggable-plus/blob/a3829222095e1949bf2c9a20979d7b5930e66f14/src/utils/index.ts#L96C1-L102C2
 */
export declare function removeNode
(node
: Node): void
export declare function moveArrayElement
<T
>(
  list
: MaybeRef
<T
[]>,
  from
: number,
  to
: number,
  e
?: Sortable.SortableEvent
 | null,
): void