Initial commit

2025-01-31 20:28:13 +08:00
parent a85d49cc16
commit 4b05fd9bb3
6 changed files with 1427 additions and 0 deletions
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -0,0 +1,286 @@
+# 开发文档
+
+## 快速开始
+
+### 开发环境要求
+- 现代浏览器（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 跟踪问题
+- 详细记录问题复现步骤
+- 及时响应用户反馈