Skip to content
u-sbPublic
forked from DejavuMoe/Smoji

About

Social emoji for mastodon, pleroma, misskey...

Resources

Stars

0 stars

Watchers

0 watching

Forks

 
 

Repository files navigation

Smoji

现代化开源表情库、配置管理工作台与轻量 Web 表情选择器

在线体验 · 源代码 · 问题反馈 · JSON Schema 规范

MIT License TypeScript Zero Dependencies Core Bundle Size Node.js 24+ pnpm


Smoji 是一套现代化开源图片表情解决方案,由两大部分组成:

  1. 表情库与工作台(Web App):面向博主与个人用户,在浏览器中自由浏览高清静态/动态表情、灵活管理自选分组、实时预览多格式数据,一键导出 Artalk、Twikoo、OwO、Ecoku 等主流博客评论系统的配置文件。
  2. 轻量表情选择器(Picker Core SDK):面向前端开发者,采用原生 TypeScript 编写、零运行时依赖(无 React / Vue 绑定)、核心压缩体积小于 1.6 KB (Gzip) 的 Web 表情选择器组件与严格防注入渲染器。

✨ 核心特性

🎨 现代化表情工作台 (Workbench)

  • 双导出模式:
    • 整包导出:一键全选、反选或按分类剔除不需要的表情包。
    • 自选分组:自由创建最多 32 个自定义分组,支持跨组拖拽投放、调序与精准筛选。
  • 优异的浏览与预览体验:缩略图列表极大节省加载流量;详情弹窗支持原图与动图播放,提供透明棋盘格、浅色纯白、深色纯黑 3 种背景预览模式。
  • 多格式快捷复制:内置复制控制台,一键复制 Markdown(![smoji:标签](url))、绝对图片 URL、HTML 标签与 BBCode。
  • 数据实时预览与下载:支持按当前分类、已勾选项目或全部表情范围实时预览导出代码,并支持一键下载。
  • 隐私保护与本地持久化:无需注册任何账号,自选分组、勾选状态、主题与视图密度均自动持久化在浏览器本地(localStorage),支持分组配置的 JSON 导入与导出备份。
  • 全键盘与无障碍支持 (A11y):严格遵循 WAI-ARIA 规范,支持键盘方向键无缝漫游、焦点捕获与丰富快捷键。

⚡ 原生极简表情选择器 (packages/smoji)

  • 零运行时依赖:原生纯 JavaScript / TypeScript 编写,完全与框架无关。
  • 极致羽量级体积:
    • Core JS: 压缩后 ~3 KB (Gzip ~1.5 KB)
    • Core CSS: 压缩后 ~1.9 KB (Gzip ~800 B)
  • 智能定位算法:结合 visualViewport 与边界碰撞检测,在复杂移动端和滚动页面中精准浮层定位,不越界、不溢出。
  • 开箱即用输入适配:提供 textTarget 绑定助手,支持光标位置插入、InputEvent 派发与自动失焦恢复。

🛡️ 安全规范与持久化设计

  • 严格防注入 (Zero XSS):富文本渲染器纯 DOM 节点组装,绝不使用 innerHTML,强制校验图片同源性与 URL 协议,杜绝恶意脚本注入。
  • 契约规范化:提供标准的单文件清单契约 smoji.json(遵循 JSON Schema),单清单最多 64 个分组、单组最多 600 项、清单体积限制 ≤ 1024 KB。
  • 历史内容永续性:导出 Markdown 均使用绝对图片链接,未来图库分类调整或个别下架不会破坏历史博客评论的正常渲染。

📦 支持的导出格式

工作台支持一键将挑选的表情导出为各主流博客评论系统与文档格式:

平台 / 格式 导出文件名 适用系统 / 使用场景
Smoji v1 smoji.json Ecoku 原生评论系统、Smoji Picker 官方核心库
Artalk artalk.json Artalk 自托管评论系统 (v2+)
Twikoo twikoo.json Twikoo 无服务器评论系统
OwO OwO.json Valine、Waline 及各类兼容 OwO 格式的独立博客系统
Markdown 剪贴板 / 单项复制 支持 Markdown 语法的博客文章、即时通讯工具
URL / HTML / BBCode 剪贴板复制 Discuz、各大论坛、富文本编辑器与网页嵌入

Note

导出的配置文件需导入到对应评论系统的后台或放置在静态服务中引用。工作台中的「Ecoku 响应示例」用于展示接口数据,非后台导入文件。


