--- title: "可排序列表" description: "拖拽时重新排序的列表、标签栏和网格——makeSortableList 渲染草稿，makeSortableItem 创建行，放置时新顺序写入你的 ref。另有手柄、插入线和交换。" canonical_url: "https://zizigy.github.io/vue-dnd-kit/zh/docs/guides/sortable-lists" --- > Index of every page on this site: [llms.txt](https://zizigy.github.io/vue-dnd-kit/llms.txt) ## 列表和它的行 可排序列表需要两个组件：列表，以及它的行。 ```vue [LayersPanel.vue] ``` ```vue [LayerRow.vue] ``` 行会注册到渲染它的那个列表中。一个组件可以创建多个列表（两列、列表中的列表）：每一行加入元素包含它的那个列表，列表嵌套时加入最内层的列表。 ## 草稿 `makeSortableList` 返回 `items`，它是你的数组的一份**草稿**。拖拽时，草稿实时重新排序：被拖拽的行占据新的位置，其他行滑开让路。在放置之前，你的数组不会改变。放置时，库把新顺序写入其中。 上面的图层面板同时展示了两者：面板渲染 `items`，拖拽时随之移动；画板读取 `layers`，也就是数组本身，只有在你松开时才重新叠放。 - 渲染 `items`，而不是你的数组。如果渲染你的数组，放置之前什么都不会动。 - 写入发生在列表的 `onDrop` 之后。在 `onDrop` 中，你的数组仍是旧顺序，`e.result` 是新顺序。 - `layers` 是普通的 ref（这里是 `defineModel`，写入时会触发 `update:modelValue`），所以应用的其他部分会像看到任何其他变化一样看到它。 ```ts makeSortableList(list, { items: layers, onDrop: (e) => { console.log(e.from.index, '→', e.to.index, e.result.get(e.to.list)); }, }); ``` 使用 store、服务端状态或不可变数据？传入 getter 或 `computed`，而不是 ref。库不会写入只读的数据源：调用 `e.preventDefault()`，然后自己应用 `e.result`。见[受控列表](https://zizigy.github.io/docs/guides/shared-lists#controlled-lists)。 ## Key 行按它们的数据作为 key，从不按索引或自动生成的 id。默认 key 是 `item.id`，对于字符串和数字则是项本身。 ```ts // LayersPanel.vue: your items have another key makeSortableList(list, { items: layers, getKey: (layer) => layer.uuid }); // LayerRow.vue: `item` is keyed with the list's getKey… makeSortableItem(el, { item: () => props.layer }); // …or pass the key yourself makeSortableItem(el, { id: () => props.layer.uuid }); ``` - 在 `v-for` 中使用相同的 key：`:key="layer.uuid"`。使用 `:key="index"` 时，会有错误的行产生动画，行的状态也会在行之间跳动。 - key 在所有相互交换项的列表中必须唯一。 - 以 getter 形式传入 `item` 和 `id`，这样行的 props 变化时它也能保持同步。 ## 手柄 默认情况下，整行都能开始拖拽，但其中的按钮、输入框和其他控件除外：图层的眼睛和锁仍是普通按钮。传入 `handle`，就只能通过某一部分拖拽： ```vue [LayerRow.vue] ``` - `handle` 是项内部的一个选择器，或一个元素 ref。 - 鼠标拖拽从手柄立即开始，无需通常的 4 px。按下后不移动仍然是点击：手柄可以在 `click` 时打开菜单。 - 手柄获得拖拽的属性（`role`、`tabindex`、`aria-*`），键盘拖拽也从它开始。 把手柄做成带 `aria-label` 的 `