# AttachmentPreview

Một tệp đính kèm một tin nhắn hoặc một tin đang soạn: ảnh thu nhỏ hoặc icon loại tệp, tên tệp, rồi kích thước, tiến độ tải lên hoặc lý do lỗi, và nút gỡ. Đặt các ô trong attachments của Composer, hoặc trong tin đã gửi với href.

**Phụ thuộc:** npm: 1 trực tiếp, 4 tổng; registry: 4 trực tiếp, 4 tổng.

## Cách dùng

### Khi nào dùng

- Hiện các tệp đã chọn cho tin nhắn khi chúng đang tải lên, với cách gỡ chúng.
- Hiện các tệp trong tin đã gửi, dưới dạng liên kết để mở.

### Khi nào không dùng

- Hiện một bức ảnh cần được xem. Dùng Image.
- Chọn tệp từ vùng thả. Dùng input tệp trong Field.
- Một danh sách tài liệu trong dự án. Dùng Table.

## Ví dụ

### Tệp

```tsx
<div className="flex flex-wrap gap-sm">
  <AttachmentPreview name="brief.pdf" type="application/pdf" fileSize={482000} onRemove={removeFile} />
  <AttachmentPreview name="assets.zip" type="application/zip" fileSize={12400000} onRemove={removeFile} />
</div>
```

### Đang tải lên

Thanh tiến độ thế chỗ kích thước cho tới khi tệp tải lên xong.

```tsx
<AttachmentPreview name="photo.jpg" type="image/jpeg" progress={40} onRemove={removeFile} />
```

### Tải lên thất bại

Lý do hiện dưới tên và viền chuyển sang danger.

```tsx
<AttachmentPreview name="recording.mov" type="video/quicktime" error="Tệp lớn hơn 25 MB" onRemove={removeFile} />
```

### Trong tin đã gửi

Với href, tên mở tệp, và cả ô là vùng nhấn của nó.

```tsx
<AttachmentPreview name="invoice-0042.pdf" type="application/pdf" fileSize={96000} href="#invoice" />
```

## Nên và không nên

### Nên

- Hiện một ô ngay khi tệp được chọn, kèm tiến độ, để người đọc thấy nó đang được gửi.
- Nói lý do tải lên thất bại, như giới hạn kích thước, và giữ ô để có thể gỡ.
- Truyền href cho tệp trong tin đã gửi, để chúng mở được.

### Không nên

- Đừng hiện ảnh lớn hơn ở đây; dùng Image trong tin nhắn cho ảnh cần được xem.
- Đừng giấu tên tệp sau ảnh thu nhỏ.
- Đừng tự gỡ tệp lỗi; để người đọc gỡ nó.

## Props

| Tên | Kiểu | Giá trị | Mặc định | Mô tả |
| --- | --- | --- | --- | --- |
| `name` (bắt buộc) | `string` |  |  | Tên tệp, được hiện và dùng trong tên của nút gỡ và thanh tiến độ. |
| `type` | `string` |  |  | Loại MIME, quyết định icon, như application/pdf. Không có nó, đuôi của name quyết định. |
| `fileSize` | `number` |  |  | Kích thước tính bằng byte, hiện dưới tên. |
| `src` | `string` |  |  | URL ảnh thu nhỏ cho ảnh, như object URL của tệp đã chọn. Không có nó, icon loại tệp được hiện. |
| `progress` | `number \| null` |  |  | Tiến độ tải lên từ 0 tới 100; null cho lần tải lên không rõ độ dài. Bỏ đi khi tệp đã tải lên xong. |
| `error` | `string` |  |  | Lý do tải lên thất bại, như File is larger than 25 MB. Chuyển viền sang danger và hiện dưới tên. |
| `href` | `string` |  |  | Mở hoặc tải tệp về, như tệp đính kèm trong tin đã gửi. |
| `onRemove` | `() => void` |  |  | Hiện nút gỡ và được gọi khi nút được nhấn. |
| `formatSize` | `(bytes: number) => string` |  |  | Định dạng fileSize. Mặc định theo đơn vị thập phân, như 482 KB hoặc 1.3 MB. |
| `labels` | `{ remove?: string; uploading?: string }` |  |  | Tên nút và thanh tiến độ, với {name} cho tệp. Mặc định: Remove {name}, Uploading {name}. Tiếng Việt: Gỡ {name}, Đang tải lên {name}. |

## Cấu tạo

| Phần | Mô tả |
| --- | --- |
| `root` | Ô: ảnh thu nhỏ, phần thân và nút gỡ trên một hàng, rộng tối đa 256px. |
| `thumbnail` | Một hộp 40px nền sunken với ảnh, hoặc icon của loại tệp. |
| `image` | Ảnh thu nhỏ. Nó hiện dần khi tải xong và mờ xuống opacity-pending khi tệp đang tải lên. |
| `icon` | Icon loại tệp, 20px: ảnh, video, nhạc, PDF, tệp nén, văn bản hoặc tệp thường. |
| `body` | Tên ở trên kích thước, thanh tiến độ hoặc lỗi. |
| `name` | Tên tệp trên một dòng, cắt bằng dấu ba chấm. Là liên kết khi có href. |
| `meta` | Kích thước tệp, như 482 KB. |
| `error` | Lý do tải lên thất bại, bằng màu danger. |
| `remove` | Button icon ghost cỡ sm để gỡ tệp. |

## Khả năng truy cập

Role: `generic`

| Phím | Hành động |
| --- | --- |
| `Tab` | Chuyển tới liên kết tệp, nếu có href, rồi tới nút gỡ. |
| `Enter / Space` | Trên nút gỡ, gỡ tệp. Trên liên kết, mở tệp. |

- Tên tệp được viết ra; ảnh thu nhỏ và icon loại tệp chỉ để trang trí.
- Nút gỡ được đặt tên kèm tệp, EN `Remove brief.pdf`, từ labels.remove với {name}.
- Khi tệp đang tải lên, một thanh tiến độ tên EN `Uploading brief.pdf` báo phần trăm.
- Lần tải lên thất bại hiện lý do dưới tên bằng màu danger, bằng chữ, không chỉ bằng viền đỏ. Nút gỡ và liên kết được mô tả bằng nó.
- Liên kết phủ cả ô cho con trỏ; chỉ có tên nằm trong thứ tự tab.

## Cài đặt

```bash
npx werewolf-ui add attachment-preview
```

Chạy `npx werewolf-ui init` một lần trong app trước khi thêm component. Init cài token, thêm CSS import và luật cho agent. Add cài component này cùng các dependency và giữ nguyên theme của bạn. Xem [Cài đặt](https://www.werewolf-ui.dev/vi/docs/installation.md) để biết yêu cầu và cách cài qua registry.