EmojiPicker

表情选择面板是全部表情之上的一个搜索框：各个分组（笑脸、人物、动物、食物……）排成网格，用户最近用过的表情排在最前，能换肤色的表情可以选一种肤色。EmojiPicker 负责它的行为：表情本身（Unicode 的表情，带有来自 CLDR 的英文名称和关键词）、搜索、分组、高亮、键盘，以及屏幕阅读器听到的内容。搜索在原生端进行，网格是虚拟化的：只创建可见的行。外观和文字都由应用决定：面板本身什么也不画，也不内置任何文字，应用为每个部件设置样式（itemClass、groupClass、searchClass 等），为分组命名（groupLabels），并填入插槽（分组标签、指针下表情的预览）。

import { mount, signal, Text, View } from "nsh";
import { desktop, EmojiPanel, Log, Panel, sectionSurface, Split, ui, wide } from "./palette";

// An emoji picker as a chat app has it: the groups' tabs, search with the
// skin tone hand, the recent emoji first, the one under the pointer named
// below (the tabs at the foot on a phone). The picker owns the emoji, the
// filtering, the keys and the semantics; every pixel is the gallery's
// `EmojiPanel`.
const message = signal("Lunch at the new ramen place? ");
const recent = signal<string[]>(["👍", "😂", "❤️", "🎉", "🙏", "🔥"]);
const events = signal<string[]>([]);
const log = (line: string) => events.set([line, ...events()].slice(0, 4));

function App() {
  return (
    <View style={{ flex: 1, backgroundColor: ui().page, padding: 20, paddingTop: 24, gap: 14 }}>
      <Text style={{ fontSize: 22, fontWeight: "700", color: ui().text }}>emoji picker</Text>
      <Text style={{ color: ui().muted }}>
        {desktop ? "Type to search, the arrows to move, Return to choose; a tab scrolls to its group" : "Search, or tap a tab to scroll to its group; tap an emoji to choose it"}
      </Text>
      <Split
        gap={14}
        inspector={
          <>
            <Panel title="message">
              <Text style={{ fontSize: 14, color: ui().text }}>{message()}</Text>
            </Panel>
            <Log title="events" lines={events()} minHeight={92} />
          </>
        }
      >
        <View
          style={{
            ...sectionSurface(),
            width: wide() ? 342 : undefined,
            height: desktop ? 400 : 440,
            alignSelf: wide() ? "center" : "stretch",
            overflow: "hidden",
          }}
        >
          <EmojiPanel
            class="flex-1"
            fill={!desktop}
            recent={recent()}
            onSelect={({ emoji, base }) => {
              message.set(message() + emoji);
              recent.set([base, ...recent().filter((e) => e !== base)].slice(0, 18));
              log(`onSelect({ emoji: "${emoji}", base: "${base}" })`);
            }}
            onCancel={() => log("onCancel()")}
          />
        </View>
      </Split>
    </View>
  );
}

mount(App);

use nsh_base::{EmojiGroupLabels, EmojiPickerEvent, emoji_picker};
use nsh_core::prelude::*;

fn picker() -> impl IntoElement {
    let chosen = signal(SharedString::from("none"));
    let mut labels = EmojiGroupLabels::default();
    labels.smileys_emotion = Some("笑脸与情感".into());
    labels.people_body = Some("人物与身体".into());
    emoji_picker()
        .recent(vec!["👍".into(), "🎉".into()])
        .group_labels(labels)
        .placeholder("搜索表情")
        .accessibility_label("表情")
        .auto_focus(true)
        .on_select(move |e: &EmojiPickerEvent| {
            if let EmojiPickerEvent::Select(emoji, ..) = e {
                chosen.set(emoji.clone());
            }
        })
        .item_class("size-9 items-center justify-center rounded-md text-[22px] hover:bg-accent focus:bg-accent")
        .w(px(342.0))
        .h(px(380.0))
}

import { mount, signal, Text } from "nsh";
import { EmojiPicker } from "nsh/base";

function App() {
  const message = signal("");
  return (
    <EmojiPicker
      recent={["👍", "🎉"]}
      groupLabels={{ recent: "常用", smileysEmotion: "笑脸与情感", peopleBody: "人物与身体" }}
      placeholder="搜索表情"
      accessibilityLabel="表情"
      autoFocus
      onSelect={({ emoji }) => message.set(message() + emoji)}
      class="h-96 w-[342px] overflow-hidden rounded-xl border border-border bg-popover"
      searchBarClass="mx-2 mt-2 h-8 flex-row items-center rounded-lg bg-muted px-2.5"
      searchClass="flex-1 text-sm text-foreground placeholder:text-muted-foreground"
      rowClass="px-2"
      groupClass="px-3 pt-2.5 pb-1 text-xs font-semibold text-muted-foreground"
      itemClass="size-9 items-center justify-center rounded-md text-[22px] hover:bg-accent focus:bg-accent"
      empty={<Text class="py-6 text-center text-sm text-muted-foreground">没有找到表情</Text>}
    />
  );
}

