jianghu-ui 1.0.1

package/src/components/JhTableAttachment/JhTableAttachment.md

@@ -0,0 +1,70 @@
+# JhTableAttachment - 附件分组面板
+
+JhTableAttachment 专注于以卡片方式呈现附件列表，内置分组、搜索、预览、下载、删除等能力，可作为表格附件详情的补充。
+
+## 功能特性
+
+- 🗂️ **分组展示**：按 `groupBy` 字段将附件划分多个卡片区域
+- 🔍 **内置搜索**：顶部输入框可实时过滤文件名/类型
+- 👀 **预览能力**：图片类附件支持放大预览，其他类型显示文件图标
+- 📥 **下载/删除事件**：提供 download/delete 事件，方便接入后台接口
+- ➕ **新增入口**：可展示“新增附件”按钮，自定义上传流程
+
+## 基础用法
+
+```vue
+<template>
+  <jh-table-attachment
+    :attachments="attachmentList"
+    group-by="category"
+    :show-create-button="canEdit"
+    @create-click="openUploader"
+    @delete="removeAttachment"
+    @download="downloadAttachment"
+  />
+</template>
+```
+
+## API
+
+### Props
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| attachments | 附件数组 | Array | [] |
+| showCreateButton | 是否显示“新增附件”按钮 | boolean | true |
+| readonly | 是否只读（隐藏删除按钮） | boolean | false |
+| groupBy | 分组字段名 | string | `fileType` |
+| previewPrefix | 预览地址前缀，拼接 `downloadPath` | string | `/upload/` |
+| loading | 是否展示 loading 遮罩 | boolean | false |
+
+附件对象推荐结构：
+
+```js
+{
+  id: 1,
+  filename: '合同.pdf',
+  downloadPath: '2023/contract.pdf',
+  fileType: '合同',
+  fileSubtype: 'pdf'
+}
+```
+
+### Events
+
+| 事件名 | 说明 | 回调参数 |
+| --- | --- | --- |
+| create-click | 点击新增附件按钮 | - |
+| preview | 点击预览按钮 | (item) |
+| download | 点击下载按钮 | (item) |
+| delete | 点击删除按钮 | (item) |
+
+### Slots
+
+组件暂未开放插槽，如需扩展可 fork 组件进行定制。
+
+## 使用建议
+
+- 需要与上传接口联动时，可在 `create-click` 中打开上传抽屉，完成后刷新 `attachments`
+- 若后端已返回文件完整 URL，可把 `previewPrefix` 设为空字符串
+- 通过 `readonly` 控制权限，避免无权限用户看到删除按钮

package/src/components/JhTableAttachment/JhTableAttachment.stories.js

