# EmojiPicker

Một ô tìm kiếm, một hàng nút nhóm và một lưới emoji cuộn được, với bản xem trước của emoji dưới con trỏ hoặc có focus. Có sẵn: 536 emoji thông dụng trong tám nhóm, với tên tiếng Anh để tìm. Nó không có khung: đặt nó trong Popover, hoặc dùng bên trong MessageActions.

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

## Cách dùng

### Khi nào dùng

- Chọn một emoji để đưa vào tin nhắn hoặc làm cảm xúc.
- Cho người dùng tìm emoji theo tên.

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

- Chọn từ vài cảm xúc cố định. Dùng cảm xúc nhanh trong MessageActions.
- Chọn icon cho dự án hay trang. Dùng lưới Button icon trong Popover.
- Đánh giá một thứ. Dùng Rating.

## Ví dụ

### Bộ chọn

```tsx
<EmojiPicker onEmojiSelect={pickEmoji} className="rounded-container border border-border p-sm" />
```

### Dùng thường xuyên

Các emoji người dùng chọn nhiều nhất đứng đầu, trong nhóm riêng.

```tsx
<EmojiPicker frequent={["👍", "❤️", "😂", "🎉", "🙏", "🔥"]} onEmojiSelect={pickEmoji} className="rounded-container border border-border p-sm" />
```

### Trong popover

Chỗ thường gặp: một nút cạnh ô nhập mở nó.

```tsx
<Popover>
  <PopoverTrigger asChild>
    <Button variant="secondary" iconOnly aria-label="Thêm biểu tượng cảm xúc">
      <IconMoodSmile size={16} />
    </Button>
  </PopoverTrigger>
  <PopoverContent className="w-auto p-sm">
    <EmojiPicker autoFocus onEmojiSelect={pickEmoji} />
  </PopoverContent>
</Popover>
```

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

### Nên

- Mở nó từ một nút trong Popover, và đóng Popover khi một emoji được chọn.
- Truyền frequent với các emoji người dùng hay dùng, do ứng dụng của bạn lưu.
- Truyền categories với tên đã dịch khi muốn tìm kiếm theo ngôn ngữ của trang.

### Không nên

- Đừng dùng nó chỉ để chọn cảm xúc; MessageActions đưa cảm xúc nhanh lên trước.
- Đừng thu nhỏ nó dưới 8 cột nút md trên màn hình cảm ứng.
- Đừng hiện emoji dưới dạng ảnh của chữ; giữ font emoji của hệ thống.

## Props

| Tên | Kiểu | Giá trị | Mặc định | Mô tả |
| --- | --- | --- | --- | --- |
| `onEmojiSelect` | `(emoji: string) => void` |  |  | Được gọi với emoji người dùng chọn, như 👍. |
| `frequent` | `string[]` |  |  | Các emoji người dùng chọn nhiều nhất, hiện đầu tiên. Tự lưu danh sách, như trong local storage. |
| `categories` | `{ id: string; label: string; emojis: { emoji: string; name: string; keywords?: string[] }[] }[]` |  |  | Các nhóm được hiện. Mặc định: bộ có sẵn. Các id smileys, people, animals, food, activities, travel, objects và symbols chọn icon có sẵn. |
| `columns` | `number` |  | `8` | Số emoji mỗi hàng. |
| `showPreview` | `boolean` |  | `true` | Hiện emoji dưới con trỏ hoặc có focus, kèm tên, dưới lưới. |
| `autoFocus` | `boolean` |  | `false` | Focus vào ô tìm kiếm khi mount, như khi bộ chọn mở trong Popover. |
| `labels` | `{ picker?: string; search?: string; searchPlaceholder?: string; categories?: string; frequent?: string; results?: string; empty?: string }` |  |  | Tên và tiêu đề. Mặc định: Emoji, Search emoji, Search, Emoji categories, Frequently used, Results, No emoji found. Tiếng Việt: Biểu tượng cảm xúc, Tìm biểu tượng cảm xúc, Tìm kiếm, Nhóm biểu tượng, Dùng thường xuyên, Kết quả, Không tìm thấy biểu tượng nào. |

## Cấu tạo

| Phần | Mô tả |
| --- | --- |
| `root` | Bộ chọn: tìm kiếm, nhóm, lưới và xem trước, xếp chồng, rộng 288px. |
| `search` | Một Input cỡ sm có icon tìm kiếm. |
| `nav` | Hàng nút nhóm, bị ẩn khi đang tìm. |
| `category` | Nút icon 28px cuộn tới nhóm của nó, với vùng chạm 44px. Nhóm đang hiện dùng nền accent dịu. |
| `viewport` | Vùng cuộn 256px chứa các nhóm. |
| `section` | Một nhóm: tiêu đề ở trên lưới của nó. |
| `heading` | Tên nhóm phía trên các emoji của nó. |
| `item` | Một nút emoji, cỡ của control md, chữ cỡ xl. |
| `empty` | Chữ hiện khi không có gì khớp với tìm kiếm. |
| `preview` | Emoji dưới con trỏ hoặc có focus, kèm tên, dưới một đường kẻ. |

## Khả năng truy cập

Role: `group`

| Phím | Hành động |
| --- | --- |
| `Arrow Down` | Từ ô tìm kiếm, chuyển vào lưới. |
| `Arrow keys` | Trong lưới, di chuyển một emoji hoặc một hàng. Arrow Up từ hàng đầu quay về ô tìm kiếm. |
| `Home / End` | Trong lưới, chuyển tới emoji đầu tiên hoặc cuối cùng. |
| `Enter / Space` | Chọn emoji có focus. Enter trong ô tìm kiếm chọn kết quả đầu tiên. |
| `Tab` | Chuyển từ ô tìm kiếm tới các nút nhóm, rồi tới lưới, vốn là một điểm dừng tab. |

- Một group được đặt tên bằng labels.picker (EN `Emoji`, VI `Biểu tượng cảm xúc`). Ô tìm kiếm được đặt tên bằng labels.search.
- Mỗi emoji là một nút được đặt tên bằng tên của nó, như EN `thumbs up`, nên trình đọc màn hình không bao giờ chỉ đọc ký tự.
- Mỗi nhóm là một vùng được đặt tên bằng tiêu đề. Các nút nhóm được đặt tên bằng nhóm của chúng và nút đang hiện có aria-current.
- Bản xem trước dưới lưới chỉ được vẽ; các nút đã nói tên của chúng.
- Khi không có gì khớp, chữ trống là một trạng thái lịch sự, EN `No emoji found`.
- Tên có sẵn là tiếng Anh. Truyền categories với tên ngôn ngữ khác để tìm theo ngôn ngữ đó.

## Cài đặt

```bash
npx werewolf-ui add emoji-picker
```

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.