# Argon 主题开发文档

## 项目概述

Argon 是一款基于 WordPress 的现代化博客主题，采用 Material Design 设计语言，提供丰富的功能和高度的可定制性。

### 核心特性

- Material Design 风格界面
- 响应式布局，支持多种页面布局模式（单栏/双栏/三栏）
- 夜间模式与 AMOLED 暗黑模式
- 沉浸式主题色系统
- PJAX 无刷新页面加载
- 瀑布流文章列表布局
- 完整的评论系统（支持 Markdown、表情、点赞、置顶）
- 说说功能（类似微博的短内容发布）
- AI 摘要生成
- 代码高亮与数学公式渲染
- 友链管理系统
- 反馈系统
- 性能优化模块

### 技术栈

- PHP 7.0+
- WordPress 4.4+
- jQuery 3.x
- Bootstrap 4 (Argon Design System)
- Highlight.js (代码高亮)
- MathJax/KaTeX (数学公式)
- Headroom.js (顶栏自动隐藏)

## 项目文件结构

### 核心文件

```
argon/
├── style.css                    # 主题样式表 (核心样式定义，包含配色、排版、组件样式)
├── argontheme.js               # 主题核心 JavaScript (负责 PJAX、界面交互、功能初始化)
├── functions.php               # WordPress 主题函数 (功能入口、Hook 挂载、核心逻辑实现)
├── settings.php                # 后台设置页面 (提供外观、功能开关等配置选项)
├── header.php                  # 页面头部模板 (HTML Head、顶部导航栏、全局变量输出)
├── footer.php                  # 页面底部模板 (页脚区域、JavaScript 脚本引入)
├── index.php                   # 首页模板 (文章列表展示)
├── single.php                  # 文章页模板 (单篇文章内容展示)
├── page.php                    # 页面模板 (独立页面展示)
├── archive.php                 # 归档页模板 (分类、标签、日期归档)
├── search.php                  # 搜索结果页模板
├── 404.php                     # 404 错误页面模板
├── comments.php                # 评论区模板 (评论列表与发表评论表单)
├── sidebar.php                 # 侧边栏模板 (个人信息卡片、小工具挂载点)
├── admin.css                   # 后台设置页面样式
└── languages/                  # 多语言包目录 (.po/.mo 文件)
```

### 功能模块文件


```
argon/
├── shuoshuo.php                # 说说页面模板
├── timeline.php                # 时间线页面模板
├── msgboard.php                # 留言板页面模板
├── friend-links.php            # 友链页面模板
├── feedback.php                # 反馈系统
├── emotions.php                # 表情系统
├── parsedown.php               # Markdown 解析器
├── useragent-parser.php        # User Agent 解析
├── ai-summary-query.php        # AI 摘要查询接口
├── unsubscribe-comment-mailnotice.php  # 评论邮件退订
└── argon-performance.js        # 性能优化模块
```

### 模板片段

```
template-parts/
├── content-single.php          # 单篇文章内容
├── content-page.php            # 页面内容
├── content-preview-1.php       # 文章预览样式 1
├── content-preview-2.php       # 文章预览样式 2
├── content-preview-3.php       # 文章预览样式 3
├── content-shuoshuo.php        # 说说内容
├── content-shuoshuo-preview.php # 说说预览
├── content-shuoshuo-details.php # 说说详情
├── content-timeline.php        # 时间线内容
├── content-none-search.php     # 搜索无结果
├── content-none-tag.php        # 标签无结果
├── ai-summary.php              # AI 摘要组件
├── emotion-keyboard.php        # 表情键盘
├── post-actions.php            # 文章操作按钮
└── shuoshuo-operations.php     # 说说操作按钮
```

### 资源文件

```
assets/
├── css/
│   ├── argon.css              # Argon Design System 样式
│   └── bootstrap/             # Bootstrap 样式
├── js/
│   ├── argon.js               # Argon Design System 脚本
│   └── easter-egg.js          # 彩蛋功能
├── img/                       # 图片资源
├── icons/                     # 图标资源
├── vendor/                    # 第三方库
├── tinymce_assets/            # TinyMCE 编辑器资源
├── argon_css_merged.css       # 合并后的 CSS
└── argon_js_merged.js         # 合并后的 JS
```

### 邮件模板

```
email-templates/
├── base.php                   # 邮件模板基类
├── comment-notify.php         # 评论通知
├── reply-notify.php           # 回复通知
├── feedback-notify.php        # 反馈通知
├── spam-notify.php            # 垃圾评论通知
├── blacklist-spam-notify.php  # 黑名单垃圾评论通知
└── username-change-notify.php # 用户名变更通知
```


## 代码规范

### 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`（除非需要函数作用域或全局变量）

#### 全局变量（需保留 var）

以下全局变量必须使用 `var` 声明以确保跨作用域访问：

- `argonConfig` - 主题配置对象
- `translation` - 多语言翻译表
- `pjaxLoading` - PJAX 加载状态
- `headroom` - Headroom 实例

#### 注释规范

```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
```


## 核心架构

### 主题初始化流程

主题的初始化分为服务器端（PHP）和客户端（JavaScript）两个阶段。

#### 服务器端初始化

1. **functions.php 加载**（WordPress 加载主题时执行）

```php
// functions.php
// 检查 WordPress 版本兼容性
if (version_compare($GLOBALS['wp_version'], '4.4-alpha', '<')) {
	echo "<div style='...'>Argon 主题不支持 Wordpress 4.4 以下版本</div>";
}

// 设置主题支持功能
function theme_slug_setup() {
	add_theme_support('title-tag');        // 标题标签
	add_theme_support('post-thumbnails');  // 特色图片
	load_theme_textdomain('argon', get_template_directory() . '/languages');  // 多语言
}
add_action('after_setup_theme','theme_slug_setup');

// 设置全局变量
$argon_version = !(wp_get_theme()->Template) ? wp_get_theme()->Version : wp_get_theme(wp_get_theme()->Template)->Version;
$GLOBALS['theme_version'] = $argon_version;
$GLOBALS['assets_path'] = get_bloginfo('template_url');
```

2. **导航菜单注册**
	
	主题通过 `init` 挂钩注册了四个核心菜单位置，用于定义页面的不同导航区域：

	```php
	// functions.php
	function init_nav_menus(){
		register_nav_menus( array(
			'toolbar_menu' => __('顶部导航', 'argon'),             // 顶部工具栏菜单
			'leftbar_menu' => __('左侧栏菜单', 'argon'),           // 左侧主要导航菜单
			'leftbar_author_links' => __('左侧栏作者个人链接', 'argon'), // 左侧作者信息下方的图标链接
			'leftbar_friend_links' => __('左侧栏友情链接', 'argon')  // 左侧底部的友情链接区域
		));
	}
	add_action('init', 'init_nav_menus');
	```

	3. **header.php 渲染**（输出 HTML 头部）

```php
// header.php
// 1. 生成 HTML 类名（根据后台设置）
$htmlclasses = "";
if (get_option('argon_page_layout') == "single"){
	$htmlclasses .= "single-column ";
}
if (get_option('argon_enable_immersion_color') == "true"){
	$htmlclasses .= "immersion-color ";
}
// ... 更多类名

// 2. 获取主题色配置
$themecolor = get_option("argon_theme_color", "#5e72e4");
if (isset($_COOKIE["argon_custom_theme_color"])){
	if (checkHEX($_COOKIE["argon_custom_theme_color"]) && 
	    get_option('argon_show_customize_theme_color_picker') != 'false'){
		$themecolor = $_COOKIE["argon_custom_theme_color"];
	}
}

// 3. 输出 HTML 文档头
?>
<html <?php language_attributes(); ?> class="no-js <?php echo $htmlclasses;?>">
<head>
	<meta charset="<?php bloginfo('charset'); ?>">
	<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no">
	<meta name="theme-color" content="<?php echo $themecolor; ?>">
	
	<!-- 预加载用户样式设置 - 避免样式跳变 -->
	<script>
	(function() {
		var html = document.documentElement;
		var ls = localStorage;
		
		// 字体设置
		if (ls.getItem('Argon_Use_Serif') === 'true') {
			html.classList.add('use-serif');
		}
		// 阴影设置
		if (ls.getItem('Argon_Use_Big_Shadow') === 'true') {
			html.classList.add('use-big-shadow');
		}
		// ... 更多设置
	})();
	</script>
	
	<?php
	// 4. 加载 CSS 和 JavaScript
	$assets_version = argon_get_assets_version();
	wp_enqueue_style("argon_css_merged", $GLOBALS['assets_path'] . "/assets/argon_css_merged.css", array(), $assets_version, 'all');
	wp_enqueue_style("style", $GLOBALS['assets_path'] . "/style.css", array('argon_css_merged'), $assets_version, 'all');
	wp_enqueue_script("argon_js_merged", $GLOBALS['assets_path'] . "/assets/argon_js_merged.js", array(), $assets_version, false);
	?>
	
	<?php wp_head(); ?>
	
	<!-- 5. 输出动态 CSS 变量 -->
	<style id="themecolor_css">
	:root{
		--themecolor: <?php echo $themecolor; ?>;
		--themecolor-R: <?php echo $RGB['R']; ?>;
		--themecolor-G: <?php echo $RGB['G']; ?>;
		--themecolor-B: <?php echo $RGB['B']; ?>;
		--themecolor-H: <?php echo $HSL['H']; ?>;
		--themecolor-S: <?php echo $HSL['S']; ?>;
		--themecolor-L: <?php echo $HSL['L']; ?>;
	}
	</style>
	
	<!-- 6. 输出全局配置对象 -->
	<script>
	document.documentElement.classList.remove("no-js");
	var argonConfig = {
		wp_path: "<?php echo $GLOBALS['wp_path']; ?>",
		language: "<?php echo argon_get_locate(); ?>",
		// ... 更多配置
	};
	</script>
	
	<!-- 7. 夜间模式初始化脚本 -->
	<script>
	var darkmodeAutoSwitch = "<?php echo get_option("argon_darkmode_autoswitch");?>";
	function setDarkmode(enable){ /* ... */ }
	function toggleDarkmode(){ /* ... */ }
	// ... 夜间模式逻辑
	</script>
</head>
```

#### 客户端初始化

1. **兼容性修复**（argontheme.js 开头）

```javascript
// argontheme.js
// 确保 Prism 存在
if (typeof window.Prism === 'undefined') {
	window.Prism = { 
		highlightAll: function() {},
		highlightElement: function() {},
		plugins: {}
	};
}

// 确保 jQuery 插件存在
if (typeof jQuery !== 'undefined') {
	(function($) {
		// 修复空选择器问题
		if (!$.fn._argonInit) {
			$.fn._argonInit = $.fn.init;
			$.fn.init = function(selector, context, root) {
				if (typeof selector === 'string') {
					let trimmed = selector.trim();
					if (trimmed === '' || trimmed === '#') {
						return new $.fn._argonInit();
					}
				}
				return $.fn._argonInit.call(this, selector, context, root);
			};
			$.fn.init.prototype = $.fn;
		}
	})(jQuery);
}
```

2. **工具函数定义**

```javascript
// argontheme.js
// Cookie 操作
function setCookie(cname, cvalue, exdays) { /* ... */ }
function getCookie(cname) { /* ... */ }

// 多语言翻译
var translation = {};
translation['en_US'] = { /* ... */ };
translation['ru_RU'] = { /* ... */ };
function __(text) {
	if (typeof translation[argonConfig.language] !== 'undefined' && 
	    typeof translation[argonConfig.language][text] !== 'undefined') {
		return translation[argonConfig.language][text];
	}
	return text;
}
```

3. **DOM 加载完成后初始化**

```javascript
// argontheme.js
$(document).ready(function() {
	// 初始化顶栏
	initNavbar();
	
	// 初始化侧边栏
	initSidebar();
	
	// 初始化瀑布流
	waterflowInit();
	
	// 初始化懒加载
	if (argonConfig.lazyload) {
		initLazyload();
	}
	
	// 初始化图片缩放
	if (argonConfig.zoomify) {
		$('.post-content img').zoomify(argonConfig.zoomify);
	}
	
	// 初始化代码高亮
	if (argonConfig.code_highlight.enable) {
		initCodeHighlight();
	}
	
	// 初始化评论系统
	initCommentSystem();
	
	// 初始化浮动按钮
	initFloatButtons();
	
	// 初始化 PJAX
	if (!argonConfig.disable_pjax) {
		initPjax();
	}
	
	// 移除加载类
	$('#float_action_buttons').removeClass('fabtns-unloaded');
});
```

#### 资源加载策略

1. **CSS 加载顺序**

```php
// header.php
// 1. 合并的 CSS（包含 Bootstrap 和 Argon Design System）
wp_enqueue_style("argon_css_merged", ".../argon_css_merged.css");

// 2. 主题样式（依赖合并的 CSS）
wp_enqueue_style("style", ".../style.css", array('argon_css_merged'));
```

2. **JavaScript 加载顺序**

