jianghu-ui 1.0.1

package/src/components/JhFileInput/JhFileInput.md

@@ -0,0 +1,56 @@
+# JhFileInput - 文件上传输入框
+
+JhFileInput 封装常见图片/附件上传场景，支持单选、多选、预览、删除、数量限制等能力。
+
+## 功能特性
+
+- 🖼️ **实时预览**：自动识别图片并展示缩略图，非图片显示图标
+- ♻️ **多源值支持**：兼容字符串路径、字符串数组、File 对象数组
+- 🚦 **数量/类型限制**：`maxFiles`、`accept` 控制上传数量与格式
+- 📤 **校验规则**：通过 `rules` 注入函数即可实现自定义校验
+- 🚫 **只读模式**：设置 `readonly` 即可禁止上传与删除
+
+## 基础用法
+
+```vue
+<template>
+  <jh-file-input
+    v-model="files"
+    multiple
+    :max-files="5"
+    accept="image/*"
+    :rules="[(val) => val.length > 0 || '请至少上传一张图片']"
+  />
+</template>
+```
+
+## API
+
+### Props
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| value | `v-model`，可为字符串或 File 数组 | string \| Array | [] |
+| maxFiles | 最大上传数量，0 表示不限制 | number | 0 |
+| accept | input accept 属性 | string | `*/*` |
+| multiple | 是否多选 | boolean | false |
+| rules | 额外验证函数数组，返回 `true` 或错误消息 | Function[] | [] |
+| readonly | 是否只读 | boolean | false |
+| uploadPrefix | 拼接在字符串路径前的前缀 | string | `/upload/` |
+
+### Events
+
+| 事件名 | 说明 | 回调参数 |
+| --- | --- | --- |
+| input | `v-model` 更新 | (files: Array \| string) |
+| change | 同步触发，便于监听 | (files: Array \| string) |
+
+### Slots
+
+组件无自定义插槽。
+
+## 使用建议
+
+- 需要与后端路径解耦时，可以在回显时传入字符串数组，上传时转换为 `FormData`
+- 对于大文件建议结合外部上传接口，`rules` 中可校验文件大小/类型
+- 读写 File 对象时注意浏览器无法直接序列化，必要时把 meta 信息保存到其他字段

package/src/components/JhFileInput/JhFileInput.stories.js

@@ -0,0 +1,103 @@
+import JhFileInput from './JhFileInput.vue';
+
+export default {
+  title: '基础组件/JhFileInput - 文件上传',
+  component: JhFileInput,
+  tags: ['autodocs'],
+  argTypes: {
+    value: {
+      control: 'object',
+      description: '文件值，可以是数组、字符串或文件对象',
+    },
+    maxFiles: {
+      control: 'number',
+      description: '最多可上传的文件数量，0 表示不限制',
+    },
+    accept: {
+      control: 'text',
+      description: '接受的文件类型，如 "image/*" 或 ".jpg,.png"',
+    },
+    multiple: {
+      control: 'boolean',
+      description: '是否允许多文件上传',
+    },
+    readonly: {
+      control: 'boolean',
+      description: '是否只读模式',
+    },
+    uploadPrefix: {
+      control: 'text',
+      description: '上传文件的 URL 前缀',
+    },
+  },
+};
+
+export const 基础示例 = {
+  args: {
+    value: [],
+    maxFiles: 0,
+    accept: '*/*',
+    multiple: false,
+    readonly: false,
+    uploadPrefix: '/upload/',
+  },
+};
+
+export const 单图上传 = {
+  args: {
+    value: [],
+    maxFiles: 1,
+    accept: 'image/*',
+    multiple: false,
+    readonly: false,
+    uploadPrefix: '/upload/',
+  },
+};
+
+export const 多图上传 = {
+  args: {
+    value: [],
+    maxFiles: 5,
+    accept: 'image/*',
+    multiple: true,
+    readonly: false,
+    uploadPrefix: '/upload/',
+  },
+};
+
+export const 已有文件 = {
+  args: {
+    value: ['images/photo1.jpg', 'images/photo2.png', 'documents/file.pdf'],
+    maxFiles: 5,
+    accept: '*/*',
+    multiple: true,
+    readonly: false,
+    uploadPrefix: '/upload/',
+  },
+};
+
+export const 只读模式 = {
+  args: {
+    value: ['images/photo1.jpg', 'images/photo2.png'],
+    maxFiles: 0,
+    accept: '*/*',
+    multiple: true,
+    readonly: true,
+    uploadPrefix: '/upload/',
+  },
+};
+
+export const 带验证 = {
+  args: {
+    value: [],
+    maxFiles: 3,
+    accept: 'image/*',
+    multiple: true,
+    readonly: false,
+    uploadPrefix: '/upload/',
+    rules: [
+      (v) => (v && v.length > 0) || '请至少上传一个文件',
+      (v) => (v && v.length <= 3) || '最多只能上传3个文件',
+    ],
+  },
+};

