emoji-cheat-sheet.com 项目解析:一页式 Emoji 速查表的同义词即时搜索、一键复制与自动化部署
emoji-cheat-sheet.com 项目解析:一页式 Emoji 速查表的同义词即时搜索、一键复制与自动化部署
本文以 README.md 为核心主线,结合仓库源码(public/index.html、public/script.js、lib/emoji_optimizer.rb、lib/simple_s3_deploy.rb 等),完整剖析 emoji-cheat-sheet.com 这一"一页式 Emoji 速查表"的项目定位、页面数据模型、Instant Search 同义词搜索机制、点击复制实现,以及从雪碧图优化到 S3 部署的完整工具链。读完本文,你将掌握该项目的全部技术细节,并能够直接上手为速查表贡献同义词,或把同类方案迁移到自己的项目中。
项目定位:一个页面装下全网 Emoji
emoji-cheat-sheet.com 是一个典型的 "one pager"(单页应用):整个站点只有一张页面,集中罗列了在主流协作与社交平台上被支持的 Emoji 表情符号代码。根据 README.md 与 public/index.html 的页面描述,这些平台包括:
Campfire、GitHub、Basecamp(Basecamp Next)、Redbooth、Trac、Flowdock、Sprint.ly、Kandan、Textbox.io、Kippt、Redmine、JabbR、Trello、Hall、Qiita、Zendesk、Ruby-China、Grove、Idobata、NodeBB、Slack、Streamup、OrganisedMinds、Hackpad、Cryptbin、Kato、Reportedly、Cheerful Ghost、IRCCloud、Dashcube、MyVideoGameList、Subrosa、Sococo、Quip、And Bang、Bonusly、Discourse、Ello、Twemoji Awesome、ReadMe.io、esa、DBook、Groups.io、TeamworkChat、Damn Bugs、Let's Chat、Buildkite、IGDB.com、ChatGrape、Dokuwiki、Usersnap、Discord、Status Hero、Morfy、Gitter、Yellow、YouTube、Habitica、Mattermost、Kanban Tool、Telegram、StackEdit、Chttr.co 等数十个服务。
页面的核心价值在 public/index.html 的 <meta name="description"> 中写得很清楚:"Emoji codes used by GitHub, Basecamp, Slack and other services. Searchable. With emoji meanings."——即:可搜索、带含义说明的 Emoji 代码速查。因为不少 Emoji 代码并不容易记忆(README 原文:some of the emoji codes are not super easy to remember, so here is a little cheat sheet),一张集中、可搜索的清单正是这个项目存在的意义。
页面将 Emoji 按语义分为五大类,对应 public/index.html 中的五个 <ul> 区块:
| 分类 | HTML id | 覆盖内容示例 |
|---|---|---|
| People | emoji-people |
笑脸、手势、人物、猫脸、心形等 |
| Nature | emoji-nature |
天气、动物、植物、月亮 |
| Objects | emoji-objects |
物品、数码设备、食物、运动 |
| Places | emoji-places |
建筑、交通、国家旗帜 |
| Symbols | emoji-symbols |
数字、箭头、符号、时钟 |
页面数据模型:data-alternative-name 驱动的 Emoji 清单
从源码结构看,每个 Emoji 在 public/index.html 中对应一条结构完全一致的 <li> 记录,这是整个页面的"数据行":
<li>
<div>
<img src="graphics/emojis/smile.png">
:<span class="name" data-alternative-name="happy, cheerful, face, joy, funny, haha, laugh, like">smile</span>:
</div>
</li>
可以拆解为四个关键部分:
<img>标签:指向 public/graphics/emojis/ 目录下的 64×64 PNG 图标,例如smile.png、+1.png、shipit.png。<span class="name">:存放 Emoji 的标准代码,即聊天中输入:smile:时生效的smile部分。代码两侧的冒号在渲染时呈现为:smile:的完整写法。data-alternative-name属性:该 Emoji 的同义词(别名)列表,用逗号分隔,例如happy, cheerful, face, joy。这是本项目搜索功能的"第二索引"(详见下一节)。- 分类归属:
<li>所在的<ul>的class(people/nature/objects/places/symbols)决定了它属于哪一大类。
这种"数据行 + 属性"的结构让整个清单可以纯静态托管,不依赖数据库:新增一个 Emoji 只需要追加一条 <li>,新增搜索词只需要编辑 data-alternative-name。
值得注意的细节:部分自定义 Emoji 的同义词中带有 custom_ 标记(如 neckbeard、metal、fu、trollface),README 中也提到这是社区贡献形成的开放扩展清单;仓库还收录了如 1f98d.png(gorilla)这类以 Unicode 码点为文件名的表情。
核心功能一:Instant Search 即时搜索与同义词机制
这是 README 中"Contributions wanted"章节重点介绍的功能:速查表顶部有一个 Instant Search 输入框(public/index.html 中 <input class="search" placeholder="Instant Search">),支持对每个 Emoji 的同义词/别名进行即时过滤。README 明确指出:
There is a feature in the cheat sheet that allows you to add synonyms (or alternative names) for each emoji. This is used when using the "Instant Search" search field in the page top.
并建议查看 public/index.html 附近的 data-alternative-name 属性——该行恰好是 hushed 表情的声明,与 README 描述一致。
搜索匹配的源码实现
搜索逻辑集中在 public/script.js 的三个函数中:
function isElementMatching(element, needle) {
var alternative = element.attr("data-alternative-name");
return ($(element).text().toLowerCase().indexOf(needle) >= 0) ||
(alternative != null && alternative.toLowerCase().indexOf(needle) >= 0);
}
function highlightElements(needle) {
if (needle.length == 0) {
highlightAll();
return;
}
needle = needle.toLowerCase();
$(".emojis li").each(function (index, el) {
if (isElementMatching($('.name', el), needle)) {
$(el).show();
} else {
$(el).hide();
}
});
}
function highlightAll() {
$(".emojis li").show();
}
其匹配规则可以概括为:
- 大小写不敏感:输入先经
toLowerCase()归一化; - 子串匹配:只要 Emoji 代码(
<span class="name">的文本)或data-alternative-name中的任一关键词包含输入内容即命中; - 双通道索引:标准代码 + 同义词,两者任一命中即显示;
- 即时过滤:绑定在
change paste keyup事件上(public/script.js),输入即过滤,清空即恢复全部显示; - ESC 支持:按下 ESC 会清空输入框并恢复显示全部 Emoji(public/script.js)。
页面加载后输入框会自动聚焦($("#header .search").focus()),保证用户打开页面即可直接输入搜索。
如何为速查表贡献同义词
README 明确欢迎社区提交同义词,操作路径非常直接:
- 找到目标 Emoji 对应的
<li>(按分类和代码名定位); - 在
<span class="name">上补充或修改data-alternative-name,用逗号分隔多个关键词,例如给动物类 Emoji 加上cute, fluffy, pet之类的别名; - 通过 Pull Request 提交。
由于匹配是小写子串匹配,同义词建议使用常见英文关键词(README 举例 "add a synonym for your favourite emoji or maybe animal to one of the animals")。当前仓库中许多条目已经积累了相当丰富的同义词(如 smile 有 happy, cheerful, face, joy, funny, haha, laugh, like,wave 有 hi, hello, bye, hands, gesture, goodbye, solong, farewell, palm),这些同义词大量来自社区贡献。
核心功能二:点击 Emoji 代码一键复制
页面正文中有一句提示:"Got a modern browser or Flash enabled? Click the emoji code and it will be copied to your clipboard." 即点击任意 Emoji 代码即可复制到剪贴板。该能力在 public/script.js 中实现了双通道降级方案:
通道一:ZeroClipboard(Flash)
页面头部嵌入了一个 1×1 的 Flash 探测组件(public/index.html 中 #flash-test 内的 ZeroClipboard.swf)。脚本启动时先检测 document.flashtest.PercentLoaded() >= 0 判断 Flash 是否可用(public/script.js):
- 可用则调用
initZeroClipboard()(public/script.js):配置forceHandCursor: true,在mouseover时把div挂载到 ZeroClipboard 客户端,copy事件里通过evt.clipboardData.setData("text/plain", ...)写入剪贴板; aftercopy时给元素加上copied类触发"Copied"反馈动画,并上报 Google Analytics 事件_trackEvent('Emojis', 'Copy', ...);- 若 Flash 初始化出错,则自动销毁并降级到 JS 通道。
通道二:原生 JS 复制(无 Flash 降级方案)
initJsClipboard()(public/script.js)使用浏览器原生能力:
var selection = getSelection();
selection.removeAllRanges();
var range = document.createRange();
range.selectNodeContents(this);
selection.addRange(range);
if(document.execCommand('copy') == true) { ... }
复制成功后同样触发 copied 反馈;若失败(例如 Firefox 中 dom.allow_cut_copy 被禁用、或 IE11 权限受限),则添加 clipboardError 类并提示 "Your browser does not support copy"。
复制成功的视觉反馈
反馈动画定义在 public/style.css:li div.copied:after 显示绿色的 "Copied" 文本,li div.clipboardError:after 显示红色的 "Your browser does not support copy",两者都通过 fadeOut 关键帧动画(public/style.css)在 0.8 秒 / 6 秒后淡出。复制的文本取自元素内容的 trim(),即 :smile: 的完整代码形式。
特色功能:Campfire 声音速查
除了 Emoji 表情,页面还附带了一个 Campfire 专属的"声音"速查区块(public/index.html)。每条记录形如 <li><div data-sound="trombone">/play trombone</div></li>,罗列了 secret、trombone、crickets、rimshot、vuvuzela、nyan、dangerzone、trololo、letitgo 等数十个可用的 /play 命令。
public/script.js 中实现了对应的音频播放逻辑:当浏览器支持 MP3 时(canPlayType("audio/mpeg")),为每条声音前置一个播放按钮,点击后通过 new Audio("https://emoji-cheat-sheet.campfirenow.com/sounds/" + soundName + ".mp3") 播放,并支持切换声音时自动停止上一个(curAudio.pause())。
构建工具链:雪碧图优化与一键 S3 部署
虽然页面本体是纯静态文件,但仓库配备了一套完整的 Ruby 构建工具链,集中在 Rakefile、lib/emoji_optimizer.rb 和 lib/simple_s3_deploy.rb 中。
Rake 任务入口
Rakefile 定义了核心任务:
task :deploy do
Emoji::Optimizer.new(:size => 22, :padding => 5).optimize! do
SimpleS3Deploy.deploy 'public'
end
end
流程为:先做雪碧图优化,再部署到 S3。此外还有 rake test:sprite 任务(Rakefile),可以把所有 Emoji 生成到 public/graphics/test_sprite.png 用于本地检查——仓库中恰好保留了这个产物。
Emoji::Optimizer:把上千张 PNG 合成雪碧图
lib/emoji_optimizer.rb 是整个优化流水线的核心,主要步骤:
- 解析 HTML 提取图片路径:
Emoji::Source用 Nokogiri 解析public/index.html,通过doc.css('#content img')配合src =~ /emojis/正则收集所有 Emoji 图片(lib/emoji_optimizer.rb); - 生成普通与 Retina 双份雪碧图:
Sprite#generate(lib/emoji_optimizer.rb)调用 ImageMagick 的montage命令,参数包括tile: 'x1'(横向平铺)、geometry: "#{size}x#{size}+#{padding}"、depth: '8'、透明背景和sharpen: '0x1.5';若系统装有optipng,还会追加optipng -o5做 PNG 深度优化,否则仅提示跳过; - CSS 雪碧图映射:为每个 Emoji 生成
#e_N { background-position: -offset px 0; }规则(lib/emoji_optimizer.rb),offset 由((size + padding*2) * index) + padding计算; - Retina 适配:通过
min-device-pixel-ratio/min-resolution媒体查询切换 1x/1.5x/2x 资源(lib/emoji_optimizer.rb); - 内容寻址命名:雪碧图以内容 MD5 作为文件名(
sprite_<md5>.png/sprite_<md5>@2x.png,见 lib/emoji_optimizer.rb),天然具备缓存失效能力; - 可逆式修改:优化前先把
index.html/style.css备份到临时目录,把<img>替换为<span class="emoji" id="e_N" data-src="...">,完成后用备份还原,保证中间产物不会污染源码。
SimpleS3Deploy:静态站点一键发布
lib/simple_s3_deploy.rb 负责把 public/ 目录发布到 AWS S3,关键逻辑:
- 先清空再上传:
clear_bucket删除远端已有对象,避免残留旧文件(lib/simple_s3_deploy.rb); - CSS/JS 自动压缩:对
.css/.js文件调用yuicompressor生成临时压缩版本再上传(lib/simple_s3_deploy.rb); - MIME 与缓存头:用
mime-types推断 Content-Type,并统一设置cache_control: 'max-age=604800, public'(即 7 天公共缓存)(lib/simple_s3_deploy.rb); - 配置来源:S3 凭证从仓库根目录的
config.yaml读取(config.yaml.sample给出了模板):
s3:
access_key_id:
secret_access_key:
bucket:
- 依赖清单:Gemfile 中声明了
fog(S3 客户端)、mime-types(类型推断)、rake(任务编排)和nokogiri(HTML 解析)。
这套工具链体现了"静态页面 + 构建脚本"的极简架构:源文件始终是可读的 HTML/CSS/PNG,构建与部署过程全部可复现。
在自己的项目中集成 Emoji
README 的 "Want to add emojis to your projects?" 一节为不同技术栈提供了现成的集成方案(均为社区维护的库,名称如下,可按需检索):
- Ruby:gemoji、rails_emoji(另有 rails_emoji_picker、twemoji 等 Rails 相关扩展);
- JavaScript / Node.js:emoticons、emojify.js、emoji-images.js;
- Objective-C:NSStringEmojize;
- Python:emoji;
- Swift:Smile。
这些库覆盖了从服务端渲染到前端替换的主流场景,配合本速查表可以快速确定某个 Emoji 代码在各平台是否被支持。
参与贡献:为速查表补充同义词
README 的 "Contributing" 章节给出了标准的 GitHub Flow 协作流程:
- Fork 仓库;
- 创建特性分支:
git checkout -b my-new-feature; - 提交修改:
git commit -am 'Add some feature'; - 推送分支:
git push origin my-new-feature; - 提交 Pull Request。
结合前文分析,贡献同义词的实际改动非常轻量:只需编辑 public/index.html 中对应 <li> 的 data-alternative-name 属性,无需改动任何 JS/CSS,因为搜索逻辑已经对同义词属性做了通用支持。这也是该项目长期以社区众包方式持续丰富搜索词表的协作模式。
小结
emoji-cheat-sheet.com 的价值在于用最轻量的一页式架构承载了"可搜索、可复制、跨平台"的 Emoji 查询体验:data-alternative-name 构成了可众包扩展的同义词数据层,public/script.js 用不到 200 行代码实现了即时搜索、双通道剪贴板与声音播放,而 lib/emoji_optimizer.rb 与 lib/simple_s3_deploy.rb 则把"千图合一张、一键上 S3"的工程细节打磨成了开箱即用的 Rake 任务。对于想构建类似"数据驱动型静态速查页"的开发者,这个仓库从数据建模、前端交互到发布流水线都提供了完整且可复用的参考实现。