# FileList

文件列表组件，展示文件集合，支持预览、下载、删除、重试操作及上传进度/错误状态。

## 适用场景

- 展示已上传或待上传的文件列表
- 需要对文件执行预览、下载、删除、重试等操作
- 展示文件上传进度或上传错误状态
- 与 Upload 组件配合使用管理文件列表

## Props

### FileList Props

| 名称 | 类型 | 默认值 | 必填 | 说明 |
|------|------|--------|------|------|
| className | `string` | `""` | 否 | 自定义 class |
| data | `FileObject[]` | `-` | 否 | 文件数据列表 |
| layout | `"vertical" \| "horizontal"` | `"vertical"` | 否 | 排列布局：vertical 每个文件占一行，horizontal 横向排列 |
| onPreview | `FileActionHandler` | `-` | 否 | 点击预览的回调 |
| onDownload | `FileActionHandler` | `-` | 否 | 点击下载的回调（仅对无 downloadUrl 的 file-item 有效） |
| onRemove | `FileActionHandler` | `-` | 否 | 点击移除的回调 |
| onRetry | `FileActionHandler` | `-` | 否 | 点击重试的回调 |
| downloadType | `"download-button" \| "button"` | `"download-button"` | 否 | 下载方式：download-button 使用 `<Download />`，button 使用 `<Button />` 或 `<a />` |
| downloadMethod | `DownloadIframeMethod` | `-` | 否 | 下载请求方法，仅 downloadType 为 'download-button' 时有效 |
| downloadTarget | `string` | `-` | 否 | `<a>` 的 target，仅 downloadType 为 'button' 时有效 |
| size | `"md" \| "sm" \| "xs" \| "lg"` | `-` | 否 | 尺寸，默认读取 ConfigContext `baseSize` |

### FileItem Props

| 名称 | 类型 | 默认值 | 必填 | 说明 |
|------|------|--------|------|------|
| className | `string` | `""` | 否 | 自定义 class |
| type | `"pdf" \| "excel" \| "ppt" \| "zip" \| "eml" \| "html" \| "txt" \| "img" \| "word" \| "other"` | `-` | 否 | 文件类型（决定图标） |
| id | `ObjectId` | `-` | 否 | 唯一标识 |
| name | `string` | `-` | 是 | 文件名，不提供 id 时作为唯一标识 |
| previewUrl | `string` | `-` | 否 | 预览 url |
| downloadUrl | `string` | `-` | 否 | 下载 url（有此值时下载按钮为 `<Download />`，优先级高于 onDownload） |
| downloadTarget | `string` | `-` | 否 | 下载 anchor 的 target |
| error | `string \| boolean` | `-` | 否 | 上传错误信息或是否处于错误状态 |
| progress | `number \| boolean` | `-` | 否 | 上传进度（number）或是否处于上传中状态（boolean） |
| disableRemove | `boolean` | `false` | 否 | 是否禁用删除 |
| disableRetry | `boolean` | `false` | 否 | 是否禁用重试 |
| disableDownload | `boolean` | `false` | 否 | 是否禁用下载 |
| disablePreview | `boolean` | `false` | 否 | 是否禁用预览 |
| size | `number` | `-` | 否 | 文件大小（字节） |

## 典型用法

### 基础文件列表

```tsx
import { FileList } from '@befe/brick-comp-file-list'

const fileData = [
    { id: 'img-file', type: 'img', name: 'logo.png' },
    { id: 'excel-file', type: 'excel', name: 'report.xls' },
    { id: 'pdf-file', type: 'pdf', name: 'book.pdf' },
]

<FileList data={fileData} />
```

### 支持删除操作

```tsx
import { useState } from 'react'
import { FileList, FileObject } from '@befe/brick-comp-file-list'

function Demo() {
    const [fileData, setData] = useState(initialFileList)

    const removeData = (fileObj: FileObject) => {
        setData(prev => prev!.filter(f => f.id !== fileObj.id))
    }

    return <FileList data={fileData} onRemove={removeData} />
}
```

### 带预览和下载 URL

```tsx
const fileData = [
    {
        id: 'img',
        type: 'img',
        name: 'logo.png',
        previewUrl: 'https://example.com/logo.png',
        downloadUrl: 'https://example.com/logo.png',
    },
    {
        id: 'uploading',
        type: 'pdf',
        name: 'report.pdf',
        progress: 60,  // 上传进度 60%
    },
    {
        id: 'failed',
        type: 'excel',
        name: 'data.xls',
        error: '上传失败，请重试',
    },
]

<FileList data={fileData} onRemove={handleRemove} onRetry={handleRetry} />
```

### 横向布局

```tsx
<FileList data={fileData} layout={'horizontal'} />
```

## 注意事项

- 预览交互为**独立的预览 icon button**（hover 文件项时出现在操作区，位于下载按钮前），需提供 `previewUrl` 或 context `onPreview` 才会渲染；`disablePreview` 可单独禁用。⚠️ 自 `@befe/brick-comp-file-list@0.2.109`（`@befe/brick@0.2.191`）起，预览**不再响应「点击整行」**，且移除了「hover 用预览图标替换文件类型图标」的旧行为（breaking change）
- `onDownload` 的优先级低于 `FileItem` 的 `downloadUrl`：有 `downloadUrl` 的文件项下载使用 `<Download />` 组件，不绑定 `onDownload`；无 `downloadUrl` 的文件项下载才绑定 `onDownload`
- `downloadType='button'` 配合 `FileItem.downloadUrl` 时，下载按钮会渲染为 `<a>` 标签
- `progress` 为 `true` 时表示正在上传（无进度条），为 `number` 时显示具体进度
- `error` 为 `true` 时表示错误状态，为 `string` 时同时展示错误信息