jianghu-ui 1.0.1

package/src/components/JhDraggable/JhDraggable.md

@@ -0,0 +1,66 @@
+# JhDraggable - 拖拽搭建容器
+
+JhDraggable 是基于 `vuedraggable` 的拖拽容器，提供组件库到设计区域的拖拽、排序能力，适合作为低代码页面的基础框架。
+
+## 功能特性
+
+- 🧱 **双面板设计**：左侧组件库、右侧设计区，支持克隆式拖入
+- 🧠 **受控数据**：组件库/设计区都以数组驱动，可直接持久化配置
+- 🎨 **拖拽状态样式**：`dragClass`、`ghostClass`、`chosenClass` 可自定义
+- 🧲 **空状态引导**：未放入组件时提供占位提示，提高可用性
+- 🔌 **事件透传**：暴露 `start/end/input/change`，方便监听拖拽或保存
+
+## 基础用法
+
+```vue
+<template>
+  <jh-draggable
+    :components="materialList"
+    v-model="pageBlocks"
+    component-library-title="组件库"
+    @change="save"
+  >
+    <template #item="{ item }">
+      <div class="custom-block">{{ item.title }}</div>
+    </template>
+  </jh-draggable>
+</template>
+```
+
+## API
+
+### Props
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| components | 组件库数据源 | Array | [] |
+| value | v-model，设计区元素数组 | Array | [] |
+| showComponentLibrary | 是否显示左侧组件库 | boolean | true |
+| componentLibraryTitle | 左侧标题 | string | `组件` |
+| groupName | vuedraggable 分组名 | string | `draggable-group` |
+| animation | 拖拽动画时长(ms) | number | 300 |
+| dragClass | 拖拽中附加的 class | string | `jh-drag-class` |
+| ghostClass | 占位元素 class | string | `jh-ghost-class` |
+| chosenClass | 选中元素 class | string | `jh-chosen-class` |
+| emptyPlaceholder | 空状态提示文案 | string | `从左侧拖入或点选组件进行内容设计` |
+
+### Events
+
+| 事件名 | 说明 | 回调参数 |
+| --- | --- | --- |
+| input | 设计区内容变更 | (blocks: any[]) |
+| change | 设计区排序/新增后的内容 | (blocks: any[]) |
+| start | 拖拽开始 | - |
+| end | 拖拽结束 | - |
+
+### Slots
+
+| 名称 | 说明 |
+| --- | --- |
+| item | 自定义设计区内每个元素的展示，参数 `{ item }` |
+
+## 使用建议
+
+- 组件默认会为设计区元素补齐唯一 id，建议根据业务字段（如 `component`）渲染
+- 如需拖拽嵌套或跨页面共享，可通过 `groupName` 配置相同分组名
+- 若 `vuedraggable` 未被全局注册，需要在父级组件手动注册/引入

package/src/components/JhDraggable/JhDraggable.stories.js

