# @xiping/react-components - React 组件库

## 项目概述

这是一个功能丰富的 React 组件库，提供了 20+ 个现代化的 UI 组件，涵盖了动画效果、交互组件、数据可视化、文本处理等多个领域。所有组件都基于 React 19+ 构建，支持 TypeScript，并提供了完整的 Storybook 文档。

## 核心特性

- 🎨 **现代化设计**: 基于 HeroUI 和 Tailwind CSS 的现代 UI 设计
- ⚡ **高性能**: 使用 React 19+ 和优化的动画库
- 🎯 **TypeScript**: 完整的 TypeScript 支持
- 📱 **响应式**: 所有组件都支持响应式设计
- 🎭 **动画丰富**: 集成 Framer Motion 和多种动画效果
- 📚 **完整文档**: 提供 Storybook 文档和详细的使用示例
- 🔧 **高度可定制**: 支持主题、样式和行为的深度定制

## 组件列表

### 1. 动画组件

#### ConfettiButton
- **功能**: 带有烟花效果的按钮组件
- **特性**: 基于 canvas-confetti，支持自定义烟花配置
- **使用场景**: 庆祝按钮、成功反馈、特殊交互

#### ShimmerButton
- **功能**: 带有闪烁效果的按钮组件
- **特性**: 流光动画效果，现代化设计
- **使用场景**: 主要操作按钮、吸引注意力的交互

#### ShinyButton
- **功能**: 带有光泽效果的按钮组件
- **特性**: 金属质感，光泽动画
- **使用场景**: 特殊按钮、装饰性元素

### 2. 文本组件

#### TypingAnimation
- **功能**: 打字机动画效果组件
- **特性**: 模拟打字效果，可控制速度
- **使用场景**: 欢迎页面、介绍文字、动态内容

#### TextAnimate
- **功能**: 文本动画组件
- **特性**: 多种文本动画效果
- **使用场景**: 标题动画、强调文字

#### FlipText
- **功能**: 翻转文字动画组件
- **特性**: 3D 翻转效果
- **使用场景**: 状态切换、动态显示

#### ComicText
- **功能**: 漫画风格文字组件
- **特性**: 漫画气泡效果
- **使用场景**: 对话界面、游戏界面

#### SparklesText
- **功能**: 闪烁文字组件
- **特性**: 星星闪烁效果
- **使用场景**: 特殊标题、装饰文字

#### MorphingText
- **功能**: 文字变形动画组件
- **特性**: 文字形状变化动画
- **使用场景**: 创意标题、动态文字

#### HyperText
- **功能**: 超文本组件
- **特性**: 支持链接和格式化
- **使用场景**: 富文本显示、文档展示

### 3. 媒体组件

#### ImageViewer
- **功能**: 图片查看器组件
- **特性**: 支持缩放、旋转、缩略图、下载
- **使用场景**: 图片画廊、产品展示、媒体查看

#### ImageCompare
- **功能**: 图片对比组件
- **特性**: 滑块对比、并排显示
- **使用场景**: 产品对比、效果展示

#### VideoDialog
- **功能**: 视频对话框组件
- **特性**: 模态框播放、控制栏
- **使用场景**: 视频播放、媒体展示

### 4. 交互组件

#### PinchContent
- **功能**: 支持捏合缩放的容器组件
- **特性**: 触摸手势支持、缩放控制
- **使用场景**: 图片查看、地图交互

#### ScratchToReveal
- **功能**: 刮刮卡效果组件
- **特性**: 刮擦显示内容
- **使用场景**: 游戏、抽奖、隐藏内容

#### Pointer
- **功能**: 自定义指针组件
- **特性**: 自定义鼠标指针效果
- **使用场景**: 特殊交互、游戏界面

#### Dock
- **功能**: 停靠栏组件
- **特性**: macOS 风格的停靠栏
- **使用场景**: 应用启动器、快捷方式

### 5. 数据可视化

#### ForceGraph3D
- **功能**: 3D 力导向图组件
- **特性**: 基于 Three.js，支持节点拖拽、缩放、旋转
- **使用场景**: 网络关系图、数据可视化、知识图谱

### 6. 文本处理

