# @ferrucc-io/emoji-picker 中文文档

规范地址：https://npmcn.com/package/%40ferrucc-io/emoji-picker/

版本：0\.1\.2
npm 元数据更新时间：2026-08-17T23:20:06.217Z
中文译文更新时间：2026-11-14T14:58:14.872Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40ferrucc-io/emoji-picker
原文对照：https://npmcn.com/package/%40ferrucc-io/emoji-picker/?lang=original
项目主页：https://emoji.ferrucc.io/
源码仓库：https://github.com/ferrucc-io/emoji-picker

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.5 MB，41 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：6 个
- peer 依赖：react ^18\.0\.0 \|\| ^19\.0\.0，react-dom ^18\.0\.0 \|\| ^19\.0\.0，tailwindcss \>=3\.0\.0
- 首次发布：2025-01-25T15:59:09.806Z
- 最新版本发布：2026-08-17T23:20:05.920Z
- 近 30 天下载量：173269（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：46（近 12 个月 4 个）

## 中文简介

美丽的现代爱莫吉采摘器

## 安装

```sh
npm install @ferrucc-io/emoji-picker
```

也可以使用：`pnpm add @ferrucc-io/emoji-picker`、`yarn add @ferrucc-io/emoji-picker`、`bun add @ferrucc-io/emoji-picker`

## README

# 爱莫吉·皮克

带有 Tailwind styling 的可堆叠回放的取相器组件