```php
// header.php
// 1. 资源加载器（用于备用资源加载）
wp_enqueue_script("resource_loader", ".../resource-loader.js");

// 2. 合并的 JS（包含 jQuery 和其他库）- 在头部同步加载
wp_enqueue_script("argon_js_merged", ".../argon_js_merged.js", array(), $assets_version, false);

// 3. Argon 修复补丁（必须在 wp_head() 之后）
<script src="<?php echo get_template_directory_uri(); ?>/assets/js/argon.min.js?ver=<?php echo $assets_version; ?>"></script>

// 4. 主题核心脚本（在 footer.php 中加载）
<?php $assets_version = function_exists('argon_get_assets_version') ? argon_get_assets_version() : $GLOBALS['theme_version']; ?>
<script src="<?php echo $GLOBALS['assets_path']; ?>/argontheme.js?v=<?php echo $assets_version; ?>"></script>
```

3. **按需加载**

```javascript
// argontheme.js
// Google Fonts 按需加载
if (typeof ArgonResourceLoader !== "undefined") {
	ArgonResourceLoader.smartLoad("//fonts.googleapis.com/css?family=...", "css");
}

// 数学公式渲染库在 footer.php 中按设置输出（get_option('argon_math_render')）
// 可选：mathjax3 / mathjax2 / katex / disabled
```

#### 强制刷新机制

当主题更新后，可能需要清除客户端缓存：

```php
// functions.php
function argon_is_force_refresh_enabled() {
	$enabled_time = get_option('argon_force_refresh_enabled_time', 0);
	if ($enabled_time == 0) {
		return false;
	}
	// 1 小时后自动关闭
	if (time() - $enabled_time > 3600) {
		update_option('argon_force_refresh_enabled_time', 0);
		return false;
	}
	return true;
}

function argon_get_assets_version() {
	if (argon_is_force_refresh_enabled()) {
		$enabled_time = get_option('argon_force_refresh_enabled_time', 0);
		return $GLOBALS['theme_version'] . '.r' . $enabled_time;
	}
	return $GLOBALS['theme_version'];
}
```

强制刷新时，header.php 会输出清除缓存的脚本：

```javascript
// header.php
<?php if (argon_is_force_refresh_enabled()): ?>
<script>
(function() {
	var forceRefreshKey = 'argon_force_refresh_version';
	var currentVersion = '<?php echo get_option('argon_force_refresh_enabled_time', 0); ?>';
	var lastVersion = localStorage.getItem(forceRefreshKey);
	
	if (lastVersion !== currentVersion) {
		localStorage.setItem(forceRefreshKey, currentVersion);
		if (lastVersion !== null) {
			// 清除所有缓存
			if ('caches' in window) {
				caches.keys().then(function(names) {
					return Promise.all(names.map(function(name) {
						return caches.delete(name);
					}));
				});
			}
			// 重新加载页面
			window.location.reload();
		}
	}
})();
</script>
<?php endif; ?>
```

### 全局配置对象

`argonConfig` 是主题的核心配置对象，在 header.php 中通过 PHP 动态生成并输出到页面：

```javascript
var argonConfig = {
	wp_path: "/",                    // WordPress 安装路径
	language: "zh_CN",               // 当前语言代码
	dateFormat: "YMD",               // 日期显示格式
	
	// 图片缩放配置（Zoomify）
	zoomify: {
		duration: 200,               // 缩放动画时长（毫秒）
		easing: "cubic-bezier(0.4,0,0,1)", // 缓动函数
		scale: 0.9                   // 缩放比例
	},
	// 如果禁用则为 false
	
	pangu: "false",                  // 盘古之白（中英文间自动加空格）
	
	// 懒加载配置
	lazyload: true,                  // 是否启用懒加载
	lazyload_effect: "fadeIn",       // 懒加载显示效果
	lazyload_threshold: 800,         // 提前加载阈值（像素）
	
	fold_long_comments: false,       // 是否折叠长评论
	fold_long_shuoshuo: false,       // 是否折叠长说说
	
	// PJAX 配置
	disable_pjax: false,             // 是否禁用 PJAX
	pjax_animation_durtion: 600,     // PJAX 切换动画时长（毫秒）
	
	headroom: "false",               // 顶栏自动隐藏模式（false/true/absolute）
	
	// 文章列表布局
	waterflow_columns: "1",          // 瀑布流列数（1/2/3）
	article_list_layout_mobile: "1", // 移动端文章列表布局样式
	
	// 代码高亮配置
	code_highlight: {
		enable: false,               // 是否启用代码高亮
		hide_linenumber: false,      // 是否隐藏行号
		transparent_linenumber: false, // 行号是否透明
		break_line: false            // 是否自动折行
	}
};
```

配置对象的值从 WordPress 后台设置中读取，通过 PHP 的 `get_option()` 函数获取。例如：

```php
// header.php
lazyload: <?php echo (get_option('argon_enable_lazyload', 'true') == 'false' ? 'false' : 'true'); ?>,
```

### CSS 变量系统

主题使用 CSS 自定义属性（CSS Variables）实现动态主题色和样式配置。这些变量在 header.php 中通过 PHP 动态生成。

#### 主题色变量

```php
// header.php - 获取主题色
$themecolor = get_option("argon_theme_color", "#5e72e4");
// 支持用户自定义主题色（通过 Cookie）
if (isset($_COOKIE["argon_custom_theme_color"])) {
	if (checkHEX($_COOKIE["argon_custom_theme_color"]) && 
	    get_option('argon_show_customize_theme_color_picker') != 'false') {
		$themecolor = $_COOKIE["argon_custom_theme_color"];
	}
}

// 转换为 RGB 和 HSL 值
$RGB = hexstr2rgb($themecolor);
$HSL = rgb2hsl($RGB['R'], $RGB['G'], $RGB['B']);
```

生成的 CSS 变量：

```css
:root {
	/* 主题色 - 十六进制 */
	--themecolor: #5e72e4;
	
	/* 主题色 - RGB 分量（用于 rgba() 函数）*/
	--themecolor-R: 94;
	--themecolor-G: 114;
	--themecolor-B: 228;
	
	/* 主题色 - HSL 分量（用于生成色调变体）*/
	--themecolor-H: 231;
	--themecolor-S: 71;
	--themecolor-L: 63;
}
```

#### 动画系统变量

```css
:root {
	/* 动画时长 - 遵循 Material Design 3 规范 */
	--animation-fast: 150ms;      // 快速动画（按钮点击等）
	--animation-normal: 250ms;    // 标准动画（卡片展开等）
	--animation-slow: 400ms;      // 慢速动画（页面切换等）
	
	/* 缓动函数 - 融合 Material 3 + Apple 风格 */
	--ease-standard: cubic-bezier(0.25, 0.1, 0.25, 1);  // 标准缓动，流畅自然
	--ease-spring: cubic-bezier(0.34, 1.56, 0.64, 1);   // 弹性缓动，有活力
}
```

#### 卡片样式变量

```css
:root {
	--card-radius: 4px;           // 卡片圆角
	--card-opacity: 0.7;          // 卡片透明度
	--card-blur: 20px;            // 毛玻璃模糊度
	--card-saturate: 180%;        // 饱和度增强
	--toolbar-blur: 12px;         // 顶栏模糊度（卡片的 60%）
	--page-background-opacity: 1; // 页面背景透明度
}
```

这些值可以通过后台设置动态调整：

```php
// header.php
$card_opacity = get_option('argon_post_background_opacity', '0.7');
$card_blur = get_option('argon_card_blur', '20');
$card_saturate = get_option('argon_card_saturate', '180');
```

#### 颜色变量

```css
:root {
	/* 日间模式颜色 */
	--color-background: #f4f5f7;   // 页面背景色
	--color-foreground: #fff;      // 卡片背景色
	--color-widgets: #fff;         // 小工具背景色
	--color-border: #dce0e5;       // 边框颜色
	--color-text-deeper: #212529;  // 深色文本
}
```

夜间模式通过 `html.darkmode` 类切换颜色变量：

```css
html.darkmode body {
	--color-background: #282828;   // 深色背景
	--color-foreground: #424242;   // 深色卡片
	--color-widgets: #555;         // 深色小工具
	--color-text-deeper: #eee;     // 浅色文本
}
```

AMOLED 暗黑模式提供更深的黑色：

```css
html.darkmode.amoled-dark body {
	--color-background: #111;      // 纯黑背景
	--color-foreground: #000;      // 纯黑卡片
	--color-widgets: #151515;      // 深黑小工具
}
```



### 后台设置框架

Argon 主题不依赖第三方设置框架（如 Redux 或 Codestar），而是使用原生 PHP + HTML 实现了一个轻量级的设置页面。

#### 1. 设置页面结构

设置页面位于 `settings.php`，通过 `functions.php` 中的 `add_theme_page` 挂载：

```php
// functions.php
function themeoptions_admin_menu() {
    add_theme_page("Argon 主题设置", "Argon 主题选项", 'edit_themes', basename(__FILE__), 'themeoptions_page');
}
add_action('admin_menu', 'themeoptions_admin_menu');
```

页面内容主要由 `themeoptions_page()` 函数输出，采用 HTML Table 布局，包含多个选项卡（如“全局设置”、“侧栏设置”等）。

#### 2. 选项存储与更新

设置数据的保存逻辑集成在 `settings.php` 顶部：

```php
// settings.php
if (isset($_POST['update_themeoptions']) && $_POST['update_themeoptions'] == 'true') {
    // 1. 验证 Nonce 安全令牌
    check_admin_referer('argon_update_themeoptions', 'argon_update_themeoptions_nonce');
    
    // 2. 处理复选框（未选中的 checkbox 不会提交，需要手动设为 false）
    if (!isset($_POST['argon_enable_lazyload'])) $_POST['argon_enable_lazyload'] = 'false';
    
    // 3. 循环更新所有选项
    foreach ($_POST as $key => $value) {
        if (isset($value) && $value != '') {
            update_option($key, $value);
        } else {
            delete_option($key); // 空值则删除选项
        }
    }
    
    // 4. 提示保存成功
    echo '<div id="message" class="updated fade"><p><strong>设置已保存</strong></p></div>';
}
```

#### 3. 添加新选项指南

要在主题中添加一个新的设置项，需遵循以下步骤：

1.  在 `settings.php` 的对应表格行中添加 HTML 输入控件。
2.  `name` 属性必须以 `argon_` 开头（这是约定，方便管理）。
3.  使用 `get_option('option_name')` 获取当前值回显。

示例：添加一个“显示版权信息”的开关

```php
<tr>
    <th><label><?php _e('显示版权信息', 'argon');?></label></th>
    <td>
        <select name="argon_show_copyright">
            <?php $show_copyright = get_option('argon_show_copyright', 'true'); ?>
            <option value="true" <?php selected($show_copyright, 'true'); ?>>开启</option>
            <option value="false" <?php selected($show_copyright, 'false'); ?>>关闭</option>
        </select>
    </td>
</tr>
```

### 前端交互架构 (PJAX & SPA)

Argon 主题采用 PJAX (PushState + AJAX) 技术实现单页应用 (SPA) 体验，核心逻辑位于 `assets/js/argontheme.js`。

#### 1. PJAX 工作原理

1.  **拦截点击**：监听所有 `a` 标签点击事件。
2.  **获取内容**：通过 AJAX 请求目标页面 URL。
3.  **解析响应**：从响应 HTML 中提取 `#content` 容器内容。
4.  **替换容器**：将当前页面的 `#content` 替换为新内容。
5.  **更新状态**：使用 `history.pushState` 更新浏览器 URL。
6.  **重载资源**：重新执行内联脚本，重置事件监听器。

#### 2. 初始化与重载机制

由于 PJAX 会替换页面的部分 DOM，依赖旧 DOM 的事件绑定与第三方实例需要在 PJAX 完成后重新初始化。Argon 的实现采用“首屏最小初始化 + PJAX 完整重初始化”的策略。

首屏加载完成后的初始化入口位于 `argontheme.js` 的 `$(document).ready(...)`，主要执行性能优化模块初始化（如已加载）以及基础渲染：

```javascript
$(document).ready(function(){
	if (typeof initArgonPerformance === 'function') {
		initArgonPerformance();
	}
	highlightJsRender();
	waterflowInit();
});
```

PJAX 主流程通过 `$(document).pjax(...)` 建立，并在 `pjax:beforeReplace` 统一清理旧页面资源，在 `pjax:complete` 完整初始化新页面模块（包含数学公式渲染、脚本执行与各功能模块的错误隔离初始化）。

#### 3. 脚本执行器 (Inline Script Executor)

PJAX 替换的 DOM 片段中可能包含内联 `<script>`。Argon 使用“创建新 script 节点并插入 head”的方式执行内联脚本，同时为每个脚本标记 `data-pjax-executed`，避免重复执行：

```javascript
function executeInlineScripts(container) {
	const scripts = container.querySelectorAll('script');
	scripts.forEach((script) => {
		if (script.getAttribute('data-pjax-executed') === 'true') return;
		if (script.src) return;
		if (!script.textContent || script.textContent.trim() === '') return;
		const newScript = document.createElement('script');
		newScript.text = script.textContent;
		document.head.appendChild(newScript);
		document.head.removeChild(newScript);
		script.setAttribute('data-pjax-executed', 'true');
	});
}
```

**开发注意**：如果你在文章或页面中编写了自定义 JavaScript，确保它们不依赖 `document.ready`，或者在 PJAX 重载时能被正确处理。

## 核心功能模块

### 1. 主题色系统

#### 实现原理

主题色通过 PHP 动态生成 CSS 变量，支持用户自定义：