🚀 核心选择器接入指南

packages/smoji 提供独立的轻量级表情选择器,可直接用于任何网页或前端项目。

1. 基础用法 (Vanilla JS / TS)

import { createSmoji, textTarget } from 'smoji'
import { smojiMarker } from 'smoji/marker'
import 'smoji/style.css'

// 绑定触发按钮与输入框
const triggerBtn = document.querySelector('#emoji-btn')
const textarea = document.querySelector('#comment-textarea')

const picker = createSmoji({
  trigger: triggerBtn,
  target: textTarget(textarea, { serialize: smojiMarker }),
  packs: [
    {
      id: 'default',
      label: '默认表情',
      items: [
        { id: 'smile', label: '微笑', src: 'https://s3-cdn.zsh.moe/smoji/smile.webp' },
        { id: 'thumbsup', label: '点赞', src: 'https://s3-cdn.zsh.moe/smoji/thumbsup.webp' },
      ],
    },
  ],
  closeOnSelect: true,
  onSelect: (item, pack) => {
    console.log(`选择了 ${pack.label} 中的 ${item.label}`)
  },
})

// 编程式控制 API
// picker.open()
// picker.close()
// picker.toggle()
// picker.destroy()

2. 安全加载远程清单

import { loadSmojiManifest } from 'smoji/manifest'

// 内置体积限制检查(<= 1MB)、Content-Type 校验与超时控制
const manifest = await loadSmojiManifest('https://s3-cdn.zsh.moe/smoji/smoji.json', {
  timeoutMs: 8000,
})

console.log(manifest.packs)

3. 安全渲染评论内容 (Zero XSS)

import { renderSmojiContent } from 'smoji/marker'

const container = document.querySelector('#comment-content')
const rawComment = '今天天气真好!![smoji:微笑](https://s3-cdn.zsh.moe/smoji/smile.webp)'
const manifestUrl = 'https://s3-cdn.zsh.moe/smoji/smoji.json'

// 仅同源图片会转为安全的 <img> 元素,其他内容均为纯文本,绝不调用 innerHTML
renderSmojiContent(container, rawComment, manifestUrl)

⌨️ 快捷键一览

快捷键 作用场景 说明
Ctrl / ⌘ + 1 / 2 全局 切换「整包导出」与「自选分组」模式
Ctrl / ⌘ + E 全局 触发底部 Dock 导出当前配置
Ctrl / ⌘ + . 全局 聚焦底部导出格式选择框
Ctrl / ⌘ + Shift + P 全局 打开实时数据预览弹窗
Ctrl / ⌘ + D 全局 切换图库显示密度(紧凑 / 舒适)
Ctrl / ⌘ + Z 全局 撤销最近的移出、删除或清空分组操作
↑ ↓ ← → 表情网格 网格内键盘方向移动
Enter / Space 表情网格 打开当前选中表情详情弹窗
← / → 详情弹窗 切换上一个 / 下一个表情
1 ~ 4 详情弹窗 快速切换复制格式(Markdown / URL / HTML / BBCode)
Esc 弹窗 / 浮层 关闭当前弹窗或选择器
Alt + ↑ / ↓ 自选分组 列表向上 / 向下移动分组
Alt + ← / → 自选分组 托盘内表情调序(首尾可跨组)
? 全局 打开接入与规范说明指南

🛠️ 本地开发

环境要求

  • Node.js:24.0.0+
  • 包管理器:pnpm 11.24.0+
  • 系统工具:支持 WebP 的 ImageMagick 7(magick 命令可用)

快速开始

# 克隆仓库
git clone https://github.com/DejavuMoe/Smoji.git
cd Smoji

# 安装依赖
pnpm install --frozen-lockfile

# 启动本地开发工作台 (基于 Vite 开发服务器)
pnpm dev

常用命令

pnpm check         # 全面检查:类型检查、测试、完整构建与体积预算校验
pnpm typecheck     # 运行 TypeScript 类型检查
pnpm test          # 运行 Vitest 单元与集成测试
pnpm build         # 构建核心选择器与工作台静态网站
pnpm build:core    # 仅构建 packages/smoji
pnpm build:demo    # 仅构建 demo 网站,使用已提交的缩略图
pnpm generate:previews # 提交前手动生成缩略图与 data/previews.json
pnpm check:size    # 校验核心库与样式体积预算限制

构建产物输出:

  • 网站应用:demo/dist/
  • 表情选择器:packages/smoji/dist/

