feat: Argon WordPress主题完整版本

- 基于Argon主题的WordPress博客主题 - 支持响应式设计和暗色模式 - 包含完整的文章管理和评论系统 - 集成友情链接管理功能 - 支持多种自定义设置选项 - 优化的用户界面和交互体验
2026-01-11 19:48:02 +08:00
commit 31d8fde308
547 changed files with 147669 additions and 0 deletions
--- a/.kiro/steering/communication.md
+++ b/.kiro/steering/communication.md
@@ -0,0 +1,23 @@
+# 交流规范
+
+## 语言
+- 与用户交流时使用中文
+- 代码注释可以使用英文或中文，根据项目现有风格保持一致
+
+## Git 提交规范
+- 功能修复和添加功能使用不同的 git commit/push
+- 修复类提交：`fix: 简要描述修复内容`
+- 功能类提交：`feat: 简要描述新功能`
+- commit 信息应包含详细的修改说明，格式如下：
+  ```
+  fix/feat: 简要标题
+  
+  - 具体修改点1
+  - 具体修改点2
+  - ...
+  ```
+
+## 回答风格
+- 内容详略得当，重点突出
+- 通俗易懂，避免过度技术化的表述
+- 修复报告应写在 git commit 信息中，而非对话回复中
--- a/.kiro/steering/settings-page-guide.md
+++ b/.kiro/steering/settings-page-guide.md
@@ -0,0 +1,285 @@
+---
+inclusion: fileMatch
+fileMatchPattern: "settings.php"
+---
+
+# Argon 主题设置页开发指南
+
+本文档为 AI 助手和开发者提供 `settings.php` 文件的结构说明和开发规范。
+
+## 文件概述
+
+`settings.php` 是 Argon 主题的核心设置页面，包含所有主题配置选项。该文件通过 WordPress 后台管理界面呈现给用户。
+
+## 设置页分类结构
+
+设置页采用 **二级分类** 结构：
+- **一级分类 (h2)**：主要功能模块
+- **二级分类 (h3)**：模块内的子功能
+
+### 分类层级（当前结构）
+
+```
+1. 基础设置 (section-basic)
+   ├── 主题色 (subsection-theme-color)
+   └── 夜间模式 (subsection-dark-mode)
+
+2. 外观样式 (section-appearance)
+   ├── 卡片样式 (subsection-card-style)
+   └── 字体 (subsection-font)
+
+3. 页面布局 (section-layout)
+   └── 整体布局 (subsection-page-layout)
+
+4. 顶栏设置 (section-toolbar)
+   ├── 基本设置 (subsection-toolbar-basic)
+   ├── 顶栏标题 (subsection-toolbar-title)
+   ├── 顶栏图标 (subsection-toolbar-icon)
+   ├── 顶栏外观 (subsection-toolbar-appearance)
+   └── 自定义链接 (subsection-toolbar-links)
+
+5. Banner 设置 (section-banner)
+   ├── Banner 内容 (subsection-banner-content)
+   ├── Banner 外观 (subsection-banner-appearance)
+   └── Banner 动画 (subsection-banner-animation)
+
+6. 页面背景 (section-background)
+   ├── 背景图片 (subsection-background-image)
+   └── 透明度与毛玻璃 (subsection-transparency)
+
+7. 侧边栏 (section-sidebar)
+   ├── 作者信息 (subsection-author-info)
+   ├── 扩展功能 (subsection-sidebar-features)
+   └── 博客公告 (subsection-announcement)
+
+8. 浮动按钮与页脚 (section-fab-footer)
+   ├── 浮动操作按钮 (subsection-fab)
+   └── 页脚设置 (subsection-footer)
+
+9. 高级设置 (section-advanced)
+   ├── SEO (subsection-seo)
+   ├── CDN (subsection-cdn)
+   ├── 子目录 (subsection-subdirectory)
+   ├── 日期格式 (subsection-date-format)
+   ├── 自定义脚本 (subsection-scripts)
+   └── 杂项 (subsection-misc)
+
+10. 文章显示 (section-post-display)
+    ├── Meta 信息 (subsection-post-meta)
+    ├── 文章头图 (subsection-thumbnail)
+    ├── 标题样式 (subsection-title-style)
+    └── 过时提示 (subsection-post-other)
+
+11. 文章功能 (section-post-features)
+    ├── 脚注引用 (subsection-footnote)
+    ├── 分享按钮 (subsection-share)
+    ├── 文章目录 (subsection-toc)
+    ├── 赞赏功能 (subsection-donate)
+    ├── 文末内容 (subsection-post-footer)
+    └── 相似推荐 (subsection-related-posts)
+
+12. 特殊页面 (section-special-pages)
+    ├── 归档页面 (subsection-archive)
+    ├── 搜索设置 (subsection-search)
+    └── 友情链接 (subsection-friend-links)
+
+13. 功能增强 (section-enhancements)
+    ├── 代码高亮 (subsection-code-highlight)
+    ├── 数学公式 (subsection-math)
+    ├── Lazyload (subsection-lazyload)
+    ├── 图片放大 (subsection-lightbox)
+    ├── Pangu.js (subsection-pangu)
+    └── 动画效果 (subsection-animation)
+
+14. 评论设置 (section-comment)
+    ├── 评论分页 (subsection-comment-pagination)
+    ├── 发送评论 (subsection-comment-submit)
+    ├── 评论功能 (subsection-comment-features)
+    └── 评论区外观 (subsection-comment-appearance)
+
+15. 验证码与安全 (section-security)
+    ├── 验证码设置 (subsection-captcha)
+    ├── 场景验证码 (subsection-captcha-scenes)
+    └── 速率限制 (subsection-rate-limit)
+```
+
+## HTML 结构规范
+
+### 一级分类标题 (h2)
+```php
+<!-- ========== N. 分类名称 ========== -->
+<tr><th class="subtitle"><h2 id="section-{section-id}"><?php _e("分类名称", 'argon');?></h2></th></tr>
+```
+
+### 二级分类标题 (h3)
+```php
+<tr><th class="subtitle"><h3 id="subsection-{subsection-id}"><?php _e("子分类名称", 'argon');?></h3></th></tr>
+```
+
+### 设置项结构
+```php
+<tr>
+    <th><label><?php _e("设置项名称", 'argon');?></label></th>
+    <td>
+        <!-- 输入控件 -->
+        <p class="description"><?php _e("设置项说明", 'argon');?></p>
+    </td>
+</tr>
+```
+
+## 常用输入控件
+
+### 下拉选择框
+```php
+<select name="argon_option_name">
+    <?php $value = get_option('argon_option_name', 'default'); ?>
+    <option value="value1" <?php if ($value=='value1'){echo 'selected';} ?>><?php _e('选项1', 'argon');?></option>
+    <option value="value2" <?php if ($value=='value2'){echo 'selected';} ?>><?php _e('选项2', 'argon');?></option>
+</select>
+```
+
+### 文本输入框
+```php
+<input type="text" class="regular-text" name="argon_option_name" value="<?php echo get_option('argon_option_name', ''); ?>"/>
+```
+
+### 数字输入框
+```php
+<input type="number" name="argon_option_name" min="0" max="100" value="<?php echo get_option('argon_option_name', '50'); ?>"/>
+```
+
+### 复选框
+```php
+<?php $checked = get_option('argon_option_name', 'false'); ?>
+<label>
+    <input type="checkbox" name="argon_option_name" value="true" <?php if ($checked=='true'){echo 'checked';}?>/> 
+    <?php _e('选项说明', 'argon');?>
+</label>
+```
+
+### 颜色选择器
+```php
+<input type="color" name="argon_option_name" value="<?php echo get_option('argon_option_name', '#5e72e4'); ?>" style="height:40px;width:80px;cursor:pointer;"/>
+```
+
+### 多行文本框
+```php
+<textarea name="argon_option_name" rows="5" cols="70"><?php echo get_option('argon_option_name', ''); ?></textarea>
+```
+
+## 选项保存
+
+在文件末尾的 `argon_update_themeoptions()` 函数中添加选项保存：
+
+```php
+// 普通选项
+argon_update_option('argon_option_name');
+
+// 允许 HTML 标签的选项
+argon_update_option_allow_tags('argon_option_name');
+
+// 复选框选项
+argon_update_option_checkbox('argon_option_name');
+```
+
+## 国际化
+
+所有用户可见文本必须使用 `_e()` 或 `__()` 函数包裹：
+
+```php
+<?php _e("文本内容", 'argon');?>
+<?php echo __("文本内容", 'argon');?>
+<?php echo sprintf(__('包含 %s 的文本', 'argon'), $variable);?>
+```
+
+## 设置项归属参考
+
+### 应归入"基础设置"的选项
+- argon_theme_color (主题颜色)
+- argon_enable_immersion_color (沉浸式主题色)
+- argon_show_customize_theme_color_picker (允许用户自定义主题色)
+- argon_darkmode_autoswitch (夜间模式切换方案)
+- argon_enable_amoled_dark (夜间模式颜色方案)
+- argon_dateformat (日期格式)
+
+### 应归入"外观样式"的选项
+- argon_card_radius (卡片圆角)
+- argon_card_shadow (卡片阴影)
+- argon_font (默认字体)
+- argon_enable_smoothscroll_type (平滑滚动)
+- argon_enable_into_article_animation (进入文章动画)
+- argon_disable_pjax_animation (禁用 Pjax 动画)
+
+### 应归入"页面布局"的选项
+- argon_page_layout (页面布局)
+- argon_article_list_waterflow (文章列表布局)
+- argon_article_list_layout (文章列表卡片布局)
+
+### 应归入"顶栏设置"的选项
+- argon_enable_headroom (顶栏显示状态)
+- argon_toolbar_title (顶栏标题)
+- argon_toolbar_icon (图标地址)
+- argon_toolbar_icon_link (图标链接)
+- argon_toolbar_blur (毛玻璃效果)
+- argon_toolbar_style (顶栏样式)
+- argon_toolbar_shadow (顶栏阴影)
+- argon_toolbar_border (底部边框)
+- argon_toolbar_compact (紧凑模式)
+- argon_toolbar_center (标题居中)
+- argon_toolbar_links_left (左侧自定义链接)
+- argon_toolbar_links_right (右侧自定义链接)
+
+### 应归入"Banner 设置"的选项
+- argon_banner_title (Banner 标题)
+- argon_banner_subtitle (Banner 副标题)
+- argon_banner_size (Banner 显示状态)
+- argon_page_background_banner_style (Banner 透明化)
+- argon_show_toolbar_mask (顶栏遮罩)
+- argon_banner_background_url (背景图地址)
+- argon_banner_background_color_type (渐变背景样式)
+- argon_banner_background_hide_shapes (隐藏背景圆)
+- argon_enable_banner_title_typing_effect (打字动画)
+- argon_banner_typing_effect_interval (打字动画时长)
+
+### 应归入"侧边栏"的选项
+- argon_sidebar_banner_title (左侧栏标题)
+- argon_sidebar_banner_subtitle (左侧栏子标题)
+- argon_sidebar_auther_name (作者名称)
+- argon_sidebar_auther_image (作者头像)
+- argon_sidebar_author_description (作者简介)
+- argon_show_todo_list (TODO 列表)
+- argon_show_duolingo_streak (多邻国连胜)
+- argon_duolingo_username (多邻国用户名)
+- argon_sidebar_announcement (公告内容)
+- argon_show_headindex_number (目录序号)
+
+### 应归入"验证码与安全"的选项
+- argon_need_captcha (全局验证码开关)
+- argon_captcha_type (验证码类型)
+- argon_geetest_captcha_id (极验 ID)
+- argon_geetest_captcha_key (极验 Key)
+- argon_geetest_api_server (极验服务器)
+- argon_get_captcha_by_ajax (Ajax 获取验证码)
+- argon_comment_captcha_mode (评论验证码)
+- argon_todo_captcha_mode (TODO 验证码)
+- argon_friend_link_captcha (友链验证码)
+- argon_rate_limit_enable (速率限制)
+- argon_rate_limit_window (速率窗口)
+- argon_rate_limit_max_count (最大次数)
+- argon_rate_limit_min_interval (最小间隔)
+
+## 注意事项
+
+1. **选项命名**：所有选项名必须以 `argon_` 前缀开头
+2. **默认值**：使用 `get_option('name', 'default')` 的第二个参数设置默认值
+3. **安全性**：用户输入的 HTML 内容需使用 `argon_update_option_allow_tags()` 保存
+4. **响应式**：设置页需要在移动端正常显示
+5. **目录导航**：页面右侧有自动生成的目录，h2/h3 标题会被收录
+
+## 相关文件
+
+- `functions.php` - 主题函数，包含选项的使用逻辑
+- `header.php` - 页头，使用顶栏相关选项
+- `footer.php` - 页脚，使用页脚相关选项
+- `style.css` - 主题样式
+- `admin.css` - 后台样式