docs(project_rules): update project documentation with detailed technical specifications
- Expand project overview with responsive design and theme switching details - Update technology stack section with configuration file references - Reorganize component library section with enhanced component descriptions - Restructure directory layout for better clarity - Add comprehensive documentation for internationalization, data flow, blog features, and animations
This commit is contained in:
joyzhao
@@ -4,150 +4,205 @@
|
|||||||
|
|
||||||
## 1. 项目概述
|
## 1. 项目概述
|
||||||
|
|
||||||
`zhaoguiyang.site` 是一个现代化的个人作品集网站模板，具有动画和玻璃拟态效果。该项目旨在展示个人信息、工作经历、技能和项目，并包含完整的博客功能，支持多语言（英文和中文）。
|
`zhaoguiyang.site` 是一个现代化的个人作品集网站模板，具有动画和玻璃拟态效果。该项目旨在展示个人信息、工作经历、技能和项目，并包含完整的博客功能，支持多语言（英文和中文）。网站采用响应式设计，适配各种设备尺寸，并支持亮色/暗色主题切换。
|
||||||
|
|
||||||
## 2. 技术栈和框架
|
## 2. 技术栈和框架
|
||||||
|
|
||||||
- **主要框架**: [Astro](https://astro.build/) - 一个用于构建快速、内容驱动的网站的现代前端框架。它允许使用多种 UI 框架（如 React, Vue, Svelte 等）并支持服务器端渲染 (SSR) 和静态站点生成 (SSG)。
|
- **主要框架**: [Astro](https://astro.build/) - 一个用于构建快速、内容驱动的网站的现代前端框架。它允许使用多种 UI 框架（如 React, Vue, Svelte 等）并支持服务器端渲染 (SSR) 和静态站点生成 (SSG)。项目配置在 `astro.config.mjs` 中，包含了对 React、TailwindCSS、MDX 和国际化的支持。
|
||||||
- **UI 框架**: [React](https://react.dev/) - 用于构建用户界面的 JavaScript 库。在本项目中，部分组件（如头部、各个内容区域）是使用 React 实现的，并通过 Astro 的集成功能嵌入到页面中。
|
- **UI 框架**: [React](https://react.dev/) - 用于构建用户界面的 JavaScript 库。在本项目中，交互性组件（如头部导航、主题切换、语言切换、动画效果等）是使用 React 实现的，并通过 Astro 的集成功能嵌入到页面中。
|
||||||
- **样式**: [Tailwind CSS](https://tailwindcss.com/) - 一个实用工具优先的 CSS 框架，用于快速构建自定义用户界面。通过 `@tailwindcss/vite` 集成到 Astro 项目中。项目还使用了 `@tailwindcss/typography` 插件来美化博客文章内容。
|
- **样式**: [Tailwind CSS](https://tailwindcss.com/) - 一个实用工具优先的 CSS 框架，用于快速构建自定义用户界面。通过 `@tailwindcss/vite` 集成到 Astro 项目中。项目还使用了 `@tailwindcss/typography` 插件来美化博客文章内容。全局样式定义在 `src/styles/global.css` 中，包含了亮色和暗色主题的颜色变量。
|
||||||
- **动画**: [Framer Motion](https://www.framer.com/motion/) (`framer-motion`) - 一个用于 React 的生产级动画库，用于实现声明式的、基于物理的动画以及复杂的交互动效。在项目中，它被用于增强用户体验，例如在 <mcsymbol name="HeroSection" path="src/components/HeroSection.tsx" filename="HeroSection.tsx" type="function" startline="5"></mcsymbol> 等组件中实现元素的入场动画、悬停效果等。具体使用方式可以参考 <mcfile path="src/components/MotionWrapper.tsx" name="MotionWrapper.tsx"></mcfile> 组件，它是一个统一处理动画逻辑的封装。
|
- **动画**: [Framer Motion](https://www.framer.com/motion/) (`framer-motion`) - 一个用于 React 的生产级动画库，用于实现声明式的、基于物理的动画以及复杂的交互动效。在项目中，它被用于增强用户体验，例如在页面元素中实现入场动画、悬停效果等。具体使用方式可以参考 `src/components/MotionWrapper.tsx` 组件，它是一个统一处理动画逻辑的封装，提供了淡入和Y轴位移动画效果。
|
||||||
- **图标**: [Lucide React](https://lucide.dev/) - 一个简单、美观的 SVG 图标库。
|
- **图标**: [Lucide React](https://lucide.dev/) - 一个简单、美观的 SVG 图标库，用于提供界面图标。
|
||||||
- **包管理器**: [pnpm](https://pnpm.io/) - 一个快速、磁盘空间高效的包管理器。
|
- **包管理器**: [pnpm](https://pnpm.io/) - 一个快速、磁盘空间高效的包管理器。
|
||||||
- **TypeScript**: 用于类型检查和提高代码质量。
|
- **TypeScript**: 用于类型检查和提高代码质量。项目使用严格的 TypeScript 配置，类型定义集中在 `src/types/index.ts` 文件中。
|
||||||
- **国际化**: 使用自定义的国际化解决方案，通过 `src/i18n` 目录下的文件管理多语言内容。
|
- **国际化**: 使用自定义的国际化解决方案，通过 `src/i18n` 目录下的文件管理多语言内容。`ui.ts` 定义了翻译文本，`utils.ts` 提供了国际化工具函数，如 `useTranslations` 和 `getLocalizedPath`。
|
||||||
|
- **内容管理**: 使用 MDX 进行博客文章的编写，支持 Markdown 语法和 React 组件的混合使用。
|
||||||
- **UI 组件增强**: 使用 Radix UI 的 `@radix-ui/react-scroll-area` 和 `@radix-ui/react-slot` 组件来增强用户界面的可访问性和交互性。
|
- **UI 组件增强**: 使用 Radix UI 的 `@radix-ui/react-scroll-area` 和 `@radix-ui/react-slot` 组件来增强用户界面的可访问性和交互性。
|
||||||
|
|
||||||
## 3. 组件库和 UI
|
## 3. 组件库和 UI
|
||||||
|
|
||||||
- **自定义组件**: 项目包含多个自定义 React 组件，位于 `src/components/` 目录下，用于展示不同的内容区域，例如：
|
- **核心组件**: 项目包含多个自定义 React 组件，位于 `src/components/` 目录下：
|
||||||
- `HeroSection.tsx`: 个人简介区域。
|
- `GlassHeader.tsx`: 玻璃拟态效果的导航栏，实现了响应式设计、语言切换、主题切换、滚动效果和移动端菜单。
|
||||||
- `ExperienceSection.tsx`: 工作经历区域。
|
- `Footer.tsx`: 页脚组件，包含社交媒体链接和版权信息。
|
||||||
- `SkillsSection.tsx`: 技能展示区域。
|
- `LanguageSwitcher.tsx`: 语言切换组件，支持英文和中文切换，使用 Framer Motion 实现动画效果。
|
||||||
- `ProjectsSection.tsx`: 项目展示区域。
|
- `TypewriterEffect.tsx`: 打字机效果组件，支持单文本或文本数组的循环显示、自定义打字/删除速度、延迟和光标样式。
|
||||||
- `GlassHeader.tsx`: 玻璃拟态效果的导航栏。
|
- `SkillsMarquee.tsx`: 技能标签滚动展示组件，使用 Framer Motion 实现无限滚动效果，支持自定义滚动方向和速度。
|
||||||
- `Footer.tsx`: 页脚。
|
- `MotionWrapper.tsx`: 动画包装组件，为子组件添加基于 Framer Motion 的动画效果，包括淡入和Y轴位移。
|
||||||
- `LanguageSwitcher.tsx`: 语言切换组件。
|
- `AuthorCard.tsx`: 作者信息卡片，用于博客文章页面，显示作者头像、姓名、简介和社交媒体链接。
|
||||||
- `ThemeToggle.tsx`: 主题切换组件 (位于 `src/components/ui/`)
|
- `ShareButtons.tsx`: 社交媒体分享按钮组件，用于博客文章页面，支持 Twitter、LinkedIn、Facebook 分享和链接复制。
|
||||||
- `AuthorCard.tsx`: 作者信息卡片，用于博客文章页面。
|
|
||||||
- `ShareButtons.tsx`: 社交媒体分享按钮组件，用于博客文章页面。
|
|
||||||
- `SkillsMarquee.tsx`: 技能标签滚动展示组件，使用 Framer Motion 实现无限滚动效果。
|
|
||||||
- **博客组件 (src/components/blog/)**: 专门用于博客功能的组件集合：
|
- **博客组件 (src/components/blog/)**: 专门用于博客功能的组件集合：
|
||||||
- `BlogList.astro`: 博客文章列表组件，支持分类和标签筛选。
|
- `BlogList.astro`: 博客文章列表组件，支持分类和标签筛选，展示文章标题、描述、特色图片和阅读链接。
|
||||||
- `CategoryCard.astro`: 博客分类卡片组件，用于展示和筛选文章分类。
|
- `CategoryCard.astro`: 博客分类卡片组件，用于展示和筛选文章分类，支持多语言。
|
||||||
- `TagCard.astro`: 博客标签卡片组件，用于展示和筛选文章标签。
|
- `TagCard.astro`: 博客标签卡片组件，用于展示和筛选文章标签，支持多语言。
|
||||||
- `PostMeta.astro`: 博客文章元数据组件，展示发布日期、阅读时间等信息。
|
- `PostMeta.astro`: 博客文章元数据组件，展示发布日期、阅读时间等信息。
|
||||||
- **布局组件 (src/components/layout/)**: 用于页面布局的组件：
|
- **布局组件 (src/layouts/)**: 用于页面布局的组件：
|
||||||
- `BlogNavigation.astro`: 博客文章导航组件，用于在文章之间导航。
|
- `Layout.astro`: 基础布局组件，定义了页面的基本HTML结构、元数据、字体引入、全局CSS样式和主题切换逻辑。
|
||||||
- `TableOfContents.astro`: 文章目录组件，自动生成文章内容的目录导航。
|
- `BlogLayout.astro`: 博客页面布局组件，继承自 Layout，添加了博客特定的样式和结构。
|
||||||
- **UI 组件 (src/components/ui/)**: 基于 Shadcn UI 风格，提供可复用的基础 UI 元素。
|
- `BlogPostLayout.astro`: 博客文章页面布局组件，用于展示单篇博客文章，集成了作者信息、目录导航和文章导航功能。
|
||||||
- `button.tsx`: 按钮组件。
|
- **UI 组件 (src/components/ui/)**: 基于 Shadcn UI 风格，提供可复用的基础 UI 元素：
|
||||||
- `card.tsx`: 卡片组件 (包含 `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter`)。
|
- `button.tsx`: 按钮组件，支持多种变体和尺寸。
|
||||||
- `glass-card.tsx`: 自定义玻璃拟态效果的卡片组件，使用 Framer Motion。
|
- `glass-card.tsx`: 自定义玻璃拟态效果的卡片组件，使用 Framer Motion 实现悬停动画效果。
|
||||||
- `scroll-area.tsx`: 基于 Radix UI 的滚动区域组件，用于目录导航等场景。
|
- `theme-toggle.tsx`: 主题切换组件，实现亮色/暗色模式切换功能。
|
||||||
- `Container.tsx`: 容器组件，用于统一页面内容的宽度和边距。
|
- `Container.tsx`: 容器组件，用于统一页面内容的宽度和边距。
|
||||||
|
- **工具函数 (src/utils/)**: 提供各种实用功能：
|
||||||
|
- `blog-utils.ts`: 博客相关工具函数，包括获取文章、排序、按分类和标签过滤等功能。
|
||||||
|
- `lib/utils.ts`: 通用工具函数，如类名合并等。
|
||||||
|
- **数据管理 (src/lib/)**:
|
||||||
|
- `data.ts`: 集中管理个人信息和项目数据，支持多语言。
|
||||||
- **UI 辅助库**:
|
- **UI 辅助库**:
|
||||||
- `class-variance-authority`: 用于创建可变样式的组件。
|
- `class-variance-authority`: 用于创建可变样式的组件。
|
||||||
- `clsx`: 用于有条件地组合类名。
|
- `clsx` 和 `tailwind-merge`: 用于有条件地组合和合并 Tailwind CSS 类名。
|
||||||
- `tailwind-merge`: 用于合并 Tailwind CSS 类名，避免冲突。
|
|
||||||
- `tw-animate-css`: 用于集成 Animate.css 的 Tailwind CSS 插件。
|
- `tw-animate-css`: 用于集成 Animate.css 的 Tailwind CSS 插件。
|
||||||
- **Radix UI**: `@radix-ui/react-slot` 和 `@radix-ui/react-scroll-area` 被用作依赖，用于构建可访问和可组合的 UI 组件。
|
|
||||||
|
|
||||||
## 4. 目录结构
|
## 4. 目录结构
|
||||||
|
|
||||||
```
|
```
|
||||||
├── .gitignore # Git 忽略文件配置
|
zhaoguiyang.site/
|
||||||
├── .trae/ # Trae AI 相关配置目录
|
├── .github/ # GitHub 相关配置
|
||||||
│ └── rules/
|
├── public/ # 静态资源
|
||||||
│ └── project_rules.md # 本项目说明文档
|
│ ├── assets/ # 图片、字体等资源
|
||||||
├── .vscode/ # VS Code 编辑器配置
|
│ └── favicon.svg # 网站图标
|
||||||
│ ├── extensions.json
|
├── src/ # 源代码
|
||||||
│ └── launch.json
|
│ ├── components/ # React 组件
|
||||||
├── 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 组件目录
|
|
||||||
│ │ ├── AuthorCard.tsx # 作者信息卡片组件
|
|
||||||
│ │ ├── Footer.tsx # 页脚组件
|
|
||||||
│ │ ├── GlassHeader.tsx # 玻璃拟态效果的导航栏
|
|
||||||
│ │ ├── LanguageSwitcher.tsx # 语言切换组件
|
|
||||||
│ │ ├── MotionWrapper.tsx # Framer Motion 包装组件
|
|
||||||
│ │ ├── ShareButtons.tsx # 社交媒体分享按钮组件
|
|
||||||
│ │ ├── SkillsMarquee.tsx # 技能标签滚动展示组件
|
|
||||||
│ │ ├── blog/ # 博客相关组件
|
│ │ ├── blog/ # 博客相关组件
|
||||||
│ │ │ ├── BlogList.astro # 博客文章列表组件
|
│ │ │ ├── BlogList.astro # 博客文章列表组件
|
||||||
│ │ │ ├── CategoryCard.astro # 博客分类卡片组件
|
│ │ │ ├── CategoryCard.astro # 分类卡片组件
|
||||||
│ │ │ ├── PostMeta.astro # 博客文章元数据组件
|
│ │ │ ├── PostMeta.astro # 文章元数据组件
|
||||||
│ │ │ └── TagCard.astro # 博客标签卡片组件
|
│ │ │ └── TagCard.astro # 标签卡片组件
|
||||||
│ │ ├── layout/ # 布局相关组件
|
│ │ ├── ui/ # UI 组件
|
||||||
│ │ │ ├── BlogNavigation.astro # 博客文章导航组件
|
│ │ │ ├── button.tsx # 按钮组件
|
||||||
│ │ │ └── TableOfContents.astro # 文章目录组件
|
│ │ │ ├── Container.tsx # 容器组件
|
||||||
│ │ └── ui/ # 通用 UI 组件 (基于 Shadcn UI 风格)
|
│ │ │ ├── glass-card.tsx # 玻璃效果卡片组件
|
||||||
│ │ ├── button.tsx # 按钮组件
|
│ │ │ └── theme-toggle.tsx # 主题切换组件
|
||||||
│ │ ├── card.tsx # 卡片组件
|
│ │ ├── AuthorCard.tsx # 作者信息卡片组件
|
||||||
│ │ ├── glass-card.tsx # 玻璃拟态卡片组件
|
│ │ ├── Footer.tsx # 页脚组件
|
||||||
│ │ ├── scroll-area.tsx # 滚动区域组件
|
│ │ ├── GlassHeader.tsx # 玻璃效果导航栏组件
|
||||||
│ │ └── theme-toggle.tsx # 主题切换组件
|
│ │ ├── LanguageSwitcher.tsx # 语言切换组件
|
||||||
│ ├── i18n/ # 国际化相关文件
|
│ │ ├── MotionWrapper.tsx # 动画包装组件
|
||||||
│ │ ├── ui.ts # 存储翻译文本
|
│ │ ├── ShareButtons.tsx # 社交分享按钮组件
|
||||||
│ │ └── utils.ts # i18n 辅助函数
|
│ │ ├── SkillsMarquee.tsx # 技能标签滚动组件
|
||||||
|
│ │ └── TypewriterEffect.tsx # 打字机效果组件
|
||||||
|
│ ├── i18n/ # 国际化相关
|
||||||
|
│ │ ├── ui.ts # UI 文本翻译
|
||||||
|
│ │ └── utils.ts # 国际化工具函数
|
||||||
│ ├── layouts/ # Astro 布局组件
|
│ ├── layouts/ # Astro 布局组件
|
||||||
│ │ ├── AboutLayout.astro # 关于页面布局
|
|
||||||
│ │ ├── BlogLayout.astro # 博客页面布局
|
│ │ ├── BlogLayout.astro # 博客页面布局
|
||||||
│ │ ├── BlogPostLayout.astro # 博客文章页面布局
|
│ │ ├── BlogPostLayout.astro # 博客文章页面布局
|
||||||
│ │ ├── Layout.astro # 全局页面布局
|
│ │ └── Layout.astro # 基础页面布局
|
||||||
│ │ └── TaxonomyPageLayout.astro # 分类/标签页面布局
|
│ ├── lib/ # 工具库
|
||||||
│ ├── lib/ # 辅助函数和数据
|
│ │ ├── data.ts # 个人信息和项目数据
|
||||||
│ │ ├── data.ts # 存储个人信息、经历、技能等静态数据
|
|
||||||
│ │ └── utils.ts # 通用工具函数
|
│ │ └── utils.ts # 通用工具函数
|
||||||
│ ├── pages/ # Astro 页面组件
|
│ ├── pages/ # 页面
|
||||||
│ │ ├── about.md # 关于页面 (Markdown)
|
│ │ ├── blog/ # 博客页面
|
||||||
│ │ ├── blog/ # 博客相关页面
|
|
||||||
│ │ │ ├── index.astro # 博客首页
|
│ │ │ ├── index.astro # 博客首页
|
||||||
│ │ │ ├── category/ # 分类页面
|
│ │ │ ├── category/ # 分类页面
|
||||||
│ │ │ ├── tag/ # 标签页面
|
│ │ │ ├── tag/ # 标签页面
|
||||||
│ │ │ └── posts/ # 博客文章 (Markdown)
|
│ │ │ └── posts/ # 博客文章
|
||||||
│ │ ├── index.astro # 网站主页 (英文)
|
|
||||||
│ │ ├── projects.astro # 项目页面
|
│ │ ├── projects.astro # 项目页面
|
||||||
│ │ ├── services.md # 服务页面 (Markdown)
|
│ │ ├── index.astro # 首页
|
||||||
│ │ └── zh/ # 中文语言目录
|
│ │ └── zh/ # 中文页面
|
||||||
│ │ ├── blog/ # 中文博客页面
|
│ │ ├── blog/ # 中文博客页面
|
||||||
│ │ └── index.astro # 网站主页 (中文)
|
│ │ │ ├── index.astro # 中文博客首页
|
||||||
│ ├── styles/ # 全局样式
|
│ │ │ ├── category/ # 中文分类页面
|
||||||
│ │ └── global.css
|
│ │ │ ├── tag/ # 中文标签页面
|
||||||
|
│ │ │ └── posts/ # 中文博客文章
|
||||||
|
│ │ ├── projects.astro # 中文项目页面
|
||||||
|
│ │ └── index.astro # 中文首页
|
||||||
|
│ ├── styles/ # 样式
|
||||||
|
│ │ └── global.css # 全局样式
|
||||||
│ ├── types/ # TypeScript 类型定义
|
│ ├── types/ # TypeScript 类型定义
|
||||||
│ │ └── index.ts # 集中管理项目中的类型定义
|
│ │ └── index.ts # 类型定义文件
|
||||||
│ └── utils/ # 工具函数
|
│ └── utils/ # 工具函数
|
||||||
│ └── blog-utils.ts # 博客相关工具函数
|
│ └── blog-utils.ts # 博客相关工具函数
|
||||||
├── temp_docs/ # 临时文档目录
|
├── .gitignore # Git 忽略文件
|
||||||
└── tsconfig.json # TypeScript 配置文件
|
├── astro.config.mjs # Astro 配置
|
||||||
|
├── package.json # 项目依赖
|
||||||
|
├── pnpm-lock.yaml # pnpm 锁文件
|
||||||
|
├── tailwind.config.cjs # Tailwind CSS 配置
|
||||||
|
└── tsconfig.json # TypeScript 配置
|
||||||
```
|
```
|
||||||
|
|
||||||
## 5. 关键文件说明
|
## 5. 关键文件说明
|
||||||
|
|
||||||
- **`astro.config.mjs`**: 配置 Astro 项目，包括 Vite 插件（如 Tailwind CSS）和 Astro 集成（如 React）。
|
- **astro.config.mjs**: Astro 配置文件，定义了项目的构建设置、集成（React、TailwindCSS、MDX）和国际化支持。
|
||||||
- **`package.json`**: 定义项目元数据、依赖项和 npm 脚本（如 `dev`, `build`, `preview`）。
|
- **tailwind.config.cjs**: Tailwind CSS 配置文件，定义了自定义主题、颜色、动画、插件和其他 Tailwind 相关设置。
|
||||||
- **`tsconfig.json`**: 配置 TypeScript 编译器选项，包括路径别名（`@/*` 指向 `./src/*`）和 JSX 设置。
|
- **src/i18n/ui.ts**: 包含所有 UI 文本的翻译，按语言（英文和中文）组织，包括导航、按钮、标题和描述等文本。
|
||||||
- **`src/layouts/Layout.astro`**: 定义网站的全局 HTML 结构、头部信息（`<head>`）、全局样式和客户端脚本。所有页面都将使用此布局。
|
- **src/i18n/utils.ts**: 提供国际化相关的实用函数，如 `useTranslations`（获取翻译文本）和 `getLocalizedPath`（处理多语言路径）。
|
||||||
- **`src/layouts/BlogLayout.astro`**: 博客页面的布局组件，包含博客特有的样式和结构。
|
- **src/lib/data.ts**: 集中管理个人信息（姓名、位置、邮箱、社交媒体链接、职位、描述、关于、统计数据、技能等）和项目数据（标题、描述、图片、链接、技术栈等），支持多语言。
|
||||||
- **`src/layouts/BlogPostLayout.astro`**: 博客文章页面的布局组件，包含文章内容、目录导航、作者信息和分享按钮等。
|
- **src/lib/utils.ts**: 包含通用工具函数，如 `cn`（合并类名）等。
|
||||||
- **`src/pages/index.astro`**: 网站的英文版入口页面。它导入并使用 `Layout.astro` 作为布局，并按顺序引入各个 React 内容区域组件。通过 `getLangFromUrl` 从 URL 判断当前语言并传递给布局和组件。`client:only="react"`指令表示这些 React 组件仅在客户端渲染。
|
- **src/utils/blog-utils.ts**: 提供博客相关工具函数，包括根据语言获取文章、按日期排序、按类别和标签过滤文章等功能。
|
||||||
- **`src/pages/zh/index.astro`**: 网站的中文版入口页面，结构与 `index.astro` 类似，但为中文内容服务，展示个人简介、工作经历、技能和项目。
|
- **src/styles/global.css**: 全局 CSS 样式，包括 Tailwind 指令、自定义 CSS 变量（亮色和暗色主题的颜色方案）和博客相关样式。
|
||||||
- **`src/pages/blog/index.astro`**: 博客首页，展示所有博客文章、分类和标签。
|
- **src/types/index.ts**: 集中定义项目中使用的 TypeScript 类型和接口，如 `Project`、`Author`、`SocialLink` 等。
|
||||||
- **`src/lib/data.ts`**: 存储网站展示的静态数据，如个人信息、工作经历、技能列表和项目信息。文件中的许多键值对应于 `src/i18n/ui.ts` 中的翻译键，以支持多语言。这使得内容易于更新和管理，而无需直接修改组件代码。
|
|
||||||
- **`src/i18n/ui.ts`**: 定义了支持的语言 (英语和简体中文) 以及所有需要翻译的文本内容的键值对。是实现网站国际化的核心文件。
|
## 6. 国际化实现
|
||||||
- **`src/i18n/utils.ts`**: 包含国际化相关的辅助函数，如 `getLangFromUrl` (从 URL 获取当前语言)、`useTranslations` (提供一个 `t` 函数用于在组件中获取翻译文本) 和 `getLocalizedPath` (生成本地化路径)。
|
|
||||||
- **`src/utils/blog-utils.ts`**: 博客功能的工具函数集合，包括获取博客文章、按日期排序、按分类/标签筛选等功能。
|
项目使用自定义的国际化解决方案，主要包括以下部分：
|
||||||
- **`src/types/index.ts`**: 集中管理项目中的类型定义，包括博客文章、作者信息、组件 Props 等接口定义。
|
|
||||||
- **`src/components/*.tsx`**: 构成页面主要内容的 React 组件。它们从 `src/lib/data.ts` 获取数据并使用 Tailwind CSS 进行样式设置，使用 Framer Motion 实现动画效果。
|
1. **语言定义**: 在 `src/i18n/ui.ts` 中定义所有支持的语言（英文和中文）和翻译文本，使用 TypeScript 类型确保翻译的完整性。
|
||||||
- **`public/`**: 存放可以直接通过 URL 访问的静态文件，如 `favicon.svg` 和 `profile.jpg`。
|
2. **工具函数**:
|
||||||
|
- `src/i18n/utils.ts` 中的 `useTranslations` 函数用于获取当前语言的翻译文本
|
||||||
|
- `getLocalizedPath` 函数用于处理多语言路径，根据当前语言生成正确的 URL
|
||||||
|
3. **目录结构**: 使用 `/zh/` 前缀区分中文页面，默认路径为英文页面。所有页面内容都有对应的中英文版本。
|
||||||
|
4. **语言切换**: 通过 `LanguageSwitcher.tsx` 组件实现语言切换功能，使用 Framer Motion 实现动画效果，并根据选择的语言更新 URL 路径。
|
||||||
|
5. **数据国际化**: 在 `src/lib/data.ts` 中，所有个人信息和项目数据都支持多语言，根据当前语言显示相应的内容。
|
||||||
|
|
||||||
|
## 7. 数据流和状态管理
|
||||||
|
|
||||||
|
项目使用简单的数据流模式，主要通过以下方式管理数据和状态：
|
||||||
|
|
||||||
|
1. **静态数据**: 大部分内容（如个人信息、工作经历、技能、项目）存储在 `src/lib/data.ts` 中，作为静态数据导出，支持多语言。
|
||||||
|
2. **国际化文本**: UI 文本存储在 `src/i18n/ui.ts` 中，通过 `useTranslations` 钩子在组件中获取当前语言的翻译文本。
|
||||||
|
3. **主题状态**: 使用 `localStorage` 和 DOM 操作管理主题状态（亮色/暗色），通过 `theme-toggle.tsx` 组件实现切换功能，并在页面加载时通过 `useEffect` 钩子恢复主题设置。
|
||||||
|
4. **博客文章**: 使用 Markdown/MDX 文件存储博客文章内容，通过 Astro 的 `import.meta.glob` 在构建时处理，支持按分类和标签筛选。
|
||||||
|
5. **组件状态**: 使用 React 的 `useState` 和 `useEffect` 钩子管理组件内部状态，如打字机效果的当前文本、技能标签滚动的动画控制等。
|
||||||
|
6. **动画状态**: 使用 Framer Motion 的 `animate`、`initial`、`whileHover` 等属性和 `useAnimationControls` 钩子管理动画状态。
|
||||||
|
|
||||||
|
项目没有使用复杂的状态管理库（如 Redux 或 MobX），因为大部分内容是静态的，不需要复杂的状态管理。组件之间的通信主要通过 props 传递和上下文（如当前语言）实现。
|
||||||
|
|
||||||
|
## 8. 博客功能
|
||||||
|
|
||||||
|
博客功能主要通过以下方式实现：
|
||||||
|
|
||||||
|
1. **内容管理**: 使用 Markdown/MDX 文件存储博客文章，位于 `src/pages/blog/posts/` 和 `src/pages/zh/blog/posts/` 目录，支持 Markdown 语法和 React 组件的混合使用。
|
||||||
|
2. **文章列表**: 通过 `src/pages/blog/index.astro` 和 `src/pages/zh/blog/index.astro` 实现博客文章列表页面，使用 `import.meta.glob` 读取所有文章，并处理文章数据。
|
||||||
|
3. **分类和标签**: 支持按分类和标签筛选文章，通过 `CategoryCard.astro` 和 `TagCard.astro` 组件实现，从所有文章中提取分类和标签，并生成对应的链接。
|
||||||
|
4. **文章元数据**: 每篇文章包含标题、描述、日期、作者、分类、标签、特色图片等元数据，通过 Markdown frontmatter 定义。
|
||||||
|
5. **阅读时间**: 自动计算文章的阅读时间，通过 `PostMeta.astro` 组件显示。
|
||||||
|
6. **作者信息**: 通过 `AuthorCard.tsx` 组件显示作者信息，包括头像、姓名、简介和社交媒体链接。
|
||||||
|
7. **社交分享**: 通过 `ShareButtons.tsx` 组件实现社交媒体分享功能，支持 Twitter、LinkedIn、Facebook 分享和链接复制。
|
||||||
|
8. **博客工具函数**: 在 `src/utils/blog-utils.ts` 中提供博客相关工具函数，包括获取文章、排序、按类别和标签过滤等功能。
|
||||||
|
|
||||||
|
## 9. 项目功能
|
||||||
|
|
||||||
|
项目展示功能主要通过以下方式实现：
|
||||||
|
|
||||||
|
1. **项目数据**: 在 `src/lib/data.ts` 中定义项目数据，包括标题、描述、图片、链接、技术栈等信息，支持多语言。
|
||||||
|
2. **项目列表**: 通过 `src/pages/projects.astro` 和 `src/pages/zh/projects.astro` 实现项目列表页面，根据当前语言获取项目数据。
|
||||||
|
3. **项目卡片**: 使用 `glass-card.tsx` 组件展示项目信息，实现玻璃拟态效果和悬停动画效果，使用 Framer Motion 进行动画处理。
|
||||||
|
4. **响应式设计**: 项目列表页面采用响应式设计，在不同设备尺寸下自动调整布局和显示方式。
|
||||||
|
|
||||||
|
## 10. 主题切换
|
||||||
|
|
||||||
|
项目支持亮色/暗色主题切换，主要通过以下方式实现：
|
||||||
|
|
||||||
|
1. **主题定义**: 在 `src/styles/global.css` 中定义亮色和暗色主题的 CSS 变量，包括背景色、文本色、边框色等。
|
||||||
|
2. **主题切换组件**: 通过 `src/components/ui/theme-toggle.tsx` 组件实现主题切换功能，通过操作 `document.documentElement` 的 `classList` 来改变主题。
|
||||||
|
3. **主题持久化**: 使用 `localStorage` 存储用户的主题偏好，在页面加载时通过 `useEffect` 钩子恢复主题设置。
|
||||||
|
4. **系统主题检测**: 支持检测系统主题偏好，并自动应用相应的主题。
|
||||||
|
|
||||||
|
## 11. 特殊效果和动画
|
||||||
|
|
||||||
|
项目使用多种技术实现特殊效果和动画，主要包括：
|
||||||
|
|
||||||
|
1. **玻璃拟态效果**: 通过 `glass-card.tsx` 和 `GlassHeader.tsx` 组件实现玻璃拟态效果，使用 CSS 的 `backdrop-filter` 和 `background-color` 属性。
|
||||||
|
2. **打字机效果**: 通过 `TypewriterEffect.tsx` 组件实现打字机效果，支持单文本或文本数组的循环显示、自定义打字/删除速度、延迟和光标样式，使用 Framer Motion 和 React hooks 实现。
|
||||||
|
3. **技能标签滚动**: 通过 `SkillsMarquee.tsx` 组件实现技能标签的无限滚动效果，使用 Framer Motion 的 `animate` 和 `useAnimationControls` 实现，支持自定义滚动方向和速度。
|
||||||
|
4. **动画包装**: 通过 `MotionWrapper.tsx` 组件为子组件添加基于 Framer Motion 的动画效果，包括淡入和Y轴位移，提供统一的动画处理方式。
|
||||||
|
5. **悬停动画**: 多个组件（如 `glass-card.tsx`、按钮等）实现了悬停动画效果，通过 Framer Motion 的 `whileHover` 属性实现。
|
||||||
|
6. **页面过渡**: 页面元素的入场动画，通过 Framer Motion 的 `initial`、`animate` 和 `exit` 属性实现。
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
## 6. 数据流和状态管理
|
## 6. 数据流和状态管理
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user