# Shop-Taro - 项目框架

基于 Taro 4.0.8 + React 18.3.1 + TypeScript 5.7.2 的跨端开发框架

## 📦 技术栈

### 核心框架
- **Taro**: `4.0.8` - 跨端开发框架
- **React**: `18.3.1` - UI 框架
- **TypeScript**: `5.7.2` - 类型系统

### UI 组件库
- **NutUI React Taro**: `2.7.4` - 京东风格的 Taro React 组件库
- **NutUI Icons**: `^1.0.0` - 图标库

### 样式方案
- **Sass**: `^1.81.0` - CSS 预处理器
- **TailwindCSS**: `3.4.17` - 原子化 CSS 框架

### 状态管理
- **React Hooks** - 内置 Hooks
- **Context API** - 跨组件状态共享

### 工具库
- **Day.js**: `^1.11.13` - 日期处理
- **Crypto-js**: `^4.2.0` - 加密解密
- **React Router DOM**: `^6.28.0` - 路由管理

## 🚀 快速开始

### 安装依赖

```bash
# 使用 npm
npm install

# 使用 yarn
yarn install

# 使用 pnpm
pnpm install
```

### 开发模式

```bash
# 微信小程序
npm run dev:weapp

# H5
npm run dev:h5

# 支付宝小程序
npm run dev:alipay

# 百度小程序
npm run dev:swan

# 字节跳动小程序
npm run dev:tt

# QQ 小程序
npm run dev:qq
```

### 生产构建

```bash
# 微信小程序
npm run build:weapp

# H5
npm run build:h5

# 其他平台类似
npm run build:[platform]
```

## 📁 项目结构

```
shop-taro/
├── config/                   # Taro 配置文件
│   ├── index.ts            # 主配置
│   ├── dev.ts              # 开发配置
│   └── prod.ts             # 生产配置
├── src/                     # 源代码
│   ├── app.config.ts       # 应用配置（页面路由、tabBar等）
│   ├── app.tsx             # 应用入口
│   ├── app.scss            # 全局样式
│   ├── pages/              # 页面目录
│   │   ├── index/         # 首页
│   │   │   ├── index.tsx
│   │   │   ├── index.scss
│   │   │   └── index.config.ts
│   │   └── home/          # 个人中心页
│   │       ├── home.tsx
│   │       ├── home.scss
│   │       └── home.config.ts
│   ├── components/         # 自定义组件
│   ├── contexts/           # Context API
│   │   └── AppContext.tsx  # 应用上下文
│   ├── hooks/              # 自定义 Hooks
│   │   └── useAppContext.ts
│   ├── utils/              # 工具函数
│   │   └── index.ts       # 常用工具（日期、加密、防抖节流等）
│   ├── types/              # TypeScript 类型定义
│   │   └── global.d.ts    # 全局类型声明
│   ├── styles/             # 样式文件
│   └── assets/             # 静态资源
│       └── tabbar/         # tabBar 图标
├── package.json            # 项目依赖
├── tsconfig.json           # TypeScript 配置
├── tailwind.config.js      # TailwindCSS 配置
├── postcss.config.js       # PostCSS 配置
├── project.config.json     # 小程序项目配置
└── README.md              # 项目说明
```

## ✨ 特性

### 1. 主题切换
- 支持浅色/深色模式切换
- 使用 Context API 管理主题状态
- 暗黑模式适配

### 2. NutUI 组件库
- 已集成 @nutui/nutui-react-taro@2.7.4
- 支持按需引入
- 中文国际化配置

### 3. TailwindCSS 集成
- 支持原子化 CSS 编写
- 暗黑模式支持（dark mode）
- 自定义主题色配置

### 4. 工具函数封装
- **日期处理**: 基于 Day.js 的格式化
- **加密解密**: MD5、AES 加密
- **性能优化**: 防抖、节流函数
- **数据操作**: 深拷贝等工具

### 5. TypeScript 支持
- 完整的类型定义
- 路径别名配置 `@/*`
- 严格模式开启

## 🎨 代码示例

### 使用 NutUI 组件

```tsx
import { Button, Cell, CellGroup } from '@nutui/nutui-react-taro'

export default function MyPage() {
  return (
    <CellGroup>
      <Cell title="标题" description="描述" />
      <Button type="primary" block>
        提交
      </Button>
    </CellGroup>
  )
}
```

### 使用 TailwindCSS

```tsx
<View className="p-4 bg-white dark:bg-gray-800">
  <Text className="text-lg font-bold text-gray-800 dark:text-white">
    暗黑模式适配文本
  </Text>
</View>
```

### 使用 Context 管理状态

```tsx
import { useAppContext } from '@/hooks/useAppContext'

export default function MyPage() {
  const { theme, toggleTheme } = useAppContext()
  
  return (
    <Button onClick={toggleTheme}>
      当前主题: {theme}
    </Button>
  )
}
```

### 使用工具函数

```tsx
import { formatDate, md5, debounce } from '@/utils'

// 日期格式化
const dateStr = formatDate(new Date())

// MD5 加密
const encrypted = md5('hello world')

// 防抖
const handleSearch = debounce((keyword) => {
  console.log(keyword)
}, 500)
```

## 📝 开发规范

### 文件命名
- 页面目录: `kebab-case` (如 `user-profile/`)
- 组件文件: `PascalCase` (如 `UserProfile.tsx`)
- 工具文件: `camelCase` (如 `formatDate.ts`)

### 代码风格
- 使用 ESLint + @typescript-eslint 进行代码检查
- 使用 2 空格缩进
- 分号结尾
- 单引号优先

### 提交规范
```
feat: 新功能
fix: 修复 bug
docs: 文档更新
style: 代码格式调整
refactor: 重构
test: 测试相关
chore: 构建/工具配置
```

## 🔧 常见问题

### 1. TailwindCSS 样式不生效？
检查 `postcss.config.js` 配置，确保已安装 `postcss-nested`。

### 2. NutUI 组件样式丢失？
确保在 `app.scss` 中引入了 NutUI 样式：
```scss
@import '@nutui/nutui-react-taro/dist/styles/vitamin.css';
```

### 3. TypeScript 路径别名报错？
检查 `tsconfig.json` 的 `paths` 配置，并确保 IDE 正确识别。

## 📚 相关文档

- [Taro 官方文档](https://taro-docs.jd.com/)
- [React 官方文档](https://react.dev/)
- [NutUI React 文档](https://nutui.jd.com/react-taro/)
- [TailwindCSS 文档](https://tailwindcss.com/docs)
- [TypeScript 文档](https://www.typescriptlang.org/docs/)

## 📄 License

MIT

---

**构建时间**: 2026-05-10  
**作者**: Senior Developer