# 缩略图 · Thumbnail

- 页面: https://jiguang132.com/zh/resources/astryx/docs/thumbnail
- 资源: Astryx (https://jiguang132.com/zh/resources/astryx.md)
- 全部指南: https://jiguang132.com/zh/resources/astryx/docs.md

缩略图用于内容展示场景。下面的官方示例展示原生用法与状态，属性名保持上游 API。

## 安装与前置条件

```bash
npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0
```

需要 React 19+，按顺序导入基础 CSS 和主题，并设置 Theme Provider。参见[开始使用](/resources/astryx/docs/getting-started)。

## 示例与使用方式

- **缩略图 · 综合展示 1**：首先体验这个示例，再查看代码理解组件的组合方式。
- **缩略图 · 禁用状态 2**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **缩略图 · 交互示例 3**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **缩略图 · 交互示例 4**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **缩略图 · 多种状态 5**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。

## API 与上游详细参考

优先使用 0.7.1 官方中文说明；上游尚未提供中文的条目保留英文。属性名、类型及默认值保持原生 API，不把示例状态名称当成组件属性。

## Thumbnail

Thumbnail 是图片附件的方形预览卡片。上传时显示骨架屏动画，成功后显示图片，未设置源时显示占位图标。用于聊天编辑器、文件上传列表或任何需要紧凑图片预览的场景。

| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| src | string |  | 图片源 URL。 |
| alt | string |  | 图片的替代文本。省略时图片会被显式标记为装饰性（alt=""、role="presentation"、aria-hidden）并对屏幕阅读器隐藏；若 alt 和 label 均未设置，开发环境会发出警告。 |
| label | string |  | 无障碍标签（如文件名）。悬停时以提示工具显示。 |
| onRemove | (e: React.MouseEvent) => void |  | 覆盖层移除按钮的回调。 |
| onClick | (e: React.MouseEvent) => void |  | 点击处理器。添加按钮语义和悬停覆盖层。 |
| isLoading | boolean | false | 显示骨架屏（无 src）或上传覆盖层（有 src）。 |
| isDisabled | boolean | false | 是否禁用缩略图。 |
| showRemoveOn | 'always' \| 'hover' | 'hover' | 何时显示移除按钮：hover（默认，悬停时以及键盘聚焦时显示，触摸设备上保持可见）\| always（始终显示）。仅在设置 onRemove 时生效。 |
| xstyle | StyleXStyles |  | 用于布局自定义的 StyleX 样式。必须是 stylex.create() 的值，而非内联样式对象。 |
| className | string |  | 根元素的 CSS 类名。建议使用 xstyle。 |
| style | CSSProperties |  | 根元素的内联样式。建议使用 xstyle。 |
| data-testid | string |  | 用于自动化测试框架的测试选择器。 |

### 使用建议

- 始终提供 label 属性并填写文件名，以便屏幕阅读器能够识别缩略图及其移除按钮，并在悬停时显示提示。
- 上传初期使用不带 src 的 isLoading 显示骨架屏；获得预览 URL 后使用带 src 的 isLoading 显示旋转加载覆盖层。
- 将 onClick 与灯箱或详情视图配对，以便用户查看完整图片——组件会自动添加按钮语义和悬停覆盖层。
- 避免：对 PDF 或电子表格等非图片文件类型使用 Thumbnail——应使用带有相应图标的文件附件组件。
- 避免：提供 src 时省略 alt 文本——屏幕阅读器需要图片内容的描述，而不仅是 label 中的文件名。

### 主题 API

```json
{
  "targets": [
    {
      "className": "astryx-thumbnail"
    }
  ],
  "vars": [
    {
      "name": "--_thumbnail-hit-inset",
      "description": "Outset of the remove button's invisible hit area, applied to a ::after overlay. 0 on a fine pointer; negative on a coarse one, which grows the 20px button to the 24px touch target without changing what is drawn.",
      "default": "0px",
      "private": true
    },
    {
      "name": "--_press-overlay",
      "description": "Fill of the ::after interaction overlay: transparent at rest, the hover overlay token on hover (hover-capable pointers), the pressed overlay token while pressed (`:active` on a mouse; `data-astryx-press=\"on\"` written by the touch press controller under a finger) and the hover token for the release fade. Set on the card element by its own interaction arms.",
      "default": "transparent",
      "private": true
    },
    {
      "name": "--_press-overlay-transition",
      "description": "Duration of the overlay's background-color transition: the fast duration token, except 0s while a believed touch press paints so it lands on the first frame.",
      "default": "var(--duration-fast)",
      "private": true
    }
  ]
}
```

### 组件结构

- **Image**: The preview image, displayed as a square with cover fit.
- **Placeholder**: An image silhouette icon shown when no src is provided.
- **Remove button**: An overlaid close button in the top-right corner. Appears when onRemove is set. Sits on a fixed --color-overlay scrim with an --color-on-dark icon to stay visible on any image.
- **Upload overlay**: A semi-transparent overlay with a spinner, shown when isLoading is true and a src preview is available.
- **Skeleton**: A shimmer animation shown when isLoading is true and no src is set.

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt