xtf-drag-layout

组件说明

xtf-drag-layout 是拖拽排序布局组件，用于展示可拖拽排序的网格项。支持触摸和鼠标拖拽、删除按钮、添加按钮、自定义列数和最大数量，适用于图片排序、模块管理和自定义布局等场景。

---

基础用法

1. 最简示例

通过 value / v-model 绑定数据列表：

<template>
  <xtf-drag-layout v-model="items" :cols="4" :max="9" @add="onAdd" @remove="onRemove" />
</template>

<script>
export default {
  data() {
    return {
      items: [
        { id: 1, url: '/static/img1.png', name: '图片1' },
        { id: 2, url: '/static/img2.png', name: '图片2' },
        { id: 3, url: '/static/img3.png', name: '图片3' }
      ]
    }
  },
  methods: {
    onAdd() {},
    onRemove(item) {}
  }
}
</script>

2. 自定义列数与间距

通过 cols 设置列数，通过 gap 设置间距：

<template>
  <xtf-drag-layout v-model="items" :cols="3" :gap="16" :max="6" />
</template>

<script>
export default {
  data() {
    return {
      items: [
        { id: 1, url: '/static/img1.png', name: 'A' },
        { id: 2, url: '/static/img2.png', name: 'B' }
      ]
    }
  }
}
</script>

3. 禁用拖拽

通过 disabled 禁用拖拽和删除：

<template>
  <xtf-drag-layout v-model="items" :cols="4" disabled show-readonly-mask />
</template>

<script>
export default {
  data() {
    return {
      items: [
        { id: 1, url: '/static/img1.png', name: '只读1' },
        { id: 2, url: '/static/img2.png', name: '只读2' }
      ]
    }
  }
}
</script>

---

全部属性

属性	类型	默认值	作用描述	适用范围
value / modelValue	Array	[]	数据列表	双向绑定
srcKey	String	'url'	图片地址字段名	数据映射
labelKey	String	'name'	标签字段名	数据映射
idKey	String	'id'	唯一标识字段名	数据映射
cols	Number	4	列数	布局
max	Number	9	最大数量	数量限制
imageWidth	Number	0	图片宽度	图片尺寸
imageHeight	Number	0	图片高度	图片尺寸
itemWidthKey / itemHeightKey	String	'width' / 'height'	项内自定义尺寸字段名（rpx）	数据映射
colSpanKey / rowSpanKey	String	'colSpan' / 'rowSpan'	项内横向、纵向占格字段名	数据映射
borderRadius / padding	Number	24 / 12	卡片圆角与单元格内边距（rpx）	布局
dragScale / dragOpacity / dragDamping	Number	1.08 / 0.82 / 40	拖拽时缩放、透明度和跟随阻尼（ms）	拖拽效果
snapDuration / dragTransitionDuration	Number	120 / 180	吸附与视觉过渡时长（ms）	动画
deletable	Boolean	true	是否可删除	删除
showDeleteButton	Boolean	true	是否显示删除按钮	删除按钮
deleteIcon	String	'×'	删除图标文字	删除图标
deleteIconColor	String	''	删除图标颜色	删除图标
deleteIconImage	String	''	删除图标图片地址；设置后优先显示图片	删除图标
deleteBgColor / deleteSize	String / Number	'' / 40	删除按钮背景色与尺寸（rpx）	删除按钮
deletePosition	String	'top-right'	删除按钮位置：'top-right' / 'top-left' / 'bottom-right' / 'bottom-left'	删除按钮
deleteTrigger / deleteLongpressDuration	String / Number	'always' / 320	删除按钮显示时机：'always' / 'hover' / 'longpress'，以及长按时长（ms）	删除按钮
dragShadowColor / dragShadow / dragPlaceholderColor	String	源码默认值	拖拽边框色、阴影和占位色	拖拽效果
showAddButton	Boolean	true	是否显示添加按钮	添加按钮
addText	String	''	添加按钮文字	添加按钮
disabled	Boolean	false	是否禁用拖拽	禁用
showReadonlyMask	Boolean	false	是否显示只读遮罩	只读
readonlyMaskText / readonlyMaskTextKey	String	'只读' / 'readonlyText'	只读遮罩默认文字及项内覆盖字段名	只读
showLabel	Boolean	true	是否显示标签	标签
gap	Number	12	间距	间距
customClass	String	''	自定义类名	样式覆盖
customStyle	String | Object	''	自定义样式	动态样式覆盖
itemClass / itemStyle	String / String | Object	'' / ''	所有拖拽项的附加类名与样式	项样式
itemClassKey / itemStyleKey	String	'itemClass' / 'itemStyle'	项内附加类名与样式的字段名	数据映射

---

事件

事件名称	触发时机	回调参数	参数说明
input / update:modelValue / change	排序或删除完成	(items)	新列表
reorder	拖拽排序完成时触发	(items, moved)	moved 为 { item, from, to }
remove	删除项时触发	(payload)	{ item, index, items }
add	点击添加按钮时触发	-	仅通知父级自行追加数据

插槽

item、delete、readonly-mask 提供 item、display-item、index，其中 item、delete 还提供 remove；add 提供 add。

<template>
  <xtf-drag-layout v-model="items">
    <template #item="{ item, remove }">
      <view @tap="remove">{{ item.name }}</view></template>

    <template #add="{ add }"><xtf-button label="添加" @click="add" /></template>
  </xtf-drag-layout>
</template>
<script>
export default {
  data() {
    return { items: [{ id: 1, name: '封面', url: '/static/a.png' }] }
  }
}
</script>

---

主题说明

• 拖拽项使用卡片样式，带圆角和阴影
• 删除按钮默认在右上角
• 添加按钮使用 + 图标和文字
• 只读遮罩覆盖在项上方

如需全局调整主题，请在 xtf-config-provider 或主题配置中覆盖相关 CSS 变量。