> Leaf UI 0.8.1 · Package: @ifhover/leaf-ui · Source: 435bab23cad7d343653d9b63b049c0b0601eeefb
> Browser documentation: https://ifhover.github.io/leaf-ui/components/file-list.html

> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/llms-full.txt.

# FileList 文件列表

展示文件信息、上传状态，并提供预览、下载和移除操作。

## 文件信息

按文件类型展示图标，文件大小可按需提供。图片支持预览，其他文件可直接下载。


- 项目方案.pdf

PDF685 B[](/leaf-ui/media/sample.pdf)
- 季度数据.csv

CSV[](/leaf-ui/media/quarterly-data.csv)
- 夏日风景.svg

SVG414 B[](/leaf-ui/media/landscape-1.svg)
- 交付说明.md

MD[](/leaf-ui/media/file-list-readme.md)

basic.tsx

复制代码

```tsx lineNumbers file="../../src/examples/file-list/basic.tsx"
import { FileList, Space } from '@ifhover/leaf-ui';

import { withBase } from '@rspress/core/runtime';

export function FileListBasic() {
  return (
    <Space direction="vertical" align="stretch">
      <FileList
        items={[
          {
            url: withBase('/media/sample.pdf'),
            name: '项目方案.pdf',
            size: 685,
          },
          { url: withBase('/media/quarterly-data.csv'), name: '季度数据.csv' },
          { url: withBase('/media/landscape-1.svg'), name: '夏日风景.svg', size: 414 },
          { url: withBase('/media/file-list-readme.md'), name: '交付说明.md' },
        ]}
      />
    </Space>
  );
}
```

展开代码

## 缩略图列表

使用 `listType="picture"` 展示图片缩略图，非图片文件保留类型图标。


- ![](/leaf-ui/media/landscape-1.svg)夏日风景.svg

SVG414 B[](/leaf-ui/media/landscape-1.svg)
- ![](/leaf-ui/media/landscape-2.svg)山间小径.svg

SVG[](/leaf-ui/media/landscape-2.svg)
- 项目方案.pdf

PDF685 B[](/leaf-ui/media/sample.pdf)

picture.tsx

复制代码

```tsx lineNumbers file="../../src/examples/file-list/picture.tsx"
import { FileList } from '@ifhover/leaf-ui';

import { withBase } from '@rspress/core/runtime';

export function FileListPicture() {
  return (
    <div>
      <FileList
        listType="picture"
        items={[
          { uid: 'lake', url: withBase('/media/landscape-1.svg'), name: '夏日风景.svg', size: 414 },
          { uid: 'trail', url: withBase('/media/landscape-2.svg'), name: '山间小径.svg' },
          { uid: 'plan', url: withBase('/media/sample.pdf'), name: '项目方案.pdf', size: 685 },
        ]}
      />
    </div>
  );
}
```

展开代码

## 图片卡片

使用 `listType="picture-card"` 展示图片卡片，预览中可以切换同一列表中的图片。


- ![](/leaf-ui/media/landscape-1.svg)夏日风景.svg

SVG414 B[](/leaf-ui/media/landscape-1.svg)
- ![](/leaf-ui/media/landscape-2.svg)山间小径.svg

SVG[](/leaf-ui/media/landscape-2.svg)
- ![](/leaf-ui/media/landscape-3.svg)首页封面最终稿.svg

SVG[](/leaf-ui/media/landscape-3.svg)

cards.tsx

复制代码

```tsx lineNumbers file="../../src/examples/file-list/cards.tsx"
import { FileList } from '@ifhover/leaf-ui';

import { withBase } from '@rspress/core/runtime';

export function FileListCards() {
  return (
    <div>
      <FileList
        listType="picture-card"
        items={[
          { uid: 'lake', url: withBase('/media/landscape-1.svg'), name: '夏日风景.svg', size: 414 },
          { uid: 'trail', url: withBase('/media/landscape-2.svg'), name: '山间小径.svg' },
          { uid: 'cover', url: withBase('/media/landscape-3.svg'), name: '首页封面最终稿.svg' },
        ]}
      />
    </div>
  );
}
```

展开代码

## 上传状态

分别展示上传进度、完成、失败、等待和取消状态。失败说明放在对应文件下方。


- 项目介绍.mp4

MP412 MB上传中 42%
- 交付说明.pdf

PDF685 B上传完成
- 附件包.zip

ZIP3 MB上传失败连接中断，请重新上传。


- 项目笔记.md

MD待上传
- 备份文件.zip

ZIP已取消

states.tsx

复制代码

```tsx lineNumbers file="../../src/examples/file-list/states.tsx"
import { FileList } from '@ifhover/leaf-ui';

import { withBase } from '@rspress/core/runtime';

export function FileListStates() {
  return (
    <div>
      <FileList
        downloadable={false}
        previewable={false}
        items={[
          {
            uid: 'uploading',
            name: '项目介绍.mp4',
            size: 12582912,
            status: 'uploading',
            percent: 42,
          },
          {
            uid: 'done',
            name: '交付说明.pdf',
            size: 685,
            status: 'done',
            url: withBase('/media/sample.pdf'),
          },
          {
            uid: 'error',
            name: '附件包.zip',
            size: 3145728,
            status: 'error',
            error: '连接中断，请重新上传。',
          },
          { uid: 'ready', name: '项目笔记.md', status: 'ready' },
          { uid: 'cancelled', name: '备份文件.zip', status: 'cancelled' },
        ]}
      />
    </div>
  );
}
```