```php
// header.php
$themecolor = get_option("argon_theme_color", "#5e72e4");
if (isset($_COOKIE["argon_custom_theme_color"])) {
	$themecolor = $_COOKIE["argon_custom_theme_color"];
}
$RGB = hexstr2rgb($themecolor);
$HSL = rgb2hsl($RGB['R'], $RGB['G'], $RGB['B']);
```

生成的 CSS 变量：

```css
:root {
	--themecolor: #5e72e4;
	--themecolor-R: 94;
	--themecolor-G: 114;
	--themecolor-B: 228;
	--themecolor-H: 231;
	--themecolor-S: 71;
	--themecolor-L: 63;
}
```

#### 沉浸式主题色

开启沉浸式主题色后，页面背景和卡片会使用主题色的浅色变体：

```css
html.immersion-color body {
	--color-background: rgb(var(--color-tint-86));
	--color-foreground: rgb(var(--color-tint-92));
}
```

### 2. 夜间模式

#### 切换方案

主题支持四种夜间模式切换方案，通过后台设置 `argon_darkmode_autoswitch` 选项控制：

1. **false（默认）** - 手动切换，不自动切换
2. **system** - 跟随系统，通过 `prefers-color-scheme` 媒体查询
3. **time** - 根据时间自动切换（22:00-7:00）
4. **alwayson** - 始终开启夜间模式

#### 实现代码

夜间模式的核心实现在 header.php 中：

```javascript
// header.php
var darkmodeAutoSwitch = "<?php echo (get_option("argon_darkmode_autoswitch") == '' ? 'false' : get_option("argon_darkmode_autoswitch"));?>";

// 设置夜间模式
function setDarkmode(enable){
	// 添加过渡类以启用平滑切换动画
	document.documentElement.classList.add("theme-transitioning");
	
	if (enable == true){
		document.documentElement.classList.add("darkmode");
	}else{
		document.documentElement.classList.remove("darkmode");
	}
	
	// 过渡完成后移除过渡类（300ms 后）
	setTimeout(function() {
		document.documentElement.classList.remove("theme-transitioning");
	}, 300);
	
	// 触发滚动事件以更新顶栏状态
	if (typeof jQuery !== 'undefined') {
		jQuery(window).trigger("scroll");
	} else {
		window.dispatchEvent(new Event('scroll'));
	}
	
	// 触发自定义事件，供其他模块监听
	document.dispatchEvent(new CustomEvent('argon:theme-switched', {
		detail: { darkmode: enable }
	}));
}

// 切换夜间模式
function toggleDarkmode(){
	if (document.documentElement.classList.contains("darkmode")){
		setDarkmode(false);
		sessionStorage.setItem("Argon_Enable_Dark_Mode", "false");
	}else{
		setDarkmode(true);
		sessionStorage.setItem("Argon_Enable_Dark_Mode", "true");
	}
}
```

#### 跟随系统方案

使用 `matchMedia` API 监听系统主题变化：

```javascript
// header.php
function toggleDarkmodeByPrefersColorScheme(media){
	// 如果用户手动设置过，则不自动切换
	if (sessionStorage.getItem('Argon_Enable_Dark_Mode') == "false" || 
	    sessionStorage.getItem('Argon_Enable_Dark_Mode') == "true"){
		return;
	}
	
	if (media.matches){
		setDarkmode(true);
	}else{
		setDarkmode(false);
	}
}

if (darkmodeAutoSwitch == 'system'){
	var darkmodeMediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
	darkmodeMediaQuery.addListener(toggleDarkmodeByPrefersColorScheme);
	toggleDarkmodeByPrefersColorScheme(darkmodeMediaQuery);
}
```

#### 根据时间方案

```javascript
// header.php
function toggleDarkmodeByTime(){
	// 如果用户手动设置过，则不自动切换
	if (sessionStorage.getItem('Argon_Enable_Dark_Mode') == "false" || 
	    sessionStorage.getItem('Argon_Enable_Dark_Mode') == "true"){
		return;
	}
	
	let hour = new Date().getHours();
	
	// 默认：22:00-7:00 开启夜间模式
	// 可通过过滤器 argon_darkmode_time_check 自定义时间范围
	if (<?php echo apply_filters("argon_darkmode_time_check", "hour < 7 || hour >= 22")?>){
		setDarkmode(true);
	}else{
		setDarkmode(false);
	}
}

if (darkmodeAutoSwitch == 'time'){
	toggleDarkmodeByTime();
}
```

#### AMOLED 暗黑模式

AMOLED 模式提供更深的黑色背景，适合 AMOLED 屏幕节省电量：

```javascript
// header.php
function toggleAmoledDarkMode(){
	document.documentElement.classList.toggle("amoled-dark");
	
	if (document.documentElement.classList.contains("amoled-dark")){
		localStorage.setItem("Argon_Enable_Amoled_Dark_Mode", "true");
	}else{
		localStorage.setItem("Argon_Enable_Amoled_Dark_Mode", "false");
	}
}

// 页面加载时恢复 AMOLED 模式设置
if (localStorage.getItem("Argon_Enable_Amoled_Dark_Mode") == "true"){
	document.documentElement.classList.add("amoled-dark");
}else if (localStorage.getItem("Argon_Enable_Amoled_Dark_Mode") == "false"){
	document.documentElement.classList.remove("amoled-dark");
}
```

#### 用户偏好存储

夜间模式的用户选择存储在 `sessionStorage` 中，AMOLED 模式存储在 `localStorage` 中：

- `sessionStorage.Argon_Enable_Dark_Mode` - 夜间模式开关（会话级别）
- `localStorage.Argon_Enable_Amoled_Dark_Mode` - AMOLED 模式开关（持久化）

这样设计的原因：
- 夜间模式使用 sessionStorage，每次打开浏览器都会根据设置重新判断
- AMOLED 模式使用 localStorage，用户设置会永久保存

### 3. PJAX 无刷新加载

#### 配置与初始化

PJAX 使用 jquery-pjax 库实现页面无刷新加载。配置在 argontheme.js 中：

```javascript
// argontheme.js
$.pjax.defaults.timeout = 10000;  // 超时时间 10 秒
var pjaxContainerSelectors = ['#primary', '#leftbar_part1_menu', '#leftbar_part2_inner', '.page-information-card-container', '#rightbar', '#wpadminbar'];
var pjaxContainers = pjaxContainerSelectors.filter(function(selector) {
	return document.querySelector(selector);
});
$.pjax.defaults.container = pjaxContainers;  // 要替换的容器
$.pjax.defaults.fragment = pjaxContainers;   // 从响应中提取的片段
```

#### 链接拦截

主题会自动拦截站内链接的点击事件：

```javascript
// argontheme.js
$(document).pjax(
	"a[href]:not([no-pjax]):not(.no-pjax):not([target='_blank']):not([download]):not(.reference-link):not(.reference-list-backlink):not([href^='#'])",
	pjaxContainers.length ? pjaxContainers[0] : '#primary',
	{ fragment: (pjaxContainers.length ? pjaxContainers : ['#primary']), timeout: $.pjax.defaults.timeout }
);
```

#### 页面切换流程

PJAX 加载过程中会触发一系列事件：

```javascript
// argontheme.js

// 1. 开始发送请求
$(document).on('pjax:send', function() {
	// 设置加载状态
	pjaxLoading = true;
	
	// 显示加载动画
	$('#content').addClass('pjax-loading');
	
	// 添加淡出效果
	$('#content, #leftbar, #rightbar').css('opacity', '0');
});

// 2. 请求成功，内容已替换
$(document).on('pjax:complete', function() {
	// 清除加载状态
	pjaxLoading = false;
	
	// 移除加载动画
	$('#content').removeClass('pjax-loading');
	
	// 添加淡入效果
	$('#content, #leftbar, #rightbar').animate({
		opacity: 1
	}, argonConfig.pjax_animation_durtion);
	
	// 滚动到顶部
	$('html, body').animate({
		scrollTop: 0
	}, argonConfig.pjax_animation_durtion);
	
	// 重新初始化各功能模块（主题在 pjax:complete 内集中处理，如 waterflowInit / lazyloadInit / zoomifyInit / highlightJsRender 等）
});

// 3. 请求失败
$(document).on('pjax:error', function(xhr, textStatus, error) {
	console.error('PJAX 加载失败:', error);
	// 失败时会自动回退到普通页面跳转
});

// 4. 超时
$(document).on('pjax:timeout', function(event) {
	// 阻止默认的超时处理（会中断请求）
	event.preventDefault();
});
```

#### 重新初始化

PJAX 加载完成后，需要重新初始化页面功能：

```javascript
// argontheme.js
// 主题在 pjax:complete 事件里集中完成“功能重置/再初始化”（单个模块失败不会影响其他模块）
try { waterflowInit(); } catch (err) {}
try { lazyloadInit(); } catch (err) {}
try { zoomifyInit(); } catch (err) {}
try { highlightJsRender(); } catch (err) {}
try { panguInit(); } catch (err) {}
try { clampInit(); } catch (err) {}
try { tippyInit(); } catch (err) {}
try { getGithubInfoCardContent(); } catch (err) {}
try { showPostOutdateToast(); } catch (err) {}
try { calcHumanTimesOnPage(); } catch (err) {}
try { foldLongComments(); } catch (err) {}
try { foldLongShuoshuo(); } catch (err) {}
try { handleHashNavigation(); } catch (err) {}
```

#### 禁用 PJAX

可以通过以下方式禁用 PJAX：

1. 后台设置中禁用（`argon_pjax_disabled` 选项）
2. 给链接添加 `no-pjax` 属性：

```html
<a href="/page" no-pjax>普通跳转</a>
```

3. 给链接添加 `target` 属性：

```html
<a href="/page" target="_blank">新窗口打开</a>
```

#### 浏览器历史记录

PJAX 会自动更新浏览器历史记录，支持前进后退按钮：

```javascript
// argontheme.js
$(window).on('popstate', function() {
	// 浏览器前进/后退时，PJAX 会自动加载对应页面
});
```

#### 性能优化

PJAX 加载时的性能优化措施：

1. 只替换必要的容器（content、leftbar、rightbar）
2. 使用 CSS 动画而非 JavaScript 动画
3. 延迟初始化非关键功能
4. 复用已加载的资源（CSS、JS）

```javascript
// argontheme.js
// 动画时长可配置，设为 0 可禁用动画
pjax_animation_durtion: <?php echo (get_option("argon_disable_pjax_animation") == 'true' ? '0' : '600'); ?>
```

### 4. 瀑布流布局

#### 实现原理

瀑布流布局通过 JavaScript 动态计算每个文章卡片的位置，实现类似 Pinterest 的多列布局。

#### 核心算法

```javascript
// argontheme.js
function waterflowInit() {
	// 如果设置为单列，直接返回
	if (argonConfig.waterflow_columns == "1") {
		return;
	}
	
	// 监听图片加载，加载完成后重新计算布局
	$("#main.article-list img").each(function(index, ele){
		ele.onload = function(){
			waterflowInit();
		}
	});
	
	// 确定列数
	let columns;
	if (argonConfig.waterflow_columns == "2and3") {
		// 自适应 2-3 列
		if ($("#main").outerWidth() > 1000) {
			columns = 3;
		} else {
			columns = 2;
		}
	}else{
		columns = parseInt(argonConfig.waterflow_columns);
	}
	
	// 响应式适配：窄屏幕时强制单列
	if ($("#main").outerWidth() < 650 && columns == 2) {
		columns = 1;
	}else if ($("#main").outerWidth() < 800 && columns == 3) {
		columns = 1;
	}
	
	// 记录每列的高度
	let heights = [0, 0, 0];
	
	// 获取当前最矮列的索引
	function getMinHeightPosition(){
		let res = 0, minn = 2147483647;
		for (var i = 0; i < columns; i++) {
			if (heights[i] < minn) {
				minn = heights[i];
				res = i;
			}
		}
		return res;
	}
	
	// 获取最高列的高度
	function getMaxHeight(){
		let res = 0;
		for (let i in heights) {
			res = Math.max(res, heights[i]);
		}
		return res;
	}
	
	// 添加瀑布流类
	$("#primary").css("transition", "none").addClass("waterflow");
	
	let $container = $("#main.article-list");
	if (!$container.length){
		return;
	}
	
	// 获取所有文章卡片
	let $items = $container.find("article.post:not(.no-results), .shuoshuo-preview-container");
	
	// 列数不能超过文章数量
	columns = Math.max(Math.min(columns, $items.length), 1);
	
	if (columns == 1) {
		// 单列模式：移除瀑布流样式
		$container.removeClass("waterflow");
		$items.css("transition", "")
			.css("position", "")
			.css("width", "")
			.css("top", "")
			.css("left", "")
			.css("margin", "");
		$(".waterflow-placeholder").remove();
	}else{
		// 多列模式：计算每个卡片的位置
		$container.addClass("waterflow");
		$items.each(function(index, item) {
			let $item = $(item);
			
			// 设置卡片宽度（平分容器宽度，减去间距）
			$item.css("transition", "none")
				.css("position", "absolute")
				.css("width", "calc(" + (100 / columns) + "% - " + (10 * (columns - 1) / columns) + "px)")
				.css("margin", 0);
			
			// 计算卡片高度（包含 10px 间距）
			let itemHeight = $item.outerHeight() + 10;
			
			// 找到最矮的列
			let pos = getMinHeightPosition();
			
			// 设置卡片位置
			$item.css("top", heights[pos] + "px")
				.css("left", (pos * $item.outerWidth() + 10 * pos) + "px");
			
			// 更新该列的高度
			heights[pos] += itemHeight;
		});
	}
	
	// 创建占位元素，撑开容器高度
	if ($(".waterflow-placeholder").length) {
		$(".waterflow-placeholder").css("height", getMaxHeight() + "px");
	}else{
		$container.prepend("<div class='waterflow-placeholder' style='height: " + getMaxHeight() +"px;'></div>");
	}
}
```