#### TxtReader
- **功能**: 文本阅读器组件
- **特性**: 支持大文件、分页显示、阅读进度
- **使用场景**: 文档阅读、小说阅读器

#### TxtEditor
- **功能**: 文本编辑器组件
- **特性**: 基于 Monaco Editor，语法高亮、代码编辑
- **使用场景**: 代码编辑、文本编辑、配置编辑

### 7. 工具组件

#### QRCode
- **功能**: 二维码生成组件
- **特性**: 支持自定义颜色、大小、错误纠正级别
- **使用场景**: 分享链接、支付码、信息展示

#### Message
- **功能**: 消息提示组件
- **特性**: 多种消息类型、自动消失
- **使用场景**: 用户反馈、状态提示

#### Toast
- **功能**: 轻提示组件
- **特性**: 非阻塞式提示
- **使用场景**: 操作反馈、临时信息

### 8. 特效组件

#### BlurFade
- **功能**: 模糊淡入淡出组件
- **特性**: 背景模糊效果
- **使用场景**: 模态框、焦点效果

## 技术栈

### 核心依赖
- **React**: 19.1.0 - 核心框架
- **TypeScript**: 5.8.3 - 类型支持
- **Vite**: 7.0.6 - 构建工具

### UI 框架
- **HeroUI**: 2.8.1 - UI 组件库
- **Tailwind CSS**: 3.4.17 - 样式框架
- **Lucide React**: 0.525.0 - 图标库

### 动画库
- **Framer Motion**: 12.23.9 - 动画库
- **React Spring**: 10.0.1 - 物理动画
- **Canvas Confetti**: 1.9.3 - 烟花效果

### 编辑器
- **Monaco Editor**: 4.7.0 - 代码编辑器
- **React Markdown**: 10.1.0 - Markdown 渲染

### 可视化
- **React Force Graph 3D**: 1.28.0 - 3D 图表
- **Three.js** - 3D 渲染

### 工具库
- **Axios**: 1.11.0 - HTTP 客户端
- **Day.js**: 1.11.13 - 日期处理
- **Lodash-es**: 4.17.21 - 工具函数
- **Zustand**: 5.0.6 - 状态管理

## 安装和使用

### 安装
```bash
npm install @xiping/react-components
```

### 基本使用
```tsx
import { ConfettiButton, ImageViewer } from '@xiping/react-components';

function App() {
  return (
    <div>
      <ConfettiButton>
        点击触发烟花 🎉
      </ConfettiButton>
      
      <ImageViewer images={[...]} />
    </div>
  );
}
```

## 开发环境

### 脚本命令
- `npm run dev` - 启动开发服务器
- `npm run build` - 构建生产版本
- `npm run storybook` - 启动 Storybook 文档
- `npm run lint` - 代码检查

### 开发要求
- Node.js >= 22
- React >= 18
- TypeScript >= 5.8

## 文档和示例

### Storybook 文档
每个组件都提供了完整的 Storybook 文档，包括：
- 基本用法示例
- 属性配置说明
- 交互演示
- 代码示例

### 组件文档
每个组件都有详细的 README 文档，包含：
- 功能描述
- API 文档
- 使用示例
- 注意事项

## 性能优化

### 组件优化
- 使用 React.memo 进行组件优化
- 合理使用 useMemo 和 useCallback
- 动画使用 CSS transform 和 opacity

### 构建优化
- Tree shaking 支持
- 按需加载
- 代码分割
- 图片优化

## 浏览器支持

- Chrome 60+
- Firefox 55+
- Safari 12+
- Edge 79+

## 许可证

MIT License

## 贡献指南

1. Fork 项目
2. 创建功能分支
3. 提交更改
4. 推送到分支
5. 创建 Pull Request

## 更新日志

### v1.0.33
- 优化 ConfettiButton 性能
- 修复 ImageViewer 移动端问题
- 更新依赖版本

## 联系方式

- GitHub: https://github.com/xiping
- NPM: https://www.npmjs.com/package/@xiping/react-components

---

这个组件库提供了丰富的 React 组件，涵盖了现代 Web 应用开发中的各种需求。所有组件都经过精心设计，具有良好的性能和用户体验。