展开代码

## 仅 URL 与移除操作

名称可从 URL 获取。通过 `onRemove` 更新 `items`；返回 Promise 时，移除按钮会等待操作结束。


名称可以从 URL 获取，文件大小可不提供。零字节文件也会展示大小。

- main.zip

ZIP[](https://github.com/ifhover/leaf-ui/archive/refs/heads/main.zip)
- file-list-readme.md

MD[](/leaf-ui/media/file-list-readme.md)
- empty.txt

TXT0 B[](/leaf-ui/media/empty.txt)

advanced.tsx

复制代码

```tsx lineNumbers file="../../src/examples/file-list/advanced.tsx"
import { type FileItem, FileList, Space, Text } from '@ifhover/leaf-ui';

import { withBase } from '@rspress/core/runtime';

import { useState } from 'react';

export function FileListActions() {
  const [items, setItems] = useState<FileItem[]>([
    { uid: 'a', url: 'https://github.com/ifhover/leaf-ui/archive/refs/heads/main.zip' },
    { uid: 'b', url: withBase('/media/file-list-readme.md') },
    { uid: 'c', url: withBase('/media/empty.txt'), size: 0 },
  ]);
  return (
    <Space direction="vertical" align="stretch">
      <Text tone="muted">名称可以从 URL 获取，文件大小可不提供。零字节文件也会展示大小。</Text>
      <FileList
        items={items}
        removable
        onRemove={(file) => setItems((current) => current.filter((item) => item.uid !== file.uid))}
      />
    </Space>
  );
}
```

展开代码

## 空列表

没有文件时展示空状态，也可以通过 `emptyContent` 自定义内容。


暂无文件

empty.tsx

复制代码

```tsx lineNumbers file="../../src/examples/file-list/empty.tsx"
import { FileList } from '@ifhover/leaf-ui';

export function FileListEmpty() {
  return (
    <div>
      <FileList items={[]} />
    </div>
  );
}
```

展开代码

## 使用说明

文件大小可不提供，不会自动请求文件元信息。图标根据 MIME 或后缀识别，缩略图加载失败时回退为类型图标。图片、视频、音频支持预览，其他文件只提供下载。媒体能否播放取决于浏览器支持的编码。跨域下载可能在新标签打开，可通过 `onDownload` 接入下载服务。上传交互请使用 [Upload](https://ifhover.github.io/leaf-ui/components/upload.md)。

## 类型

```ts
import type { FileItem, FileListProps } from '@ifhover/leaf-ui';
```

## FileListProps API

| 属性              | 类型                                                                                              | 默认值      | 说明                                                       |
| --------------- | ----------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------- |
| `items`         | `readonly `[`FileItem`](#fileitem-api)`[]`                                                      | 必填       | 必需。展示的文件                                                 |
| `downloadable`  | `boolean`                                                                                       | `true`   | 为有 URL 的文件显示下载操作                                         |
| `previewable`   | `boolean`                                                                                       | `true`   | 为有 URL 的图片、视频和音频显示预览操作                                   |
| `removable`     | `boolean`                                                                                       | `false`  | 配合 `onRemove` 显示移除操作                                     |
| `onPreview`     | `(file: `[`FileItem`](#fileitem-api)`) => void`                                                 | —        | 接管媒体预览；未提供时使用内置预览                                        |
| `onDownload`    | `(file: `[`FileItem`](#fileitem-api)`) => void`                                                 | —        | 接管下载；未提供时使用文件 URL                                        |
| `onRemove`      | `(file: `[`FileItem`](#fileitem-api)`) => void \| boolean \| Promise<void> \| Promise<boolean>` | —        | 请求移除，由调用方更新 `items`。等待异步操作；拒绝时在该文件行显示错误。返回 `false` 可拒绝移除 |
| `renderActions` | `(file: `[`FileItem`](#fileitem-api)`, actions: ReactNode) => ReactNode`                        | —        | 定制操作区                                                    |
| `emptyContent`  | `ReactNode`                                                                                     | 暂无文件     | 空列表内容                                                    |
| `disabled`      | `boolean`                                                                                       | `false`  | 禁用交互。                                                    |
| `listType`      | `'text' \| 'picture' \| 'picture-card'`                                                         | `'text'` | 文件列表的展示形式。                                               |

## FileItem API

| 属性           | 类型                                                           | 默认值 | 说明                  |
| ------------ | ------------------------------------------------------------ | --- | ------------------- |
| `uid`        | `string`                                                     | —   | 稳定标识，建议提供           |
| `url`        | `string`                                                     | —   | 文件地址                |
| `name`       | `string`                                                     | —   | 文件名称，默认取 URL 的文件名   |
| `size`       | `number`                                                     | —   | 字节数，可不提供；未提供时不显示大小  |
| `type`       | `string`                                                     | —   | MIME 类型，未提供时根据扩展名识别 |
| `status`     | `'ready' \| 'uploading' \| 'done' \| 'error' \| 'cancelled'` | —   | 上传状态，可不提供           |
| `percent`    | `number`                                                     | —   | 上传进度 0–100          |
| `error`      | `string`                                                     | —   | 失败说明                |
| `originFile` | `globalThis.File`                                            | —   | 浏览器选择的原始文件          |