emoji-mart 完整集成指南：数据解耦、Picker 配置、Emoji 组件与 Headless 搜索

前端UI组件【免费下载链接】emoji-mart One component to pick them all项目地址https://gitcode.com/gh_mirrors/em/emoji-mart点击查看免费下载导读本文围绕开源仓库 emoji-martpackages/emoji-mart当前版本 5.6.0的官方 README 展开系统讲解如何在一个 Web 应用中完整接入这套可自定义的 emoji 选择器 HTML 组件。你将掌握数据与组件库解耦的两种加载方式、Picker 全部 30 配置项的含义与源码级默认值、em-emoji与em-emoji-picker两个 Web Component 的用法、无 UI 的 Headless 搜索 API、原生 emoji 反查以及国际化与自定义 emoji 的实现细节。文中所有示例均基于仓库真实源码与配置可直接复制运行。仓库结构总览emoji-mart 是一个 monorepo核心代码按包拆分见 packages/emoji-mart/package.jsonpackages/emoji-mart组件库本体源码位于 packages/emoji-mart/src入口为 packages/emoji-mart/src/index.ts对外导出Picker、Emoji、FrequentlyUsed、SafeFlags、SearchIndex、Store、init、Data、I18n、getEmojiDataFromNativepackages/emoji-mart-data完全独立的 emoji 数据集包含 i18n 的 22 种语言 JSON 与 sets 下 10 个 emoji 版本的 5 种表情风格apple / facebook / google / native / twitterpackages/emoji-mart-reactReact 封装层react.tsxpackages/emoji-mart-website示例站点含 example-categories.html、example-emoji-component.html、example-headless-search.html 等 6 个可直接在浏览器打开的演示页。 数据层与组件库完全解耦为什么数据要与库分离README 明确说明Picker 运行所需的全部 emoji 数据已从库中彻底解耦。这一设计的核心收益是让开发者自己掌控 bundle 体积并自主决定数据的加载时机与方式。数据的两种接入策略各有取舍直接打包进代码Bundled优点Picker 瞬时渲染数据可离线使用缺点首屏加载更慢文件更大。yarn add emoji-mart/dataimport data from emoji-mart/data import { Picker } from emoji-mart new Picker({ data })远程按需获取Fetched remotely优点仅在需要时才拉取数据不影响应用 bundle 体积缺点存在网络延迟无法离线工作除非配合 ServiceWorker。import { Picker } from emoji-mart new Picker({ data: async () { const response await fetch( https://cdn.jsdelivr.net/npm/emoji-mart/data, ) return response.json() } })README 特别指出示例中是走 CDN 获取但如果你要自己托管数据也可以从自己的域名获取。从源码看init()对data的处理同时支持同步对象与异步函数两种形态——typeof props.data function ? await props.data() : props.data见 packages/emoji-mart/src/config.ts如果连data都没传则会回退到从 jsdelivr 按emojiVersion与set动态拉取对应的数据集文件。数据初始化背后的源码逻辑init()是整条数据链路的枢纽packages/emoji-mart/src/config.ts它返回一个Promise组件在数据就绪前会一直等待若在未调用init前就使用 Emoji 组件或SearchIndex会输出警告requires data to be initialized first. Promise will be pending until init is called数据加载完成后_init会做一系列预计算为Data注入frequent分类、把别名aliases回填到对应 emoji、建立 native 字符与 emoji ID 的映射表、为每个 emoji 生成搜索用的search字符串等packages/emoji-mart/src/config.ts。 Picker 组件React 接入npm install --save emoji-mart emoji-mart/data emoji-mart/reactimport data from emoji-mart/data import Picker from emoji-mart/react function App() { return ( Picker data{data} onEmojiSelect{console.log} / ) }React 封装包 packages/emoji-mart-react/react.tsx 会把 Props 透传给原生组件。浏览器无构建工具接入script srchttps://cdn.jsdelivr.net/npm/emoji-martlatest/dist/browser.js/script script const pickerOptions { onEmojiSelect: console.log } const picker new EmojiMart.Picker(pickerOptions) document.body.appendChild(picker) /scriptdist/browser.js对应 packages/emoji-mart/src/browser.js并以全局对象EmojiMart暴露 API。注意这里 Picker 实例其实是自定义元素em-emoji-picker见 PickerElement.tsx 的customElements.define(em-emoji-picker, ...)所以可直接appendChild到文档中。Options / Props 全表含源码级默认值下表完整继承自 README并与 packages/emoji-mart/src/components/Picker/PickerProps.ts 中的默认实现逐项核对Option默认值可选值说明data{}Picker 使用的 emoji 数据集i18n{}Picker 使用的本地化数据categories[]frequent,people,nature,foods,activity,places,objects,symbols,flags在 Picker 中展示的分类顺序会被尊重按传入顺序排序见 config.tscustom[]自定义 emoji见下文onEmojiSelectnullemoji 被选中时的回调onClickOutsidenull点击 Picker 外部时的回调onAddCustomEmojinull点击Add custom emoji按钮时的回调。只有提供了该回调按钮才会显示当搜索无结果时出现autoFocusfalse是否自动聚焦搜索输入框categoryIcons{}自定义分类图标见下文dynamicWidthfalse是否根据em-emoji-picker的宽度动态计算perLine开启后perLine被忽略。源码实现通过ResizeObserver监听元素宽度并重算perLine见 Picker.tsxemojiButtonColors[]如#f00、pink、rgba(155,223,88,.7)影响 hover 背景色的颜色数组按按钮位置循环取色见 Picker.tsxemojiButtonRadius100%如6px、1em、100%emoji 按钮的圆角emojiButtonSize36emoji 按钮的尺寸像素emojiSize24emoji 本身按钮内部的尺寸emojiVersion14源码默认 151,2,3,4,5,11,12,12.1,13,13.1,14,15使用的 emoji 数据版本exceptEmojis[]从 Picker 中排除的 emoji ID 列表在_init中逐条剔除见 config.tsiconsautoauto,outline,solidPicker 使用的图标类型浅色主题配outline深色主题配solidlocaleenen,ar,be,cs,de,es,fa,fi,fr,hi,it,ja,ko,nl,pl,pt,ru,sa,tr,uk,vi,zhPicker 使用的语言maxFrequentRows4最多显示几行常用分类0表示禁用常用分类navPositiontoptop,bottom,none导航栏的位置noCountryFlagsfalse是否显示国旗。未提供时自动处理Windows 不支持国旗noResultsEmojicry搜索无结果时使用的 emoji IDperLine9每行显示几个 emojipreviewEmojipoint_up未悬停任何 emoji 时预览区使用的 emoji ID预览在底部时用point_up预览在顶部时用point_downpreviewPositionbottomtop,bottom,none预览区的位置searchPositionstickysticky,static,none搜索输入框的位置setnativenative,apple,facebook,google,twitter使用的 emoji 表情风格。native性能最好直接渲染系统字符其余依赖雪碧图spritesheetskin11,2,3,4,5,6emoji 肤色skinTonePositionpreviewpreview,search,none肤色选择器的位置themeautoauto,light,darkPicker 的配色主题。auto会跟随prefers-color-scheme见 Picker.tsxgetSpritesheetURLnull返回雪碧图 URL 的函数需与所提供数据兼容版本差异提示README 中emojiVersion默认写为14而当前仓库源码 PickerProps.ts 已将默认值升级为15可选值列表中也包含15packages/emoji-mart-data/sets目录下确实包含15/数据集。以仓库实际代码为准。关于默认值的源码细节getPropconfig.ts会从 DOM attribute、传入 props 中取值当值为字符串且与默认类型不符时自动做类型转换布尔值false视为false当值不在choices白名单内时回退到默认值——这也是为什么上表所有枚举型选项都配了choices数组。Custom emojis自定义表情可以传入一个数组每个元素是一个分类category及其 emoji 列表。自定义 emoji 支持多肤色也支持 GIF 或 SVG。import data from emoji-mart/data import Picker from emoji-mart/react const custom [ { id: github, name: GitHub, emojis: [ { id: octocat, name: Octocat, keywords: [github], skins: [{ src: ./octocat.png }], }, { id: shipit, name: Squirrel, keywords: [github], skins: [ { src: ./shipit-1.png }, { src: ./shipit-2.png }, { src: ./shipit-3.png }, { src: ./shipit-4.png }, { src: ./shipit-5.png }, { src: ./shipit-6.png }, ], }, ], }, { id: gifs, name: GIFs, emojis: [ { id: party_parrot, name: Party Parrot, keywords: [dance, dancing], skins: [{ src: ./party_parrot.gif }], }, ], }, ] function App() { return ( Picker data{data} custom{custom} / ) }源码侧行为补充_init在处理props.custom时会为没有id的分类自动生成custom_${i 1}形式的 ID、把无name的分类名称设为国际化键I18n.categories.custom并把每个自定义 emoji 直接写入Data.emojis[emoji.id]见 config.ts。仓库网站资源里恰好有示例使用的 octocat.png 与 shipit.png 等素材。Custom category icons自定义分类图标通过一个以分类名为 key、图标为 value 的对象来覆盖分类图标。目前支持svg字符串与src两种格式对应仓库演示页 example-categories.htmlconst customCategoryIcons { categoryIcons: { activity: { svg: svg xmlnshttp://www.w3.org/2000/svg viewBox0 0 640 512path dM57.89 397.2c-6.262-8.616-16.02-13.19-25.92-13.19c-23.33 0-31.98 20.68-31.98 32.03c0 6.522 1.987 13.1 6.115 18.78l46.52 64C58.89 507.4 68.64 512 78.55 512c23.29 0 31.97-20.66 31.97-32.03c0-6.522-1.988-13.1-6.115-18.78L57.89 397.2zM496.1 352c-44.13 0-79.72 35.75-79.72 80s35.59 80 79.72 80s79.91-35.75 79.91-80S540.2 352 496.1 352zM640 99.38c0-13.61-4.133-27.34-12.72-39.2l-23.63-32.5c-13.44-18.5-33.77-27.68-54.12-27.68c-13.89 0-27.79 4.281-39.51 12.8L307.8 159.7C262.2 192.8 220.4 230.9 183.4 273.4c-24.22 27.88-59.18 63.99-103.5 99.63l56.34 77.52c53.79-35.39 99.15-55.3 127.1-67.27c51.88-22 101.3-49.87 146.9-82.1l202.3-146.7C630.5 140.4 640 120 640 99.38z//svg, }, people: { src: ./people.png, }, }, }在_init中categoryIcons会被应用到对应分类上仅当分类自身没有 icon 时生效见 config.ts。 Emoji 组件em-emojiEmoji Web Component 的用法与前端框架无关。首先确保数据已初始化——每个页面加载只需调用一次。注意如果像这样调用了initPicker 的 props 里可以不再传data传了也无妨会被去重noop。import data from emoji-mart/data import { init } from emoji-mart init({ data })之后就可以在 HTML / JSX 中使用em-emoji id1 size2em/em-emoji em-emoji id1 skin2/em-emoji em-emoji shortcodes:1::skin-tone-1:/em-emoji em-emoji shortcodes:1::skin-tone-2:/em-emoji组件注册位于 EmojiElement.jsx 的customElements.define(em-emoji, ...)。渲染时组件会先await init()等待数据就绪再通过 preact 渲染内部 UI仓库本体用 preact 实现见 package.json 的 devDependencies 与alias配置。Attributes / Props 表Attribute示例说明id1emoji IDshortcodes:1::skin-tone-2:emoji 短代码native原生 emoji 字符size2em行内元素尺寸fallback:shrug:找不到 emoji 时渲染的字符串setnativeemoji 风格native,apple,facebook,google,twitterskin1肤色1–6渲染实现说明见 Emoji.tsxshortcodes属性会先通过SearchIndex.SHORTCODES_REGEX/^(?:\:([^\:])\:)(?:\:skin-tone-(\d)\:)?$/见 search-index.ts解析出 emoji ID 与可选肤色再按优先级取图片优先emojiSkin.src→ 非 native 且未用 spritesheet 时走getImageURL或 CDN 图片 → native 时直接渲染系统 emoji 字符 → 其余用雪碧图backgroundPosition由数据中的x/y坐标计算。size若传入纯数字会被自动追加px见 EmojiProps.ts。️ Headless 搜索不要 UI 也能搜可以脱离 Picker 直接使用搜索。和 Emoji 组件一样使用搜索索引前必须先初始化data。import data from emoji-mart/data import { init, SearchIndex } from emoji-mart init({ data }) async function search(value) { const emojis await SearchIndex.search(value) const results emojis.map((emoji) { return emoji.skins[0].native }) console.log(results) } search(christmas) // [, , ‍, , , , ☃️, ❄️, , ⛄]搜索算法剖析见 search-index.ts查询词会被toLowerCase()后按空格/逗号拆分、去重每个 emoji 的search字段是_init阶段预生成的逗号分隔字符串由 id、name、keywords、emoticons、native 字符拼成见 config.ts逐词过滤时用emoji.search.indexOf(,${value})计算匹配得分得分越低越靠前ID 完全命中得 0 分多词用交集过滤pool 不断收窄结果超过maxResults默认 90时截断少于 2 条时直接返回SearchIndex.get(emojiId)负责把 ID / 别名 / native 字符解析成 emoji 对象见 search-index.ts。仓库测试 packages/emoji-mart/src/helpers/tests/search-index.test.js 覆盖了多词搜索、别名解析等行为可作为进一步参考。 从原生 emoji 反查数据getEmojiDataFromNative可以把一个原生 emoji 字符反查为完整的 emoji 数据例如拿到 emoji ID。与 Emoji 组件相同使用前需先init初始化数据。import data from emoji-mart/data import { init, getEmojiDataFromNative } from emoji-mart init({ data }) getEmojiDataFromNative().then(console.log) /* { aliases: [hand_with_index_and_middle_fingers_crossed], id: crossed_fingers, keywords: [hand, with, index, and, middle, good, lucky], name: Crossed Fingers, native: , shortcodes: :crossed_fingers::skin-tone-6:, skin: 6, unified: 1f91e-1f3ff, } */实现原理见 utils.ts该函数内部实际调用SearchIndex.search(nativeString, { maxResults: 1, caller: getEmojiDataFromNative })反查 emoji再遍历其skins定位与输入 native 完全匹配的那一个皮肤索引最后用getEmojiData组装成完整数据对象getEmojiData见 utils.ts。 国际化Internationalizationemoji-mart 的 UI 支持多语言完整语言包位于 packages/emoji-mart-data/i18n含ar, be, cs, de, en, es, fa, fi, fr, hi, it, ja, ko, nl, pl, pt, ru, sa, tr, uk, vi, zh。若缺少你的语言可以提交 PR 补充。import i18n from emoji-mart/data/i18n/fr.json i18n.search_no_results_1 Aucun emoji new Picker({ i18n })由于英文语言包体积很小英文是内置的无需传入源码中locale en时直接使用内置的i18n_en见 config.ts。非英文场景若未提供i18n_init会从 CDN 拉取对应 locale 的语言文件。 仓库内示例页仓库自带 6 个可独立打开的示例页面位于 packages/emoji-mart-websiteexample-categories.html自定义分类图标example-custom-font.html自定义 emoji 字体example-custom-styles.html自定义样式对应 styles.scssexample-emoji-component.htmlEmoji 组件用法example-headless-search.htmlHeadless 搜索example-slack-colors.htmlSlack 配色风格 浏览器兼容性要求emoji-mart 面向现代浏览器依赖以下 Web API如需支持旧浏览器需自行引入 polyfillShadow DOMCustom elementsem-emoji与em-emoji-picker的自定义元素机制IntersectionObserver 的Performance.rowsPerRender与 observeRowsAsync/Await数据初始化与搜索均依赖异步流程。另外dynamicWidth依赖ResizeObserverPicker.tsxtheme: auto依赖matchMedia((prefers-color-scheme: dark))Picker.tsx旧环境同样需要注意。 本地开发仓库根目录使用 yarn 管理启动开发环境yarn install yarn dev组件库构建走 Parcel见 packages/emoji-mart/package.json 的build: parcel build --no-autoinstall会产出dist/main.jsCommonJS、dist/module.jsESM与dist/browser.js浏览器全局版三个入口。单元测试位于各包的src/__tests__与src/helpers/__tests__目录使用 jest见根目录 jest.config.js运行。小结一份可落地的接入清单选择数据加载方式打包 or 远程拉取用init({ data })完成一次性初始化按需选择接入形态React 用emoji-mart/react、无构建工具用dist/browser.js、Web Component 直接用em-emoji-picker通过上文的 Options 全表按场景调参set、skin、theme、perLine、navPosition、previewPosition等用custom与categoryIcons扩展品牌内容在任意框架中用em-emoji渲染单个表情或用SearchIndex.search/getEmojiDataFromNative实现无 UI 的检索与反查针对旧浏览器补齐 Shadow DOM、Custom elements、IntersectionObserver、Async/Await以及dynamicWidth所需的ResizeObserver的 polyfill。赞分享前端UI组件【免费下载链接】emoji-mart One component to pick them all项目地址https://gitcode.com/gh_mirrors/em/emoji-mart点击查看免费下载相关推荐如何快速掌握Emoji Mart核心组件Picker与EmojiElement实现原理全解析如何快速掌握Emoji Mart核心组件Picker与EmojiElement实现原理全解析 Emoji Mart是一个功能强大的可定制化网页表情选择器组件前端UI组件Hexo主题Matery插件集成终极指南搜索、RSS、emoji等完整配置Hexo主题Matery插件集成终极指南搜索、RSS、emoji等完整配置 Hexo主题Matery是一个基于Material Design设计的响应式博客主前端MouseFlight高级技巧如何自定义飞机操控灵敏度与响应曲线MouseFlight高级技巧如何自定义飞机操控灵敏度与响应曲线 MouseFlight是一款为飞行模拟游戏打造的开源鼠标操控系统提供类似War Thund数据分析数据工程机器学习上一篇终极指南如何在欧洲卡车模拟2中实现智能车道保持辅助驾驶下一篇如何为Windows 11 LTSC企业版安装微软商店3分钟完整解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考