#### 初始化与监听

```javascript
// argontheme.js
// 页面加载时初始化
waterflowInit();

// 非单列模式下监听窗口大小变化
if (argonConfig.waterflow_columns != "1") {
	// 窗口大小改变时重新计算
	$(window).resize(function(){
		waterflowInit();
	});
	
	// 监听 DOM 变化（如 PJAX 加载新内容）
	new MutationObserver(function(mutations, observer){
		waterflowInit();
	}).observe(document.querySelector("#primary"), {
		'childList': true
	});
}
```

#### 移动端布局切换

移动端可以使用不同的文章列表布局样式：

```javascript
// argontheme.js
!function(){
	var mobileLayout = argonConfig.article_list_layout_mobile || "1";
	var isMobile = window.innerWidth <= 900;
	
	function applyMobileLayout() {
		var nowMobile = window.innerWidth <= 900;
		if (nowMobile) {
			// 添加移动端布局类
			$("html").addClass("mobile-layout-" + mobileLayout);
		} else {
			// 移除移动端布局类
			$("html").removeClass("mobile-layout-1 mobile-layout-2 mobile-layout-3");
		}
	}
	
	applyMobileLayout();
	$(window).resize(applyMobileLayout);
}();
```

#### 配置选项

瀑布流列数通过后台设置 `argon_article_list_waterflow` 控制：

- `"1"` - 单列（默认）
- `"2"` - 双列
- `"3"` - 三列
- `"2and3"` - 自适应 2-3 列（宽屏 3 列，窄屏 2 列）

#### 性能优化

1. 图片加载完成后才计算布局，避免高度计算错误
2. 使用 `MutationObserver` 监听 DOM 变化，而非轮询
3. 窗口大小改变时使用防抖，避免频繁计算
4. 单列模式下不监听事件，减少性能开销

#### CSS 配合

```css
/* style.css */
#main.article-list.waterflow {
	position: relative;
}

#main.article-list.waterflow article.post {
	position: absolute;
	transition: top 0.3s ease, left 0.3s ease;
}

.waterflow-placeholder {
	width: 100%;
	pointer-events: none;
}
```


### 5. 评论系统

#### 数据库结构

评论数据存储在 WordPress 标准的 `wp_comments` 表中，扩展字段通过 `wp_commentmeta` 表存储：

**标准字段（wp_comments 表）：**
- `comment_ID` - 评论 ID
- `comment_post_ID` - 所属文章 ID
- `comment_author` - 评论者昵称
- `comment_author_email` - 评论者邮箱
- `comment_author_url` - 评论者网站
- `comment_content` - 评论内容（HTML）
- `comment_parent` - 父评论 ID（用于回复）
- `user_id` - 用户 ID（登录用户）
- `comment_date` - 评论时间

**扩展字段（wp_commentmeta 表）：**
- `comment_upvote` - 点赞数
- `comment_is_private` - 是否私密评论
- `comment_use_markdown` - 是否使用 Markdown
- `comment_content_source` - Markdown 源码
- `comment_edit_history` - 编辑历史（JSON 格式）
- `comment_pinned` - 是否置顶
- `qq` - QQ 号（用于 QQ 头像）

#### AJAX 发送评论

前端通过 AJAX 提交评论，避免页面刷新：

```javascript
// argontheme.js
function postComment() {
	let formData = {
		action: 'ajax_post_comment',
		comment_post_ID: postID,
		author: $('#comment_author').val(),
		email: $('#comment_email').val(),
		url: $('#comment_url').val(),
		comment: $('#comment_content').val(),
		comment_parent: replyID,
		use_markdown: $('#use_markdown').is(':checked') ? 'true' : 'false',
		is_private: $('#is_private').is(':checked') ? 'true' : 'false',
		argon_nonce: $('#argon_comment_nonce').val(),
		// 验证码相关字段
		captcha_seed: $('#captcha_seed').val(),
		captcha_answer: $('#captcha_answer').val()
	};
	
	$.ajax({
		type: 'POST',
		url: argonConfig.wp_path + "wp-admin/admin-ajax.php",
		dataType: "json",
		data: formData,
		beforeSend: function() {
			$('#comment_submit').text(__('发送中'));
			$('#comment_submit').prop('disabled', true);
		},
		success: function(result) {
			if (result.status == "success") {
				// 插入新评论到页面
				insertComment(result.html, result.parentID, result.commentOrder);
				// 清空表单
				$('#comment_content').val('');
				// 更新验证码
				updateCaptcha(result.newCaptchaSeed, result.newCaptcha);
			} else {
				alert(result.msg);
			}
		},
		error: function() {
			alert(__('评论发送失败'));
		},
		complete: function() {
			$('#comment_submit').text(__('发送'));
			$('#comment_submit').prop('disabled', false);
		}
	});
}
```

#### PHP 处理函数

服务器端处理评论提交：

```php
// functions.php
function ajax_post_comment(){
	// 1. IP 黑名单检查
	if (argon_is_ip_blocked_global()) {
		exit(json_encode(array(
			'status' => 'failed',
			'msg' => __('您的 IP 已被限制访问', 'argon'),
			'isAdmin' => current_user_can('level_7')
		)));
	}
	
	// 2. 私密评论权限检查
	$parentID = $_POST['comment_parent'];
	if (is_comment_private_mode($parentID)){
		if (!user_can_view_comment($parentID)){
			exit(json_encode(array(
				'status' => 'failed',
				'msg' =>  __('不能回复其他人的悄悄话评论', 'argon'),
				'isAdmin' => current_user_can('level_7')
			)));
		}
	}
	
	// 3. QQ 邮箱处理
	if (get_option('argon_comment_enable_qq_avatar') == 'true'){
		if (check_qqnumber($_POST['email'])){
			$_POST['qq'] = $_POST['email'];
			$_POST['email'] .= "@qq.com";
		}
	}
	
	// 4. CSRF nonce 校验
	if (!isset($_POST['argon_nonce']) || !wp_verify_nonce($_POST['argon_nonce'], 'argon_comment')) {
		exit(json_encode(array(
			'status' => 'failed',
			'msg' => __('请求已失效，请刷新页面后重试', 'argon'),
			'isAdmin' => current_user_can('level_7')
		)));
	}
	
	// 5. Honeypot 反垃圾检查
	if (!empty($_POST['argon_comment_honeypot'])) {
		exit(json_encode(array(
			'status' => 'failed',
			'msg' => __('Spam detected', 'argon'),
			'isAdmin' => current_user_can('level_7')
		)));
	}
	
	// 6. 速率限制（防止刷评论）
	$rate_enable = get_option('argon_rate_limit_enable', 'true');
	if ($rate_enable === 'true') {
		$ip = isset($_SERVER['HTTP_X_FORWARDED_FOR']) ? explode(',', $_SERVER['HTTP_X_FORWARDED_FOR'])[0] : $_SERVER['REMOTE_ADDR'];
		$ip = sanitize_text_field($ip);
		$rate_key = 'argon_rate_cmt_' . md5($ip);
		$state = get_transient($rate_key);
		$now = time();
		$window = intval(get_option('argon_rate_limit_window', 300)); // 窗口秒数（默认 5 分钟）
		$max_count = intval(get_option('argon_rate_limit_max_count', 5)); // 窗口内最大次数
		$min_interval = intval(get_option('argon_rate_limit_min_interval', 10)); // 两次最小间隔（秒）
		
		// 检查最小间隔
		if (!is_array($state)) {
			$state = array('count' => 0, 'start' => $now, 'last' => 0);
		}
		if ($state['last'] > 0 && ($now - intval($state['last'])) < $min_interval) {
			exit(json_encode(array(
				'status' => 'failed',
				'msg' => __('您评论过快，请稍后再试', 'argon'),
				'isAdmin' => current_user_can('level_7')
			)));
		}
		
		// 检查窗口内次数
		if (($now - intval($state['start'])) < $window && intval($state['count']) >= $max_count) {
			exit(json_encode(array(
				'status' => 'failed',
				'msg' => __('操作过于频繁，请稍后再试', 'argon'),
				'isAdmin' => current_user_can('level_7')
			)));
		}
		
		// 更新速率状态
		if (($now - intval($state['start'])) >= $window) {
			$state['start'] = $now;
			$state['count'] = 0;
		}
		$state['count'] = intval($state['count']) + 1;
		$state['last'] = $now;
		set_transient($rate_key, $state, $window);
	}
	
	// 7. 提交评论
	$comment = wp_handle_comment_submission(wp_unslash($_POST));
	if (is_wp_error($comment)){
		$msg = $comment->get_error_message();
		exit(json_encode(array(
			'status' => 'failed',
			'msg' => $msg,
			'isAdmin' => current_user_can('level_7')
		)));
	}
	
	// 8. 设置 Cookie
	$user = wp_get_current_user();
	do_action('set_comment_cookies', $comment, $user);
	
	// 9. 生成评论 HTML
	$html = wp_list_comments(
		array(
			'type'      => 'comment',
			'callback'  => 'argon_comment_format',
			'echo'      => false
		),
		array($comment)
	);
	
	// 10. 生成新验证码
	$newCaptchaSeed = get_comment_captcha_seed(true);
	$newCaptcha = get_comment_captcha($newCaptchaSeed);
	
	// 11. 返回结果
	exit(json_encode(array(
		'status' => 'success',
		'html' => $html,
		'id' => $comment->comment_ID,
		'parentID' => $comment->comment_parent,
		'commentOrder' => (get_option("comment_order") == "" ? "desc" : get_option("comment_order")),
		'newCaptchaSeed' => $newCaptchaSeed,
		'newCaptcha' => $newCaptcha,
		'isAdmin' => current_user_can('level_7'),
		'isLogin' => is_user_logged_in()
	)));
}
add_action('wp_ajax_ajax_post_comment', 'ajax_post_comment');
add_action('wp_ajax_nopriv_ajax_post_comment', 'ajax_post_comment');
```

#### Markdown 解析

评论支持 Markdown 语法，使用 Parsedown 库解析：

```php
// functions.php
require_once(get_template_directory() . '/parsedown.php');

function comment_markdown_parse($comment_content){
	// 允许评论中额外的 HTML 标签
	global $allowedtags;
	$allowedtags['pre'] = array('class' => array());
	$allowedtags['i'] = array('class' => array(), 'aria-hidden' => array());
	$allowedtags['img'] = array('src' => array(), 'alt' => array(), 'class' => array());
	$allowedtags['ol'] = array();
	$allowedtags['ul'] = array();
	$allowedtags['li'] = array();
	$allowedtags['span'] = array('class' => array(), 'style' => array(), 'title' => array());
	$allowedtags['a']['class'] = array();
	$allowedtags['a']['data-src'] = array();
	$allowedtags['a']['target'] = array();
	$allowedtags['h1'] = $allowedtags['h2'] = $allowedtags['h3'] = $allowedtags['h4'] = $allowedtags['h5'] = $allowedtags['h6'] = array();
	
	// 解析 Markdown
	$parsedown = new _Parsedown();
	$res = $parsedown->text($comment_content);
	
	// 为链接添加 target="_blank"
	$res = preg_replace(
		'/<a (.*?)>(.*?)<\/a>/',
		'<a $1 target="_blank">$2</a>',
		$res
	);
	
	return $res;
}

// 评论发送前处理
function post_comment_preprocessing($comment){
	// 保存评论未经 Markdown 解析的源码
	$_POST['comment_content_source'] = $comment['comment_content'];
	
	// 应用评论宏（黑幕、彩幕等）
	$comment['comment_content'] = argon_apply_comment_macros($comment['comment_content']);
	
	// Markdown 解析
	if ($_POST['use_markdown'] == 'true' && get_option("argon_comment_allow_markdown") != "false"){
		$comment['comment_content'] = comment_markdown_parse($comment['comment_content']);
	}
	
	return $comment;
}
add_filter('preprocess_comment', 'post_comment_preprocessing');
```

#### 评论宏

主题支持多种评论宏，用于实现特殊效果：