@@ -0,0 +1,198 @@
+import JhTableAttachment from './JhTableAttachment.vue';
+
+export default {
+  title: '基础组件/JhTableAttachment - 附件表格',
+  component: JhTableAttachment,
+  tags: ['autodocs'],
+  argTypes: {
+    attachments: {
+      control: 'object',
+      description: '附件列表数据',
+    },
+    showCreateButton: {
+      control: 'boolean',
+      description: '是否显示新增按钮',
+    },
+    readonly: {
+      control: 'boolean',
+      description: '是否只读模式',
+    },
+    groupBy: {
+      control: 'text',
+      description: '分组字段名',
+    },
+    previewPrefix: {
+      control: 'text',
+      description: '预览路径前缀',
+    },
+    loading: {
+      control: 'boolean',
+      description: '是否加载中',
+    },
+  },
+};
+
+const sampleAttachments = [
+  {
+    id: 1,
+    filename: '合同文档.pdf',
+    downloadPath: 'documents/contract.pdf',
+    fileType: '合同文件',
+    fileSubtype: 'pdf'
+  },
+  {
+    id: 2,
+    filename: '产品图片1.jpg',
+    downloadPath: 'images/product1.jpg',
+    fileType: '产品图片',
+    fileSubtype: 'jpg'
+  },
+  {
+    id: 3,
+    filename: '产品图片2.png',
+    downloadPath: 'images/product2.png',
+    fileType: '产品图片',
+    fileSubtype: 'png'
+  },
+  {
+    id: 4,
+    filename: '技术文档.docx',
+    downloadPath: 'documents/tech.docx',
+    fileType: '技术资料',
+    fileSubtype: 'docx'
+  },
+  {
+    id: 5,
+    filename: '财务报表.xlsx',
+    downloadPath: 'documents/financial.xlsx',
+    fileType: '财务文件',
+    fileSubtype: 'xlsx'
+  },
+  {
+    id: 6,
+    filename: '宣传海报.jpg',
+    downloadPath: 'images/poster.jpg',
+    fileType: '产品图片',
+    fileSubtype: 'jpg'
+  },
+];
+
+export const 基础示例 = {
+  args: {
+    attachments: sampleAttachments,
+    showCreateButton: true,
+    readonly: false,
+    groupBy: 'fileType',
+    previewPrefix: '/upload/',
+    loading: false,
+  },
+};
+
+export const 空数据 = {
+  args: {
+    attachments: [],
+    showCreateButton: true,
+    readonly: false,
+    groupBy: 'fileType',
+    previewPrefix: '/upload/',
+    loading: false,
+  },
+};
+
+export const 加载状态 = {
+  args: {
+    attachments: [],
+    showCreateButton: true,
+    readonly: false,
+    groupBy: 'fileType',
+    previewPrefix: '/upload/',
+    loading: true,
+  },
+};
+
+export const 只读模式 = {
+  args: {
+    attachments: sampleAttachments,
+    showCreateButton: false,
+    readonly: true,
+    groupBy: 'fileType',
+    previewPrefix: '/upload/',
+    loading: false,
+  },
+};
+
+export const 仅图片 = {
+  args: {
+    attachments: [
+      {
+        id: 1,
+        filename: '风景照片1.jpg',
+        downloadPath: 'photos/landscape1.jpg',
+        fileType: '风景照片',
+        fileSubtype: 'jpg'
+      },
+      {
+        id: 2,
+        filename: '风景照片2.jpg',
+        downloadPath: 'photos/landscape2.jpg',
+        fileType: '风景照片',
+        fileSubtype: 'jpg'
+      },
+      {
+        id: 3,
+        filename: '人物照片1.png',
+        downloadPath: 'photos/portrait1.png',
+        fileType: '人物照片',
+        fileSubtype: 'png'
+      },
+      {
+        id: 4,
+        filename: '人物照片2.png',
+        downloadPath: 'photos/portrait2.png',
+        fileType: '人物照片',
+        fileSubtype: 'png'
+      },
+    ],
+    showCreateButton: true,
+    readonly: false,
+    groupBy: 'fileType',
+    previewPrefix: '/upload/',
+    loading: false,
+  },
+};
+
+export const CustomGroupBy = {
+  args: {
+    attachments: [
+      {
+        id: 1,
+        filename: 'report-q1.pdf',
+        downloadPath: 'reports/q1.pdf',
+        fileType: '报告',
+        fileSubtype: 'pdf',
+        year: '2024'
+      },
+      {
+        id: 2,
+        filename: 'report-q2.pdf',
+        downloadPath: 'reports/q2.pdf',
+        fileType: '报告',
+        fileSubtype: 'pdf',
+        year: '2024'
+      },
+      {
+        id: 3,
+        filename: 'report-q1.pdf',
+        downloadPath: 'reports/2025-q1.pdf',
+        fileType: '报告',
+        fileSubtype: 'pdf',
+        year: '2025'
+      },
+    ],
+    showCreateButton: true,
+    readonly: false,
+    groupBy: 'year',
+    previewPrefix: '/upload/',
+    loading: false,
+  },
+};

package/src/components/JhTableAttachment/JhTableAttachment.vue

