156 lines
5.9 KiB
Markdown
156 lines
5.9 KiB
Markdown
<!-- ...existing code... -->
|
||
# astro-jiao77.cn
|
||
|
||
一个基于 Astro 5、TypeScript 与 Tailwind CSS 打造的现代静态网站，融合玻璃质感设计、莫兰蒂配色与定制动画系统，适合构建专题站点、数据报告与导航中心。
|
||
|
||
## 项目简介
|
||
|
||
- 使用 Astro 的岛屿架构实现快速加载与细粒度交互。
|
||
- Tailwind CSS 提供统一的设计令牌与主题扩展，支持深浅配色切换。
|
||
- 组件库涵盖导航、报告、通用 UI 与动画包装器，降低页面搭建成本。
|
||
- 内置部署脚本与检查流程，支持快速上线与质量验证。
|
||
|
||
## 环境要求
|
||
|
||
| 工具 | 建议版本 | 说明 |
|
||
| --- | --- | --- |
|
||
| Node.js | ≥ 18.17.0 | 可用 nvm 管理不同版本 |
|
||
| npm / pnpm | npm ≥ 9 / pnpm ≥ 8 | 根据团队习惯选择包管理器 |
|
||
| Git | 最新版本 | 代码管理与部署同步 |
|
||
|
||
## 快速开始
|
||
|
||
1. 安装依赖
|
||
```bash
|
||
npm install
|
||
```
|
||
2. 启动开发服务器（默认端口 4321）
|
||
```bash
|
||
npm run dev
|
||
```
|
||
3. 构建与预览产物
|
||
```bash
|
||
npm run build
|
||
npm run preview
|
||
```
|
||
4. 类型与模板检查
|
||
```bash
|
||
npm run astro check
|
||
```
|
||
|
||
## 目录结构
|
||
|
||
```text
|
||
.
|
||
├─ src/
|
||
│ ├─ components/
|
||
│ │ ├─ common/ # 通用组件（按钮、动画包装、图像查看器等）
|
||
│ │ ├─ navigation/ # 导航页面组件 (NavigationCard、NavigationGrid)
|
||
│ │ └─ report/ # 报告组件 (ReportSection、MetricCard、MetricsGrid)
|
||
│ ├─ layouts/ # 布局组件 (BaseLayout 等)
|
||
│ ├─ pages/ # Astro 页面 (首页、报告模板、专题页)
|
||
│ └─ scripts/ # 浏览器交互脚本 (滚动、头部动画等)
|
||
├─ docs/ # 说明文档与部署指南
|
||
├─ public/ # 静态资源 (图片、图标、字体等)
|
||
├─ tailwind.config.mjs # 主题与配色扩展
|
||
├─ deploy.sh / deploy-full.sh # 部署脚本
|
||
└─ astro.config.mjs # Astro 全局配置
|
||
```
|
||
|
||
## 常用命令
|
||
|
||
| 命令 | 功能 |
|
||
| --- | --- |
|
||
| `npm run dev` | 本地开发，支持热更新 |
|
||
| `npm run build` | 产出静态文件到 `dist/` |
|
||
| `npm run preview` | 使用 Astro 内置服务器预览构建结果 |
|
||
| `npm run astro check` | 运行 TypeScript + Astro 模板检查 |
|
||
| `npm run lighthouse` | （如配置）执行性能与可访问性检测 |
|
||
|
||
## 核心模块与文件
|
||
|
||
- 报告模板：`src/pages/report/template/index.astro`，配合 `docs/REPORT_TEMPLATE_SUMMARY.md` 快速复用结构。
|
||
- 导航模板：`src/pages/navigation-template.astro`，搭配 `docs/NAVIGATION_TEMPLATE_GUIDE.md` 定制导航入口。
|
||
- 交互脚本：`src/scripts/scroll-progress.ts`、`src/scripts/header.ts` 管理滚动进度条与动态头部。
|
||
- 通用组件：`src/components/common/AnimatedElement.astro`、`GlowButton.astro`、`ImageViewer.astro` 提供动画与图片交互。
|
||
- 配色定义：`tailwind.config.mjs` 中的 `morandi` 调色盘，实现统一的莫兰蒂主题。
|
||
|
||
## 页面与组件使用
|
||
|
||
### 导航页面
|
||
|
||
- 组合 `NavigationGrid` 与 `NavigationCard` 构建入口矩阵。
|
||
- 支持自定义列数、动画延迟与卡片主题，适用于首页、功能导航等场景。
|
||
|
||
### 报告页面
|
||
|
||
- 使用 `ReportSection` 划分章节，搭配 `MetricCard`、`MetricsGrid` 展示核心指标。
|
||
- 支持深色渐变背景与滚动触发动画，适合数据报告、分析仪表盘。
|
||
|
||
### 通用组件
|
||
|
||
- `Container`：多种视觉变体（glass、solid、outline）与尺寸可选。
|
||
- `AnimatedElement`：封装 8 种滚动动画，支持延迟与持续时间配置。
|
||
- `Header`：响应滚动的智能页眉，移动端自适应。
|
||
|
||
## 设计与交互
|
||
|
||
- **玻璃质感**：半透明背景 + 模糊滤镜，营造层次感。
|
||
- **莫兰蒂配色**：柔和雅致，适用于深浅背景。定义示例：
|
||
```css
|
||
morandi: {
|
||
cream: '#F4F1E8',
|
||
beige: '#E8DCC0',
|
||
sage: '#C8D5B9',
|
||
dusty: '#D4B5A0',
|
||
mauve: '#B8A5A5',
|
||
clay: '#A68B7B',
|
||
mist: '#C7B8A1',
|
||
stone: '#9B8B7A',
|
||
deep: '#7A6B5D'
|
||
}
|
||
```
|
||
- **动画系统**：加载、滚动、悬浮多种动效，增强反馈与沉浸感。
|
||
- **响应式布局**：针对桌面、平板、移动端优化栅格与交互。
|
||
|
||
## 开发流程
|
||
|
||
1. 基于模板创建页面：复制 `pages/report/template` 或现有导航页。
|
||
2. 在 `src/components/` 中组合组件，必要时拓展新变体。
|
||
3. Tailwind 实现局部样式，注意复用 `@apply` 与设计令牌。
|
||
4. 若需脚本交互，将逻辑放入 `src/scripts/` 并在页面中按需引入。
|
||
5. 执行 `npm run astro check` 与 `npm run build` 确保质量。
|
||
|
||
## 部署流程
|
||
|
||
1. 本地构建：`npm run build`
|
||
2. 根据上线需求选择：
|
||
- `./deploy.sh`：快速增量部署
|
||
- `./deploy-full.sh`：完整部署，包含权限校验、压缩检测
|
||
3. 部署验证请参考 `docs/DEPLOYMENT.md` 与 `docs/DEPLOY_FULL_VERIFICATION.md`
|
||
4. 上线后建议检查服务器日志与浏览器控制台，确保资源加载正常。
|
||
|
||
## 调试技巧
|
||
|
||
- 利用浏览器 DevTools 观察 CSS 变量与动画帧率。
|
||
- Astro CLI 支持 `--open`、`--host`，例如 `npm run dev -- --host` 供局域网调试。
|
||
- 对滚动行为可在控制台监听 `scroll-progress` 脚本的状态输出。
|
||
- 若遇到类型问题，运行 `npm run astro check -- --watch` 进行持续监控。
|
||
|
||
## 技术栈
|
||
|
||
- **Astro**：静态站点生成 + 部分组件岛屿渲染。
|
||
- **Tailwind CSS**：实用类样式与主题扩展。
|
||
- **TypeScript**：类型安全与更佳的开发体验。
|
||
- **Font Awesome / 自定义图标**：图标资源。
|
||
- **Vite**：开发服务器与构建工具。
|
||
|
||
## 贡献指南
|
||
|
||
欢迎提交 Issue 或 Pull Request 改进项目。建议遵循以下流程：
|
||
|
||
1. Fork 仓库并创建新分支。
|
||
2. 完成改动后运行 `npm run build` 与相关检查。
|
||
3. 提交 PR 并在描述中说明变更内容及影响范围。
|
||
|
||
<!-- ...existing code... --> |