mount(App);

EmojiPicker 来自 nsh/base，在 Rust 里是 nsh-base crate。在 Rust 中用 emoji_picker() 创建，每个 prop 对应一个设置方法，每个事件对应一个监听方法，另有类型化的样式方法。它本身不弹出：桌面上放进 Popover，手机上放进 Sheet，也可以直接放在页面里。

#表情数据

面板内置 Unicode 的表情（emojibase-data，Emoji 18.0），保持它们的分组和顺序，每个表情带有引入它的 Emoji 版本，以及来自 Unicode CLDR 的英文名称和关键词。原生平台把数据打包在应用里；Web 上页面在第一次显示面板时下载（nsh-emoji.bin，压缩后约 30 KB），下载完成前显示 loading。

• 应用语言的名称：annotations 为每个表情提供应用语言的名称和关键词，可以直接取自 emojibase 对应语言的数据（compact.json：{ emoji: unicode, label, keywords: tags }）。格子和 onSelect 使用应用给的名称；查询词同时匹配应用的词和英文词。
• 搜索：名称或某个关键词包含查询词（不区分大小写）的表情会被匹配；名称里有以查询词开头的词的表情排在最前，其次是关键词里有这样的词的，然后是其余匹配项。匹配结果显示为一个没有标题的分组。
• 分组：groups 选择显示哪些分组以及顺序。"recent" 是应用的 recent 表情：由应用保存（取自 onSelect 的 base），面板负责显示。
• 肤色：skinTone 为所有能换肤色的表情设置同一种肤色（多人表情的每个人都会换上）。
• 较新的表情：emojiVersion 去掉某个 Emoji 版本之后新增的表情，供字体还画不出它们的系统使用（Emoji 16 需要 iOS 18.4、Android 16 或较新的 Windows 11）。

#Props

#事件

EmojiEntry 描述一个表情：emoji（带肤色）、base、label、keywords、group、version（引入它的 Emoji 版本）和 hasSkinTones（能否换肤色）。renderItem 会为每个可见的格子拿到它，高亮是格子的 focus:：每个表情只绘制一次，高亮移动时视图保持不变。

#部件

#Ref

#分组标签

分组标签是应用放在 header（手机上放在 footer）里的 Tabs：顶部所在的分组被选中（onGroupChange），按下标签滚动到对应分组（scrollToGroup）。

const group = signal<EmojiGroupId>("smileysEmotion");
let picker: EmojiPickerRef | undefined;

<EmojiPicker
  ref={(r) => (picker = r)}
  onGroupChange={({ group: next }) => group.set(next)}
  header={
    <Tabs class="flex-row justify-between" indicatorClass="bottom-0 h-0.5 bg-foreground">
      {groups.map((g) => (
        <Tab selected={group() === g.id} onPress={() => picker?.scrollToGroup(g.id)} accessibilityLabel={g.label}>
          <Icon name={g.icon} />
        </Tab>
      ))}
    </Tabs>
  }
/>;

#应用语言的名称

// 应用语言的 emojibase 数据：下载一次，由应用保存。
const annotations = signal<EmojiAnnotation[]>([]);
void fetch("https://cdn.jsdelivr.net/npm/emojibase-data@18/zh/compact.json")
  .then((r) => r.json())
  .then((data) => annotations.set(data.map((e) => ({ emoji: e.unicode, label: e.label, keywords: e.tags ?? [] }))));

<EmojiPicker annotations={annotations()} />;

#无障碍

• 网格的角色是 "listbox"，名称来自 accessibilityLabel；每个格子是一个 "option"，名称是表情的名称；分组标题是 "header"。最后一行不满时保留的空位对屏幕阅读器隐藏。
• 方向键移动高亮时键盘焦点留在搜索框里，屏幕阅读器读出高亮表情的名称。

标签、角色和播报的通用说明见无障碍。

#键盘

输入法组字时按键归输入法：回车和 Escape 用来确认或取消正在输入的文字，不会选中表情或关闭面板。

#平台说明

• 每个平台用自己的彩色表情字体绘制：iOS 和 macOS 是 Apple Color Emoji，Android（Linux 上通常也是）是 Noto Color Emoji（缺少时请安装），Windows 是 Segoe UI Emoji，浏览器里是系统的字体。Windows 上国旗显示为两个字母：在那里可以把 "flags" 从 groups 里去掉。
• 桌面（macOS、Windows、Linux、GPUI）和 Web：指针移到哪个格子就高亮哪个格子，点击在按下时就选中，所以搜索框保持键盘焦点。
• iOS、Android 和 Mac Catalyst：轻点选中；键盘上的回车键选中高亮的表情。