| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228 |
- ---
- description:
- globs:
- alwaysApply: true
- ---
- # 项目介绍
- ## 项目概述
- 这是一个基于TypeScript + React Router v7 + shadcn/ui + Tailwind CSS+Zustand的React前端项目
- ## 技术栈
- TypeScript + React Router v7 + shadcn/ui + Tailwind CSS+Zustand的React
- ### 核心框架和库
- - **React 19**: 用于构建用户界面的JavaScript库
- - **TypeScript**: 添加静态类型检查的JavaScript超集
- - **Vite**: 现代化的前端构建工具，提供快速的开发体验
- - **React Router**: 用于处理应用程序的路由
- - **Zustand**: 轻量级状态管理库，用于管理应用状态
- ### UI组件和样式
- - **Shadcn UI**: 基于Radix UI的组件集合，提供了可定制的UI组件
- - **Tailwind CSS**: 实用优先的CSS框架，用于快速构建自定义设计
- - **Radix UI**: 提供无样式、可访问的UI组件
- - **Lucide React**: 提供简洁的图标集
- ### 表单和验证
- - **React Hook Form**: 用于表单处理和验证
- - **Zod**: TypeScript优先的模式验证库
- ### 开发工具
- - **ESLint**: 代码质量检查工具
- - **TypeScript ESLint**: TypeScript的ESLint插件
- ## 项目结构
- ```
- ├── src/ # 源代码目录
- │ ├── App.tsx # 应用主组件（ThemeProvider + Outlet）
- │ ├── main.tsx # 应用入口，挂载 RouterProvider 与全局样式
- │ ├── vite-env.d.ts # Vite 环境类型声明
- │ ├── assets/ # 静态资源
- │ │ └── react.svg # React 图标
- │ ├── components/ # 组件目录
- │ │ ├── theme-provider.tsx # 主题提供者
- │ │ ├── theme-toggle.tsx # 主题切换（圆形扩散动画）
- │ │ ├── blog/ # 博客相关组件
- │ │ │ ├── article-card.tsx
- │ │ │ ├── article-toc.tsx
- │ │ │ ├── blog-footer.tsx
- │ │ │ ├── blog-header.tsx
- │ │ │ ├── blog-sidebar.tsx
- │ │ │ ├── code-block.tsx
- │ │ │ ├── markdown-renderer.tsx
- │ │ │ ├── search-suggestions.tsx
- │ │ │ ├── simple-markdown.tsx
- │ │ │ ├── timeline-archive.tsx
- │ │ │ ├── user-profile.tsx
- │ │ │ └── UserIpInfo.tsx
- │ │ ├── layout/ # 布局组件
- │ │ │ ├── blog-layout.tsx
- │ │ │ ├── mode-toggle.tsx
- │ │ │ └── page-transition.tsx
- │ │ └── ui/ # 基础 UI 组件（shadcn/ui 集合）
- │ │ ├── accordion.tsx
- │ │ ├── alert-dialog.tsx
- │ │ ├── alert.tsx
- │ │ ├── aspect-ratio.tsx
- │ │ ├── avatar.tsx
- │ │ ├── badge.tsx
- │ │ ├── breadcrumb.tsx
- │ │ ├── button.tsx
- │ │ ├── calendar.tsx
- │ │ ├── card.tsx
- │ │ ├── carousel.tsx
- │ │ ├── chart.tsx
- │ │ ├── checkbox.tsx
- │ │ ├── collapsible.tsx
- │ │ ├── command.tsx
- │ │ ├── context-menu.tsx
- │ │ ├── dialog.tsx
- │ │ ├── drawer.tsx
- │ │ ├── dropdown-menu.tsx
- │ │ ├── form.tsx
- │ │ ├── hover-card.tsx
- │ │ ├── input-otp.tsx
- │ │ ├── input.tsx
- │ │ ├── label.tsx
- │ │ ├── menubar.tsx
- │ │ ├── navigation-menu.tsx
- │ │ ├── pagination.tsx
- │ │ ├── popover.tsx
- │ │ ├── progress.tsx
- │ │ ├── radio-group.tsx
- │ │ ├── resizable.tsx
- │ │ ├── scroll-area.tsx
- │ │ ├── select.tsx
- │ │ ├── separator.tsx
- │ │ ├── sheet.tsx
- │ │ ├── sidebar.tsx
- │ │ ├── skeleton.tsx
- │ │ ├── slider.tsx
- │ │ ├── sonner.tsx
- │ │ ├── switch.tsx
- │ │ ├── table.tsx
- │ │ ├── tabs.tsx
- │ │ ├── textarea.tsx
- │ │ ├── toggle-group.tsx
- │ │ ├── toggle.tsx
- │ │ └── tooltip.tsx
- │ ├── hooks/ # 自定义 Hook
- │ │ ├── api/ # API 请求钩子目录
- │ │ ├── use-mobile.ts # 移动设备检测
- │ │ ├── use-mouse-transform.ts # 鼠标位移变换
- │ │ └── use-simple-mouse-scale.ts # 简易鼠标缩放
- │ ├── lib/ # 工具与服务
- │ │ ├── highlight-utils.ts # 代码高亮工具
- │ │ ├── search-service.ts # 搜索服务
- │ │ ├── simple-post-loader.ts # Markdown 文章加载器
- │ │ └── utils.ts # 通用工具函数
- │ ├── pages/ # 页面
- │ │ ├── About.tsx
- │ │ ├── Archive.tsx
- │ │ ├── ArticleDetail.tsx
- │ │ ├── ArticleList.tsx
- │ │ ├── BlogHome.tsx
- │ │ ├── Categories.tsx
- │ │ ├── HelloWorld.tsx
- │ │ ├── Search.tsx
- │ │ ├── Tags.tsx
- │ │ └── TestPost.tsx
- │ ├── posts/ # Markdown 文章目录（节选，禁止在当前文件更新该目录下的文章）
- │ │ ├── 4月测试文章.md
- │ │ ├── 2002-最佳实践 copy.md
- │ │ └── ......
- │ ├── routes/ # 路由配置
- │ │ ├── blog-routes.tsx
- │ │ └── routes.tsx
- │ ├── store/ # 状态管理（Zustand）
- │ │ ├── blog-store.ts
- │ │ ├── counter-store.ts
- │ │ └── theme-store.ts
- │ ├── styles/ # 样式
- │ │ ├── App.css
- │ │ └── index.css # 包含 Tailwind CSS 引入
- │ └── types/ # TypeScript 类型定义
- │ ├── blog.ts
- │ ├── components.ts
- │ └── index.ts
- ├── public/ # 公共静态资源
- │ ├── avatar.jpg
- │ ├── blog-background.jpg
- │ └── vite.svg
- ├── rule/ # 项目规则与文档
- │ ├── rule.md
- │ ├── 前端代码注释规则.md
- │ ├── 前端页面设计规则.md
- │ ├── 文件命名规则.md
- │ └── 后端api接口文档/
- │ └── 接口统一响应文档.md
- ├── .gitignore
- ├── components.json # shadcn/ui 组件配置
- ├── eslint.config.js
- ├── index.html
- ├── package.json
- ├── pnpm-lock.yaml
- ├── tsconfig.json
- ├── tsconfig.app.json
- ├── tsconfig.node.json
- └── vite.config.ts
- ```
- ## 主要功能
- ### 状态管理
- 项目使用Zustand进行状态管理，包括：
- - **主题状态管理**: 支持亮色、暗色和系统主题
- - **计数器状态管理**: 简单的计数器示例，展示Zustand的基本用法
- ### 路由管理
- 使用React Router进行路由管理，支持嵌套路由和动态路由。
- ### 组件系统
- 项目采用组件化开发方式，组件分为以下几类：
- - **功能组件**: 实现特定业务功能的组件
- - **布局组件**: 处理页面布局的组件
- - **UI组件**: 基础UI组件，如按钮、卡片等
- ## 开发指南
- ### 安装依赖
- ```bash
- pnpm install
- ```
- ### 启动开发服务器
- ```bash
- pnpm dev
- ```
- ### 构建项目
- ```bash
- pnpm build
- ```
- ### 代码检查
- ```bash
- pnpm lint
- ```
- ## 最佳实践
- 1. 使用TypeScript类型定义确保代码类型安全
- 2. 遵循组件化开发原则，保持组件的单一职责
- 3. 使用Zustand进行状态管理，避免过度使用全局状态
- 4. 使用Tailwind CSS进行样式开发，保持样式的一致性
- 5. 遵循ESLint规则，保持代码质量
|