[![npm version](https://img.shields.io/npm/v/@ferrucc-io/emoji-picker.svg?style=flat)](https://www.npmjs.com/package/@ferrucc-io/emoji-picker) [![npm downloads](https://img.shields.io/npm/dm/@ferrucc-io/emoji-picker.svg?style=flat)](https://www.npmjs.com/package/@ferrucc-io/emoji-picker) [![License](https://img.shields.io/npm/l/@ferrucc-io/emoji-picker.svg?style=flat)](https://github.com/ferrucc-io/emojicn/blob/main/LICENSE)

![Emojicn Demo](https://npmcn.com/package/%40ferrucc-io/emoji-picker/public/emoji-picker-repo-asset.png)

### [现场直播](https://emoji.ferrucc.io/)

## 特征

-   🎨 **未命名可编译( C)**:由Tailwind CSS所建造. 每个组件默认的样式最小,而且完全可以自定义.
-   ⚡️ **快速轻量级( L)**: 用于平滑滚动的虚拟列表. 只能让Emojis进入视野.
-   🎯 **可访问**: 完整的键盘和屏幕阅读器导航支持.
-   🛜 **无外部 CDN**:所有emoji数据都包含在这个依赖中,没有外部CDN.
-   🔣 **无符号**: 不支持的emojis 自动隐藏
-   🌈 **主导色彩花纹**: 被支持的emojis被构建出主导色彩.
-   🖼️ **自定义 Emojis**: 添加您自己的基于图像的emoji部分(如Slack自定义的emojis)和一个被频繁使用的部分.

## 安装

要使用此组件, 您的项目必须使用 React 和 Tailwind .

要安装组件 :

```bash
bun add @ferrucc-io/emoji-picker
# or
yarn add @ferrucc-io/emoji-picker
# or
npm i @ferrucc-io/emoji-picker
# or
pnpm add @ferrucc-io/emoji-picker
```

在您的工程中,您可以使用这样的组件:

```tsx
<EmojiPicker onEmojiSelect={handleEmojiSelect}>
  <EmojiPicker.Header>
    <EmojiPicker.Input placeholder="Search emoji" />
  </EmojiPicker.Header>
  <EmojiPicker.Group>
    <EmojiPicker.List />
  </EmojiPicker.Group>
</EmojiPicker>
```

最后,导入您 Tailwind 配置中的组件样式 :

```tsx
// If you're using Tailwind v4.x
// In your CSS file containing your tailwind configuration
// Add this line:
@source "../node_modules/@ferrucc-io/emoji-picker";

// If you're using Tailwind v3.x
// In your tailwind.config.ts
"content": [
  // Keep the existing content array
  // Add this line:
  "./node_modules/@ferrucc-io/emoji-picker/dist/**/*.{js,jsx,ts,tsx}",
],
```

## 默认样式

```tsx
<EmojiPicker onEmojiSelect={handleEmojiSelect}>
  <EmojiPicker.Header>
    <EmojiPicker.Input placeholder="Search emoji" />
  </EmojiPicker.Header>
  <EmojiPicker.Group>
    <EmojiPicker.List />
  </EmojiPicker.Group>
</EmojiPicker>
```

### 道具自定义( C)

基础组件接受几种定制道具:

```tsx
interface EmojiPickerProps {
  emojisPerRow?: number;      // Number of emojis per row
  emojiSize?: number;         // Size of each emoji in pixels
  containerHeight?: number;    // Height of the emoji container
  maxUnicodeVersion?: number; // Maximum Unicode version to include (defaults to 16.0, matching unicode-emoji-json package). Hides unsupported emojis that render as � on the user's system
  onEmojiSelect?: (emoji: string) => void; // Callback when emoji is selected
  customSections?: CustomSection[]; // Custom image-based emoji sections to show alongside the standard categories
  frequentlyUsedEmojis?: (string | CustomEmoji)[]; // Emojis to show in a "Frequently Used" section at the top
  renderHeader?: (props: HeaderRendererProps) => React.ReactNode; // Custom renderer for section headers
}
```

### 自定义 Emojis

您可以通过 : `customSections` prop,并将一个"经常使用"的段落标出在列表的首位,其中 `frequentlyUsedEmojis`数字 :

```tsx
import { EmojiPicker } from '@ferrucc-io/emoji-picker';
import type { CustomEmoji, CustomSection } from '@ferrucc-io/emoji-picker';

const customSections: CustomSection[] = [
  {
    id: 'custom',
    name: 'Custom',
    priority: 1, // Lower values appear first (defaults to 999)
    emojis: [
      { id: 'mic-drop', name: 'mic-drop', imageUrl: '/custom-emojis/mic-drop.gif' },
      { id: 'shipitparrot', name: 'shipitparrot', imageUrl: '/custom-emojis/shipitparrot.gif' },
    ],
  },
];

// Mix standard emoji strings and custom emoji objects
const frequentlyUsedEmojis: (string | CustomEmoji)[] = [
  '👍',
  '❤️',
  { id: 'thisisfine', name: 'thisisfine', imageUrl: '/custom-emojis/thisisfine.gif' },
];

<EmojiPicker
  customSections={customSections}
  frequentlyUsedEmojis={frequentlyUsedEmojis}
  onEmojiSelect={(emoji) => {
    // Standard emojis: the emoji character, e.g. "👍"
    // Custom emojis: the name wrapped in colons, e.g. ":mic-drop:"
    console.log(emoji);
  }}
>
  {/* ... */}
</EmojiPicker>
```

自定义的emojis按名可搜索,支持完整的键盘导航,并像标准emojis一样出现在预览中.

相关类型从包中导出,并带有 `isCustomEmoji` 类型守护 :

```tsx
interface CustomEmoji {
  id: string;
  name: string;
  imageUrl: string;
  category?: string;
}

interface CustomSection {
  id: string;
  name: string;
  emojis: (EmojiMetadata | CustomEmoji)[];
  priority?: number; // Lower values appear first (defaults to 999)
}
```

### 自定义区域标题

使用 `renderHeader` 完全控制分区标题的配置道具 :

```tsx
import type { HeaderRendererProps } from '@ferrucc-io/emoji-picker';

function MyHeader({ content, isSticky }: HeaderRendererProps) {
  return (
    <div className={isSticky ? 'bg-white/95 backdrop-blur-sm' : 'bg-transparent'}>
      {content}
    </div>
  );
}

<EmojiPicker renderHeader={MyHeader}>
  {/* ... */}
</EmojiPicker>
```

## 实例

组成部分背后的主要思想是能够支持尽可能多的不同风格. 我们制作的第一个版本 支持建立一个拾取器 看起来像Slack和Linear的.

将来最好能支持Discord,Whatsapp,Notion等更多风格.

### 线性样式

```tsx
<EmojiPicker
  className="border border-zinc-200 dark:border-zinc-800 rounded-lg"
  emojisPerRow={12}
  emojiSize={28}
  onEmojiSelect={onEmojiSelect}
>
  <EmojiPicker.Header className="p-2 pb-0">
    <EmojiPicker.Input
      placeholder="Search emoji"
      autoFocus={true}
      className="focus:ring-2 focus:ring-inset ring-1 ring-transparent"
    />
  </EmojiPicker.Header>
  <EmojiPicker.Group>
    <EmojiPicker.List hideStickyHeader={true} containerHeight={400} />
  </EmojiPicker.Group>
</EmojiPicker>
```

### 黑样式

```tsx
<EmojiPicker 
  className="font-['Lato'] w-[380px] border-none"
  emojisPerRow={9}
  emojiSize={36}
>
  <EmojiPicker.Header>
    <EmojiPicker.Input 
      placeholder="Search all emoji" 
      className="h-[36px] bg-white dark:bg-zinc-800 border border-zinc-300 dark:border-zinc-600 w-full rounded-[8px] text-[15px] focus:shadow-[0_0_0_1px_#1d9bd1,0_0_0_6px_rgba(29,155,209,0.3)] dark:focus:shadow-[0_0_0_1px_#1d9bd1,0_0_0_6px_rgba(29,155,209,0.3)] focus:border-transparent focus:outline-none mb-1"
      hideIcon
    />
  </EmojiPicker.Header>
  <EmojiPicker.Group>
    <EmojiPicker.List containerHeight={320} />          
  </EmojiPicker.Group>
  <EmojiPicker.Preview>
    {({ previewedEmoji }) => (
      <>
        {previewedEmoji ? 
          <EmojiPicker.Content />
          :
          <button>Add Emoji</button>
        }
        <EmojiPicker.SkinTone />
      </>
    )}
  </EmojiPicker.Preview>
</EmojiPicker>
```

## 用于

该项目目前用于:

-   [6月份](https://june.so/) - B2B SaaS的分析产品
-   [兰福斯](https://langfuse.com/) - 追踪, evals, 快速管理和度量衡来调试和改进您的 LLM 应用.
-   [类型](https://typefully.com/) - X、LinkedIn、线索等的写作应用程序

**随便打开公关,在这里添加你的名字 如果你在项目里使用组件的话.**

## 贷项

此工程是使用 `bun init` 在包子v1.2.0. [阿宝](https://bun.sh/) 是一个快速的全能JavaScript运行时间.

## 捐款

这个项目的结构是单一的,有两个主要部分:

-   `packages/emoji-picker`: 主包中包含 emoji 拾取器组件
-   `demo`:演示应用程序显示组件的不同用途

### 开发设置

要从发展入手:

```bash
# Install dependencies for all packages
bun install

# Run the development server
bun dev
```

### 更新 Emoji 颜色

要更新 emoji 徘徊的颜色 :

```bash
cd packages/emoji-picker
bun run build:emoji-colors
```

这将产生一个新的 `emojiColors.ts` 在软件包中的文件 `src/utils` 目录.

### 测试

```bash
# Run tests for the emoji picker package
cd packages/emoji-picker
bun test
```

欢迎捐款! 请随意提交公关.

## 常见问题

### @ferrucc-io/emoji-picker 是什么？

美丽的现代爱莫吉采摘器

### 如何安装 @ferrucc-io/emoji-picker？

在项目目录运行 npm install @ferrucc-io/emoji-picker，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18\.0\.0 \|\| ^19\.0\.0）、react-dom（^18\.0\.0 \|\| ^19\.0\.0）、tailwindcss（\>=3\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @ferrucc-io/emoji-picker 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @ferrucc-io/emoji-picker 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @ferrucc-io/emoji-picker 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @ferrucc-io/emoji-picker 可以商用吗？

@ferrucc-io/emoji-picker 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @ferrucc-io/emoji-picker 的下载量有多少？

根据 npm 官方下载统计，@ferrucc-io/emoji-picker 在 2026/10/15 – 2026/11/13 这 30 天内被下载 173,269 次，日均约 5,776 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @ferrucc-io/emoji-picker 还在维护吗？

最新版本 0\.1\.2 发布于 2026/08/18（2 个月前）；至今共发布 46 个版本，其中过去 12 个月发布了 4 个；首次发布于 2025/01/25。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。