@@ -0,0 +1,161 @@
+import JhDraggable from './JhDraggable.vue';
+
+export default {
+  title: '基础组件/JhDraggable - 拖拽排序',
+  component: JhDraggable,
+  tags: ['autodocs'],
+  argTypes: {
+    components: {
+      control: 'object',
+      description: '组件库列表',
+    },
+    value: {
+      control: 'object',
+      description: '设计区域的元素列表',
+    },
+    showComponentLibrary: {
+      control: 'boolean',
+      description: '是否显示左侧组件库',
+    },
+    componentLibraryTitle: {
+      control: 'text',
+      description: '组件库标题',
+    },
+    groupName: {
+      control: 'text',
+      description: '拖拽分组名称',
+    },
+    animation: {
+      control: 'number',
+      description: '动画时长（毫秒）',
+    },
+    emptyPlaceholder: {
+      control: 'text',
+      description: '空状态占位文本',
+    },
+  },
+  parameters: {
+    docs: {
+      description: {
+        component: `
+
+基于 Vue.Draggable 的拖拽排序组件。
+
+## 使用前提
+
+需要在项目中安装并引入 vuedraggable：
+
+\`\`\`bash
+npm install vuedraggable
+\`\`\`
+
+或在 HTML 中引入 CDN：
+
+\`\`\`html
+<script src="https://cdn.jsdelivr.net/npm/sortable@1.15.0/Sortable.min.js"></script>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/Vue.Draggable/2.20.0/vuedraggable.umd.min.js"></script>
+\`\`\`
+
+## 功能特性
+
+- 支持从组件库拖拽到设计区
+- 支持设计区内拖拽排序
+- 自动处理 ID 冲突
+- 支持自定义样式
+- 支持空状态提示
+        `,
+      },
+    },
+  },
+};
+
+const formComponents = [
+  { id: 1, name: '输入框', type: 'input' },
+  { id: 2, name: '单选框', type: 'radio' },
+  { id: 3, name: '多选框', type: 'checkbox' },
+  { id: 4, name: '下拉选择', type: 'select' },
+  { id: 5, name: '日期选择', type: 'date' },
+  { id: 6, name: '文本域', type: 'textarea' },
+];
+
+export const 基础示例 = {
+  args: {
+    components: formComponents,
+    value: [],
+    showComponentLibrary: true,
+    componentLibraryTitle: '组件',
+    groupName: 'form-builder',
+    animation: 300,
+    emptyPlaceholder: '从左侧拖入或点选组件进行内容设计',
+  },
+};
+
+export const 预设元素 = {
+  args: {
+    components: formComponents,
+    value: [
+      { id: 101, name: '用户名输入框', type: 'input' },
+      { id: 102, name: '性别单选框', type: 'radio' },
+      { id: 103, name: '兴趣多选框', type: 'checkbox' },
+    ],
+    showComponentLibrary: true,
+    componentLibraryTitle: '表单组件',
+    groupName: 'form-builder',
+    animation: 300,
+    emptyPlaceholder: '从左侧拖入组件',
+  },
+};
+
+export const 无组件库 = {
+  args: {
+    components: [],
+    value: [
+      { id: 1, name: '任务 1', status: 'todo' },
+      { id: 2, name: '任务 2', status: 'in-progress' },
+      { id: 3, name: '任务 3', status: 'done' },
+      { id: 4, name: '任务 4', status: 'todo' },
+    ],
+    showComponentLibrary: false,
+    componentLibraryTitle: '',
+    groupName: 'task-list',
+    animation: 200,
+    emptyPlaceholder: '暂无任务',
+  },
+};
+
+export const 自定义动画 = {
+  args: {
+    components: [
+      { id: 1, name: '标题', type: 'heading' },
+      { id: 2, name: '段落', type: 'paragraph' },
+      { id: 3, name: '图片', type: 'image' },
+      { id: 4, name: '视频', type: 'video' },
+      { id: 5, name: '按钮', type: 'button' },
+    ],
+    value: [],
+    showComponentLibrary: true,
+    componentLibraryTitle: '页面元素',
+    groupName: 'page-builder',
+    animation: 500,
+    emptyPlaceholder: '拖拽元素到这里构建页面',
+  },
+};
+
+export const 卡片组件 = {
+  args: {
+    components: [
+      { id: 1, name: '📊 数据卡片', type: 'data-card' },
+      { id: 2, name: '📈 图表卡片', type: 'chart-card' },
+      { id: 3, name: '📋 列表卡片', type: 'list-card' },
+      { id: 4, name: '📝 表单卡片', type: 'form-card' },
+    ],
+    value: [
+      { id: 100, name: '📊 销售数据', type: 'data-card' },
+    ],
+    showComponentLibrary: true,
+    componentLibraryTitle: '卡片组件',
+    groupName: 'dashboard-builder',
+    animation: 300,
+    emptyPlaceholder: '拖拽卡片组件到这里',
+  },
+};

package/src/components/JhDraggable/JhDraggable.vue

