FileList 文件列表

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

文件信息

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

项目方案.pdf
PDF685 B
季度数据.csv
CSV
夏日风景.svg
SVG414 B
交付说明.md
MD

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" 展示图片缩略图，非图片文件保留类型图标。

夏日风景.svg
SVG414 B
山间小径.svg
SVG
项目方案.pdf
PDF685 B

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" 展示图片卡片，预览中可以切换同一列表中的图片。

夏日风景.svg
SVG414 B
山间小径.svg
SVG
首页封面最终稿.svg
SVG

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

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
file-list-readme.md
MD
empty.txt
TXT0 B

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

import { FileList } from '@ifhover/leaf-ui';

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

使用说明

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

类型

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

FileListProps API

属性	类型	默认值	说明
`items`	`readonly FileItem[]`	必填	必需。展示的文件
`downloadable`	`boolean`	`true`	为有 URL 的文件显示下载操作
`previewable`	`boolean`	`true`	为有 URL 的图片、视频和音频显示预览操作
`removable`	`boolean`	`false`	配合 `onRemove` 显示移除操作
`onPreview`	`(file: FileItem) => void`	—	接管媒体预览；未提供时使用内置预览
`onDownload`	`(file: FileItem) => void`	—	接管下载；未提供时使用文件 URL
`onRemove`	`(file: FileItem) => void \| boolean \| Promise<void> \| Promise<boolean>`	—	请求移除，由调用方更新 `items`。等待异步操作；拒绝时在该文件行显示错误。返回 `false` 可拒绝移除
`renderActions`	`(file: FileItem, 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`	—	浏览器选择的原始文件

#FileList 文件列表

#文件信息

#缩略图列表

#图片卡片

#上传状态

#仅 URL 与移除操作

#空列表

#使用说明

#类型

#FileListProps API

#FileItem API