wechat-emojis 1.0.2 → 2.0.0

package/README.md

@@ -1,6 +1,62 @@
 # 微信表情包
 
-完整的微信内置表情资源库，包含 109 个高清 PNG 图片和类型安全的 TypeScript API。
+完整的微信内置表情资源库，包含 109 个 100×100 PNG 图片和类型安全的 TypeScript API，全部图片合计 690.3 KB。
+
+## 在线浏览
+
+[https://xxk8.github.io/wechat-emojis/](https://xxk8.github.io/wechat-emojis/)
+
+网站是纯静态的：`index.html` 由 `site/index.template.html`、`site/app.ts` 和 `src/index.ts` 生成，表情图片直接复用 `assets/`。视觉与交互规范记录在仓库的 `design.md`。
+
+```bash
+npm run build:site   # 重新生成 index.html（含内联的页面脚本）
+npm run check:site   # 校验表情数量、资源引用和页面结构
+```
+
+修改表情映射或 `site/` 下的模板、样式、脚本后，重新运行 `build:site` 并提交 `index.html`。GitHub Pages 直接从 `main` 分支根目录发布，不需要构建流水线。
+
+### 全部源码为 TypeScript
+
+仓库里没有手写的 `.js` / `.mjs`：`src/`、`scripts/`、`site/app.ts` 都是 TypeScript。脚本由 Node 的类型剥离直接运行，不产出中间文件；页面脚本由构建时用 esbuild 编译并内联进 `index.html`，所以站点没有额外的 JS 请求。
+
+运行脚本需要 **Node.js ≥ 22.6**（类型剥离）；已发布的 npm 包本身仍支持 Node 14+，因为消费者只用 `dist/` 与 PNG。
+
+```bash
+npm run typecheck:scripts   # 校验 scripts/ 与 site/app.ts 的类型
+```
+
+迁移细节与取舍记录在仓库的 `docs/TYPESCRIPT.md`。
+
+### npm 包里装的是什么
+
+只装运行时需要的东西，网站源码不随包发布：
+
+| 内容 | 路径 |
+| --- | --- |
+| 运行时 | `dist/index.js`、`dist/index.d.ts` |
+| 表情资源 | `assets/**/*.png`（109 张） |
+| 使用文档 | `docs/API.md`、`docs/NPM_USAGE.md`、`docs/REACT_USAGE.md` |
+| 包说明 | `README.md`、`package.json` |
+
+**不会**包含 `site/`、`scripts/`、`src/`、`examples/`、`index.html`、`design.md`、`docs/TYPESCRIPT.md`、`tsconfig*`、`.github/`。白名单在 `package.json` 的 `files` 字段，已显式列到单个文件而不是通配目录。
+
+```bash
+npm run check:package   # 实际跑 npm pack，断言包内没有开发文件与死链
+```
+
+#### 从本地目录安装时的注意
+
+`files` 字段只作用于 `npm pack` / `publish`。如果直接 `npm install ../wechat-emojis` 指向本地仓库，npm 会以**软链接**把整个仓库接进项目（包括 `site/`、`scripts/`、`index.html`）。这是 npm 对本地路径的固有行为。
+
+要拿到与发布版一致的内容：
+
+```bash
+npm install ../wechat-emojis --install-links   # 按 files 白名单打包后安装
+# 或者先打包再装
+npm pack ../wechat-emojis && npm install ./wechat-emojis-2.0.0.tgz
+```
+
+从 npm registry 或 Git 地址安装不受此影响，实际内容仍是上表那 116 个文件。
 
 ## 功能特性
 
@@ -9,7 +65,7 @@
 - 🚀 **即插即用** - 支持 React、Vue、Angular 等主流框架
 - 📦 **多种导入方式** - ES6 模块、CommonJS、直接文件引用
 - 🔍 **强大 API** - 搜索、分类、随机获取等功能
-- 📱 **高质量图片** - PNG 格式，适合各种显示场景
+- 📱 **统一尺寸** - 全部 PNG 都是 100×100 透明背景，整套 690.3 KB
 - 📚 **详细文档** - 完整 API 文档和使用示例
 
 ## 快速开始
@@ -34,7 +90,7 @@ cp -r node_modules/wechat-emojis/assets/* public/assets/
 import { getEmojiPath, getEmojisByCategory, EmojiCategory, searchEmojis } from 'wechat-emojis';
 
 // 或者从本地导入
-// import { getEmojiPath, getEmojisByCategory, EmojiCategory, searchEmojis } from './wechatEmoji';
+// import { getEmojiPath, getEmojisByCategory, EmojiCategory, searchEmojis } from './src';
 
 // 获取单个表情
 const smilePath = getEmojiPath('微笑');  // 'assets/face/微笑.png'
@@ -50,18 +106,22 @@ const laughEmojis = searchEmojis('笑');  // 包含"笑"的所有表情
 
 ```text
 wechat-emojis/
+├── index.html          # GitHub Pages 站点（由 scripts/build-site.ts 生成）
+├── design.md           # 站点设计规范与检查清单
+├── site/               # 站点模板、品牌样式、页面样式与 app.ts
+├── src/
+│   └── index.ts        # TypeScript API模块（源码）
+├── dist/               # 构建产物（npm run build 生成，含 index.js 和 index.d.ts）
 ├── assets/             # 表情图片资源 (109个PNG文件)
 │   ├── face/          # 人脸表情 (75个)
 │   ├── gesture/       # 手势表情 (10个)
 │   ├── animal/        # 动物表情 (4个)
 │   ├── blessing/      # 祝福表情 (7个)
 │   └── other/         # 其他表情 (13个)
-├── wechatEmoji.ts     # TypeScript API模块
-├── wechatEmoji.js     # 编译后的JavaScript文件
-├── data.js            # 基础数据文件
-├── example.ts         # 使用示例
-├── API.md             # 详细API文档
-└── tsconfig.json      # TypeScript配置
+├── examples/           # 使用示例（TypeScript 和 React）
+├── docs/               # API.md、REACT_USAGE.md、NPM_USAGE.md
+├── scripts/            # 资源校验、站点生成、站点检查与图片优化脚本（全部 .ts）
+└── tsconfig.json       # TypeScript配置
 ```
 
 ## 使用指南
@@ -189,22 +249,25 @@ interface EmojiInfo {
 
 ## 技术要求
 
-- **TypeScript**: 4.0+ (可选，用于类型检查)
-- **Node.js**: 12+ (用于编译，可选)
+- **TypeScript**: 5.9+（仓库开发需要；使用包时可选用任意 4.0+）
+- **Node.js**: 消费者 14+；运行本仓库的脚本需要 22.6+（类型剥离）
 - **浏览器**: 支持 ES2017+ 的现代浏览器
 - **框架**: React 16+, Vue 3+, Angular 12+ 或原生 JavaScript
 
 ## 编译和构建
 
 ```bash
-# 编译 TypeScript
-npx tsc wechatEmoji.ts --target es2017 --module commonjs
+# 编译到 dist/（同时生成 index.d.ts）
+npm run build
+
+# 仅做类型检查
+npm run typecheck
 
-# 或使用配置文件
-npx tsc
+# 构建、类型检查、校验 assets 与表情映射，并检查发布包内容
+npm test
 
-# 生成类型声明文件
-npx tsc --declaration
+# 重新生成静态站点并校验
+npm run build:site && npm run check:site
 ```
 
 ## 常见问题
@@ -246,6 +309,6 @@ const customPath = getEmojiPath('微笑')?.replace('assets/', 'my-assets/');
 # 请我喝杯茶 | buy me a cup of tea
 
 <div style="display: flex; justify-content: center; gap: 20px;">
-  <img src="public/images/alipay.png" alt="支付宝" width="300" />
-  <img src="public/images/wechat.png" alt="微信" width="300" />
+  <img src="docs/images/alipay.png" alt="支付宝" width="300" />
+  <img src="docs/images/wechat.png" alt="微信" width="300" />
 </div>

package/dist/index.d.ts

@@ -0,0 +1,162 @@
+/**
+ * 微信表情包 TypeScript 模块
+ * 提供类型安全的表情访问和图片路径获取功能
+ */
+/**
+ * 表情类别枚举
+ */
+export declare enum EmojiCategory {
+    /** 人脸表情 */
+    FACE = "face",
+    /** 手势表情 */
+    GESTURE = "gesture",
+    /** 动物表情 */
+    ANIMAL = "animal",
+    /** 祝福表情 */
+    BLESSING = "blessing",
+    /** 其他表情 */
+    OTHER = "other"
+}
+/**
+ * 表情信息接口
+ */
+export interface EmojiInfo {
+    /** 表情名称 */
+    name: string;
+    /** 表情类别 */
+    category: EmojiCategory;
+    /** 图片文件路径 */
+    path: string;
+    /** 英文名称（可选） */
+    englishName?: string;
+}
+/**
+ * 表情名称类型
+ */
+export type EmojiName = '微笑' | '撇嘴' | '色' | '发呆' | '得意' | '流泪' | '害羞' | '闭嘴' | '睡' | '大哭' | '尴尬' | '发怒' | '调皮' | '呲牙' | '惊讶' | '难过' | '囧' | '抓狂' | '吐' | '偷笑' | '愉快' | '白眼' | '傲慢' | '困' | '惊恐' | '憨笑' | '悠闲' | '咒骂' | '疑问' | '嘘' | '晕' | '衰' | '骷髅' | '敲打' | '再见' | '擦汗' | '抠鼻' | '鼓掌' | '坏笑' | '右哼哼' | '鄙视' | '委屈' | '快哭了' | '阴险' | '亲亲' | '可怜' | '笑脸' | '生病' | '脸红' | '破涕为笑' | '恐惧' | '失望' | '无语' | '嘿哈' | '捂脸' | '机智' | '皱眉' | '耶' | '吃瓜' | '加油' | '汗' | '天啊' | 'Emm' | '社会社会' | '旺柴' | '好的' | '打脸' | '哇' | '翻白眼' | '666' | '让我看看' | '叹气' | '苦涩' | '裂开' | '奸笑' | '握手' | '胜利' | '抱拳' | '勾引' | '拳头' | 'OK' | '合十' | '强' | '拥抱' | '弱' | '猪头' | '跳跳' | '发抖' | '转圈' | '庆祝' | '礼物' | '红包' | '發' | '福' | '烟花' | '爆竹' | '嘴唇' | '爱心' | '心碎' | '啤酒' | '咖啡' | '蛋糕' | '凋谢' | '菜刀' | '炸弹' | '便便' | '太阳' | '月亮' | '玫瑰';
+/**
+ * 按类别分组的表情数据
+ */
+export declare const EMOJI_CATEGORIES: {
+    readonly face: EmojiInfo[];
+    readonly gesture: EmojiInfo[];
+    readonly animal: EmojiInfo[];
+    readonly blessing: EmojiInfo[];
+    readonly other: EmojiInfo[];
+};
+/**
+ * 获取表情图片路径
+ * @param name 表情名称
+ * @returns 图片路径，如果表情不存在则返回 null
+ *
+ * @example
+ * ```typescript
+ * const path = getEmojiPath('微笑'); // 'assets/face/微笑.png'
+ * const invalidPath = getEmojiPath('不存在'); // null
+ * ```
+ */
+export declare function getEmojiPath(name: EmojiName): string | null;
+/**
+ * 获取表情信息
+ * @param name 表情名称
+ * @returns 表情信息对象，如果表情不存在则返回 null
+ *
+ * @example
+ * ```typescript
+ * const emoji = getEmojiInfo('微笑');
+ * // { name: '微笑', category: EmojiCategory.FACE, path: 'assets/face/微笑.png' }
+ * ```
+ */
+export declare function getEmojiInfo(name: EmojiName): EmojiInfo | null;
+/**
+ * 根据类别获取表情列表
+ * @param category 表情类别
+ * @returns 该类别下的所有表情信息
+ *
+ * @example
+ * ```typescript
+ * const faceEmojis = getEmojisByCategory(EmojiCategory.FACE);
+ * ```
+ */
+export declare function getEmojisByCategory(category: EmojiCategory): EmojiInfo[];
+/**
+ * 获取所有表情信息
+ * @returns 所有表情的信息数组
+ *
+ * @example
+ * ```typescript
+ * const allEmojis = getAllEmojis();
+ * console.log(`总共有 ${allEmojis.length} 个表情`);
+ * ```
+ */
+export declare function getAllEmojis(): EmojiInfo[];
+/**
+ * 搜索表情
+ * @param keyword 搜索关键词
+ * @returns 匹配的表情信息数组
+ *
+ * @example
+ * ```typescript
+ * const results = searchEmojis('笑');
+ * // 返回包含 '微笑', '偷笑', '坏笑' 等的表情
+ * ```
+ */
+export declare function searchEmojis(keyword: string): EmojiInfo[];
+/**
+ * 检查表情是否存在
+ * @param name 表情名称
+ * @returns 是否存在该表情
+ *
+ * @example
+ * ```typescript
+ * const exists = hasEmoji('微笑'); // true
+ * const notExists = hasEmoji('不存在的表情'); // false
+ * ```
+ */
+export declare function hasEmoji(name: EmojiName): boolean;
+/**
+ * 获取表情名称列表
+ * @param category 可选的类别筛选
+ * @returns 表情名称数组
+ *
+ * @example
+ * ```typescript
+ * const allNames = getEmojiNames();
+ * const faceNames = getEmojiNames(EmojiCategory.FACE);
+ * ```
+ */
+export declare function getEmojiNames(category?: EmojiCategory): string[];
+/**
+ * 随机获取表情
+ * @param category 可选的类别筛选
+ * @returns 随机表情信息
+ *
+ * @example
+ * ```typescript
+ * const randomEmoji = getRandomEmoji();
+ * const randomFaceEmoji = getRandomEmoji(EmojiCategory.FACE);
+ * ```
+ */
+export declare function getRandomEmoji(category?: EmojiCategory): EmojiInfo;
+/**
+ * 默认导出对象，包含所有主要功能
+ */
+declare const WeChatEmojis: {
+    readonly EmojiCategory: typeof EmojiCategory;
+    readonly EMOJI_CATEGORIES: {
+        readonly face: EmojiInfo[];
+        readonly gesture: EmojiInfo[];
+        readonly animal: EmojiInfo[];
+        readonly blessing: EmojiInfo[];
+        readonly other: EmojiInfo[];
+    };
+    readonly getEmojiPath: typeof getEmojiPath;
+    readonly getEmojiInfo: typeof getEmojiInfo;
+    readonly getEmojisByCategory: typeof getEmojisByCategory;
+    readonly getAllEmojis: typeof getAllEmojis;
+    readonly searchEmojis: typeof searchEmojis;
+    readonly hasEmoji: typeof hasEmoji;
+    readonly getEmojiNames: typeof getEmojiNames;
+    readonly getRandomEmoji: typeof getRandomEmoji;
+};
+export default WeChatEmojis;

package/{API.md → docs/API.md}

@@ -2,7 +2,7 @@
 
 ## 概述
 
-`wechatEmoji.ts` 提供了完整的 TypeScript 支持，让你可以类型安全地访问微信表情包资源。
+`src/index.ts` 提供了完整的 TypeScript 支持，让你可以类型安全地访问微信表情包资源。
 
 ## 安装和使用
 
@@ -36,17 +36,17 @@ import WeChatEmojis, {
   getEmojiPath,
   getEmojisByCategory,
   searchEmojis
-} from './wechatEmoji';
+} from './src';
 ```
 
 ### 3. 编译后使用 JavaScript
 
 ```bash
 # 编译 TypeScript
-npx tsc wechatEmoji.ts --target es2017 --module commonjs
+npm run build
 
 # 在 Node.js 中使用
-const { getEmojiPath, EmojiCategory } = require('./wechatEmoji.js');
+const { getEmojiPath, EmojiCategory } = require('./dist/index.js');
 ```
 
 ## API 参考