```php
// functions.php
function argon_apply_comment_macros($text){
	// 黑幕：{{黑幕|内容}} 或 {{黑幕|内容|提示}}
	$text = preg_replace_callback('/\{\{黑幕\|([\s\S]*?)(?:\|([\s\S]*?))?\}\}/u', function($m){
		$content = trim($m[1]);
		$title = isset($m[2]) ? trim($m[2]) : '你知道的太多了';
		return '<span class="heimu"' . (strlen($title) ? ' title="' . htmlspecialchars($title, ENT_QUOTES) . '"' : '') . '>' . htmlspecialchars($content) . '</span>';
	}, $text);
	
	// 彩幕：{{彩幕|内容|背景色|提示|前景色}}
	$text = preg_replace_callback('/\{\{彩幕\|([\s\S]*?)\}\}/u', function($m){
		$parts = explode('|', $m[1]);
		$content = isset($parts[0]) ? trim($parts[0]) : '';
		$bg = isset($parts[1]) ? trim($parts[1]) : '#252525';
		$tip = isset($parts[2]) ? trim($parts[2]) : '你知道的太多了';
		$fg = isset($parts[3]) ? trim($parts[3]) : '';
		
		// 如果没有指定前景色，根据背景色亮度自动计算
		if (empty($fg)) {
			$hex = ltrim($bg, '#');
			if (strlen($hex) == 6) {
				$r = hexdec(substr($hex, 0, 2));
				$g = hexdec(substr($hex, 2, 2));
				$b = hexdec(substr($hex, 4, 2));
				$luma = 0.2126 * $r + 0.7152 * $g + 0.0722 * $b;
				$fg = ($luma >= 180) ? '#000' : '#fff';
			} else {
				$fg = '#fff';
			}
		}
		
		$style = '--curtain-bg: ' . htmlspecialchars($bg, ENT_QUOTES) . '; --curtain-fg: ' . htmlspecialchars($fg, ENT_QUOTES) . ';';
		return '<span class="color-curtain"' . (strlen($tip) ? ' title="' . htmlspecialchars($tip, ENT_QUOTES) . '"' : '') . ' style="' . $style . '">' . htmlspecialchars($content) . '</span>';
	}, $text);
	
	// 文字模糊：{{文字模糊|内容|提示|颜色|时间}}
	$text = preg_replace_callback('/\{\{文字模糊\|([\s\S]*?)\}\}/u', function($m){
		$parts = explode('|', $m[1]);
		$content = isset($parts[0]) ? trim($parts[0]) : '';
		$tip = isset($parts[1]) ? trim($parts[1]) : '你知道的太多了';
		$color = isset($parts[2]) ? trim($parts[2]) : '';
		$time = isset($parts[3]) ? trim($parts[3]) : '0.2';
		$style = '--text-blur-transition-time: ' . preg_replace('/[^0-9\.]/', '', $time) . 's;';
		if (strlen($color) > 0) {
			$style .= ' --text-blur-color: ' . htmlspecialchars($color, ENT_QUOTES) . ';';
		}
		return '<span class="text-blur"' . (strlen($tip) ? ' title="' . htmlspecialchars($tip, ENT_QUOTES) . '"' : '') . ' style="' . $style . '">' . htmlspecialchars($content) . '</span>';
	}, $text);
	
	return $text;
}
add_filter('comment_text', 'argon_comment_text_render', 9);
```

使用示例：
- `{{黑幕|剧透内容}}` - 鼠标悬停显示
- `{{彩幕|彩色文字|#ff0000}}` - 彩色背景
- `{{文字模糊|模糊文字}}` - 鼠标悬停清晰


### 6. 说说功能

#### 自定义文章类型

说说是一个独立的自定义文章类型，类似微博的短内容发布功能：

```php
// functions.php
add_action('init', 'init_shuoshuo');
function init_shuoshuo(){
	$labels = array(
		'name' => __('说说', 'argon'),
		'singular_name' => __('说说', 'argon'),
		'add_new' => __('发表说说', 'argon'),
		'add_new_item' => __('发表说说', 'argon'),
		'edit_item' => __('编辑说说', 'argon'),
		'new_item' => __('新说说', 'argon'),
		'view_item' => __('查看说说', 'argon'),
		'search_items' => __('搜索说说', 'argon'),
		'not_found' => __('暂无说说', 'argon'),
		'not_found_in_trash' => __('没有已遗弃的说说', 'argon'),
		'parent_item_colon' => '',
		'menu_name' => __('说说', 'argon')
	);
	$args = array(
		'labels' => $labels,
		'public' => true,
		'publicly_queryable' => true,
		'show_ui' => true,
		'show_in_menu' => true,
		'exclude_from_search' => true,
		'query_var' => true,
		'rewrite' => array(
			'slug' => 'shuoshuo',
			'with_front' => false
		),
		'capability_type' => 'post',
		'has_archive' => false,
		'hierarchical' => false,
		'menu_position' => null,
		'menu_icon' => 'dashicons-format-quote',
		'supports' => array('editor', 'author', 'title', 'custom-fields', 'comments')
	);
	register_post_type('shuoshuo', $args);
}
```

#### 页面模板

说说页面使用独立的模板文件 `shuoshuo.php`：

```php
// shuoshuo.php
/*
Template Name: 说说
*/
query_posts("post_type=shuoshuo&post_status=publish&posts_per_page=-1");
```


#### 说说内容模板

说说内容通过 `template-parts/content-shuoshuo.php` 渲染：

```php
<div class="shuoshuo-item card">
	<div class="card-body">
		<div class="shuoshuo-author">
			<?php echo get_avatar(get_the_author_meta('ID'), 40); ?>
			<span class="shuoshuo-author-name">
				<?php the_author(); ?>
			</span>
		</div>
		<div class="shuoshuo-content">
			<?php the_content(); ?>
		</div>
		<div class="shuoshuo-meta">
			<span class="shuoshuo-time">
				<?php echo get_the_date('Y-m-d H:i'); ?>
			</span>
			<span class="shuoshuo-comment-count">
				<?php comments_number('0 条评论', '1 条评论', '% 条评论'); ?>
			</span>
		</div>
	</div>
</div>
```

#### 说说操作按钮

支持点赞、评论、分享等操作，通过 `template-parts/shuoshuo-operations.php` 实现。

#### 折叠长说说

当说说内容超过一定长度时自动折叠：

```javascript
// argontheme.js
if (argonConfig.fold_long_shuoshuo) {
	$('.shuoshuo-content').each(function() {
		let $content = $(this);
		if ($content.height() > 300) {
			$content.addClass('folded');
			$content.after('<a class="unfold-btn">展开</a>');
		}
	});
}
```


### 7. AI 摘要功能

#### 功能概述

AI 摘要功能允许为文章自动生成摘要，支持多种 AI 服务提供商。

#### 查询接口

通过独立的 PHP 文件 `ai-summary-query.php` 处理 AI 摘要请求：

```php
// ai-summary-query.php
$wp_load_path = dirname(dirname(dirname(dirname(__FILE__)))) . '/wp-load.php';
if (!file_exists($wp_load_path)) $wp_load_path = $_SERVER['DOCUMENT_ROOT'] . '/wp-load.php';
require_once($wp_load_path);
```

#### 安全防护

实现了完善的 IP 访问限制机制：

```php
/**
 * 获取客户端真实 IP
 * 优先级：CF-Connecting-IP > X-Real-IP > X-Forwarded-For > REMOTE_ADDR
 */
function argon_ai_query_get_client_ip() {
	$ip = '';
	
	// Cloudflare
	if (!empty($_SERVER['HTTP_CF_CONNECTING_IP'])) {
		$ip = $_SERVER['HTTP_CF_CONNECTING_IP'];
	}
	// Nginx proxy_pass 或其他反向代理
	elseif (!empty($_SERVER['HTTP_X_REAL_IP'])) {
		$ip = $_SERVER['HTTP_X_REAL_IP'];
	}
	// 通过代理转发（取第一个 IP）
	elseif (!empty($_SERVER['HTTP_X_FORWARDED_FOR'])) {
		$ip = explode(',', $_SERVER['HTTP_X_FORWARDED_FOR'])[0];
	}
	// 直连 IP
	else {
		$ip = $_SERVER['REMOTE_ADDR'];
	}
	
	return trim($ip);
}
```


#### 访问频率限制

```php
/**
 * 检查 IP 访问频率限制
 * @return bool|string true 表示允许访问，字符串表示错误信息
 */
function argon_ai_query_check_rate_limit() {
	$client_ip = argon_ai_query_get_client_ip();
	if (empty($client_ip)) {
		return __('无法获取客户端 IP', 'argon');
	}
	
	$transient_key = 'ai_query_lock_' . md5($client_ip);
	$rate_limit_key = 'ai_query_rate_' . md5($client_ip);
	
	// 检查是否有正在进行的查询（单线程限制）
	if (get_transient($transient_key)) {
		return __('请等待上一次查询完成', 'argon');
	}
	
	// 检查访问频率（60秒内最多10次）
	$access_count = get_transient($rate_limit_key);
	if ($access_count === false) {
		set_transient($rate_limit_key, 1, 60);
	} else {
		if ($access_count >= 10) {
			return __('访问过于频繁，请稍后再试', 'argon');
		}
		set_transient($rate_limit_key, $access_count + 1, 60);
	}
	
	// 设置查询锁（3秒超时）
	set_transient($transient_key, 1, 3);
	
	return true;
}
```

#### AI 服务配置

在后台设置页面配置 AI 服务：

- API 端点 URL
- API 密钥
- 模型名称
- 请求参数（温度、最大 token 数等）
- 超时设置

#### 前端调用

```javascript
// argontheme.js
function loadAISummary(postId) {
	$.ajax({
		url: argonConfig.wp_path + '?argon_ai_query=1',
		type: 'POST',
		data: {
			post_id: postId
		},
		success: function(response) {
			$('#ai-summary-content').html(response.summary);
		}
	});
}
```


### 8. 后台设置系统

#### 设置页面结构

`settings.php` 是主题的后台设置页面，包含 7000+ 行代码（当前仓库约 7273 行），提供完整的主题配置界面。

#### 设置分类

设置页面分为多个选项卡：

1. 外观设置 - 主题色、布局、卡片样式
2. 功能设置 - PJAX、懒加载、代码高亮
3. 文章设置 - 文章列表样式、摘要长度
4. 评论设置 - 评论验证码、邮件通知
5. 说说设置 - 说说页面配置
6. AI 设置 - AI 摘要服务配置
7. 性能优化 - 资源合并、缓存控制
8. 高级设置 - 自定义 CSS/JS、SEO

#### 选项存储

所有设置通过 WordPress Options API 存储：

```php
// 保存设置
update_option('argon_theme_color', $_POST['argon_theme_color']);

// 读取设置
$theme_color = get_option('argon_theme_color', '#5e72e4');
```

#### 设置验证

提交设置时进行安全验证：

```php
// settings.php
if (isset($_POST['save'])) {
	// 验证 nonce
	check_admin_referer('argon_theme_options');
	
	// 验证权限
	if (!current_user_can('manage_options')) {
		wp_die(__('权限不足', 'argon'));
	}
	
	// 保存设置
	foreach ($_POST as $key => $value) {
		if (strpos($key, 'argon_') === 0) {
			update_option($key, sanitize_text_field($value));
		}
	}
	
	echo '<div class="updated"><p>设置已保存</p></div>';
}
```


#### 动态设置界面

设置页面使用 jQuery 实现动态交互：

```javascript
// settings.php 内嵌脚本
$(document).ready(function() {
	// 选项卡切换
	$('.nav-tab').click(function() {
		let target = $(this).data('target');
		$('.nav-tab').removeClass('nav-tab-active');
		$(this).addClass('nav-tab-active');
		$('.settings-section').hide();
		$('#' + target).show();
	});
	
	// 颜色选择器
	$('.color-picker').wpColorPicker();
	
	// 拖拽排序
	dragula([$('#sortable-list')[0]]);
});
```

#### AI API 配置表格

支持配置多个 AI 服务提供商：

```php
<table class="argon-ai-api-table">
	<thead>
		<tr>
			<th>服务名称</th>
			<th>API 端点</th>
			<th>API 密钥</th>
			<th>模型</th>
			<th>状态</th>
			<th>操作</th>
		</tr>
	</thead>
	<tbody id="argon-unified-api-list">
		<?php
		$api_list = get_option('argon_ai_api_list', []);
		foreach ($api_list as $api) {
			echo '<tr>';
			echo '<td>' . esc_html($api['name']) . '</td>';
			echo '<td>' . esc_html($api['endpoint']) . '</td>';
			echo '<td>***</td>';
			echo '<td>' . esc_html($api['model']) . '</td>';
			echo '<td>' . ($api['enabled'] ? '启用' : '禁用') . '</td>';
			echo '<td><button class="edit-api">编辑</button></td>';
			echo '</tr>';
		}
		?>
	</tbody>
</table>
```


### 9. 性能优化

#### 资源合并

主题支持将多个 CSS 和 JS 文件合并为单个文件：

```php
// functions.php
function argon_merge_assets() {
	$css_files = [
		'assets/css/bootstrap/bootstrap.min.css',
		'assets/css/argon.min.css',
		'style.css'
	];
	
	$merged_css = '';
	foreach ($css_files as $file) {
		$merged_css .= file_get_contents(get_template_directory() . '/' . $file);
	}
	
	file_put_contents(
		get_template_directory() . '/assets/argon_css_merged.css',
		$merged_css
	);
}
```

#### 懒加载

图片懒加载通过 Lazy Load 库实现：

```javascript
// argontheme.js
function initLazyload() {
	if (!argonConfig.lazyload) return;
	
	$('img[data-src]').lazyload({
		effect: argonConfig.lazyload_effect,
		threshold: argonConfig.lazyload_threshold,
		failure_limit: 10
	});
}
```

#### 强制刷新缓存

提供强制刷新功能，用于更新后清除客户端缓存：

```php
// functions.php
function argon_is_force_refresh_enabled() {
	$enabled_time = get_option('argon_force_refresh_enabled_time', 0);
	if ($enabled_time == 0) {
		return false;
	}
	// 检查是否超过 1 小时
	if (time() - $enabled_time > 3600) {
		// 自动关闭
		update_option('argon_force_refresh_enabled_time', 0);
		return false;
	}
	return true;
}

function argon_get_assets_version() {
	if (argon_is_force_refresh_enabled()) {
		$enabled_time = get_option('argon_force_refresh_enabled_time', 0);
		return $GLOBALS['theme_version'] . '.r' . $enabled_time;
	}
	return $GLOBALS['theme_version'];
}
```


