emoji-cheat-sheet 全解析:基于 GitHub Emoji API 与 Unicode 全量 Emoji 列表自动生成 Markdown 速查表的完整实践
emoji-cheat-sheet 全解析:基于 GitHub Emoji API 与 Unicode 全量 Emoji 列表自动生成 Markdown 速查表的完整实践
本文围绕开源仓库 emoji-cheat-sheet 的核心文档 README.md 展开。该仓库交付的是一份由脚本自动生成、始终与上游数据源保持同步的 Markdown 版 Emoji 速查表:它同时覆盖 GitHub 平台可用的全部 Emoji shortcode 与 Unicode 官方全量 Emoji 列表,并按官方分类组织成可快速查阅的表格。读完本文,你将掌握这份速查表的内容结构、表格读法,以及隐藏在 scripts 目录中的完整生成链路——从抓取 GitHub Emoji API、解析 Unicode 全量列表,到输出带目录锚点的两列 Markdown 表格,并了解如何用一条命令自行重新生成与验证。
项目概览:一份"自己会更新"的 Markdown 速查表
README 的开篇一句话点明了项目的本质(见 README.md):
This cheat sheet is automatically generated from GitHub Emoji API and Unicode Full Emoji List.
也就是说,这份速查表不是人工维护的静态文档,而是由程序抓取两个权威数据源后生成的:
- GitHub Emoji API:提供 GitHub 平台上所有可用 emoji 的 id(shortcode)与对应图片 URL;
- Unicode Full Emoji List:提供官方全量 emoji 的字符、名称与分类(大类/子类)体系。
两个数据源在生成脚本中被"合流":以 Unicode 的分类为骨架,把 GitHub 的 shortcode 挂到对应的 emoji 字符上,最终产出一份"既有官方分类、又是 GitHub 可直接使用"的速查表。
仓库本身的工程实现非常精简,全部核心代码都在 scripts 目录下,配套 package.json 声明了命令与依赖:
| 文件 | 职责 |
|---|---|
| scripts/fetch.ts | 抓取并解析两个上游数据源,完成归类 |
| scripts/markdown.ts | 把归类结果渲染为 Markdown 表格与目录 |
| scripts/generate.ts | 入口:串联 fetch 与 markdown 两个步骤 |
| scripts/generate.test.ts | vitest 测试,配合快照验证生成结果 |
| scripts/snapshots/generate.test.ts.snap | 录制的上游 HTTP 响应与快照数据 |
技术栈为 TypeScript(strict 模式,见 tsconfig.json),运行命令依赖 vite-node 与 vitest,包管理使用 pnpm,要求 Node >= 18(见 package.json)。
速查表的内容结构与组织方式
十大顶级分类
README 的 Table of Contents 将全部 emoji 划分为 10 个顶级分类,这也是整份速查表的骨架:
- Smileys & Emotion(表情与情感)
- People & Body(人物与身体)
- Animals & Nature(动物与自然)
- Food & Drink(食物与饮品)
- Travel & Places(旅行与地点)
- Activities(活动)
- Objects(物品)
- Symbols(符号)
- Flags(旗帜)
- GitHub Custom Emoji(GitHub 自定义 emoji)
其中前 9 类直接继承 Unicode 官方的大类体系,而 GitHub Custom Emoji 是该项目特有的一个分类——它收纳了 :octocat:、:shipit:、:dependabot:、:trollface: 这类不属于 Unicode 标准、仅存在于 GitHub 平台的 emoji(见 README.md)。
二级子类:继承 Unicode 官方细分
每个顶级分类下又按 Unicode 官方子类继续细分,例如:
- Smileys & Emotion 下分为 Face Smiling、Face Affection、Face Tongue、Face Hand、Face Neutral Skeptical、Face Sleepy、Face Unwell、Face Hat、Face Glasses、Face Concerned、Face Negative、Face Costume、Cat Face、Monkey Face、Heart、Emotion 共 16 个子类;
- People & Body 下分为 Hand Fingers Open、Hand Fingers Partial、Hand Single Finger、Hand Fingers Closed、Hands、Hand Prop、Body Parts、Person、Person Gesture、Person Role、Person Fantasy、Person Activity、Person Sport、Person Resting、Family、Person Symbol 共 16 个子类;
- Animals & Nature 下分为 Animal Mammal、Animal Bird、Animal Amphibian、Animal Reptile、Animal Marine、Animal Bug、Plant Flower、Plant Other 共 8 个子类;
- Food & Drink 下分为 Food Fruit、Food Vegetable、Food Prepared、Food Asian、Food Marine、Food Sweet、Drink、Dishware 共 8 个子类;
- Travel & Places 下分为 Place Map、Place Geographic、Place Building、Place Religious、Place Other、Transport Ground、Transport Water、Transport Air、Hotel、Time、Sky & Weather 共 11 个子类;
- Activities 下分为 Event、Award Medal、Sport、Game、Arts & Crafts 共 5 个子类;
- Objects 下分为 Clothing、Sound、Music、Musical Instrument、Phone、Computer、Light & Video、Book Paper、Money、Mail、Writing、Office、Lock、Tool、Science、Medical、Household、Other Object 共 18 个子类;
- Symbols 下分为 Transport Sign、Warning、Arrow、Religion、Zodiac、Av Symbol、Gender、Math、Punctuation、Currency、Other Symbol、Keycap、Alphanum、Geometric 共 14 个子类;
- Flags 下分为 Flag、Country Flag、Subdivision Flag 共 3 个子类。
这些子类名称由源码从 Unicode 文本中的 @ 标记直接转换而来(下文详述),例如 face-smiling 会被格式化为 Face Smiling。
表格格式:两列布局 + 短代码
每个子类下的 emoji 以 Markdown 表格呈现,典型表头如下:
| | ico | shortcode | ico | shortcode | |
| - | :-: | - | :-: | - | - |
这是一张固定两列的表格:每行容纳两个 emoji(ico 列显示 emoji 图形,shortcode 列显示对应的代码),表格最左侧是"返回本分类顶部"的锚点链接,最右侧是"返回目录"的链接。以 Face Smiling 子类为例(完整内容见 README.md):
| ico | shortcode | ico | shortcode | ||
|---|---|---|---|---|---|
| top | :grinning: | :grinning: |
:smiley: | :smiley: |
top |
| top | :smile: | :smile: |
:grin: | :grin: |
top |
| top | :laughing: | :laughing: :satisfied: |
:sweat_smile: | :sweat_smile: |
top |
| top | :rofl: | :rofl: |
:joy: | :joy: |
top |
| top | :slightly_smiling_face: | :slightly_smiling_face: |
:upside_down_face: | :upside_down_face: |
top |
| top | :wink: | :wink: |
:blush: | :blush: |
top |
| top | :innocent: | :innocent: |
top |
这张表格能直观看到速查表的两个关键设计:
- 一图对应多个别名:
:laughing:与:satisfied:指向同一个 emoji 图形,shortcode 列用<br />换行罗列全部可用别名; - 末尾单元格留空:当子类内 emoji 数量为奇数时,最后一个格子留空补齐表格结构(如上面的
:innocent:行)。
如何使用这份速查表
在 GitHub 的 issue、PR、评论、README 等支持 Markdown 渲染的场景中,直接输入 :shortcode: 形式的代码即可显示对应 emoji 图形,例如:
- 输入
:rocket:显示 :rocket:(火箭) - 输入
:+1:或:thumbsup:显示 :+1:(点赞) - 输入
:tada:显示 :tada:(庆祝彩带) - 输入
:octocat:显示 :octocat:(GitHub 吉祥物)
速查表的价值在于:不需要记忆,打开 README.md 按分类浏览、按 Ctrl+F 搜索即可定位任意 shortcode,同时还能确认某个代码是否为 GitHub 当前支持的合法别名。
数据采集:两个上游数据源的源码级解析
生成链路的第一步是 scripts/fetch.ts,它完成"抓取 → 解析 → 归类"三个动作。
抓取 GitHub Emoji API
getGithubEmojiIdMap()(fetch.ts)请求 GitHub Emoji API,返回一个 JSON 对象,形如:
{
"+1": "https://github.githubassets.com/images/icons/emoji/unicode/1f44d.png?v8",
"octocat": "https://github.githubassets.com/images/icons/emoji/octocat.png?v8",
...
}
key 是 shortcode(如 +1、grinning),value 是图片 URL。源码对 URL 做了两类分支处理:
- URL 路径包含
/unicode/:说明这是标准 Unicode emoji,从路径末段提取十六进制码点(如1f44d),按-拆分后逐个String.fromCodePoint(...)还原成真正的 emoji 字符(fetch.ts)。多个码点用-连接,例如1f468-1f469-1f466会还原为家庭 emoji; - URL 路径不含
/unicode/:说明是 GitHub 自定义 emoji(如octocat.png),只保留文件名作为标识(fetch.ts)。
请求时源码还显式设置了 User-Agent 头为 https://github.com/ikatyang/emoji-cheat-sheet(fetch.ts),符合 GitHub API 对 UA 的要求。
解析 Unicode 全量 Emoji 列表
getUnicodeEmojiCategoryIterator()(fetch.ts)抓取 Unicode 官方 full-emoji-list 的纯文本版本,逐行解析:
- 以
@@开头的行是大类(category),例如@@Smileys & Emotion; - 以
@开头的行是子类(subcategory),例如@face-smiling; - 其余非空行是 emoji 条目,取行首 tab 分隔的第一列,再按空格拆分十六进制码点并还原为字符。
该函数返回一个惰性迭代器(generator),按顺序产出 { type: 'category' | 'subcategory' | 'emoji', value } 三种事件,供后续归类消费。
归类算法:把 GitHub shortcode 挂到 Unicode 分类上
核心函数 getCategorizeGithubEmojiIds()(fetch.ts)实现了两个映射:
emojiLiteralToGithubEmojiIdsMap:emoji 字符 → GitHub shortcode 数组。因为多个 shortcode 可能指向同一个 emoji(如laughing与satisfied),所以值是一个数组;githubSpecificEmojiUriToGithubEmojiIdsMap:自定义 emoji URI → shortcode 数组,用于收纳非 Unicode 的 GitHub 专属 emoji。
随后遍历 Unicode 分类事件,做如下处理:
- 用
categoryStack维护当前所在的大类/子类层级(fetch.ts); - 对每个 emoji 字符,先把 key 中的变体选择符(U+FE00–U+FE0F)与零宽连接符 ZWJ(U+200D)剔除(fetch.ts),再做映射匹配——这是为了保证不同平台对同一 emoji 的编码差异不影响匹配;
- 匹配成功则把该字符对应的全部 GitHub shortcode 推入当前子类的数组中,并从
githubEmojiIdMap中删除已归类的项(fetch.ts); - 遍历结束后若
githubEmojiIdMap仍有剩余,直接抛出Uncategorized emoji(s) found.错误(fetch.ts)——这是生成链路的完整性兜底:任何 GitHub 支持的 emoji 都必须找到归属,否则生成失败而不是产出残缺清单; - 清理空分类/空子类(fetch.ts);
- 最后把剩余的自定义 emoji 单独挂到
GitHub Custom Emoji分类下(fetch.ts)。
分类标题的格式化由 toTitleCase()(fetch.ts)完成:连字符转空格、合并连续空白、每个英文单词首字母大写,于是 face-smiling 变成 Face Smiling。
Markdown 渲染:表格、目录与锚点的生成逻辑
第二步由 scripts/markdown.ts 把归类结果渲染为最终文档。
generateCheatSheet()(markdown.ts)按以下顺序拼接输出:
# emoji-cheat-sheet一级标题;Up to Date徽章(指向仓库的 Actions 工作流,用于对外展示"与上游同步"的状态,见 markdown.ts);- 一句自动生成说明,并内联引用 GitHub Emoji API 与 Unicode Full Emoji List 两个数据源(对应 README.md 的原文);
## Table of Contents顶级目录;- 依次渲染每个大类:先输出
### 分类名与子类目录,再逐个输出#### 子类名与 emoji 表格。
几个值得注意的实现细节:
- 两列布局常量
COLUMNS = 2(markdown.ts):generateTable()(markdown.ts)每行渲染两个 emoji;当某子类 emoji 总数少于 2 时,表头自动退化为单列(例如 Animal Amphibian 下只有:frog:一个条目,见 README.md); - 多别名输出:一个 emoji 对应多个 shortcode 时,后续别名用
<br />追加在同一单元格内(markdown.ts); - 导航锚点:每行首列是
[top](#分类锚点),末列是[top](#table-of-contents),方便长文档内快速跳转; - 锚点生成规则
getHeaderId()(markdown.ts):标题转小写、空格替换为-、剔除所有非字母数字与连字符的字符——这正是 README 中#smileys--emotion(两个连字符)这类锚点形态的由来,&等符号会被剥除; - 目录生成
generateToc()(markdown.ts):为每个标题生成- [标题](#锚点)列表项。
入口脚本 scripts/generate.ts 则把两步串起来:generate() 先调用 getCategorizeGithubEmojiIds() 取归类数据,再交给 generateCheatSheet() 渲染;当命令行参数为 run 时把结果打印到标准输出。
一键生成与质量保障:命令、测试与持续更新
重新生成 README
package.json 定义了完整的命令集:
"scripts": {
"lint": "prettier --check .",
"check": "tsc --noEmit",
"generate": "vite-node ./scripts/generate.ts -- run > ./README.md",
"test": "vitest"
}
其中 pnpm generate 的完整语义是:用 vite-node 运行 generate.ts,传入 run 参数触发执行,并把标准输出重定向覆盖写入 README.md。也就是说 README 是生成产物,只要上游数据源(GitHub Emoji API、Unicode 全量列表)更新,重新执行这一条命令即可得到最新速查表。
前提条件:Node >= 18(engines 字段,package.json)、pnpm 8.6.6(packageManager 字段,package.json)。克隆与初始化可参考:
git clone https://gitcode.com/gh_mirrors/em/emoji-cheat-sheet.git
cd emoji-cheat-sheet
pnpm install
pnpm generate
测试与快照机制
scripts/generate.test.ts 用 vitest 编写,核心是 toMatchInlineSnapshot():它直接断言 generate() 的完整输出与快照一致。为了让测试不依赖实时网络,测试通过 jest-playback 的 setupPlayback() 把两个上游请求的 HTTP 响应录制下来(scripts/snapshots/generate.test.ts.snap 中同时保存了 GitHub API 返回的完整 JSON 与 Unicode 列表文本),后续运行时按需"回放"。
这意味着质量保障分成两层:
- 离线可重复的测试:
pnpm test用录制的数据跑通整条生成链路,任何一处归类或渲染逻辑的回归都会导致快照不匹配而失败; - 在线验证的持续更新:README 顶部的
Up to Date徽章(由生成脚本写入)指向仓库的 GitHub Actions 工作流,用于对外展示速查表是否仍与上游最新数据保持一致。
关于"更新频率"的边界说明
仓库本身并未承诺固定的更新周期,从代码结构看,更新路径是"上游数据变化 → 重新执行 pnpm generate → README 被覆盖为最新内容"。因此如果以 README 为使用依据,应以该仓库当前快照为准;需要最新数据时,可自行重新生成。
常见疑问速览
为什么同一个 emoji 有多个 shortcode?
因为 GitHub 为同一 Unicode 字符保留了多个历史别名,例如 :+1: 与 :thumbsup:、:pout: 与 :rage:、:hankey: 与 :poop:、:shit:。速查表在 shortcode 列用 <br /> 把全部别名并列展示,任选其一均可用。
为什么 GitHub Custom Emoji 单独成一章?
这一类(:octocat:、:shipit:、:dependabot:、:basecamp:、:electron: 等)不是 Unicode 标准字符,而是 GitHub 平台专属的图片型 emoji,无法套用 Unicode 的分类体系,因此在归类时被独立收纳(fetch.ts)。
为什么有些子类只有一行甚至一个 emoji?
子类体系完全继承 Unicode 官方列表。个别子类(如 Animal Amphibian 仅 :frog:)本身就只包含一个字符;而当子类条目不足 2 个时,表格渲染会自动退化为单列,这是 markdown.ts 中列数逻辑的预期行为。
手工改动 README 会被覆盖吗?
会。README 由 pnpm generate 重定向输出覆盖,属于生成产物而非手写文档。若要修改内容,正确做法是修改 scripts 下的生成逻辑,而不是直接编辑 README——这也正是本项目"自动生成、保持同步"设计理念的核心体现。
小结
emoji-cheat-sheet 用极简的工程结构解决了一个"保持最新"的维护难题:README 的 10 大类、数十个子类、数百行 emoji 表格全部由 scripts/fetch.ts 与 scripts/markdown.ts 自动产出,GitHub Emoji API 负责 shortcode 与图形,Unicode Full Emoji List 负责官方分类,两者通过"码点归一化 + 双向映射 + 未归类兜底"完成合流;配合 pnpm generate 一条命令重写 README、pnpm test 快照测试保证可复现,最终在 GitHub 场景下提供了一份始终可信、可直接检索使用的 emoji shortcode 速查表。