@@ -0,0 +1,264 @@
+<template>
+  <v-app>
+    <v-container fluid>
+      <v-card class="px-4">
+        <!-- 工具栏 -->
+        <v-row class="ma-0 pt-0 d-flex">
+          <v-btn
+            v-if="showCreateButton"
+            color="success"
+            small
+            dark
+            class="elevation-0 mr-2"
+            @click="handleCreateClick"
+          >
+            新增附件
+          </v-btn>
+
+          <v-spacer></v-spacer>
+
+          <v-col cols="12" sm="6" md="3" xl="3" class="pa-0 pt-2 pt-sm-0">
+            <v-text-field
+              v-model="searchInput"
+              color="success"
+              prefix="表格过滤："
+              class="jh-v-input"
+              dense
+              filled
+              single-line
+              hide-details
+            ></v-text-field>
+          </v-col>
+        </v-row>
+
+        <!-- 附件分组展示 -->
+        <v-card
+          v-for="(itemList, groupName) in groupedAttachments"
+          :key="groupName"
+          outlined
+          class="my-2"
+        >
+          <v-card-title class="pl-4" style="font-size: 20px; font-weight: 500;">
+            {{ groupName }}
+          </v-card-title>
+          <v-card-text style="display: flex; flex-flow: wrap;">
+            <v-card
+              v-for="item in itemList"
+              :key="item.id"
+              width="200px"
+              class="mr-2 mb-2"
+              outlined
+            >
+              <v-img
+                :src="getPreviewUrl(item)"
+                class="white--text align-end"
+                gradient="to bottom, rgba(0,0,0,.1), rgba(0,0,0,.5)"
+                height="120px"
+              >
+                <v-card-title class="text-subtitle-2">{{ item.filename }}</v-card-title>
+              </v-img>
+
+              <v-card-actions>
+                <v-chip small>{{ item.fileSubtype || getFileType(item.filename) }}</v-chip>
+                <v-spacer></v-spacer>
+
+                <!-- 预览按钮 -->
+                <v-btn
+                  v-if="isImage(item.downloadPath || item.filename)"
+                  icon
+                  small
+                  @click="handlePreview(item)"
+                  title="预览"
+                >
+                  <v-icon>mdi-eye</v-icon>
+                </v-btn>
+
+                <!-- 下载按钮 -->
+                <v-btn
+                  v-if="item.downloadPath"
+                  icon
+                  small
+                  @click="handleDownload(item)"
+                  title="下载"
+                >
+                  <v-icon>mdi-download</v-icon>
+                </v-btn>
+
+                <!-- 删除按钮 -->
+                <v-btn
+                  v-if="!readonly"
+                  icon
+                  small
+                  @click="handleDelete(item)"
+                  title="删除"
+                >
+                  <v-icon>mdi-trash-can-outline</v-icon>
+                </v-btn>
+              </v-card-actions>
+            </v-card>
+          </v-card-text>
+        </v-card>
+
+        <!-- 加载状态 -->
+        <v-overlay absolute :value="loading" color="#fff">
+          <v-progress-circular
+            color="success"
+            indeterminate
+            size="32"
+          ></v-progress-circular>
+        </v-overlay>
+
+        <!-- 空状态 -->
+        <div v-if="!loading && filteredAttachments.length === 0" class="mt-5 text-center">
+          暂无附件
+        </div>
+      </v-card>
+
+      <!-- 预览对话框 -->
+      <v-dialog v-model="previewDialog" max-width="90vw">
+        <v-card>
+          <v-card-title>
+            {{ previewItem ? previewItem.filename : '' }}
+            <v-spacer></v-spacer>
+            <v-btn icon @click="previewDialog = false">
+              <v-icon>mdi-close</v-icon>
+            </v-btn>
+          </v-card-title>
+          <v-card-text class="pa-0">
+            <v-img
+              v-if="previewItem"
+              :src="getPreviewUrl(previewItem)"
+              contain
+              max-height="70vh"
+            ></v-img>
+          </v-card-text>
+        </v-card>
+      </v-dialog>
+    </v-container>
+  </v-app>
+</template>
+
+<script>
+export default {
+  name: 'JhTableAttachment',
+  props: {
+    // 附件列表
+    attachments: {
+      type: Array,
+      default: () => []
+      /**
+       * [{
+       *   id: 1,
+       *   filename: '文件名.jpg',
+       *   downloadPath: '/upload/xxx.jpg',
+       *   fileType: '分类名称',
+       *   fileSubtype: 'jpg'
+       * }]
+       */
+    },
+    // 是否显示新增按钮
+    showCreateButton: {
+      type: Boolean,
+      default: true
+    },
+    // 是否只读
+    readonly: {
+      type: Boolean,
+      default: false
+    },
+    // 分组字段名
+    groupBy: {
+      type: String,
+      default: 'fileType'
+    },
+    // 预览路径前缀
+    previewPrefix: {
+      type: String,
+      default: '/upload/'
+    },
+    // 是否加载中
+    loading: {
+      type: Boolean,
+      default: false
+    }
+  },
+  data() {
+    return {
+      searchInput: '',
+      previewDialog: false,
+      previewItem: null
+    };
+  },
+  computed: {
+    filteredAttachments() {
+      if (!this.searchInput) {
+        return this.attachments;
+      }
+      return this.attachments.filter(item =>
+        item.filename.toLowerCase().includes(this.searchInput.toLowerCase()) ||
+        (item.fileType && item.fileType.toLowerCase().includes(this.searchInput.toLowerCase()))
+      );
+    },
+    groupedAttachments() {
+      const grouped = {};
+      this.filteredAttachments.forEach(item => {
+        const groupName = item[this.groupBy] || '未分类';
+        if (!grouped[groupName]) {
+          grouped[groupName] = [];
+        }
+        grouped[groupName].push(item);
+      });
+      return grouped;
+    }
+  },
+  methods: {
+    getPreviewUrl(item) {
+      if (item.downloadPath) {
+        return `${this.previewPrefix}${item.downloadPath}`;
+      }
+      return '/placeholder-image.jpg';
+    },
+    isImage(filename) {
+      if (!filename) return false;
+      return /\.(gif|jpg|jpeg|png|webp|svg|bmp)$/i.test(filename);
+    },
+    getFileType(filename) {
+      if (!filename) return '';
+      const ext = filename.split('.').pop();
+      return ext ? ext.toLowerCase() : '';
+    },
+    handleCreateClick() {
+      this.$emit('create-click');
+    },
+    handlePreview(item) {
+      this.previewItem = item;
+      this.previewDialog = true;
+      this.$emit('preview', item);
+    },
+    handleDownload(item) {
+      this.$emit('download', item);
+      // 默认下载逻辑
+      if (item.downloadPath) {
+        const link = document.createElement('a');
+        link.href = this.getPreviewUrl(item);
+        link.download = item.filename;
+        link.click();
+      }
+    },
+    handleDelete(item) {
+      this.$emit('delete', item);
+    }
+  }
+};
+</script>
+
+<style scoped>
+:deep(.jh-v-input) {
+  border: 1px solid #e5e7eb;
+}
+
+:deep(.jh-v-input .v-input__slot) {
+  margin: 0 !important;
+  background-color: #fff !important;
+}
+</style>

