wechat-emojis 1.0.0

package/API.md

@@ -0,0 +1,228 @@
+# 微信表情包 TypeScript API 文档
+
+## 概述
+
+`wechatEmoji.ts` 提供了完整的 TypeScript 支持，让你可以类型安全地访问微信表情包资源。
+
+## 安装和使用
+
+### 1. 通过 NPM 安装（推荐）
+
+```bash
+# 安装包
+npm install wechat-emojis
+
+# 复制表情资源到项目的 public 目录（重要）
+mkdir -p public/assets
+cp -r node_modules/wechat-emojis/assets/* public/assets/
+```
+
+使用 NPM 包：
+
+```typescript
+import WeChatEmojis, {
+  EmojiCategory,
+  getEmojiPath,
+  getEmojisByCategory,
+  searchEmojis
+} from 'wechat-emojis';
+```
+
+### 2. 直接使用 TypeScript 源文件
+
+```typescript
+import WeChatEmojis, {
+  EmojiCategory,
+  getEmojiPath,
+  getEmojisByCategory,
+  searchEmojis
+} from './wechatEmoji';
+```
+
+### 3. 编译后使用 JavaScript
+
+```bash
+# 编译 TypeScript
+npx tsc wechatEmoji.ts --target es2017 --module commonjs
+
+# 在 Node.js 中使用
+const { getEmojiPath, EmojiCategory } = require('./wechatEmoji.js');
+```
+
+## API 参考
+
+### 类型定义
+
+#### `EmojiCategory` 枚举
+
+```typescript
+enum EmojiCategory {
+  FACE = 'face',      // 人脸表情
+  GESTURE = 'gesture', // 手势表情
+  ANIMAL = 'animal',   // 动物表情
+  BLESSING = 'blessing', // 祝福表情
+  OTHER = 'other'      // 其他表情
+}
+```
+
+#### `EmojiInfo` 接口
+
+```typescript
+interface EmojiInfo {
+  name: string;           // 表情名称
+  category: EmojiCategory; // 表情类别
+  path: string;           // 图片文件路径
+  englishName?: string;   // 英文名称（可选）
+}
+```
+
+#### `EmojiName` 类型
+
+包含所有有效表情名称的联合类型，提供编译时类型检查。
+
+### 核心函数
+
+#### `getEmojiPath(name: EmojiName): string | null`
+
+获取表情图片路径。
+
+```typescript
+const path = getEmojiPath('微笑'); // 'assets/face/微笑.png'
+const invalid = getEmojiPath('不存在'); // null
+```
+
+#### `getEmojiInfo(name: EmojiName): EmojiInfo | null`
+
+获取表情详细信息。
+
+```typescript
+const emoji = getEmojiInfo('微笑');
+// { name: '微笑', category: EmojiCategory.FACE, path: 'assets/face/微笑.png' }
+```
+
+#### `getEmojisByCategory(category: EmojiCategory): EmojiInfo[]`
+
+按类别获取表情列表。
+
+```typescript
+const faceEmojis = getEmojisByCategory(EmojiCategory.FACE);
+console.log(`人脸表情数量: ${faceEmojis.length}`); // 75
+```
+
+#### `getAllEmojis(): EmojiInfo[]`
+
+获取所有表情信息。
+
+```typescript
+const allEmojis = getAllEmojis();
+console.log(`总表情数量: ${allEmojis.length}`); // 108
+```
+
+#### `searchEmojis(keyword: string): EmojiInfo[]`
+
+搜索包含关键词的表情。
+
+```typescript
+const laughEmojis = searchEmojis('笑');
+// 返回包含 '微笑', '偷笑', '坏笑' 等的表情
+```
+
+#### `hasEmoji(name: string): name is EmojiName`
+
+检查表情是否存在（类型守卫）。
+
+```typescript
+if (hasEmoji('微笑')) {
+  // TypeScript 知道这里 '微笑' 是有效的 EmojiName
+  const path = getEmojiPath('微笑');
+}
+```
+
+#### `getEmojiNames(category?: EmojiCategory): string[]`
+
+获取表情名称列表。
+
+```typescript
+const allNames = getEmojiNames();
+const faceNames = getEmojiNames(EmojiCategory.FACE);
+```
+
+#### `getRandomEmoji(category?: EmojiCategory): EmojiInfo`
+
+随机获取表情。
+
+```typescript
+const randomEmoji = getRandomEmoji();
+const randomFaceEmoji = getRandomEmoji(EmojiCategory.FACE);
+```
+
+## 使用示例
+
+### React 组件示例
+
+```typescript
+import React from 'react';
+import { getEmojiPath, getEmojisByCategory, EmojiCategory } from 'wechat-emojis';
+
+const EmojiPicker: React.FC = () => {
+  const faceEmojis = getEmojisByCategory(EmojiCategory.FACE);
+
+  return (
+    <div className="emoji-picker">
+      {faceEmojis.map(emoji => (
+        <img
+          key={emoji.name}
+          src={getEmojiPath(emoji.name)}
+          alt={emoji.name}
+          title={emoji.name}
+          className="emoji-item"
+          onClick={() => console.log(`选择了: ${emoji.name}`)}
+        />
+      ))}
+    </div>
+  );
+};
+```
+
+### Vue 组件示例
+
+```vue
+<template>
+  <div class="emoji-grid">
+    <img
+      v-for="emoji in emojis"
+      :key="emoji.name"
+      :src="getEmojiPath(emoji.name)"
+      :alt="emoji.name"
+      :title="emoji.name"
+      @click="selectEmoji(emoji)"
+    />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { getEmojisByCategory, getEmojiPath, EmojiCategory } from 'wechat-emojis';
+
+const emojis = getEmojisByCategory(EmojiCategory.FACE);
+
+const selectEmoji = (emoji: EmojiInfo) => {
+  console.log(`选择了表情: ${emoji.name}`);
+};
+</script>
+```
+
+## 数据统计
+
+- **总表情数量**: 108 个
+- **人脸表情**: 75 个
+- **手势表情**: 7 个
+- **动物表情**: 4 个
+- **祝福表情**: 7 个
+- **其他表情**: 15 个
+
+## 注意事项
+
+1. **类型安全**: 使用 `EmojiName` 类型可以在编译时检查表情名称的有效性
+2. **路径相对性**: 返回的路径是相对于项目根目录的
+3. **兼容性**: 编译目标为 ES2017，兼容现代浏览器和 Node.js
+4. **性能**: 所有数据在模块加载时预计算，查询性能优秀