@@ -0,0 +1,254 @@
+<template>
+  <v-app>
+    <v-container fluid>
+      <v-row class="draggable-container">
+        <!-- 左侧组件库 -->
+        <v-col v-if="showComponentLibrary" cols="12" md="3">
+          <div class="title">{{ componentLibraryTitle }}</div>
+          <draggable
+            v-if="isDraggableLoaded"
+            v-model="componentsInternal"
+            :group="{ name: groupName, pull: 'clone', put: false }"
+            :animation="animation"
+            :drag-class="dragClass"
+            :ghost-class="ghostClass"
+            :chosen-class="chosenClass"
+            @start="handleStart"
+            @end="handleEnd"
+          >
+            <transition-group>
+              <div
+                class="draggable-item"
+                v-for="item in componentsInternal"
+                :key="item.id"
+              >
+                {{ item.name }}
+              </div>
+            </transition-group>
+          </draggable>
+        </v-col>
+
+        <!-- 右侧设计区域 -->
+        <v-col :cols="showComponentLibrary ? 12 : 12" :md="showComponentLibrary ? 9 : 12">
+          <draggable
+            v-if="isDraggableLoaded"
+            v-model="designAreaInternal"
+            :group="groupName"
+            :animation="animation"
+            :drag-class="dragClass"
+            :ghost-class="ghostClass"
+            :chosen-class="chosenClass"
+            @start="handleStart"
+            @end="handleEnd"
+          >
+            <transition-group>
+              <div
+                class="draggable-item"
+                v-for="item in designAreaInternal"
+                :key="item.id"
+              >
+                <slot name="item" :item="item">
+                  {{ item.name }}
+                </slot>
+              </div>
+            </transition-group>
+          </draggable>
+
+          <!-- 空状态提示 -->
+          <v-row v-show="!designAreaInternal.length" class="ma-0 pa-0" style="width: 100%;">
+            <v-card height="100" class="ma-12" width="100%" color="#f5f8fa" style="border: 1px dashed #333333">
+              <draggable
+                v-if="isDraggableLoaded"
+                v-model="designAreaInternal"
+                :group="groupName"
+                :animation="animation"
+                :drag-class="dragClass"
+                :ghost-class="ghostClass"
+                class="d-flex align-center justify-center"
+                style="height: 100%;"
+              >
+                <v-card-text class="text-center title draggable-placeholder">
+                  {{ emptyPlaceholder }}
+                </v-card-text>
+              </draggable>
+            </v-card>
+          </v-row>
+        </v-col>
+      </v-row>
+    </v-container>
+  </v-app>
+</template>
+
+<script>
+export default {
+  name: 'JhDraggable',
+  props: {
+    // 组件库列表
+    components: {
+      type: Array,
+      default: () => []
+    },
+    // 设计区域列表
+    value: {
+      type: Array,
+      default: () => []
+    },
+    // 是否显示组件库
+    showComponentLibrary: {
+      type: Boolean,
+      default: true
+    },
+    // 组件库标题
+    componentLibraryTitle: {
+      type: String,
+      default: '组件'
+    },
+    // 分组名称
+    groupName: {
+      type: String,
+      default: 'draggable-group'
+    },
+    // 动画时长
+    animation: {
+      type: Number,
+      default: 300
+    },
+    // 拖拽中的样式类
+    dragClass: {
+      type: String,
+      default: 'jh-drag-class'
+    },
+    // 占位样式类
+    ghostClass: {
+      type: String,
+      default: 'jh-ghost-class'
+    },
+    // 选中样式类
+    chosenClass: {
+      type: String,
+      default: 'jh-chosen-class'
+    },
+    // 空状态占位文本
+    emptyPlaceholder: {
+      type: String,
+      default: '从左侧拖入或点选组件进行内容设计'
+    }
+  },
+  data() {
+    return {
+      drag: false,
+      componentsInternal: [],
+      designAreaInternal: [],
+      isDraggableLoaded: false
+    };
+  },
+  watch: {
+    components: {
+      handler(val) {
+        this.componentsInternal = [...val];
+      },
+      immediate: true,
+      deep: true
+    },
+    value: {
+      handler(val) {
+        this.designAreaInternal = [...val];
+      },
+      immediate: true,
+      deep: true
+    },
+    designAreaInternal: {
+      handler(val) {
+        this.$emit('input', val);
+        this.$emit('change', val);
+      },
+      deep: true
+    }
+  },
+  mounted() {
+    // 检查 vuedraggable 是否已加载
+    this.checkDraggableLibrary();
+  },
+  methods: {
+    checkDraggableLibrary() {
+      // 检查是否有 draggable 组件可用
+      if (this.$options.components.draggable || window.vuedraggable) {
+        this.isDraggableLoaded = true;
+      } else {
+        console.warn('Vue Draggable library is not loaded. Please include vuedraggable library.');
+        // 提供一个降级方案，使用原生的 v-for
+        this.isDraggableLoaded = false;
+      }
+    },
+    handleStart() {
+      this.drag = true;
+      this.$emit('start');
+    },
+    handleEnd() {
+      this.drag = false;
+      this.ensureUniqueIds();
+      this.$emit('end');
+    },
+    // 确保每个项目有唯一的 id
+    ensureUniqueIds() {
+      const allIds = [
+        ...this.componentsInternal.map(item => item.id),
+        ...this.designAreaInternal.map(item => item.id)
+      ];
+      let maxId = Math.max(...allIds);
+
+      this.designAreaInternal.forEach(item => {
+        if (this.componentsInternal.some(comp => comp.id === item.id)) {
+          item.id = ++maxId;
+        }
+      });
+    }
+  }
+};
+</script>
+
+<style scoped>
+.draggable-container {
+  margin: 10px;
+}
+
+.title {
+  padding: 6px 12px;
+  font-weight: 500;
+  color: #333;
+}
+
+.draggable-item {
+  padding: 6px 12px;
+  margin: 0px 10px 6px 10px;
+  border: solid 1px #eee;
+  background-color: #f1f1f1;
+  cursor: move;
+  transition: background-color 0.2s;
+}
+
+.draggable-item:hover {
+  background-color: #fdfdfd;
+}
+
+:deep(.jh-ghost-class) {
+  background-color: #e3f2fd !important;
+  opacity: 0.8 !important;
+}
+
+:deep(.jh-chosen-class) {
+  background-color: #bbdefb !important;
+  opacity: 1 !important;
+}
+
+:deep(.jh-drag-class) {
+  background-color: #90caf9 !important;
+  opacity: 0.9 !important;
+  box-shadow: 0 2px 4px rgba(0,0,0,0.2) !important;
+}
+
+.draggable-placeholder {
+  color: #999;
+  user-select: none;
+}
+</style>

