22799c9d8a
- Update skills data with additional frameworks and tools - Remove AwardsSection and EducationSection components - Update project documentation to reflect changes
11 KiB
11 KiB
项目说明文档
本文档旨在提供对 zhaoguiyang.site 项目的全面理解，包括其技术栈、框架、组件库、目录结构等，以便指导 AI 大模型进行代码重构和功能开发。
1. 项目概述
zhaoguiyang.site 是一个现代化的个人作品集网站模板，具有动画和玻璃拟态效果。该项目旨在展示个人信息、工作经历、技能和项目。
2. 技术栈和框架
- 主要框架: Astro - 一个用于构建快速、内容驱动的网站的现代前端框架。它允许使用多种 UI 框架（如 React, Vue, Svelte 等）并支持服务器端渲染 (SSR) 和静态站点生成 (SSG)。
- UI 框架: React - 用于构建用户界面的 JavaScript 库。在本项目中，部分组件（如头部、各个内容区域）是使用 React 实现的，并通过 Astro 的集成功能嵌入到页面中。
- 样式: Tailwind CSS - 一个实用工具优先的 CSS 框架，用于快速构建自定义用户界面。通过
@tailwindcss/vite集成到 Astro 项目中。 - 动画: Framer Motion (
framer-motion) - 一个用于 React 的生产级动画库，用于实现声明式的、基于物理的动画以及复杂的交互动效。在项目中，它被用于增强用户体验，例如在 等组件中实现元素的入场动画、悬停效果等。具体使用方式可以参考 组件，它可能是一个统一处理动画逻辑的封装。 - 图标: Lucide React - 一个简单、美观的 SVG 图标库。
- 包管理器: pnpm - 一个快速、磁盘空间高效的包管理器。
- TypeScript: 用于类型检查和提高代码质量。
3. 组件库和 UI
- 自定义组件: 项目包含多个自定义 React 组件，位于
src/components/目录下，用于展示不同的内容区域，例如：HeroSection.tsx: 个人简介区域。ExperienceSection.tsx: 工作经历区域。SkillsSection.tsx: 技能展示区域。ProjectsSection.tsx: 项目展示区域。GlassHeader.tsx: 玻璃拟态效果的导航栏。Footer.tsx: 页脚。LanguageSwitcher.tsx: 语言切换组件。ThemeToggle.tsx: 主题切换组件 (位于src/components/ui/)
- UI 组件 (src/components/ui/): 基于 Shadcn UI 风格，提供可复用的基础 UI 元素。
button.tsx: 按钮组件。card.tsx: 卡片组件 (包含Card,CardHeader,CardTitle,CardDescription,CardContent,CardFooter)。glass-card.tsx: 自定义玻璃拟态效果的卡片组件，使用 Framer Motion。
- UI 辅助库:
class-variance-authority: 用于创建可变样式的组件。clsx: 用于有条件地组合类名。tailwind-merge: 用于合并 Tailwind CSS 类名，避免冲突。tw-animate-css: 可能是用于集成 Animate.css 的 Tailwind CSS 插件（虽然package.json中列出，但具体用法需进一步查看代码）。
- Radix UI:
@radix-ui/react-slot被用作依赖，这表明项目可能使用 Radix UI 的某些底层实用程序或组件，通常用于构建可访问和可组合的 UI 组件。
4. 目录结构
├── .gitignore # Git 忽略文件配置
├── .trae/ # Trae AI 相关配置目录
│ └── rules/
│ └── project_rules.md # 本项目说明文档
├── .vscode/ # VS Code 编辑器配置
│ ├── extensions.json
│ └── launch.json
├── LICENSE # 项目许可证
├── README.md # 项目自述文件
├── astro.config.mjs # Astro 配置文件
├── components.json # 可能是 Shadcn UI 或类似组件库的配置文件
├── package.json # 项目依赖和脚本配置
├── pnpm-lock.yaml # pnpm 锁文件
├── public/ # 静态资源目录 (如图片、favicon)
│ ├── favicon.svg
│ └── profile.jpg
├── src/
│ ├── components/ # React 组件目录
│ │ ├── ExperienceSection.tsx
│ │ ├── Footer.tsx
│ │ ├── GlassHeader.tsx
│ │ ├── HeroSection.tsx
│ │ ├── MotionWrapper.tsx # Framer Motion 包装组件
│ │ ├── ProjectsSection.tsx
│ │ ├── SkillsSection.tsx
│ │ ├── TimelineItem.tsx # 时间轴条目组件
│ │ ├── LanguageSwitcher.tsx # 语言切换组件
│ │ └── ui/ # 通用 UI 组件 (基于 Shadcn UI 风格)
│ │ ├── button.tsx # 按钮组件
│ │ ├── card.tsx # 卡片组件
│ │ ├── glass-card.tsx # 玻璃拟态卡片组件
│ │ └── theme-toggle.tsx # 主题切换组件
│ ├── i18n/ # 国际化相关文件
│ │ ├── ui.ts # 存储翻译文本
│ │ └── utils.ts # i18n 辅助函数
│ ├── layouts/ # Astro 布局组件
│ │ └── Layout.astro # 全局页面布局
│ ├── lib/ # 辅助函数和数据
│ │ ├── data.ts # 存储个人信息、经历、技能等静态数据
│ │ └── utils.ts # 通用工具函数 (当前可能为空或包含少量工具)
│ ├── pages/ # Astro 页面组件
│ │ ├── index.astro # 网站主页 (英文)
│ │ └── zh/ # 中文语言目录
│ │ └── index.astro # 网站主页 (中文)
│ └── styles/ # 全局样式
│ └── global.css
└── tsconfig.json # TypeScript 配置文件
5. 关键文件说明
astro.config.mjs: 配置 Astro 项目，包括 Vite 插件（如 Tailwind CSS）和 Astro 集成（如 React）。package.json: 定义项目元数据、依赖项和 npm 脚本（如dev,build,preview）。tsconfig.json: 配置 TypeScript 编译器选项，包括路径别名（@/*指向./src/*）和 JSX 设置。src/layouts/Layout.astro: 定义网站的全局 HTML 结构、头部信息（<head>）、全局样式和一些客户端脚本（如主题切换逻辑）。所有页面都将使用此布局。src/pages/index.astro: 网站的英文版入口页面。它导入并使用Layout.astro作为布局，并按顺序引入各个 React 内容区域组件（如个人简介、工作经历、技能、项目）。通过getLangFromUrl从 URL 判断当前语言并传递给布局和组件。注意client:only="react"指令，表示这些 React 组件仅在客户端渲染。src/pages/zh/index.astro: 网站的中文版入口页面，结构与index.astro类似，但为中文内容服务，展示个人简介、工作经历、技能和项目。src/lib/data.ts: 存储网站展示的静态数据，如个人信息、工作经历、技能列表和项目信息。文件中的许多键值对应于src/i18n/ui.ts中的翻译键，以支持多语言。这使得内容易于更新和管理，而无需直接修改组件代码。src/i18n/ui.ts: 定义了支持的语言 (英语和简体中文) 以及所有需要翻译的文本内容的键值对。是实现网站国际化的核心文件。src/i18n/utils.ts: 包含国际化相关的辅助函数，如getLangFromUrl(从 URL 获取当前语言)、useTranslations(提供一个t函数用于在组件中获取翻译文本) 和getLocalizedPath(生成本地化路径)。src/components/*.tsx: 构成页面主要内容的 React 组件。它们从src/lib/data.ts获取数据并使用 Tailwind CSS 进行样式设置，使用 Framer Motion 实现动画效果。public/: 存放可以直接通过 URL 访问的静态文件，如favicon.svg和profile.jpg。
6. 数据流和状态管理
- 静态数据与国际化: 大部分内容数据（如个人信息、工作经历、技能、项目等）的键名存储在
src/lib/data.ts中。这些键名随后被用于从src/i18n/ui.ts中获取对应语言的实际文本。React 组件接收langprop，并使用useTranslations工具函数来获取翻译后的文本进行渲染。 - 主题切换:
src/layouts/Layout.astro中包含一个内联脚本，用于处理暗黑/明亮模式的主题切换，并将用户的偏好存储在localStorage中。此外，src/components/ui/ThemeToggle.tsx组件提供了用户手动切换主题的交互界面。 - 语言切换: 语言切换通过
src/components/LanguageSwitcher.tsx组件实现，它可能通过改变 URL 路径 (例如/en/或/zh/) 来加载不同语言版本的页面。src/i18n/utils.ts中的getLangFromUrl和getLocalizedPath辅助这一过程。
7. 构建和部署
- 开发: 使用
pnpm run dev命令启动 Astro 开发服务器。 - 构建: 使用
pnpm run build命令将项目构建为静态文件，输出到dist/目录（默认情况下，可由astro.config.mjs配置）。 - 预览: 使用
pnpm run preview命令在本地预览构建后的站点。
8. AI 代码重构和功能开发指南
- 遵循现有模式: 在添加新组件或修改现有组件时，请参考
src/components/和src/pages/中的现有代码风格和结构。 - 数据驱动: 如果添加新的内容区域，考虑是否可以将相关数据添加到
src/lib/data.ts中，以保持内容与表示的分离。 - 组件化: 优先创建可复用的 React 组件。
- Astro 与 React 集成: 理解 Astro 如何与 React 组件集成，特别是
client:*指令的使用。 - Tailwind CSS: 使用 Tailwind CSS 的实用工具类进行样式设置。
- TypeScript: 确保新代码符合 TypeScript 的类型要求。
- 动画: 如果需要添加动画，应优先使用 Framer Motion。可以参考 的实现方式，或者直接在组件中使用
motion组件和variants来定义动画。确保动画效果流畅且符合项目整体风格。查阅 获取更详细的 API 和示例。 - 可访问性: 在开发新功能时，请注意可访问性最佳实践。
9. 潜在的改进和扩展方向
- CMS 集成: 对于更动态的内容管理，可以考虑集成一个 Headless CMS (如 Sanity, Contentful)。
package.json中提到了Sanity (CMS)，这可能是一个未来的方向或之前的尝试。 - 国际化 (i18n): 项目已实现基本的国际化功能，支持英语和简体中文。主要通过
src/i18n/ui.ts管理翻译文本，src/i18n/utils.ts提供辅助函数，并在 Astro 页面和 React 组件中应用。URL 结构 (如/zh/) 用于区分不同语言版本。可以进一步完善，例如支持更多的语言或更复杂的复数、日期格式化等。 - 更复杂的交互: 对于需要更复杂客户端逻辑的功能，可能需要引入更全面的状态管理方案。
- API 路由: Astro 支持 API 路由，可以用于处理表单提交、与后端服务交互等。