# AttachmentFilesField 附件文件字段

一个功能全面的文件附件组件，用于管理文件上传和显示。支持文件类型检测、上传进度跟踪、文件预览和删除确认。

## 特性

- **文件上传**: 支持自定义上传处理程序和进度跟踪
- **文件类型检测**: 自动检测图片、PDF、Office文档、音频、视频等
- **文件预览**: 显示上传的文件及类型特定的图标
- **删除确认**: 删除文件前可选的确认对话框
- **显示模式**: 编辑和查看模式
- **紧凑布局**: 节省空间的紧凑模式
- **焦点管理**: 内置的焦点/失焦事件处理

## 安装

```bash
npm install @ticatec/uniface-element
```

```typescript
import AttachmentFilesField from '@ticatec/uniface-element/AttachmentFilesField';
```

## 基本用法

```svelte
<script>
  import AttachmentFilesField from '@ticatec/uniface-element/AttachmentFilesField';

  let files = [];

  const uploadFile = async (file, progressUpdate, onUploaded, errorHandler) => {
    try {
      const formData = new FormData();
      formData.append('file', file);

      const response = await fetch('/api/upload', {
        method: 'POST',
        body: formData
      });

      const result = await response.json();
      onUploaded(result.url, result.thumbnail);

      return { cancel: async () => true };
    } catch (error) {
      errorHandler(error);
      throw error;
    }
  };
</script>

<AttachmentFilesField bind:files {uploadFile} />
```

## 属性

| 属性 | 类型 | 默认值 | 说明 |
|------|------|---------|-------------|
| `files` | `Array<AttachmentFile>` | `[]` | 附件文件数组 |
| `uploadFile` | `FileUpload` | 必填 | 文件上传处理函数 |
| `variant` | `'' \| 'plain' \| 'outlined' \| 'filled'` | `''` | 视觉变体 |
| `disabled` | `boolean` | `false` | 禁用字段 |
| `readonly` | `boolean` | `false` | 只读模式 |
| `compact` | `boolean` | `false` | 紧凑布局 |
| `displayMode` | `DisplayMode` | `DisplayMode.Edit` | 显示模式 |
| `removeFileConfirm` | `RemoveConfirm \| null` | `null` | 删除确认 |
| `style` | `string` | `''` | 自定义样式 |
| `onfocus` | `() => void \| null` | `null` | 焦点回调 |
| `onblur` | `() => void \| null` | `null` | 失焦回调 |
| `onchange` | `(files: Array<AttachmentFile>) => void \| null` | `null` | 更改回调 |

## 类型定义

```typescript
interface AttachmentFile {
  name: string;      // 文件名
  type: FileType;    // 文件类型枚举
  uri: string;       // 文件URI/路径
}

enum FileType {
  IMAGE = 'img',     // 图片（jpg、png、gif等）
  PDF = 'pdf',       // PDF文档
  DOC = 'doc',       // Word（doc、docx）
  XLS = 'xml',       // Excel（xls、xlsx、csv）
  PPT = 'ppt',       // PowerPoint（ppt、pptx）
  AUDIO = 'wav',     // 音频（mp3、wav、aac等）
  VIDEO = 'mov',     // 视频（mp4、avi、mkv等）
  OTHER = 'dat'      // 其他文件
}
```

## 示例

### 基本上传

```svelte
<script>
  import AttachmentFilesField from '@ticatec/uniface-element/AttachmentFilesField';

  let files = [];

  const uploadFile = async (file, progressUpdate, onUploaded) => {
    // 你的上传逻辑
    onUploaded(`/uploads/${file.name}`);
    return { cancel: async () => true };
  };
</script>

<AttachmentFilesField bind:files {uploadFile} />
```

### 只读模式

```svelte
<script>
  import AttachmentFilesField from '@ticatec/uniface-element/AttachmentFilesField';

  let files = [
    { name: 'report.pdf', uri: '/files/report.pdf', type: 'pdf' }
  ];
</script>

<AttachmentFilesField bind:files readonly />
```

### 带删除确认

```svelte
<script>
  import AttachmentFilesField from '@ticatec/uniface-element/AttachmentFilesField';

  let files = [];

  const uploadFile = async (file, progressUpdate, onUploaded) => {
    onUploaded(`/uploads/${file.name}`);
    return { cancel: async () => true };
  };

  const removeFileConfirm = async (file) => {
    return confirm(`确定要删除 ${file.name} 吗？`);
  };
</script>

<AttachmentFilesField bind:files {uploadFile} {removeFileConfirm} />
```

## 最佳实践

1. **服务器验证**: 始终在服务器上验证文件
2. **文件大小限制**: 强制执行大小限制以防止问题
3. **错误处理**: 实现适当的错误处理
4. **进度更新**: 向用户显示上传进度
5. **安全性**: 在服务器上验证文件类型
6. **清理**: 需要时正确取消上传

## 浏览器支持

- 支持文件API的现代浏览器
- 触摸友好的界面
- 需要服务器端上传实现

## 注意事项

- 最多可一次上传10个文件
- 文件类型通过扩展名检测
- 组件自动检测并显示文件类型图标