package/REACT_USAGE.md

@@ -0,0 +1,456 @@
+# React 项目中使用微信表情包
+
+本指南详细介绍如何在React项目中集成和使用微信表情包模块。
+
+## 📦 安装和配置
+
+### 方式一：使用npm包（推荐）
+
+1. **安装包**：
+
+```bash
+npm install wechat-emojis
+```
+
+2. **复制资源文件**：
+由于npm包中的图片资源需要被复制到你的项目public目录，请执行以下命令：
+
+```bash
+# 复制表情资源到你的项目
+cp -r node_modules/wechat-emojis/assets/* public/assets/
+```
+
+你也可以在 `package.json` 中配置一个脚本，在安装后自动完成复制：
+
+```json
+// package.json
+{
+  "scripts": {
+    "postinstall": "cp -r node_modules/wechat-emojis/assets/* public/assets/"
+  }
+}
+```
+
+3. **在React项目中使用**：
+
+```typescript
+// 直接从npm包导入
+import {
+  getEmojiPath,
+  getEmojisByCategory,
+  EmojiCategory,
+  type EmojiName
+} from 'wechat-emojis';
+
+// 使用示例
+const WeChatEmoji: React.FC<{name: EmojiName}> = ({ name }) => {
+  const emojiPath = getEmojiPath(name);
+  // 确保你的 public 目录配置正确，可以直接访问 /assets/
+  return <img src={`/${emojiPath}`} alt={name} width={24} height={24} />;
+};
+```
+
+### 方式二：直接复制文件
+
+1. **复制必要文件到React项目**：
+```bash
+# 在你的React项目根目录下
+mkdir -p src/utils/wechat-emojis
+mkdir -p public/assets
+
+# 复制TypeScript模块
+cp path/to/wechatEmoji.ts src/utils/wechat-emojis/
+cp path/to/wechatEmoji.js src/utils/wechat-emojis/
+
+# 复制表情资源到public目录
+cp -r path/to/assets/* public/assets/
+```
+
+2. **调整图片路径**（重要）：
+由于React项目中public目录的资源访问方式，需要修改 `wechatEmoji.ts` 中的图片路径，将所有 `'assets/'` 替换为 `'/assets/'`。
+
+
+## 🚀 基础使用
+
+### 1. 导入模块
+
+```typescript
+// 从 npm 包导入 (推荐)
+import {
+  getEmojiPath,
+  getEmojisByCategory,
+  EmojiCategory,
+  type EmojiName
+} from 'wechat-emojis';
+```
+
+### 2. 创建表情组件
+
+```tsx
+// src/components/WeChatEmoji.tsx
+import React from 'react';
+import { getEmojiPath, type EmojiName } from 'wechat-emojis';
+
+interface WeChatEmojiProps {
+  name: EmojiName;
+  size?: number;
+  className?: string;
+  alt?: string;
+}
+
+const WeChatEmoji: React.FC<WeChatEmojiProps> = ({
+  name,
+  size = 24,
+  className = '',
+  alt
+}) => {
+  const emojiPath = getEmojiPath(name);
+
+  if (!emojiPath) {
+    console.warn(`表情 "${name}" 不存在`);
+    return null;
+  }
+
+  return (
+    <img
+      src={emojiPath}
+      alt={alt || name}
+      width={size}
+      height={size}
+      className={`wechat-emoji ${className}`}
+      style={{
+        display: 'inline-block',
+        verticalAlign: 'middle'
+      }}
+    />
+  );
+};
+
+export default WeChatEmoji;
+```
+
+### 3. 使用表情组件
+
+```tsx
+// src/App.tsx
+import React from 'react';
+import WeChatEmoji from './components/WeChatEmoji';
+
+function App() {
+  return (
+    <div className="App">
+      <h1>微信表情示例</h1>
+
+      {/* 基础使用 */}
+      <p>
+        你好 <WeChatEmoji name="微笑" size={20} />
+        今天天气真好 <WeChatEmoji name="太阳" size={20} />
+      </p>
+
+      {/* 不同尺寸 */}
+      <div>
+        <WeChatEmoji name="大哭" size={16} />
+        <WeChatEmoji name="大哭" size={24} />
+        <WeChatEmoji name="大哭" size={32} />
+      </div>
+    </div>
+  );
+}
+
+export default App;
+```
+
+## 🎨 高级使用示例
+
+### 1. 表情选择器组件
+
+```tsx
+// src/components/EmojiPicker.tsx
+import React, { useState } from 'react';
+import {
+  getEmojisByCategory,
+  EmojiCategory,
+  type EmojiInfo
+} from 'wechat-emojis';
+import WeChatEmoji from './WeChatEmoji';
+
+interface EmojiPickerProps {
+  onEmojiSelect: (emoji: EmojiInfo) => void;
+  categories?: EmojiCategory[];
+}
+
+const EmojiPicker: React.FC<EmojiPickerProps> = ({
+  onEmojiSelect,
+  categories = [
+    EmojiCategory.FACE,
+    EmojiCategory.GESTURE,
+    EmojiCategory.ANIMAL,
+    EmojiCategory.BLESSING,
+    EmojiCategory.OTHER
+  ]
+}) => {
+  const [activeCategory, setActiveCategory] = useState<EmojiCategory>(EmojiCategory.FACE);
+
+  const categoryNames = {
+    [EmojiCategory.FACE]: '人脸',
+    [EmojiCategory.GESTURE]: '手势',
+    [EmojiCategory.ANIMAL]: '动物',
+    [EmojiCategory.BLESSING]: '祝福',
+    [EmojiCategory.OTHER]: '其他'
+  };
+
+  return (
+    <div className="emoji-picker">
+      {/* 分类标签 */}
+      <div className="emoji-categories">
+        {categories.map(category => (
+          <button
+            key={category}
+            className={`category-btn ${activeCategory === category ? 'active' : ''}`}
+            onClick={() => setActiveCategory(category)}
+          >
+            {categoryNames[category]}
+          </button>
+        ))}
+      </div>
+
+      {/* 表情网格 */}
+      <div className="emoji-grid">
+        {getEmojisByCategory(activeCategory).map(emoji => (
+          <button
+            key={emoji.name}
+            className="emoji-item"
+            onClick={() => onEmojiSelect(emoji)}
+            title={emoji.name}
+          >
+            <WeChatEmoji name={emoji.name} size={24} />
+          </button>
+        ))}
+      </div>
+    </div>
+  );
+};
+
+export default EmojiPicker;
+```
+
+### 2. 聊天消息组件
+
+```tsx
+// src/components/ChatMessage.tsx
+import React from 'react';
+import { getEmojiPath, type EmojiName } from 'wechat-emojis';
+
+interface ChatMessageProps {
+  content: string;
+  emojiSize?: number;
+}
+
+const ChatMessage: React.FC<ChatMessageProps> = ({ content, emojiSize = 20 }) => {
+  // 解析消息中的表情标记，例如 [微笑] → 表情图片
+  const parseEmojis = (text: string) => {
+    const emojiRegex = /\[([^\]]+)\]/g;
+    const parts = [];
+    let lastIndex = 0;
+    let match;
+
+    while ((match = emojiRegex.exec(text)) !== null) {
+      // 添加表情前的文本
+      if (match.index > lastIndex) {
+        parts.push(text.slice(lastIndex, match.index));
+      }
+
+      // 添加表情
+      const emojiName = match[1] as EmojiName;
+      const emojiPath = getEmojiPath(emojiName);
+
+      if (emojiPath) {
+        parts.push(
+          <img
+            key={`emoji-${match.index}`}
+            src={emojiPath}
+            alt={emojiName}
+            width={emojiSize}
+            height={emojiSize}
+            style={{
+              display: 'inline-block',
+              verticalAlign: 'middle',
+              margin: '0 2px'
+            }}
+          />
+        );
+      } else {
+        // 如果表情不存在，保留原文本
+        parts.push(match[0]);
+      }
+
+      lastIndex = match.index + match[0].length;
+    }
+
+    // 添加剩余文本
+    if (lastIndex < text.length) {
+      parts.push(text.slice(lastIndex));
+    }
+
+    return parts;
+  };
+
+  return (
+    <div className="chat-message">
+      {parseEmojis(content)}
+    </div>
+  );
+};
+
+export default ChatMessage;
+```
+
+## 💡 使用技巧和最佳实践
+
+### 1. 性能优化
+
+```tsx
+// 使用 React.memo 优化表情组件
+const WeChatEmoji = React.memo<WeChatEmojiProps>(({ name, size, className, alt }) => {
+  // ... 组件实现
+});
+
+// 预加载常用表情
+const preloadEmojis = (emojiNames: EmojiName[]) => {
+  emojiNames.forEach(name => {
+    const path = getEmojiPath(name);
+    if (path) {
+      const img = new Image();
+      img.src = path;
+    }
+  });
+};
+```
+
+### 2. 错误处理
+
+```tsx
+const WeChatEmoji: React.FC<WeChatEmojiProps> = ({ name, size = 24, fallback }) => {
+  const [hasError, setHasError] = useState(false);
+  const emojiPath = getEmojiPath(name);
+
+  if (!emojiPath || hasError) {
+    return fallback || <span>[{name}]</span>;
+  }
+
+  return (
+    <img
+      src={emojiPath}
+      alt={name}
+      width={size}
+      height={size}
+      onError={() => setHasError(true)}
+    />
+  );
+};
+```
+
+### 3. 样式定制
+
+```css
+/* src/styles/emoji.css */
+.wechat-emoji {
+  display: inline-block;
+  vertical-align: middle;
+  user-select: none;
+  pointer-events: none;
+}
+
+.emoji-picker {
+  border: 1px solid #e0e0e0;
+  border-radius: 8px;
+  padding: 12px;
+  background: white;
+  box-shadow: 0 2px 8px rgba(0,0,0,0.1);
+}
+
+.emoji-categories {
+  display: flex;
+  gap: 8px;
+  margin-bottom: 12px;
+  border-bottom: 1px solid #f0f0f0;
+  padding-bottom: 8px;
+}
+
+.category-btn {
+  padding: 6px 12px;
+  border: none;
+  background: #f5f5f5;
+  border-radius: 4px;
+  cursor: pointer;
+  font-size: 12px;
+}
+
+.category-btn.active {
+  background: #1890ff;
+  color: white;
+}
+
+.emoji-grid {
+  display: grid;
+  grid-template-columns: repeat(8, 1fr);
+  gap: 4px;
+  max-height: 200px;
+  overflow-y: auto;
+}
+
+.emoji-item {
+  padding: 6px;
+  border: none;
+  background: transparent;
+  border-radius: 4px;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.emoji-item:hover {
+  background: #f0f0f0;
+}
+```
+
+## 🔧 TypeScript 支持
+
+项目完全支持TypeScript，提供完整的类型定义：
+
+```typescript
+import type {
+  EmojiName,      // 所有表情名称的联合类型
+  EmojiInfo,      // 表情信息接口
+  EmojiCategory   // 表情分类枚举
+} from 'wechat-emojis';
+
+// 类型安全的表情使用
+const validEmoji: EmojiName = '微笑';  // ✅ 正确
+const invalidEmoji: EmojiName = '不存在'; // ❌ TypeScript 错误
+```
+
+## 🚨 注意事项
+
+1. **图片路径**：确保assets目录位于public文件夹根目录，并且代码中引用的路径是正确的（例如，以 `/assets/` 开头）。
+2. **性能**：大量表情时考虑懒加载和虚拟滚动
+3. **兼容性**：确保目标浏览器支持所需的图片格式
+4. **版权**：注意表情包的使用权限和版权问题
+
+## 📱 移动端适配
+
+```css
+/* 移动端优化 */
+@media (max-width: 768px) {
+  .emoji-grid {
+    grid-template-columns: repeat(6, 1fr);
+  }
+
+  .emoji-item {
+    padding: 8px;
+  }
+}
+```
+
+这样你就可以在React项目中完美使用微信表情包了！