# preview-file-list LLMs.txt

> 供 LLM 快速理解 `@flatbiz/antd/preview-file-list` 的使用方式。

## 模块定位

正常列表：左侧缩略（图片可预览，非图片为文件图标）；非图片整行点击下载。

## 导入方式

```ts
import { PreviewFileList } from '@flatbiz/antd/preview-file-list';
// 也可以从主入口导入：import { ... } from '@flatbiz/antd';
```

## 公开导出

- `* from ./preview-file.jsx`
- `PreviewCard` - 正常列表：左侧缩略（图片可预览，非图片为文件图标）；非图片整行点击下载。
- `PreviewCardProps`
- `PreviewCompact` - 紧凑模式：纵向窄行；图片行左侧为小眼睛（预览）、文件行左侧为下载图标； 点击图片行预览，点击文件行下载。
- `PreviewCompactProps`
- `downloadByUrl`
- `isImageUrl`
- `PreviewFileList`
- `FileListPreviewProps`
- `PreviewThumbnail` - 缩略：多块水平 Flex 排版、自动换行；仅展示缩略图或文件图标， 完整文件名通过 Tooltip 悬浮展示；悬停遮罩显示下载图标。
- `PreviewThumbnailProps`

## 依赖的 antd 能力

`Image`、`Tag`、`Tooltip`、`Typography`

## Props / 配置要点

### FileImageThumbProps

- `previewUrl`（必填）：: string

### PreviewCardProps

- `imageList`（必填）：: PreviewImageItem[]

### PreviewCompactProps

- `imageList`（必填）：: PreviewImageItem[]

### FileListPreviewProps

- `imageList`（必填）：: PreviewImageItem[]
- `imageSize`（可选）：: number；图片大小，默认 50，viewType 为 thumbnail 时有效
- `viewType`（必填）：: 'thumbnail' | 'card' | 'compact'；card：卡片；thumbnail：缩略换行；compact：紧凑纵向列表，默认值为 card

### ThumbnailImageBlockProps

- `previewUrl`（必填）：: string
- `fileName`（可选）：: string
- `imageSize`（必填）：: number
- `imageList`（必填）：: PreviewImageItem[]

### PreviewThumbnailProps

- `list`（必填）：: PreviewImageItem[]
- `imageSize`（可选）：: number

## 使用规则与行为

- 整块缩略区域（含 contain 留白）点击均可打开预览
- 正常列表：左侧缩略（图片可预览，非图片为文件图标）；非图片整行点击下载。
- 紧凑模式：纵向窄行；图片行左侧为小眼睛（预览）、文件行左侧为下载图标； 点击图片行预览，点击文件行下载。
- 图片大小，默认 50，viewType 为 thumbnail 时有效
- card：卡片；thumbnail：缩略换行；compact：紧凑纵向列表，默认值为 card
- 缩略：图片 + 悬停遮罩与下载；点击图片区域预览，点下载图标下载
- 缩略：多块水平 Flex 排版、自动换行；仅展示缩略图或文件图标， 完整文件名通过 Tooltip 悬浮展示；悬停遮罩显示下载图标。
- 判断 url 是否为图片（与 click-event-render content 一致，支持带查询参数）

## 基础示例

```tsx
import { PreviewFileList, type FileImageThumbProps } from '@flatbiz/antd/preview-file-list';

const props: FileImageThumbProps = {
  // 按业务传入必要参数
};

<PreviewFileList {...props} />;
```

## 源码索引

- `src/preview-file-list/index.ts`
- `src/preview-file-list/preview-card.tsx`
- `src/preview-file-list/preview-compact.tsx`
- `src/preview-file-list/preview-file.tsx`
- `src/preview-file-list/preview-thumbnail.tsx`
- `src/preview-file-list/utils.ts`

## 给 LLM 的注意事项

- 优先使用 `@flatbiz/antd/preview-file-list` 或主入口 `@flatbiz/antd` 的公开导出，不要引用内部实现文件。
- 当 Props 与 antd 原组件同名能力冲突时，以本模块导出的 Props 类型为准。
- 若文档未覆盖某个边缘参数，请读取上方源码索引中的类型定义和 JSDoc。