nanhaoluo
1c696a9f26
- 添加项目文件结构说明 - 添加 style.css 和 argontheme.js 的模块结构 - 添加需要保留 var 的全局变量列表 - 添加 CSS/JS/PHP 注释规范示例 - 添加规范化历史记录
173 lines
3.7 KiB
Markdown
173 lines
3.7 KiB
Markdown
# Argon 主题代码规范
|
||
|
||
## 项目文件结构
|
||
|
||
### 核心文件
|
||
| 文件 | 说明 | 行数 |
|
||
|------|------|------|
|
||
| `style.css` | 主题样式，包含所有 CSS | ~12000 行 |
|
||
| `argontheme.js` | 主题核心 JS | ~3700 行 |
|
||
| `functions.php` | WordPress 函数 | ~5700 行 |
|
||
| `settings.php` | 后台设置页面 | ~6000 行 |
|
||
|
||
### style.css 结构
|
||
```
|
||
1. CSS 变量定义 (:root)
|
||
- 主题色系统 (--themecolor-*)
|
||
- 颜色变量 (--color-*)
|
||
- 动画系统 (--animation-*, --ease-*)
|
||
2. 夜间模式配色 (html.darkmode)
|
||
3. AMOLED 夜间模式
|
||
4. 沉浸式主题色
|
||
5. 主题切换过渡效果
|
||
6. Argon 框架样式覆盖
|
||
7. 基础样式
|
||
8. 页面布局 (单栏/双栏/三栏)
|
||
9. 顶栏和 Banner
|
||
10. 侧边栏
|
||
11. 文章样式
|
||
12. 评论区
|
||
13. 浮动按钮
|
||
14. 响应式适配
|
||
```
|
||
|
||
### argontheme.js 结构
|
||
```
|
||
1. 兼容性修复 - 第三方库 polyfill
|
||
2. 全局配置 - argonConfig 初始化
|
||
3. 工具函数 - Cookie、翻译等
|
||
4. 顶栏功能 - 透明度、搜索
|
||
5. 侧边栏 - 浮动、滚动
|
||
6. 文章列表 - 瀑布流布局
|
||
7. 浮动按钮 - 回顶、设置
|
||
8. 评论系统 - 发送、回复、编辑
|
||
9. 代码高亮 - Prism 增强
|
||
10. PJAX - 页面无刷新加载
|
||
```
|
||
|
||
### 全局变量（需保留 var）
|
||
- `argonConfig` - 主题配置对象
|
||
- `translation` - 多语言翻译表
|
||
- `pjaxLoading` - PJAX 加载状态
|
||
- `headroom` - Headroom 实例
|
||
|
||
---
|
||
|
||
## CSS 规范
|
||
|
||
### 格式化规则
|
||
- 使用 Tab 缩进（1 Tab = 4 空格宽度）
|
||
- 每个属性独占一行
|
||
- 属性之间不要有空行
|
||
- 规则块之间保留一个空行
|
||
- 选择器与 `{` 之间有一个空格
|
||
- 属性值后的 `;` 前不要有空格
|
||
|
||
### 示例
|
||
```css
|
||
/* 正确 */
|
||
.selector {
|
||
property: value;
|
||
another-property: value;
|
||
}
|
||
|
||
.another-selector {
|
||
property: value;
|
||
}
|
||
|
||
/* 错误 - 属性之间有空行 */
|
||
.selector {
|
||
|
||
property: value;
|
||
|
||
another-property: value;
|
||
|
||
}
|
||
```
|
||
|
||
### 注释规范
|
||
```css
|
||
/* ==========================================================================
|
||
大区块标题
|
||
========================================================================== */
|
||
|
||
/* ---------- 小区块标题 ---------- */
|
||
|
||
/* 普通注释 */
|
||
```
|
||
|
||
---
|
||
|
||
## JavaScript 规范
|
||
|
||
### 格式化规则
|
||
- 使用 Tab 缩进
|
||
- 字符串优先使用单引号 `'`
|
||
- 比较运算符使用严格相等 `===` 和 `!==`
|
||
- 语句末尾必须有分号 `;`
|
||
- 函数名与括号之间无空格
|
||
- 关键字后有空格（if, for, while, function 等）
|
||
|
||
### 变量声明
|
||
- 优先使用 `let` 和 `const`
|
||
- 避免使用 `var`（除非需要函数作用域或全局变量）
|
||
|
||
### 注释规范
|
||
```javascript
|
||
// ==========================================================================
|
||
// 大区块标题
|
||
// ==========================================================================
|
||
|
||
// ---------- 小区块标题 ----------
|
||
|
||
/**
|
||
* 函数说明
|
||
* @param {string} param - 参数说明
|
||
* @returns {boolean} 返回值说明
|
||
*/
|
||
function functionName(param) {
|
||
// 单行注释
|
||
if (param === 'value') {
|
||
return true;
|
||
}
|
||
return false;
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## PHP 规范
|
||
|
||
### 格式化规则
|
||
- 使用 Tab 缩进
|
||
- 字符串优先使用单引号
|
||
- 数组使用短语法 `[]`
|
||
- 类名使用 PascalCase
|
||
- 函数名使用 snake_case（遵循 WordPress 规范）
|
||
- 箭头操作符 `->` 前后不要有空格
|
||
|
||
### WordPress 特定
|
||
- 使用 `esc_html()`, `esc_attr()` 等函数转义输出
|
||
- 使用 `wp_nonce_field()` 进行安全验证
|
||
- 遵循 WordPress Coding Standards
|
||
|
||
### 示例
|
||
```php
|
||
// 正确
|
||
$theme->Version
|
||
get_option('argon_theme_color')
|
||
|
||
// 错误
|
||
$theme -> Version
|
||
```
|
||
|
||
---
|
||
|
||
## 规范化历史
|
||
|
||
### 2026-01-16 规范化
|
||
- CSS: 移除 4292 行多余空行，添加结构化注释
|
||
- JS: 89 个 var 改为 let，添加模块目录和 JSDoc
|
||
- PHP: 修复 200+ 处箭头操作符空格问题
|
||
- 备份位置: `tmp/` 目录
|