package/src/components/JhToast/JhToast.md

@@ -0,0 +1,67 @@
+# JhToast - 全局提示组件
+
+JhToast 基于 `v-snackbar` 封装，提供成功/错误/警告/信息/加载等多种提示效果，可用于全局消息通知。
+
+## 功能特性
+
+- ⚡ **多状态**：内置 success、error、warning、info、loading 五种风格
+- 📍 **自由定位**：通过 `position` 控制四角/上下等位置
+- 🧭 **按钮扩展**：可同时显示关闭按钮和自定义操作按钮
+- ⏱️ **超时控制**：不同类型可以设置不同的超时时间，loading 默认不自动关闭
+- ✨ **图标自定义**：可传入 icon/iconColor，也可完全隐藏
+
+## 基础用法
+
+```vue
+<template>
+  <jh-toast
+    v-model="toast.visible"
+    :message="toast.message"
+    :type="toast.type"
+    position="bottom-right"
+    action-text="撤销"
+    @action="undo"
+  />
+</template>
+```
+
+## API
+
+### Props
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| value | `v-model`，控制显隐 | boolean | false |
+| message | 提示文案 | string | `''` |
+| type | 提示类型 `success/error/warning/info/loading` | string | `success` |
+| position | 显示位置 | string | `top` |
+| timeout | 自动关闭时间（ms），-1 表示常驻 | number | 3000 |
+| color | 自定义背景色 | string | `''` |
+| icon | 自定义图标 | string | `''` |
+| iconColor | 图标颜色 | string | `white` |
+| showCloseButton | 是否显示关闭按钮 | boolean | true |
+| closeButtonText | 关闭按钮文案 | string | `关闭` |
+| closeButtonColor | 关闭按钮颜色 | string | `white` |
+| actionText | 操作按钮文本 | string | `''` |
+| actionButtonColor | 操作按钮颜色 | string | `white` |
+| vertical | 是否垂直布局 | boolean | false |
+| elevation | 阴影高度 | number \| string | 24 |
+| maxLength | 文案裁剪长度 | number | 100 |
+
+### Events
+
+| 事件名 | 说明 | 回调参数 |
+| --- | --- | --- |
+| input | `v-model` 更新 | (visible: boolean) |
+| close | Toast 消失时触发 | - |
+| action | 点击操作按钮时触发 | - |
+
+### Slots
+
+组件不提供插槽。
+
+## 使用建议
+
+- 业务中可封装 store 或 composable，集中管理 `message/type/visible`
+- 加载状态时 `timeout` 会自动变为 `-1`，需手动关闭
+- 若需多实例并存，可在父组件中渲染多个 JhToast 或改用队列