286 lines
5.5 KiB
Markdown
286 lines
5.5 KiB
Markdown
# 开发文档
|
||
|
||
## 快速开始
|
||
|
||
### 开发环境要求
|
||
- 现代浏览器（Chrome/Firefox/Safari/Edge 最新版本）
|
||
- 代码编辑器（推荐 VS Code）
|
||
- 本地服务器（可选，用于开发）
|
||
|
||
### 环境设置
|
||
1. 克隆项目：
|
||
```bash
|
||
git clone [repository-url]
|
||
cd [project-name]
|
||
```
|
||
|
||
2. VS Code 推荐插件：
|
||
- Live Server（实时预览）
|
||
- Prettier（代码格式化）
|
||
- ESLint（代码检查）
|
||
- CSS Peek（CSS 查看）
|
||
|
||
3. 启动开发服务器：
|
||
```bash
|
||
# 使用 Python
|
||
python -m http.server 8000
|
||
|
||
# 或使用 VS Code Live Server
|
||
# 右键 index.html -> Open with Live Server
|
||
```
|
||
|
||
## 项目架构
|
||
|
||
### 整体架构
|
||
```
|
||
[项目根目录]
|
||
├── index.html # 主页面
|
||
├── style.css # 样式文件
|
||
├── script.js # 主脚本
|
||
├── README.md # 项目说明
|
||
└── DEVELOPMENT.md # 开发文档
|
||
```
|
||
|
||
### 核心模块说明
|
||
|
||
#### 1. 页面管理模块
|
||
```javascript
|
||
// 页面切换核心函数
|
||
function showPage(pageId, skipSearchReset = false) {
|
||
// pageId: 目标页面ID
|
||
// skipSearchReset: 是否跳过搜索重置
|
||
}
|
||
|
||
// 使用示例：
|
||
showPage('home'); // 切换到首页
|
||
showPage('projects', true); // 切换到项目页，保持搜索状态
|
||
```
|
||
|
||
#### 2. 搜索引擎模块
|
||
```javascript
|
||
// 搜索实现核心函数
|
||
function performSearch(searchTerm) {
|
||
// searchTerm: 搜索关键词
|
||
// 返回：匹配的结果
|
||
}
|
||
|
||
// 搜索结果处理
|
||
function handleSearchResults(results) {
|
||
// results: 搜索结果数组
|
||
}
|
||
```
|
||
|
||
#### 3. 动画系统
|
||
```css
|
||
/* 页面切换动画 */
|
||
.page {
|
||
transition: opacity 0.3s ease, transform 0.3s ease;
|
||
}
|
||
|
||
/* 搜索结果动画 */
|
||
.search-section {
|
||
transition: opacity 0.3s ease, transform 0.3s ease;
|
||
}
|
||
```
|
||
|
||
## 开发指南
|
||
|
||
### 1. 添加新页面
|
||
|
||
1. HTML 结构：
|
||
```html
|
||
<div class="page" id="your-page-id">
|
||
<div class="welcome-section">
|
||
<h2>页面标题</h2>
|
||
<p class="subtitle">页面描述</p>
|
||
</div>
|
||
|
||
<section class="category">
|
||
<h2><i class="fas fa-icon"></i> 分类标题</h2>
|
||
<div class="sites-grid">
|
||
<!-- 网站卡片 -->
|
||
</div>
|
||
</section>
|
||
</div>
|
||
```
|
||
|
||
2. 注册导航：
|
||
```html
|
||
<a href="#" class="nav-item" data-page="your-page-id">
|
||
<i class="fas fa-icon"></i>
|
||
<span>页面名称</span>
|
||
</a>
|
||
```
|
||
|
||
3. 添加样式：
|
||
```css
|
||
#your-page-id {
|
||
/* 页面特定样式 */
|
||
}
|
||
|
||
#your-page-id .category {
|
||
/* 分类样式 */
|
||
}
|
||
```
|
||
|
||
### 2. 自定义搜索范围
|
||
|
||
1. 修改搜索逻辑：
|
||
```javascript
|
||
function performSearch(searchTerm) {
|
||
// 1. 在 script.js 中找到 performSearch 函数
|
||
// 2. 添加新的搜索范围：
|
||
const newPageCards = document.querySelectorAll('#your-page-id .site-card');
|
||
newPageCards.forEach(card => {
|
||
// 添加搜索逻辑
|
||
});
|
||
}
|
||
```
|
||
|
||
2. 添加结果展示区域：
|
||
```html
|
||
<section class="category search-section" data-section="your-page-id">
|
||
<h2><i class="fas fa-icon"></i> 新页面匹配项</h2>
|
||
<div class="sites-grid"></div>
|
||
</section>
|
||
```
|
||
|
||
### 3. 添加新功能
|
||
|
||
1. 创建功能模块：
|
||
```javascript
|
||
// 在 script.js 中添加新模块
|
||
const newFeature = {
|
||
init() {
|
||
// 初始化代码
|
||
},
|
||
|
||
// 功能方法
|
||
someMethod() {
|
||
// 方法实现
|
||
}
|
||
};
|
||
|
||
// 初始化
|
||
document.addEventListener('DOMContentLoaded', () => {
|
||
newFeature.init();
|
||
});
|
||
```
|
||
|
||
2. 添加相关样式：
|
||
```css
|
||
/* 在 style.css 中添加样式 */
|
||
.new-feature {
|
||
/* 功能相关样式 */
|
||
}
|
||
```
|
||
|
||
## 性能优化指南
|
||
|
||
### 1. 动画性能优化
|
||
```css
|
||
/* 使用 transform 代替位置属性 */
|
||
.element {
|
||
transform: translateX(100px);
|
||
will-change: transform;
|
||
}
|
||
|
||
/* 使用 opacity 代替 visibility */
|
||
.element {
|
||
opacity: 0;
|
||
transition: opacity 0.3s ease;
|
||
}
|
||
```
|
||
|
||
### 2. 搜索性能优化
|
||
```javascript
|
||
// 实现防抖
|
||
const debounce = (fn, delay) => {
|
||
let timer = null;
|
||
return (...args) => {
|
||
if (timer) clearTimeout(timer);
|
||
timer = setTimeout(() => {
|
||
fn.apply(this, args);
|
||
}, delay);
|
||
};
|
||
};
|
||
|
||
// 使用 Map 优化查找
|
||
const searchIndex = new Map();
|
||
```
|
||
|
||
### 3. DOM 操作优化
|
||
```javascript
|
||
// 使用文档片段
|
||
const fragment = document.createDocumentFragment();
|
||
elements.forEach(el => fragment.appendChild(el));
|
||
container.appendChild(fragment);
|
||
|
||
// 批量更新
|
||
requestAnimationFrame(() => {
|
||
// DOM 更新操作
|
||
});
|
||
```
|
||
|
||
## 调试技巧
|
||
|
||
### 1. 常见问题排查
|
||
```javascript
|
||
// 页面切换问题
|
||
console.log('当前页面:', currentPageId);
|
||
console.log('搜索状态:', isSearchActive);
|
||
|
||
// 搜索问题
|
||
console.log('搜索词:', searchTerm);
|
||
console.log('结果数:', results.length);
|
||
```
|
||
|
||
### 2. 性能监控
|
||
```javascript
|
||
// 性能标记
|
||
performance.mark('featureStart');
|
||
// ... 代码执行 ...
|
||
performance.mark('featureEnd');
|
||
performance.measure('featureDuration', 'featureStart', 'featureEnd');
|
||
```
|
||
|
||
## 发布流程
|
||
|
||
### 1. 代码检查
|
||
```bash
|
||
# 运行代码格式化
|
||
prettier --write "**/*.{html,css,js}"
|
||
|
||
# 运行代码检查
|
||
eslint "**/*.js"
|
||
```
|
||
|
||
### 2. 性能测试
|
||
- 使用 Chrome DevTools 的 Performance 面板
|
||
- 检查页面加载时间
|
||
- 检查动画性能
|
||
- 内存使用监控
|
||
|
||
### 3. 部署前检查清单
|
||
- [ ] 所有链接可访问
|
||
- [ ] 响应式布局正常
|
||
- [ ] 搜索功能正常
|
||
- [ ] 动画效果流畅
|
||
- [ ] 控制台无错误
|
||
|
||
## 维护指南
|
||
|
||
### 1. 代码更新
|
||
- 遵循语义化版本控制
|
||
- 保持文档同步更新
|
||
- 记录重要更改
|
||
|
||
### 2. 性能监控
|
||
- 定期检查性能指标
|
||
- 分析用户反馈
|
||
- 优化改进建议
|
||
|
||
### 3. 问题追踪
|
||
- 使用 GitHub Issues 跟踪问题
|
||
- 详细记录问题复现步骤
|
||
- 及时响应用户反馈 |