#### 缓存控制

针对不同类型的资源设置不同的缓存策略：

```php
// functions.php
function argon_static_resource_headers() {
	if (is_admin() || argon_is_force_refresh_enabled()) {
		return;
	}
	
	$request_uri = $_SERVER['REQUEST_URI'] ?? '';
	$static_extensions = array('.css', '.js', '.jpg', '.jpeg', '.png', '.gif', '.svg', '.woff', '.woff2', '.ttf', '.eot', '.ico');
	
	$is_static = false;
	foreach ($static_extensions as $ext) {
		if (strpos($request_uri, $ext) !== false) {
			$is_static = true;
			break;
		}
	}
	
	if ($is_static && !headers_sent()) {
		// 静态资源缓存 1 年
		header('Cache-Control: public, max-age=31536000, immutable', true);
	}
}
add_action('send_headers', 'argon_static_resource_headers', 30);
```

#### 移动端缓存控制

禁止移动端浏览器缓存 HTML 页面，避免内容更新不及时：

```php
// functions.php
function argon_prevent_mobile_cache() {
	if (wp_is_mobile() && !is_admin()) {
		header('Cache-Control: no-cache, no-store, must-revalidate');
		header('Pragma: no-cache');
		header('Expires: 0');
	}
}
add_action('send_headers', 'argon_prevent_mobile_cache');
```


### 10. 安全机制

#### HTTP 安全头部

设置安全相关的 HTTP 头部：

```php
// functions.php
function argon_security_headers() {
	if (is_admin()) {
		return;
	}
	
	if (!headers_sent()) {
		// 使用 Content-Security-Policy 替代 X-Frame-Options
		// 允许同源嵌入，防止点击劫持
		header("Content-Security-Policy: frame-ancestors 'self'", false);
		
		// 移除 X-Frame-Options（如果存在）
		header_remove('X-Frame-Options');
	}
}
add_action('send_headers', 'argon_security_headers', 20);
```

#### AJAX 请求验证

所有 AJAX 请求都需要验证 nonce：

```php
// functions.php
function ajax_post_comment() {
	// 验证 nonce
	check_ajax_referer('post_comment', 'nonce');
	
	// 验证验证码
	if (argon_is_comment_captcha_enabled()) {
		verify_captcha();
	}
	
	// 处理评论...
}
add_action('wp_ajax_ajax_post_comment', 'ajax_post_comment');
add_action('wp_ajax_nopriv_ajax_post_comment', 'ajax_post_comment');
```

#### 内容过滤

使用 WordPress 内置函数过滤用户输入：

```php
// 过滤 HTML 标签
$comment_content = wp_filter_kses($_POST['comment']);

// 转义输出
echo esc_html($user_name);
echo esc_attr($user_email);
echo esc_url($user_url);
```


#### 权限检查

在执行敏感操作前检查用户权限：

```php
// functions.php
function user_edit_comment() {
	check_ajax_referer('edit_comment', 'nonce');
	
	$comment_id = intval($_POST['id']);
	$comment = get_comment($comment_id);
	
	// 权限检查：管理员或评论作者本人
	if (!current_user_can('edit_comment', $comment_id) && 
	    $comment->user_id != get_current_user_id()) {
		wp_send_json(array('status' => 'failed', 'reason' => '权限不足'));
	}
	
	// 执行编辑操作...
}
```

#### 验证码系统

评论与部分交互功能支持验证码验证，用于减少机器人提交与恶意请求。验证码启用逻辑采用“评论独立开关 + 全局开关”组合：

- 评论验证码开关：`argon_comment_captcha_mode`，取值为 `enabled` / `disabled` / `global`
- 全局验证码开关：`argon_need_captcha`（兼容旧选项 `argon_comment_need_captcha`）

当前版本的验证码实现包含：

- **算术验证码**：通过 `captcha_calculation` 生成挑战题，`get_comment_captcha()` 输出题目，`get_comment_captcha_answer()` 用于校验答案
- **极验验证码 (Geetest 4)**：通过 `geetest_validate(...)` 校验前端提交的四个字段（lot_number/captcha_output/pass_token/gen_time）

评论场景是否启用验证码由 `argon_is_comment_captcha_enabled()` 决定：

```php
function argon_is_comment_captcha_enabled() {
    $mode = get_option('argon_comment_captcha_mode', 'global');
    if ($mode === 'enabled') {
        return true;
    } elseif ($mode === 'disabled') {
        return false;
    }
    return argon_is_captcha_enabled();
}
```


### 11. 友链管理系统

#### 功能概述

Argon 主题内置了一套独立的友链管理系统，支持友链的申请、审核、分组和展示，无需依赖第三方插件。

#### 数据存储

友链数据不使用 WordPress 的 Links Manager API（已废弃），而是存储在 `argon_friend_links` 选项中，数据结构为 JSON 数组。该数组既包含展示所需字段，也包含审核与可用性检测的状态字段：

```php
$links = get_option('argon_friend_links', array());
// 结构示例：
// [
//     {
//         'id' => 'fl_5f...',
//         'name' => '站点名称',
//         'url' => 'https://example.com',
//         'avatar' => '...',
//         'description' => '...',
//         'category' => '',
//         'email' => '',
//         'message' => '',
//         'status' => 'approved',  // pending, approved
//         'verified' => false,
//         'is_wordpress' => false,
//         'accessible' => true,
//         'last_check' => 1700000000,
//         'created_at' => 1700000000,
//         'updated_at' => 1700000000
//     },
//     ...
// ]
```

#### 核心逻辑

主要逻辑在 `functions.php` 中实现：

- `argon_add_friend_link($data)`: 添加新友链
- `argon_update_friend_link($id, $data)`: 更新友链信息
- `argon_handle_link_application_v3($post_data)`: 处理友链申请

#### 自动获取站点信息

在申请友链和后台新增友链时，主题会自动获取目标网站的基础信息。实现入口为 `argon_fetch_site_info($url)`，其返回结构包含可用性与安全拦截相关的状态字段：

```php
$info = array(
    'favicon' => '',
    'title' => '',
    'description' => '',
    'author_avatar' => '',
    'is_wordpress' => false,
    'accessible' => false,
    'blocked_by_waf' => false,
    'error_reason' => ''
);
```

核心流程包括：

1. 使用模拟浏览器的请求头与 UA 进行 `wp_remote_get`（`timeout` 约 20 秒，允许最多 5 次重定向）
2. 根据 HTTP 状态码与页面内容特征识别 WAF 拦截（403/503/关键字命中），并写入 `blocked_by_waf` 与 `error_reason`
3. 在可访问的前提下解析 `<title>`、`meta description`，并通过多种 `<link rel="icon">` 规则获取 favicon，必要时回退到 `/favicon.ico`
4. 尝试检测站点是否为 WordPress（页面特征 + `/wp-json/` 探测），若为 WordPress 则进一步尝试获取作者头像信息

#### 申请频率限制与安全校验

为了防止滥用，申请入口 `argon_handle_link_application_v3($post_data)` 依次执行以下校验：

1. **IP 黑名单**：读取 `argon_global_blocked_ips`，支持精确匹配 / 通配符 / CIDR
2. **频率限制**：按“用户标识符”限制提交频率
   - 已登录用户：`user_{ID}`
   - 未登录用户：对 `IP + User-Agent` 计算哈希并截断（用于避免单纯按 IP 误伤共享网络）
   - 计数使用 transient：`flink_apply_{identifier}`
   - 默认限制来自选项：`argon_flink_apply_limit`（默认 3）与 `argon_flink_apply_period`（默认 3600 秒）
3. **Nonce 验证**：校验字段 `argon_link_apply_nonce`，action 为 `argon_link_apply`
4. **可选验证码**：当全局验证码开启时，会调用 `argon_verify_captcha('flink')` 对友链申请场景进行验证

## 12. 短代码与小工具系统

Argon 主题内置了丰富的小工具区域和短代码支持，增强了内容展示的灵活性。

### 小工具区域 (Sidebars)

主题在 `functions.php` 的 `argon_widgets_init` 函数中注册了三个主要的小工具区域：

1. **左侧栏小工具 (`leftbar-tools`)**
   - 显示在页面左侧边栏。
   - 如果设置了小工具，会在侧栏增加一个 Tab 标签页。
   
2. **右侧栏小工具 (`rightbar-tools`)**
   - 仅在 "Argon 主题选项" 中选择 "三栏布局" 时显示。
   - 位于页面右侧。

3. **站点概览额外内容 (`leftbar-siteinfo-extra-tools`)**
   - 用于在左侧栏站点概览卡片下方添加额外内容。

**注册代码示例：**

```php
function argon_widgets_init(){
    register_sidebar(
        array(
            'name'          => __('左侧栏小工具', 'argon'),
            'id'            => 'leftbar-tools',
            // ...
        )
    );
    // ...
}
add_action('widgets_init', 'argon_widgets_init');
```

### 短代码系统 (Shortcodes)

主题定义了大量自定义短代码，用于在文章中快速插入特殊样式或功能组件。所有短代码均在 `functions.php` 中通过 `add_shortcode` 注册。

#### 主要短代码列表

- **布局与样式**：`[br]`, `[label]`, `[progressbar]`, `[checkbox]`, `[collapse]/[fold]`
- **提示框**：`[alert]`, `[admonition]`
- **功能组件**：`[timeline]`, `[github]`, `[video]`
- **元数据**：`[post_time]`, `[post_modified_time]`, `[hide_reading_time]`
- **其他**：`[friendlinks]`, `[sfriendlinks]`, `[hidden]/[spoiler]`, `[ref]`

#### 实现示例：Alert 短代码

`[alert]` 短代码用于显示带颜色的提示框，支持 `color` 和 `icon` 参数。

```php
// 注册短代码
add_shortcode('alert','shortcode_alert');

// 回调函数实现
function shortcode_alert($attr, $content=""){
    // 预处理内容
    $content = shortcode_content_preprocess($attr, $content);
    
    // 构建 HTML
    $out = "<div class='alert";
    $color = isset( $attr['color'] ) ? $attr['color'] : 'indigo';
    
    // 根据颜色参数添加对应的 CSS 类
    switch ($color){
        case 'indigo': $out .= " alert-primary"; break;
        case 'green':  $out .= " alert-success"; break;
        // ...
    }
    
    $out .= "'>";
    // ...
    return $out;
}
```

## 13. 扩展接口与 Hooks

Argon 主题提供了一些自定义的 Action 和 Filter Hooks，方便开发者在不修改核心文件的情况下扩展主题功能。

### 主要 Hooks 列表

#### Filters (过滤器)

1. **`argon_banner_title_html`**
   - **作用**：过滤 Banner 标题的 HTML 内容。
   - **位置**：`header.php`
   - **参数**：`$banner_title` (当前标题)

2. **`argon_page_background_url`**
   - **作用**：过滤页面背景图片的 URL。
   - **位置**：`header.php`
   - **参数**：`$url` (设置中的背景 URL)

3. **`argon_email_types`**
   - **作用**：过滤邮件通知类型列表，可用于修改默认邮件模板或添加新类型。
   - **位置**：`email-templates/base.php`
   - **参数**：`$types` (包含邮件类型配置的数组)

#### Actions (动作)

1. **`argon_cache_cleared`**
   - **作用**：当主题缓存被清除时触发（如保存设置时）。
   - **位置**：`functions.php`

**使用示例：**

```php
// 修改 Banner 标题后缀
add_filter('argon_banner_title_html', function($title) {
    return $title . ' <small>(Dev Mode)</small>';
});

// 自定义背景图片逻辑
add_filter('argon_page_background_url', function($url) {
    if (is_page('special')) {
        return 'https://example.com/special-bg.jpg';
    }
    return $url;
});
```

## 14. 国际化与多语言支持

Argon 主题完全支持国际化（I18n），允许开发者轻松创建多语言版本。

### 核心配置

- **Text Domain**: `argon`
- **语言包路径**: `/languages`
- **加载逻辑**: `functions.php` 中的 `theme_slug_setup` 函数。

```php
function theme_slug_setup() {
    // ...
    load_theme_textdomain('argon', get_template_directory() . '/languages');
}
```

### 翻译指南

1. **PHP 文件中**：
   使用 WordPress 标准本地化函数：
   ```php
   // 返回翻译字符串
   $text = __('Hello World', 'argon');
   
   // 直接输出翻译字符串
   _e('Settings', 'argon');
   
   // 带有上下文的翻译
   _x('Post', 'noun', 'argon');
   ```

2. **创建语言包**：
   - 当前仓库未提供 `languages/argon.pot` 模板文件。
   - 可使用 Poedit 扫描主题源代码生成新的 `.po`（Text Domain 选择 `argon`），完成翻译后生成 `.mo`。
   - 将生成的 `.po/.mo` 文件放在 `languages/` 目录下即可被加载。

## 开发指南

### 本地开发环境搭建

#### 环境要求

- PHP 7.0 或更高版本
- WordPress 4.4 或更高版本
- MySQL 5.6 或更高版本
- 支持 .htaccess 的 Web 服务器（Apache/Nginx）

#### 安装步骤