package/src/components/JhFileInput/JhFileInput.vue

@@ -0,0 +1,253 @@
+<template>
+  <v-app>
+    <v-container fluid class="pa-0">
+      <div class="w-full">
+        <!-- 文件上传区域 -->
+        <div class="grid grid-cols-[repeat(auto-fill,minmax(100px,1fr))] gap-4">
+          <!-- 已上传的文件 -->
+          <div v-if="value && isString(value)" class="relative aspect-square rounded overflow-hidden">
+            <div class="w-full h-full flex flex-col items-center justify-center p-2 bg-gray-100">
+              <img v-if="isImage(value)" :src="getImageUrl(value)" class="max-w-full max-h-full object-contain">
+              <v-icon v-else size="40" class="text-gray-500">mdi-file-document-outline</v-icon>
+            </div>
+            <!-- 删除按钮 -->
+            <v-btn
+              v-if="!readonly"
+              icon
+              x-small
+              class="absolute top-1 right-1 !bg-black/50"
+              @click="handleRemoveSingleFile"
+            >
+              <v-icon small color="white">mdi-close</v-icon>
+            </v-btn>
+          </div>
+          <div v-else-if="value && Array.isArray(value)" v-for="(file, index) in value" :key="index" class="relative aspect-square border border-gray-200 rounded overflow-hidden">
+            <!-- 预览图 -->
+            <div v-if="isString(file)" class="w-full h-full flex flex-col items-center justify-center p-2 bg-gray-100">
+              <img v-if="isImage(file)" :src="getImageUrl(file)" class="max-w-full max-h-full object-contain">
+              <v-icon v-else size="40" class="text-gray-500">mdi-file-document-outline</v-icon>
+            </div>
+            <div v-else class="w-full h-full flex flex-col items-center justify-center p-2 bg-gray-100">
+              <img v-if="isImage(file)" :src="getObjectUrl(file)" class="max-w-full max-h-full object-contain">
+              <v-icon v-else size="40" class="text-gray-500">mdi-file-document-outline</v-icon>
+            </div>
+            <!-- 删除按钮 -->
+            <v-btn
+              v-if="!readonly"
+              icon
+              x-small
+              class="absolute top-1 right-1 !bg-black/50"
+              @click="removeFile(index)"
+            >
+              <v-icon small color="white">mdi-close</v-icon>
+            </v-btn>
+            <!-- 类型 -->
+            <div class="absolute top-0 left-2 text-xs bg-green-500 text-white px-1 rounded-b-sm">
+              {{ getFileExtension(file) }}
+            </div>
+          </div>
+
+          <!-- 上传按钮 -->
+          <div class="aspect-square border-2 border-dashed border-gray-200 rounded flex items-center justify-center cursor-pointer transition-all hover:border-blue-500 hover:bg-blue-50" @click="triggerFileInput" v-if="isCanUpload">
+            <input
+              type="file"
+              ref="fileInput"
+              :multiple="multiple"
+              :accept="accept"
+              @change="handleFileChange"
+              class="hidden"
+            >
+            <v-icon size="40" class="text-gray-500 transition-all group-hover:text-blue-500">mdi-plus</v-icon>
+          </div>
+        </div>
+
+        <!-- 错误提示 -->
+        <div v-if="errorMessage" class="text-red-500 text-xs mt-2 pl-0.5">
+          {{ errorMessage }}
+        </div>
+
+        <!-- 上传限制提示 -->
+        <div v-if="isShowUploadLimit" class="text-gray-500 text-xs mt-2 pl-0.5">
+          最多可上传 {{ maxFiles }} 个文件 (已上传 {{ isString(value) ? 1 : (value || []).length }} 个)
+        </div>
+      </div>
+    </v-container>
+  </v-app>
+</template>
+
+<script>
+export default {
+  name: 'JhFileInput',
+  props: {
+    // 已选文件集合，可为 File[]、字符串路径数组或单个字符串
+    value: {
+      type: [Array, String],
+      default: () => []
+    },
+    // 限制最大可上传文件数，0 表示不限制
+    maxFiles: {
+      type: Number,
+      default: 0  // 0 表示不限制
+    },
+    // input accept 属性，控制允许的文件类型
+    accept: {
+      type: String,
+      default: '*/*'  // 默认接受所有文件类型
+    },
+    // 是否允许多选
+    multiple: {
+      type: Boolean,
+      default: false
+    },
+    // 额外的校验规则
+    rules: {
+      type: Array,
+      default: () => []
+    },
+    // 只读模式（禁用上传和删除）
+    readonly: {
+      type: Boolean,
+      default: false
+    },
+    // 上传接口需要拼接的路径前缀
+    uploadPrefix: {
+      type: String,
+      default: '/upload/'
+    }
+  },
+  data() {
+    return {
+      errorMessage: ''
+    }
+  },
+  watch: {
+    value: {
+      handler() {
+        this.validate();
+      },
+      deep: true
+    }
+  },
+  computed: {
+    isCanUpload() {
+      if (this.readonly) return false;
+
+      if (this.multiple) {
+        return !this.maxFiles || ((this.value || []).length < this.maxFiles);
+      } else {
+        return (this.value || []).length < 1;
+      }
+    },
+    isShowUploadLimit() {
+      return !this.readonly && this.multiple && this.maxFiles > 0;
+    }
+  },
+  methods: {
+    isString(val) {
+      return typeof val === 'string';
+    },
+    triggerFileInput() {
+      this.$refs.fileInput.click();
+    },
+
+    async handleFileChange(event) {
+      const files = Array.from(event.target.files);
+
+      // 检查文件数量限制
+      if (this.maxFiles && (this.value || []).length + files.length > this.maxFiles) {
+        this.errorMessage = `最多只能上传 ${this.maxFiles} 个文件`;
+        return;
+      }
+
+      let newFiles = [...(this.value || [])];
+      for (const file of files) {
+        try {
+          // 检查是否已存在相同文件
+          const isDuplicate = newFiles.some(existingFile =>
+            existingFile.name === file.name &&
+            existingFile.size === file.size
+          );
+
+          if (isDuplicate) {
+            this.errorMessage = `文件 ${file.name} 已存在`;
+            continue;
+          }
+
+          newFiles.push(file);
+        } catch (error) {
+          console.error('Upload error:', error);
+          this.errorMessage = `上传文件 ${file.name} 失败`;
+        }
+      }
+
+      this.$emit('input', newFiles);
+      this.$emit('change', newFiles);
+      if (!this.errorMessage) {
+        this.errorMessage = '';
+      }
+
+      // 清空 input，以便重复选择同一文件
+      event.target.value = '';
+    },
+
+    handleRemoveSingleFile() {
+      this.$emit('input', []);
+      this.$emit('change', []);
+    },
+
+    removeFile(index) {
+      const files = [...this.value];
+      files.splice(index, 1);
+      this.$emit('input', files);
+      this.$emit('change', files);
+    },
+
+    isImage(file) {
+      if (this.isString(file)) {
+        return ['jpg', 'jpeg', 'png', 'gif', 'bmp', 'webp', 'svg'].includes(file.split('.').pop().toLowerCase());
+      }
+      return file.type ? file.type.startsWith('image/') : false;
+    },
+
+    getImageUrl(path) {
+      return `${this.uploadPrefix}${path}`;
+    },
+
+    getObjectUrl(file) {
+      return URL.createObjectURL(file);
+    },
+
+    getFileExtension(file) {
+      if (this.isString(file)) {
+        return file.split('.').pop();
+      }
+      return file.name.split('.').pop();
+    },
+
+    validate() {
+      this.errorMessage = '';
+
+      // 执行验证规则
+      for (const rule of this.rules) {
+        const result = rule(this.value);
+        if (result !== true) {
+          this.errorMessage = result;
+          return false;
+        }
+      }
+
+      return true;
+    }
+  }
+}
+</script>
+
+<style scoped>
+.aspect-square {
+  aspect-ratio: 1 / 1;
+}
+
+.grid {
+  display: grid;
+}
+</style>