---
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` - 后台样式