1. 安装 WordPress
2. 将主题文件夹放置到 `wp-content/themes/argon/`
3. 在 WordPress 后台启用主题
4. 访问主题设置页面进行配置

#### 开发工具推荐

- 代码编辑器：VS Code、PhpStorm
- 浏览器开发工具：Chrome DevTools、Firefox Developer Tools
- 本地服务器：XAMPP、MAMP、Local by Flywheel
- 版本控制：Git

### 调试技巧

#### 启用 WordPress 调试模式

在 `wp-config.php` 中添加：

```php
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);
```

#### 查看错误日志

错误日志位于 `wp-content/debug.log`。

#### 浏览器控制台

JavaScript 错误会显示在浏览器控制台中。使用 `console.log()` 输出调试信息：

```javascript
console.log('argonConfig:', argonConfig);
console.log('PJAX loading:', pjaxLoading);
```


#### 网络请求调试

使用浏览器开发工具的 Network 面板查看 AJAX 请求：

- 检查请求 URL 和参数
- 查看响应内容和状态码
- 分析请求耗时

#### PJAX 调试

监听 PJAX 事件输出调试信息：

```javascript
$(document).on('pjax:send', function() {
	console.log('PJAX: 开始加载');
});

$(document).on('pjax:complete', function() {
	console.log('PJAX: 加载完成');
});

$(document).on('pjax:error', function(xhr, textStatus, error) {
	console.error('PJAX 错误:', error);
});
```

### 常见开发任务

#### 添加新的主题选项

1. 在 `settings.php` 中添加表单字段：

```php
<tr>
	<th>新选项</th>
	<td>
		<input type="text" name="argon_new_option" 
		       value="<?php echo esc_attr(get_option('argon_new_option', '')); ?>" />
		<p class="description">选项说明</p>
	</td>
</tr>
```

2. 在需要使用的地方读取选项：

```php
$new_option = get_option('argon_new_option', '默认值');
```


#### 修改文章列表样式

文章列表有三种预览样式，对应三个模板文件：

- `template-parts/content-preview-1.php` - 标准卡片样式
- `template-parts/content-preview-2.php` - 大图样式
- `template-parts/content-preview-3.php` - 简洁列表样式

修改对应文件即可改变样式。

#### 添加自定义 CSS

在后台设置页面的"高级设置"选项卡中，有"自定义 CSS"文本框，输入的 CSS 会自动添加到页面中。

或者直接修改 `style.css` 文件。

#### 添加自定义 JavaScript

在后台设置页面的"高级设置"选项卡中，有"自定义 JavaScript"文本框。

或者在 `argontheme.js` 文件末尾添加代码。

#### 修改评论表单

评论表单在 `comments.php` 文件中定义。可以修改表单字段、布局和样式。

#### 创建新的页面模板

1. 创建新的 PHP 文件，例如 `custom-page.php`
2. 在文件开头添加模板声明：

```php
<?php
/*
Template Name: 自定义页面
*/
?>
```

3. 编写页面内容
4. 在 WordPress 后台编辑页面时，可以在"页面属性"中选择该模板


### 主题更新

#### 更新检查器

主题使用 `plugin-update-checker`（Puc v4）实现自动更新检查。更新源由选项 `argon_update_source` 控制，不同取值会切换到不同的元数据地址：

```php
// functions.php
require_once(get_template_directory() . '/theme-update-checker/plugin-update-checker.php');
$argon_update_source = get_option('argon_update_source');
switch ($argon_update_source) {
	case "stop":
		break;
	case "fastgit":
		Puc_v4_Factory::buildUpdateChecker('https://api.solstice23.top/argon/info.json?source=fastgit', get_template_directory() . '/functions.php', 'argon');
		break;
	case "cfworker":
		Puc_v4_Factory::buildUpdateChecker('https://api.solstice23.top/argon/info.json?source=cfworker', get_template_directory() . '/functions.php', 'argon');
		break;
	case "solstice23top":
		Puc_v4_Factory::buildUpdateChecker('https://api.solstice23.top/argon/info.json?source=0', get_template_directory() . '/functions.php', 'argon');
		break;
	case "github":
	default:
		Puc_v4_Factory::buildUpdateChecker('https://raw.githubusercontent.com/solstice23/argon-theme/master/info.json', get_template_directory() . '/functions.php', 'argon');
}
```

#### 更新流程

1. 主题通过更新检查器向 WordPress 更新系统注册可用版本信息
2. 在后台“仪表盘 → 更新”或“外观 → 主题”中显示更新提示
3. 管理员点击更新后，由 WordPress 负责下载并覆盖主题文件

#### 手动更新

1. 下载最新版本的主题文件
2. 备份当前主题文件和数据库
3. 删除旧的主题文件夹
4. 上传新的主题文件夹
5. 在后台重新激活主题
6. 检查设置是否正常

### 多语言支持

#### 翻译文件

主题支持多语言，翻译文件位于 `languages/` 目录：

- `zh_TW.po` / `zh_TW.mo` - 繁体中文
- `en_US.po` / `en_US.mo` - 英文
- `ru_RU.po` / `ru_RU.mo` - 俄文

#### 添加新语言

当前仓库未提供 `languages/argon.pot` 模板文件。新增语言时可采用两种方式之一：

1. 使用 Poedit 扫描主题源代码生成新的 `.po`（Text Domain 选择 `argon`），完成翻译后生成 `.mo`
2. 使用 WP-CLI i18n 工具自行生成 POT，再在 Poedit 中基于 POT 创建语言包

生成的 `.po/.mo` 文件放置到 `languages/` 目录即可被 `load_theme_textdomain('argon', ... )` 加载


#### 在代码中使用翻译

PHP 中使用 `__()` 函数：

```php
echo __('文本内容', 'argon');
```

JavaScript 中使用全局翻译函数：

```javascript
// header.php 中定义翻译表
var translation = {
	'确定': '<?php _e("确定", "argon"); ?>',
	'取消': '<?php _e("取消", "argon"); ?>'
};

// argontheme.js 中使用
function __(text) {
	return translation[text] || text;
}

alert(__('确定'));
```

## 常见问题

### 样式问题

#### 样式不生效

1. 检查浏览器缓存，强制刷新（Ctrl+F5）
2. 在后台设置中启用"强制刷新缓存"
3. 检查 CSS 选择器优先级
4. 使用浏览器开发工具检查元素样式

#### 夜间模式颜色异常

1. 检查 CSS 变量是否正确定义
2. 确认 `html.darkmode` 类是否正确添加
3. 检查自定义 CSS 是否覆盖了夜间模式样式

#### 响应式布局错乱

1. 检查媒体查询断点
2. 确认元素宽度设置正确
3. 使用浏览器开发工具的响应式模式测试


### 功能问题

#### PJAX 加载失败

1. 检查浏览器控制台是否有 JavaScript 错误
2. 确认目标页面的 HTML 结构正确
3. 检查 PJAX 容器选择器是否匹配
4. 尝试禁用 PJAX 功能排查问题

#### 评论发送失败

1. 检查 AJAX 请求是否成功
2. 确认 nonce 验证是否通过
3. 检查验证码是否正确
4. 查看 PHP 错误日志

#### 图片懒加载不工作

1. 确认图片标签使用了 `data-src` 属性
2. 检查 Lazy Load 库是否正确加载
3. 确认懒加载功能已在后台启用
4. 检查浏览器控制台是否有错误

#### 代码高亮显示异常

1. 确认 Highlight.js 已加载（浏览器控制台 `window.hljs` 存在）
2. 确认代码高亮已启用（`argon_enable_code_highlight` 为 true，且 `argonConfig.code_highlight.enable` 为 true）
3. 确认高亮主题 CSS 已加载（footer.php 会输出 highlight 样式链接）
4. PJAX 场景下检查 `pjax:complete` 是否触发 `highlightJsRender()`

### 性能问题

#### 页面加载缓慢

1. 启用资源合并功能
2. 开启图片懒加载
3. 使用 CDN 加速静态资源
4. 优化数据库查询
5. 启用服务器缓存（如 Redis、Memcached）
6. 压缩图片大小


#### 内存占用过高

1. 减少同时加载的文章数量
2. 优化图片尺寸
3. 清理无用的插件和主题
4. 增加 PHP 内存限制（在 `wp-config.php` 中设置 `WP_MEMORY_LIMIT`）

#### JavaScript 执行卡顿

1. 减少 DOM 操作频率
2. 使用事件委托代替多个事件监听器
3. 优化瀑布流布局计算
4. 使用 `requestAnimationFrame` 优化动画

### 兼容性问题

#### 插件冲突

1. 逐个禁用插件排查冲突源
2. 检查插件是否修改了主题依赖的 WordPress 核心功能
3. 查看插件和主题的 JavaScript 是否有命名冲突
4. 联系插件作者或主题作者寻求解决方案

#### 浏览器兼容性

主题主要支持现代浏览器：

- Chrome 60+
- Firefox 60+
- Safari 12+
- Edge 79+

不支持 IE 浏览器。如需支持旧版浏览器，需要添加 polyfill。

#### PHP 版本兼容性

主题要求 PHP 7.0+。如果服务器 PHP 版本过低，需要升级 PHP 版本。


## 最佳实践

### 代码组织

#### 模块化开发

将功能拆分为独立的模块，便于维护和复用：

```javascript
// 评论模块
let CommentModule = {
	init: function() {
		this.bindEvents();
	},
	bindEvents: function() {
		$('#comment-submit').on('click', this.submitComment);
	},
	submitComment: function() {
		// 提交评论逻辑
	}
};

// 初始化
CommentModule.init();
```

#### 避免全局污染

使用立即执行函数表达式（IIFE）封装代码：

```javascript
(function($) {
	'use strict';
	
	// 私有变量和函数
	let privateVar = 'value';
	
	function privateFunction() {
		// ...
	}
	
	// 公开接口
	window.MyModule = {
		publicMethod: function() {
			// ...
		}
	};
	
})(jQuery);
```

#### 使用命名空间

避免函数名冲突：

```javascript
let ArgonTheme = ArgonTheme || {};

ArgonTheme.Utils = {
	getCookie: function(name) {
		// ...
	},
	setCookie: function(name, value) {
		// ...
	}
};
```


### 性能优化

#### 减少 HTTP 请求

1. 合并 CSS 和 JavaScript 文件
2. 使用 CSS Sprites 合并小图标
3. 使用字体图标代替图片图标
4. 启用浏览器缓存

#### 优化资源加载

1. 异步加载非关键 JavaScript
2. 延迟加载图片和视频
3. 使用 WebP 格式图片
4. 压缩和混淆 JavaScript 代码

#### 数据库优化

1. 使用索引加速查询
2. 避免 N+1 查询问题
3. 使用对象缓存（如 Redis）
4. 定期清理无用数据

#### 前端优化

1. 减少 DOM 操作
2. 使用 CSS3 动画代替 JavaScript 动画
3. 避免强制同步布局
4. 使用虚拟滚动处理长列表

### 安全实践

#### 输入验证

1. 验证所有用户输入
2. 使用白名单而非黑名单
3. 限制输入长度和格式
4. 防止 SQL 注入和 XSS 攻击

#### 输出转义

1. 使用 `esc_html()` 转义 HTML 内容
2. 使用 `esc_attr()` 转义 HTML 属性
3. 使用 `esc_url()` 转义 URL
4. 使用 `esc_js()` 转义 JavaScript 字符串


#### 权限控制

1. 检查用户权限后再执行敏感操作
2. 使用 `current_user_can()` 验证权限
3. 为 AJAX 请求添加 nonce 验证
4. 限制文件上传类型和大小

#### 数据保护

1. 使用 HTTPS 加密传输
2. 敏感数据加密存储
3. 定期备份数据库
4. 设置合理的文件权限

### 可维护性

#### 代码注释

1. 为复杂逻辑添加注释
2. 使用 JSDoc 格式注释函数
3. 注释应说明"为什么"而非"是什么"
4. 保持注释与代码同步更新

#### 版本控制

1. 使用 Git 管理代码
2. 编写清晰的提交信息
3. 使用分支管理功能开发
4. 定期合并和清理分支

#### 文档编写

1. 维护完整的开发文档
2. 记录 API 接口和参数
3. 提供使用示例
4. 更新变更日志

#### 代码审查

1. 定期审查代码质量
2. 检查是否遵循编码规范
3. 识别潜在的性能问题
4. 确保代码可读性


## 扩展开发

### 创建子主题

如果需要大量自定义修改，建议创建子主题：

1. 创建子主题目录 `wp-content/themes/argon-child/`

2. 创建 `style.css`：

```css
/*
Theme Name: Argon Child
Template: argon
Version: 1.0.0
*/
```

3. 创建 `functions.php`：

```php
<?php
function argon_child_enqueue_styles() {
	wp_enqueue_style('argon-parent-style', get_template_directory_uri() . '/style.css');
}
add_action('wp_enqueue_scripts', 'argon_child_enqueue_styles');
```

4. 在 WordPress 后台启用子主题

5. 在子主题中覆盖父主题的模板文件或添加新功能

### 开发插件扩展

为主题开发配套插件：

```php
<?php
/*
Plugin Name: Argon Extension
Description: Argon 主题扩展插件
Version: 1.0.0
*/

// 添加新功能
function argon_extension_feature() {
	// 功能代码
}
add_action('init', 'argon_extension_feature');

// 添加短代码
function argon_custom_shortcode($atts) {
	return '<div class="custom-content">自定义内容</div>';
}
add_shortcode('argon_custom', 'argon_custom_shortcode');
```


