# UploadFile 组件使用说明

## 功能特性
- 支持多种文件上传（图片、PDF等）
- 自动生成文件预览URL
- 支持文件删除和预览
- 兼容多种v-model绑定方式
- 严格的文件数量限制控制
- 自动内存管理（blob URL清理）

## Props 属性

| 属性名 | 类型 | 默认值 | 必需 | 说明 |
|--------|------|--------|------|------|
| modelValue | Array | [] | 否 | v-model默认绑定的文件列表 |
| fileIds | Array | [] | 否 | v-model:fileIds绑定的文件ID数组 |
| limit | Number | 1 | 否 | 上传文件数量限制，limit=1时会严格替换现有文件 |
| attmodel | String | - | 是 | 关联模块名称，用于文件分类存储 |
| attpath | String | '' | 否 | 自定义路径，默认为`/${attmodel}/` |
| attId | String | '' | 否 | 单个文件ID，用于初始化单文件场景 |
| message | String | '' | 否 | 提示消息，与tips作用相同，优先显示tips |
| tips | String | '' | 否 | 提示信息，显示在上传组件下方 |
| listType | String | 'text' | 否 | 列表类型，支持 'text'、'picture'、'picture-card' |

## Events 事件

| 事件名 | 参数 | 说明 |
|--------|------|------|
| update:modelValue | Array | 更新文件列表 |
| update:fileIds | Array | 更新文件ID数组 |
| update:fileID | String | 更新文件ID字符串（逗号分隔，兼容旧版本） |

## 使用方式

### 方式一：单文件上传（推荐）
```vue
<UploadFile
  v-model:fileIds="formData.avatarIds"
  attmodel="user_avatar"
  :limit="1"
  listType="picture-card"
  tips="请上传头像，支持jpg、png格式"
/>
```

### 方式二：多文件上传
```vue
<UploadFile
  v-model="formData.attachmentFiles"
  v-model:fileIds="formData.attachmentIds"
  attmodel="project_attachments"
  :limit="5"
  tips="最多上传5个文件，支持图片和PDF格式"
/>
```

### 方式三：自定义路径
```vue
<UploadFile
  v-model:fileIds="formData.documentIds"
  attmodel="contract"
  attpath="/contracts/2024/"
  :limit="3"
  tips="上传合同文档"
/>
```

### 方式四：初始化单个文件
```vue
<UploadFile
  v-model:fileIds="formData.certIds"
  attmodel="certification"
  :attId="existingFileId"
  :limit="1"
  tips="营业执照"
/>
```

## 重要特性说明

### 严格的数量限制
- 当 `limit=1` 时，上传新文件会自动替换现有文件
- 超出数量限制时会显示警告并阻止上传
- 自动清理被替换文件的内存占用

### 双向绑定支持
- `v-model`: 绑定完整的文件对象数组
- `v-model:fileIds`: 绑定文件ID数组
- `@update:fileID`: 兼容旧版本的字符串格式ID

### 自动内存管理
- 组件会自动清理不再使用的blob URL
- 文件删除时自动释放相关内存
- 组件销毁时清理所有资源

## 暴露的方法

### clearFiles()
清空所有已上传的文件

```vue
<script setup>
const uploadRef = ref(null);

const handleClear = () => {
  uploadRef.value?.clearFiles();
};
</script>

<template>
  <UploadFile 
    ref="uploadRef" 
    v-model:fileIds="fileIds" 
    attmodel="demo" 
  />
  <button @click="handleClear">清空文件</button>
</template>
```

## 注意事项

1. **attmodel是必需的**：用于服务端文件分类和路径管理
2. **limit=1时的行为**：会严格替换现有文件，而不是添加新文件
3. **内存管理**：组件会自动管理blob URL，无需手动清理
4. **事件兼容性**：同时支持新的fileIds数组格式和旧的fileID字符串格式