package/src/components/JhDrawer/JhDrawer.md

@@ -0,0 +1,68 @@
+# JhDrawer - 抽屉面板组件
+
+JhDrawer 提供左右或底部滑出的信息面板，包含统一的头部、操作按钮和默认内容区域，适合在列表页展示详情、表单或设置。
+
+## 功能特性
+
+- 📐 **多方向弹出**：通过 `position` 快速切换左/右/底部抽屉
+- 🎯 **受控显示**：`v-model` 控制开关，自动派发 open/close 事件
+- 🧩 **插槽扩展**：`actions` 插槽可自定义按钮组，默认提供确定/取消
+- 📏 **自定义尺寸**：支持百分比或像素宽度，满足不同布局
+- 🔔 **快捷操作**：内置浮动关闭按钮，移动端也可轻松关闭
+
+## 基础用法
+
+```vue
+<template>
+  <jh-drawer
+    v-model="visible"
+    title="高级筛选"
+    width="480px"
+    @confirm="submit"
+    @cancel="close"
+  >
+    <filter-form />
+  </jh-drawer>
+</template>
+```
+
+## API
+
+### Props
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| value | v-model，抽屉显隐 | boolean | false |
+| title | 标题文本 | string | `抽屉` |
+| position | 抽屉位置 `left/right/bottom` | string | `right` |
+| width | 抽屉宽度，支持百分比或像素 | string / number | `90%` |
+| height | 底部抽屉高度，支持百分比、像素或 `vh` | string / number | `60vh` |
+| showConfirmButton | 是否显示确认按钮 | boolean | true |
+| showCancelButton | 是否显示取消按钮 | boolean | true |
+| showCloseButton | 是否显示浮动关闭按钮 | boolean | true |
+| confirmText | 确认按钮文本 | string | `确认` |
+| cancelText | 取消按钮文本 | string | `取消` |
+
+### Events
+
+| 事件名 | 说明 | 回调参数 |
+| --- | --- | --- |
+| input | `v-model` 绑定事件 | (visible: boolean) |
+| open | 抽屉打开时触发 | - |
+| close | 抽屉关闭后触发 | - |
+| confirm | 点击确认按钮触发 | - |
+| cancel | 点击取消按钮或浮动关闭触发 | - |
+
+### Slots
+
+| 名称 | 说明 |
+| --- | --- |
+| default | 主体内容区域 |
+| actions | 头部按钮区域，覆盖默认确认/取消按钮 |
+
+## 使用建议
+
+- 当抽屉内容需要滚动时，可自行在插槽内部包裹滚动容器
+- 通过监听 `confirm/cancel` 事件，在外部控制提交或关闭逻辑
+- 底部抽屉默认隐藏浮动关闭按钮，可在内容区自行提供操作区
+- 配合 `JhDrawerForm` 可以快速构建配置中心、复杂筛选面板