### 自定义 Widget

创建自定义侧边栏小工具：

```php
<?php
class Argon_Custom_Widget extends WP_Widget {
	public function __construct() {
		parent::__construct(
			'argon_custom_widget',
			'Argon 自定义小工具',
			array('description' => '自定义小工具描述')
		);
	}
	
	public function widget($args, $instance) {
		echo $args['before_widget'];
		echo $args['before_title'];
		echo esc_html($instance['title']);
		echo $args['after_title'];
		
		// 小工具内容
		echo '<div class="custom-widget-content">';
		echo esc_html($instance['content']);
		echo '</div>';
		
		echo $args['after_widget'];
	}
	
	public function form($instance) {
		$title = !empty($instance['title']) ? $instance['title'] : '';
		$content = !empty($instance['content']) ? $instance['content'] : '';
		?>
		<p>
			<label for="<?php echo $this->get_field_id('title'); ?>">标题：</label>
			<input class="widefat" id="<?php echo $this->get_field_id('title'); ?>" 
			       name="<?php echo $this->get_field_name('title'); ?>" 
			       type="text" value="<?php echo esc_attr($title); ?>">
		</p>
		<p>
			<label for="<?php echo $this->get_field_id('content'); ?>">内容：</label>
			<textarea class="widefat" id="<?php echo $this->get_field_id('content'); ?>" 
			          name="<?php echo $this->get_field_name('content'); ?>"><?php echo esc_textarea($content); ?></textarea>
		</p>
		<?php
	}
	
	public function update($new_instance, $old_instance) {
		$instance = array();
		$instance['title'] = sanitize_text_field($new_instance['title']);
		$instance['content'] = sanitize_text_field($new_instance['content']);
		return $instance;
	}
}

function register_argon_custom_widget() {
	register_widget('Argon_Custom_Widget');
}
add_action('widgets_init', 'register_argon_custom_widget');
```


### 添加自定义短代码

创建可在文章中使用的短代码：

```php
// 简单短代码
function argon_alert_shortcode($atts, $content = null) {
	$atts = shortcode_atts(array(
		'type' => 'info',
		'title' => ''
	), $atts);
	
	$output = '<div class="alert alert-' . esc_attr($atts['type']) . '">';
	if (!empty($atts['title'])) {
		$output .= '<h4>' . esc_html($atts['title']) . '</h4>';
	}
	$output .= do_shortcode($content);
	$output .= '</div>';
	
	return $output;
}
add_shortcode('alert', 'argon_alert_shortcode');

// 使用方式：
// [alert type="warning" title="注意"]这是警告内容[/alert]
```

### 自定义文章类型

除了说说，还可以创建其他自定义文章类型：

```php
function register_custom_post_type() {
	$args = array(
		'labels' => array(
			'name' => '作品集',
			'singular_name' => '作品'
		),
		'public' => true,
		'has_archive' => true,
		'rewrite' => array('slug' => 'portfolio'),
		'supports' => array('title', 'editor', 'thumbnail', 'excerpt'),
		'menu_icon' => 'dashicons-portfolio'
	);
	register_post_type('portfolio', $args);
}
add_action('init', 'register_custom_post_type');
```


### 添加自定义字段

为文章添加额外的元数据：

```php
// 添加元框
function argon_add_custom_meta_box() {
	add_meta_box(
		'argon_custom_meta',
		'自定义字段',
		'argon_custom_meta_box_callback',
		'post',
		'normal',
		'high'
	);
}
add_action('add_meta_boxes', 'argon_add_custom_meta_box');

// 元框内容
function argon_custom_meta_box_callback($post) {
	wp_nonce_field('argon_save_custom_meta', 'argon_custom_meta_nonce');
	$value = get_post_meta($post->ID, '_argon_custom_field', true);
	?>
	<label for="argon_custom_field">自定义字段：</label>
	<input type="text" id="argon_custom_field" name="argon_custom_field" 
	       value="<?php echo esc_attr($value); ?>" style="width: 100%;">
	<?php
}

// 保存元数据
function argon_save_custom_meta($post_id) {
	if (!isset($_POST['argon_custom_meta_nonce'])) {
		return;
	}
	if (!wp_verify_nonce($_POST['argon_custom_meta_nonce'], 'argon_save_custom_meta')) {
		return;
	}
	if (defined('DOING_AUTOSAVE') && DOING_AUTOSAVE) {
		return;
	}
	if (!current_user_can('edit_post', $post_id)) {
		return;
	}
	
	if (isset($_POST['argon_custom_field'])) {
		update_post_meta(
			$post_id,
			'_argon_custom_field',
			sanitize_text_field($_POST['argon_custom_field'])
		);
	}
}
add_action('save_post', 'argon_save_custom_meta');
```


## 测试与部署

### 本地测试

#### 功能测试

1. 测试所有页面模板是否正常显示
2. 测试评论发送、回复、编辑功能
3. 测试说说发布和显示
4. 测试 PJAX 页面切换
5. 测试夜间模式切换
6. 测试响应式布局在不同设备上的表现
7. 测试表单验证和错误提示

#### 兼容性测试

1. 在不同浏览器中测试（Chrome、Firefox、Safari、Edge）
2. 测试移动端浏览器（iOS Safari、Android Chrome）
3. 测试不同屏幕尺寸的显示效果
4. 测试与常用插件的兼容性

#### 性能测试

1. 使用 Chrome DevTools 的 Lighthouse 进行性能评分
2. 检查页面加载时间
3. 分析资源加载瀑布图
4. 测试大量数据时的性能表现

### 部署流程

#### 准备工作

1. 备份当前网站数据和数据库
2. 检查服务器环境是否满足要求
3. 准备主题文件和配置

#### 上传主题

1. 通过 FTP 上传主题文件到 `wp-content/themes/argon/`
2. 或在 WordPress 后台上传主题 ZIP 包
3. 确认文件权限正确（目录 755，文件 644）


#### 配置主题

1. 在 WordPress 后台启用主题
2. 访问主题设置页面进行配置
3. 设置主题色、布局等基本选项
4. 配置评论系统和验证码
5. 设置 AI 摘要服务（如需要）
6. 配置性能优化选项

#### 数据迁移

如果从其他主题迁移：

1. 导出原主题的设置和数据
2. 手动迁移必要的配置
3. 检查文章格式是否正常
4. 重新设置小工具和菜单
5. 测试所有功能是否正常

#### 上线检查

1. 清除所有缓存（浏览器、CDN、服务器）
2. 检查首页和主要页面显示
3. 测试评论功能
4. 检查移动端显示
5. 验证 SEO 设置
6. 测试表单提交
7. 检查 HTTPS 证书

### 维护与监控

#### 日常维护

1. 定期备份网站数据和数据库
2. 及时更新主题版本
3. 更新 WordPress 核心和插件
4. 清理垃圾评论和无用数据
5. 优化数据库表

#### 性能监控

1. 监控网站加载速度
2. 检查服务器资源使用情况
3. 分析访问日志
4. 监控错误日志
5. 定期进行性能测试


#### 安全维护

1. 定期更新所有组件
2. 检查文件完整性
3. 监控异常登录尝试
4. 定期更改管理员密码
5. 检查用户权限设置
6. 扫描恶意代码

#### 故障排查

当出现问题时：

1. 查看 WordPress 调试日志
2. 检查 PHP 错误日志
3. 查看浏览器控制台错误
4. 检查服务器错误日志
5. 禁用插件逐个排查
6. 切换到默认主题测试
7. 检查数据库连接
8. 验证文件权限

## 参考资源

### 官方文档

- WordPress Codex：https://codex.wordpress.org/
- WordPress Developer Resources：https://developer.wordpress.org/
- Bootstrap 4 文档：https://getbootstrap.com/docs/4.6/
- Argon Design System：https://www.creative-tim.com/product/argon-design-system

### 开发工具

- WordPress Debug Bar：调试插件
- Query Monitor：性能监控插件
- Theme Check：主题检查插件
- WP-CLI：WordPress 命令行工具

### 学习资源

- WordPress 主题开发手册
- PHP 官方文档
- JavaScript MDN 文档
- CSS-Tricks 网站


### 社区支持

- GitHub Issues：https://github.com/solstice23/argon-theme/issues
- WordPress 中文论坛
- Stack Overflow

## 附录

### 常用 WordPress 函数

#### 文章相关

```php
the_title()              // 输出文章标题
the_content()            // 输出文章内容
the_excerpt()            // 输出文章摘要
the_permalink()          // 输出文章链接
the_post_thumbnail()     // 输出特色图片
get_the_date()           // 获取发布日期
get_the_author()         // 获取作者名称
```

#### 评论相关

```php
comments_number()        // 输出评论数量
wp_list_comments()       // 输出评论列表
comment_form()           // 输出评论表单
get_comment_author()     // 获取评论作者
comment_text()           // 输出评论内容
```

#### 选项相关

```php
get_option()             // 获取选项值
update_option()          // 更新选项值
delete_option()          // 删除选项
add_option()             // 添加选项
```

#### 用户相关

```php
is_user_logged_in()      // 检查用户是否登录
current_user_can()       // 检查用户权限
get_current_user_id()    // 获取当前用户 ID
wp_get_current_user()    // 获取当前用户对象
```


### 常用 jQuery 方法

```javascript
// 选择器
$('#id')                 // ID 选择器
$('.class')              // 类选择器
$('element')             // 元素选择器

// DOM 操作
.html()                  // 获取或设置 HTML 内容
.text()                  // 获取或设置文本内容
.val()                   // 获取或设置表单值
.attr()                  // 获取或设置属性
.css()                   // 获取或设置样式
.addClass()              // 添加类
.removeClass()           // 移除类
.toggleClass()           // 切换类

// 事件
.on()                    // 绑定事件
.off()                   // 解绑事件
.click()                 // 点击事件
.change()                // 改变事件
.submit()                // 提交事件

// AJAX
$.ajax()                 // AJAX 请求
$.get()                  // GET 请求
$.post()                 // POST 请求
```

### 常用 CSS 类

Argon 主题基于 Bootstrap 4，可以使用以下常用类：

```css
/* 布局 */
.container               // 容器
.row                     // 行
.col-*                   // 列

/* 间距 */
.m-*                     // margin
.p-*                     // padding
.mt-*, .mb-*, .ml-*, .mr-*  // 单边间距

/* 文本 */
.text-center             // 居中对齐
.text-left               // 左对齐
.text-right              // 右对齐
.text-primary            // 主色文本
.text-muted              // 灰色文本

/* 按钮 */
.btn                     // 按钮基类
.btn-primary             // 主按钮
.btn-secondary           // 次按钮
.btn-sm, .btn-lg         // 按钮尺寸

/* 卡片 */
.card                    // 卡片
.card-body               // 卡片内容
.card-header             // 卡片头部
.card-footer             // 卡片底部
```


### 主题钩子列表

Argon 主题提供的自定义钩子：

```php
// 动作钩子
do_action('argon_before_header')      // 头部之前
do_action('argon_after_header')       // 头部之后
do_action('argon_before_content')     // 内容之前
do_action('argon_after_content')      // 内容之后
do_action('argon_before_footer')      // 底部之前
do_action('argon_after_footer')       // 底部之后
do_action('argon_before_comment')     // 评论之前
do_action('argon_after_comment')      // 评论之后

// 过滤钩子
apply_filters('argon_post_content', $content)        // 文章内容
apply_filters('argon_comment_content', $content)     // 评论内容
apply_filters('argon_excerpt_length', 200)           // 摘要长度
apply_filters('argon_theme_color', $color)           // 主题色
```

使用示例：

```php
// 在头部之后添加内容
function custom_after_header() {
	echo '<div class="custom-notice">自定义通知</div>';
}
add_action('argon_after_header', 'custom_after_header');

// 修改摘要长度
function custom_excerpt_length($length) {
	return 150;
}
add_filter('argon_excerpt_length', 'custom_excerpt_length');
```

### 版本历史

- v1.5.0 - 当前版本
  - 添加 AI 摘要功能
  - 优化性能和缓存机制
  - 改进安全性
  - 修复已知问题

- v1.4.x - 功能增强
  - 添加说说功能
  - 改进评论系统
  - 优化移动端体验

- v1.3.x - 稳定版本
  - 完善 PJAX 功能
  - 添加多种文章列表样式
  - 改进夜间模式

- v1.2.x - 初始版本
  - 基础功能实现
  - Material Design 界面
  - 响应式布局


## 結語

本文檔用於內部開發協作，聚焦於主題架構、關鍵模組、開發規範與排查路徑，目標是讓開發者能以一致的方法理解、修改與驗證功能。

在日常開發與維護中，建議遵循以下原則：

1. 以實際程式碼為準，文件同步更新，避免規格漂移
2. 變更前先界定影響範圍（頁面類型、PJAX、設定項、相依資源）
3. 變更後完成基本回歸（切換頁面、文章頁、評論、行動端、暗色模式）
4. 優先保留相容性與可回退性，避免破壞既有站點行為
5. 對安全與效能保持敏感（輸出轉義、權限檢查、資源載入與快取）

若需討論或提案，請依內部既定流程提交（需求/缺陷、代碼審查、發布/回滾），並附上可重現步驟與必要的日誌或截圖。