emoji-cheat-sheet 全解析:基于 GitHub Emoji API 与 Unicode 全量 Emoji 列表自动生成 Markdown 速查表的完整实践

原创2026-10-13 13:10:172,275 阅读
文章标签:文档

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

这张表格能直观看到速查表的两个关键设计:

  1. 一图对应多个别名::laughing: 与 :satisfied: 指向同一个 emoji 图形,shortcode 列用 <br /> 换行罗列全部可用别名;
  2. 末尾单元格留空:当子类内 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 分类事件,做如下处理:

  1. 用 categoryStack 维护当前所在的大类/子类层级(fetch.ts);
  2. 对每个 emoji 字符,先把 key 中的变体选择符(U+FE00–U+FE0F)与零宽连接符 ZWJ(U+200D)剔除(fetch.ts),再做映射匹配——这是为了保证不同平台对同一 emoji 的编码差异不影响匹配;
  3. 匹配成功则把该字符对应的全部 GitHub shortcode 推入当前子类的数组中,并从 githubEmojiIdMap 中删除已归类的项(fetch.ts);
  4. 遍历结束后若 githubEmojiIdMap 仍有剩余,直接抛出 Uncategorized emoji(s) found. 错误(fetch.ts)——这是生成链路的完整性兜底:任何 GitHub 支持的 emoji 都必须找到归属,否则生成失败而不是产出残缺清单;
  5. 清理空分类/空子类(fetch.ts);
  6. 最后把剩余的自定义 emoji 单独挂到 GitHub Custom Emoji 分类下(fetch.ts)。

分类标题的格式化由 toTitleCase()(fetch.ts)完成:连字符转空格、合并连续空白、每个英文单词首字母大写,于是 face-smiling 变成 Face Smiling。

Markdown 渲染:表格、目录与锚点的生成逻辑

第二步由 scripts/markdown.ts 把归类结果渲染为最终文档。

generateCheatSheet()(markdown.ts)按以下顺序拼接输出:

  1. # emoji-cheat-sheet 一级标题;
  2. Up to Date 徽章(指向仓库的 Actions 工作流,用于对外展示"与上游同步"的状态,见 markdown.ts);
  3. 一句自动生成说明,并内联引用 GitHub Emoji API 与 Unicode Full Emoji List 两个数据源(对应 README.md 的原文);
  4. ## Table of Contents 顶级目录;
  5. 依次渲染每个大类:先输出 ### 分类名 与子类目录,再逐个输出 #### 子类名 与 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 速查表。

登录后查看全文
emoji-cheat-sheet