nanhaoluo/argon-theme
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a7af3877b862b24a7b5fa9631c2a9f8cfda42e6e
argon-theme/.kiro/steering/settings-page-guide.md
nanhaoluo 31d8fde308 feat: Argon WordPress主题完整版本 
- 基于Argon主题的WordPress博客主题
- 支持响应式设计和暗色模式
- 包含完整的文章管理和评论系统
- 集成友情链接管理功能
- 支持多种自定义设置选项
- 优化的用户界面和交互体验
2026-01-11 19:48:02 +08:00

9.7 KiB
Raw Blame History

inclusion, fileMatchPattern
inclusion fileMatchPattern
fileMatch 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)

<!-- ========== N. 分类名称 ========== -->
<tr><th class="subtitle"><h2 id="section-{section-id}"><?php _e("分类名称", 'argon');?></h2></th></tr>

二级分类标题 (h3)

<tr><th class="subtitle"><h3 id="subsection-{subsection-id}"><?php _e("子分类名称", 'argon');?></h3></th></tr>

设置项结构

<tr>
    <th><label><?php _e("设置项名称", 'argon');?></label></th>
    <td>
        <!-- 输入控件 -->
        <p class="description"><?php _e("设置项说明", 'argon');?></p>
    </td>
</tr>

常用输入控件

下拉选择框

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

文本输入框

<input type="text" class="regular-text" name="argon_option_name" value="<?php echo get_option('argon_option_name', ''); ?>"/>

数字输入框

<input type="number" name="argon_option_name" min="0" max="100" value="<?php echo get_option('argon_option_name', '50'); ?>"/>

复选框

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

颜色选择器

<input type="color" name="argon_option_name" value="<?php echo get_option('argon_option_name', '#5e72e4'); ?>" style="height:40px;width:80px;cursor:pointer;"/>

多行文本框

<textarea name="argon_option_name" rows="5" cols="70"><?php echo get_option('argon_option_name', ''); ?></textarea>

选项保存

在文件末尾的 argon_update_themeoptions() 函数中添加选项保存：

// 普通选项
argon_update_option('argon_option_name');

// 允许 HTML 标签的选项
argon_update_option_allow_tags('argon_option_name');

// 复选框选项
argon_update_option_checkbox('argon_option_name');

国际化

所有用户可见文本必须使用 _e() 或 __() 函数包裹：

<?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 - 后台样式
Reference in New Issue View Git Blame Copy Permalink