🗂️ 目录结构

Smoji/
├── packages/
│   └── smoji/               # 轻量原生表情选择器核心库 (Zero Runtime Dependency)
│       ├── src/             # 选择器源码 (picker, manifest, marker, types 等)
│       ├── data.schema.json # Smoji v1 单文件清单 JSON Schema 规范
│       └── test/            # 核心库契约与无障碍测试
├── demo/                    # Smoji 在线工作台前端应用 (Vite)
│   ├── src/                 # 工作台交互、导出适配器、状态管理与持久化
│   ├── public/              # 静态资源与缩略图目录 (_previews)
│   └── index.html           # 工作台主入口界面
├── data/                    # 图库元数据、S3 CDN 映射与有效索引
│   ├── hosting.json         # 远程原图 CDN 基地址配置
│   ├── packs.json           # 扫描后的表情包结构数据
│   └── smoji.json           # 最终发布的清单文件
└── scripts/                 # 自动化脚本 (生成清单、生成缩略图、体积检查、发布部署)

🖼️ 图库维护与资产更新

表情原图托管于对象存储 CDN(由 data/hosting.json 配置,当前默认指向 https://s3-cdn.zsh.moe/smoji/)。data/ 目录保存有分类、标签与哈希索引,需随代码版本提交。

本地素材更新流程:

百度贴吧收录 89 张 90×90 WebP(已移除立体小黄人系列),托管于 CDN 的 tieba/ 目录,来自 Tieba_mobile_emotions(贴吧 Android 11.6.8.2 提取版)。本地 pnpm dev 优先读取原图;生产构建使用 CDN 地址,上传时保留 tieba/ 目录与文件名。

  1. 准备素材:在本地 packs/ 目录(已由 .gitignore 忽略)下创建包名子目录(仅允许小写字母与连字符,如 packs/my-pack/),将规范命名的表情放入该目录。
  2. 生成清单与缩略图:
    pnpm generate:packs     # 扫描素材,更新 data/ 中的清单与哈希索引
    pnpm generate:previews  # 采用 ImageMagick 生成优化后的 WebP 缩略图
  3. 上传云端与核对:将本地原图同步上传至 S3 存储桶的对应路径,验证无误后可删除本地原图;本地手动生成缩略图时,如缺少原图,生成器会从 S3 下载对应文件并核对 SHA-256。
  4. 提交前生成并保存:执行上述生成命令,将 data/ 与 demo/public/_previews/ 一起提交。pnpm dev、网站构建和 CI 直接使用这些缩略图,不再自动生成全量缩略图。
  5. 下架表情包:保留同名的空文件夹并重新运行 pnpm generate:packs 即可安全下架,不会破坏既有历史别名。

🌐 静态站点托管

执行 pnpm build:demo 后,将 demo/dist/ 完整发布到静态站点根目录。HTML 和 smoji.json 应使用 Cache-Control: no-cache,使客户端在复用缓存前重新验证;assets/ 和 _previews/ 内的文件名包含哈希,可长期缓存。

Nginx 示例(map 放在 http 上下文;域名、证书和根目录按环境配置):

map $uri $smoji_cache_control {
    default                 "no-cache";
    ~^/(assets|_previews)/   "public, max-age=31536000, immutable";
}

server {
    listen 443 ssl;
    http2 on;
    server_name example.com;
    ssl_certificate /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;
    root /path/to/site;
    index index.html;

    expires off;
    add_header Cache-Control $smoji_cache_control;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;

    location ~ /\. {
        return 404;
    }
    location /assets/ {
        try_files $uri =404;
    }
    location /_previews/ {
        try_files $uri =404;
    }
    location / {
        try_files $uri $uri/ =404;
    }
}

add_header 统一设置在 server 层,避免在 location 中添加缓存头时丢失上层安全响应头。无需同时设置 expires 1y,否则会重复生成 Cache-Control。更新站点时应保留旧哈希资源,避免已打开页面加载旧分块失败。


📄 许可证与版权说明

  • 代码许可:本项目源码基于 MIT License 开源。
  • 字体许可:界面内嵌的 IBM Plex 字体遵循 SIL Open Font License。
  • 素材免责声明:Smoji 收集并索引的各表情包知识产权与版权均归各自原作者或合法权利人所有,仅供个人交流与展示使用。如需商用请联系相应权利人。

About

Social emoji for mastodon, pleroma, misskey...

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages