nanhaoluo
31d8fde308
- 基于Argon主题的WordPress博客主题 - 支持响应式设计和暗色模式 - 包含完整的文章管理和评论系统 - 集成友情链接管理功能 - 支持多种自定义设置选项 - 优化的用户界面和交互体验
286 lines
9.7 KiB
Markdown
286 lines
9.7 KiB
Markdown
---
|
||
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` - 后台样式
|