Vue 无渲染组件库

一个兼容 Vue 2 和 Vue 3 的无渲染（Renderless）组件库，提供强大的拖动排序功能。

✨ 特性

• 🚀 Vue 2/3 兼容: 同时支持 Vue 2.6+ 和 Vue 3.x
• 🎨 无渲染设计: 完全的样式自由度，逻辑与UI分离
• 🖱️ 智能拖动预览: 自动生成拖动预览，支持自定义抓取区域
• 📱 移动端友好: 支持触摸设备的拖动操作
• 🎯 TypeScript 支持: 完整的类型定义
• 🔧 灵活配置: 支持禁用、自定义样式类等配置
• 📦 轻量级: 无额外依赖，体积小巧

📦 安装

npm install @yeepay/vue-renderless-components
# 或
yarn add @yeepay/vue-renderless-components
# 或
pnpm add @yeepay/vue-renderless-components

🚀 快速开始

安装和注册

方式1：使用插件（推荐）

Vue 3:

import { createApp } from 'vue';
import VueRenderlessComponents, { createInstaller } from '@yeepay/vue-renderless-components';
import App from './App.vue';

const app = createApp(App);

// 方法1：直接使用，库会自动检测Vue版本
app.use(VueRenderlessComponents);

// 方法2：明确指定Vue版本
const installer = createInstaller(Vue);
app.use(installer);

app.mount('#app');

Vue 2:

import Vue from 'vue';
import { createInstaller } from '@yeepay/vue-renderless-components';

// 传入Vue构造函数，库会自动选择Vue 2组件
const installer = createInstaller(Vue);
Vue.use(installer);

方式2：手动获取组件

import { getRenderlessDragSorter } from '@yeepay/vue-renderless-components';

// 根据Vue版本自动获取对应组件
const RenderlessDragSorter = getRenderlessDragSorter(Vue);

// Vue 3
app.component('RenderlessDragSorter', RenderlessDragSorter);

// Vue 2
Vue.component('RenderlessDragSorter', RenderlessDragSorter);

使用方式（Vue 2 和 Vue 3 统一）

<template>
  <RenderlessDragSorter 
    :items="tasks" 
    v-slot="{ items, dragEvents, isDragging, draggedIndex, overIndex }"
    @update:items="tasks = $event">
    
    <div class="sortable-list">
      <div 
        v-for="(item, index) in items" 
        :key="item.id"
        class="sort-item"
        :class="{
          dragging: isDragging && index === draggedIndex,
          over: isDragging && index === overIndex
        }"
        v-bind="dragEvents(item, index)"
      >
        <h3>{{ item.title }}</h3>
        <p>{{ item.description }}</p>
      </div>
    </div>
  </RenderlessDragSorter>
</template>

<script>
export default {
  data() {
    return {
      tasks: [
        { id: 1, title: "任务1", description: "描述1" },
        { id: 2, title: "任务2", description: "描述2" },
        { id: 3, title: "任务3", description: "描述3" }
      ]
    };
  }
};
</script>

📖 API 文档

Props

| 属性名 | 类型 | 默认值 | 说明 | |--------|------|--------|------| | items | Array | [] | 要排序的数据数组，每个项目必须有唯一的 id | | disabled | Boolean | false | 是否禁用拖动功能 | | dragClass | String | '' | 拖动时添加的CSS类名 | | overClass | String | '' | 拖动悬停时添加的CSS类名 |

Events

| 事件名 | 参数 | 说明 | |--------|------|------| | update:items | (items: Array) | 排序改变时触发，返回新的数组 | | drag-start | (item: Object, index: number) | 开始拖动时触发 | | drag-end | (item: Object, index: number) | 拖动结束时触发 | | drag-over | (item: Object, index: number) | 拖动悬停时触发 | | drop | (item: Object, fromIndex: number, toIndex: number) | 放置时触发 |

Slot Props

| 属性名 | 类型 | 说明 | |--------|------|------| | items | Array | 当前的数据数组 | | dragEvents | Function | 返回整个项目的拖动事件处理器 | | handleEvents | Function | 返回抓取区域的拖动事件处理器 | | dropEvents | Function | 返回放置区域的事件处理器 | | isDragging | Boolean | 是否正在拖动 | | draggedIndex | Number | 当前拖动项目的索引 | | overIndex | Number | 当前悬停位置的索引 |

🎯 使用场景

1. 默认拖动（整个项目可拖动）

<RenderlessDragSorter :items="items" v-slot="{ items, dragEvents, isDragging, draggedIndex, overIndex }">
  <div v-for="(item, index) in items" :key="item.id" v-bind="dragEvents(item, index)">
    <!-- 项目内容 -->
  </div>
</RenderlessDragSorter>

2. 自定义抓取区域

<RenderlessDragSorter :items="items" v-slot="{ items, handleEvents, dropEvents, isDragging, draggedIndex, overIndex }">
  <div v-for="(item, index) in items" :key="item.id" v-bind="dropEvents(item, index)">
    <div class="drag-handle" v-bind="handleEvents(item, index)">⋮⋮</div>
    <!-- 项目内容 -->
  </div>
</RenderlessDragSorter>

🎨 样式定制

组件不包含任何默认样式，您可以完全自定义样式：

.sort-item {
  padding: 15px;
  border: 1px solid #ddd;
  margin-bottom: 10px;
  transition: all 0.3s ease;
}

.sort-item.dragging {
  opacity: 0.5;
}

.sort-item.over {
  border: 2px dashed #2196f3;
  background-color: #bbdefb;
}

/* 拖动预览样式（自动生成） */
.drag-preview {
  position: fixed;
  z-index: 1000;
  pointer-events: none;
  opacity: 0.9;
  transform: rotate(5deg) scale(0.9);
  box-shadow: 0 10px 20px rgba(0, 0, 0, 0.2);
}

🔧 高级配置

禁用拖动

<RenderlessDragSorter :items="items" :disabled="true">
  <!-- 内容 -->
</RenderlessDragSorter>

自定义事件处理

<RenderlessDragSorter 
  :items="items"
  @drag-start="onDragStart"
  @drag-end="onDragEnd"
  @drop="onDrop">
  <!-- 内容 -->
</RenderlessDragSorter>

🌐 浏览器支持

• Chrome >= 51
• Firefox >= 54
• Safari >= 10
• Edge >= 79
• IE >= 11（需要polyfill）

📄 License

MIT License

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📝 更新日志

v1.0.0

• 🎉 初始版本发布
• ✅ 支持 Vue 2 和 Vue 3
• ✅ 无渲染拖动排序组件
• ✅ TypeScript 支持
• ✅ 完整的示例和文档