B2 子主题开发文档

目录

1. 概述
2. 目录结构
3. 框架架构
4. 字段类型详解
5. 后台设置模块
6. 前端应用
7. 开发指南
8. 常见问题
9. API 参考

---

概述

B2 子主题（b2child）是基于 B2 主题的子主题，内置了 Xun Framework 选项框架。它允许开发者在不需要修改父主题核心代码的前提下，实现主题的定制和扩展。

主要特性

• 完整的选项框架：内置 Xun Framework，提供 23 种字段类型
• 模块化设计：清晰的目录结构，便于维护和扩展
• 前端集成：自动输出自定义 CSS/JS 到前端
• 多语言支持：支持 WordPress 国际化
• 性能优化：轻量级框架，不影响主题性能

---

目录结构

wp-content/themes/b2child/
├── functions.php                    # 子主题主入口文件
├── style.css                       # 子主题样式文件
├── child.js                        # 子主题脚本文件
├── 说明.txt                        # 简要说明文档
├── README.md                       # 开发文档（MDX版本）
├── README.mdx                      # 开发文档（MDX版本）
├── B2子主题开发文档.md             # 本文档
└── framework/                      # Xun Framework框架目录
    ├── xun-framework.php          # 框架入口文件
    ├── classes/                    # 框架核心类
    │   ├── setup.class.php         # 初始化类
    │   ├── admin-options.class.php # 后台选项页类
    │   ├── fields.class.php       # 字段基类
    │   └── icons.class.php        # 图标管理类
    ├── functions/                  # 辅助函数
    │   ├── helpers.php            # 通用工具函数
    │   ├── sanitize.php           # 数据清理函数
    │   └── validate.php           # 数据验证函数
    ├── fields/                     # 字段类型实现
    │   ├── text/                   # 文本字段
    │   ├── textarea/               # 文本域字段
    │   ├── switch/                 # 开关字段
    │   ├── select/                # 选择字段
    │   ├── number/                 # 数字字段
    │   ├── color/                  # 颜色字段
    │   ├── media/                  # 媒体字段
    │   ├── gallery/                # 画廊字段
    │   ├── radio/                  # 单选字段
    │   ├── checkbox/               # 多选字段
    │   ├── palette/                # 色板字段
    │   ├── slider/                 # 滑块字段
    │   ├── sortable/               # 排序字段
    │   ├── sorter/                 # 分类器字段
    │   ├── background/             # 背景字段
    │   ├── border/                 # 边框字段
    │   ├── icon/                   # 图标字段
    │   ├── date/                   # 日期字段
    │   ├── code/                   # 代码字段
    │   ├── button/                 # 按钮字段
    │   └── accordion/               # 折叠组字段
    └── assets/                     # 后台UI资源
        ├── css/                    # 样式文件
        ├── js/                     # 脚本文件
        └── fields/                 # 字段专用脚本

---

框架架构

核心组件

1. 初始化系统

• 文件: framework/classes/setup.class.php
• 功能: 框架初始化、常量定义、资源加载、钩子注册
• 关键方法:
  • init(): 框架初始化
  • load_classes(): 加载核心类
  • enqueue_assets(): 加载资源文件

2. 选项管理

• 文件: framework/classes/admin-options.class.php
• 功能: 后台选项页面管理、表单渲染、数据保存
• 关键方法:
  • create_options_page(): 创建选项页面
  • render_sections(): 渲染设置分区
  • save_options(): 保存选项数据

3. 字段系统

• 文件: framework/classes/fields.class.php
• 功能: 字段工厂、统一渲染、数据验证
• 关键方法:
  • render_field(): 渲染字段
  • sanitize_value(): 清理数据
  • validate_value(): 验证数据

4. 图标系统

• 文件: framework/classes/icons.class.php
• 功能: 图标注册、检索、渲染
• 支持: Heroicons 图标库

---

字段类型详解

基础字段

1. 文本字段 (text)

array(
    'id' => 'site_title',
    'type' => 'text',
    'title' => '站点标题',
    'placeholder' => '请输入站点标题',
    'default' => '',
    'attributes' => array(
        'maxlength' => 100,
        'required' => true
    )
)

属性说明:

• id: 字段唯一标识符
• type: 字段类型
• title: 字段标题
• placeholder: 占位符文本
• default: 默认值
• attributes: HTML 属性

2. 文本域字段 (textarea)

array(
    'id' => 'site_description',
    'type' => 'textarea',
    'title' => '站点描述',
    'placeholder' => '请输入站点描述...',
    'default' => '',
    'attributes' => array(
        'rows' => 4,
        'cols' => 50
    )
)

3. 开关字段 (switch)

array(
    'id' => 'enable_feature',
    'type' => 'switch',
    'title' => '启用功能',
    'default' => true,
    'on_text' => '开启',
    'off_text' => '关闭'
)

选择字段

4. 下拉选择 (select)

array(
    'id' => 'layout_style',
    'type' => 'select',
    'title' => '布局风格',
    'options' => array(
        'default' => '默认',
        'wide' => '通栏',
        'boxed' => '居中盒装'
    ),
    'default' => 'default'
)

5. 单选字段 (radio)

array(
    'id' => 'display_mode',
    'type' => 'radio',
    'title' => '展示模式',
    'options' => array(
        'list' => '列表',
        'grid' => '网格',
        'masonry' => '瀑布流'
    ),
    'default' => 'list'
)

6. 多选字段 (checkbox)

array(
    'id' => 'enabled_modules',
    'type' => 'checkbox',
    'title' => '启用模块',
    'options' => array(
        'banner' => '横幅',
        'sidebar' => '侧边栏',
        'footer' => '页脚工具区'
    ),
    'default' => array('banner', 'sidebar')
)

媒体字段

7. 媒体字段 (media)

array(
    'id' => 'logo',
    'type' => 'media',
    'title' => '站点Logo',
    'library' => 'image',
    'default' => '',
    'attributes' => array(
        'accept' => 'image/*'
    )
)

8. 画廊字段 (gallery)

array(
    'id' => 'homepage_gallery',
    'type' => 'gallery',
    'title' => '首页画廊',
    'default' => array(),
    'attributes' => array(
        'multiple' => true
    )
)

样式字段

9. 颜色字段 (color)

array(
    'id' => 'primary_color',
    'type' => 'color',
    'title' => '主题主色',
    'default' => '#2f54eb',
    'attributes' => array(
        'alpha' => true
    )
)

10. 色板字段 (palette)

array(
    'id' => 'accent_palette',
    'type' => 'palette',
    'title' => '强调色板',
    'options' => array(
        '#1677ff', '#fa541c', '#13c2c2',
        '#eb2f96', '#2f54eb', '#52c41a'
    ),
    'default' => '#1677ff'
)

11. 背景字段 (background)

array(
    'id' => 'page_background',
    'type' => 'background',
    'title' => '页面背景',
    'default' => array(
        'color' => '#ffffff',
        'image' => '',
        'position' => 'center center',
        'repeat' => 'no-repeat',
        'size' => 'cover'
    )
)

12. 边框字段 (border)

array(
    'id' => 'card_border',
    'type' => 'border',
    'title' => '卡片边框',
    'default' => array(
        'width' => '1px',
        'style' => 'solid',
        'color' => '#e0e0e0',
        'radius' => '4px'
    )
)

数值字段

13. 数字字段 (number)

array(
    'id' => 'items_per_page',
    'type' => 'number',
    'title' => '每页文章数',
    'default' => 10,
    'attributes' => array(
        'min' => 1,
        'max' => 50,
        'step' => 1
    )
)

14. 滑块字段 (slider)

array(
    'id' => 'slider_speed',
    'type' => 'slider',
    'title' => '轮播速度(秒)',
    'min' => 1,
    'max' => 10,
    'step' => 1,
    'default' => 5
)

交互字段

15. 排序字段 (sortable)

array(
    'id' => 'homepage_blocks_order',
    'type' => 'sortable',
    'title' => '首页区块排序',
    'fields' => array(
        array(
            'id' => 'hero',
            'type' => 'content',
            'title' => '焦点图',
            'content' => '<div>首页焦点图模块</div>'
        ),
        array(
            'id' => 'posts',
            'type' => 'content',
            'title' => '文章',
            'content' => '<div>最新文章模块</div>'
        )
    ),
    'default' => array('hero', 'posts')
)

16. 分类器字段 (sorter)

array(
    'id' => 'modules_sorter',
    'type' => 'sorter',
    'title' => '模块启用/禁用',
    'options' => array(
        'enabled' => array(
            'hero' => '焦点图',
            'posts' => '文章'
        ),
        'disabled' => array(
            'links' => '友链',
            'footer' => '页脚区块'
        )
    )
)

高级字段

17. 代码字段 (code)

array(
    'id' => 'custom_css',
    'type' => 'code',
    'title' => '自定义CSS',
    'default' => '',
    'language' => 'css',
    'theme' => 'light',
    'height' => 260,
    'tab_size' => 2,
    'show_line_numbers' => true,
    'format_button' => true,
    'copy_button' => true,
    'word_wrap' => true
)

18. 图标字段 (icon)

array(
    'id' => 'default_icon',
    'type' => 'icon',
    'title' => '默认图标',
    'default' => 'hero-outline-home',
    'library' => 'heroicons'
)

19. 日期字段 (date)

array(
    'id' => 'event_date',
    'type' => 'date',
    'title' => '活动日期',
    'default' => '',
    'attributes' => array(
        'date_format' => 'Y-m-d',
        'time_format' => 'H:i'
    )
)

20. 按钮字段 (button)

array(
    'id' => 'action_button',
    'type' => 'button',
    'title' => '测试按钮',
    'text' => '点击测试',
    'class' => 'button button-primary',
    'attributes' => array(
        'onclick' => 'alert("按钮被点击了！")'
    )
)

分组字段

21. 折叠组字段 (accordion)

array(
    'id' => 'faq_group',
    'type' => 'accordion',
    'title' => 'FAQ 折叠组',
    'multiple' => true,
    'collapsible' => true,
    'accordions' => array(
        array(
            'title' => '常见问题',
            'open' => true,
            'fields' => array(
                array(
                    'id' => 'faq_title',
                    'type' => 'text',
                    'title' => '问题标题'
                ),
                array(
                    'id' => 'faq_answer',
                    'type' => 'textarea',
                    'title' => '问题答案'
                )
            )
        )
    )
)

22. 重复项字段 (repeater)

array(
    'id' => 'links_repeater',
    'type' => 'repeater',
    'title' => '自定义链接列表',
    'fields' => array(
        array(
            'id' => 'title',
            'type' => 'text',
            'title' => '标题'
        ),
        array(
            'id' => 'url',
            'type' => 'text',
            'title' => '链接URL'
        ),
        array(
            'id' => 'thumb',
            'type' => 'media',
            'title' => '缩略图'
        )
    ),
    'default' => array()
)

23. 内容字段 (content)

array(
    'id' => 'info_content',
    'type' => 'content',
    'title' => '信息内容',
    'content' => '<div class="notice notice-info"><p>这是一个信息提示框</p></div>'
)

---

后台设置模块

菜单结构

WordPress后台
├── 子主题设置 (b2child-options)
    ├── 基本设置
    ├── 媒体与图集
    ├── 自定义代码
    ├── 文本与内容
    ├── 选择控件
    ├── 数值与滑块
    ├── 排序与拖拽
    ├── 设计与外观
    ├── 日期与按钮
    └── 分组与重复项

已配置的字段

基本设置

• 站点副标题 (text): site_subtitle
• 启用自定义功能 (switch): enable_feature
• 主题主色 (color): primary_color – 默认 #2f54eb
• 站点 Logo (media): logo
• 布局风格 (select): layout_style – 选项: 默认/通栏/居中盒装
• 每页文章数 (number): items_per_page – 范围: 1-50，默认: 10

媒体与图集

• 首页画廊 (gallery): homepage_gallery

自定义代码

• 自定义 CSS (code): custom_css – 语言: CSS，主题: light
• 自定义 JS (code): custom_js – 语言: JavaScript，主题: light

文本与内容

• 站点描述 (textarea): site_description

选择控件

• 展示模式 (radio): display_mode – 选项: 列表/网格/瀑布流
• 启用模块 (checkbox): enabled_modules – 选项: 横幅/侧边栏/页脚工具区
• 强调色板 (palette): accent_palette – 预设颜色选择

数值与滑块

• 轮播速度 (slider): homepage_slider_speed – 范围: 1-10 秒，默认: 5

排序与拖拽

• 首页区块排序 (sortable): homepage_blocks_order – 包含: 焦点图/文章/产品/友链/页脚区块
• 模块启用/禁用 (sorter): modules_sorter – 左右两列分类

设计与外观

• 页面背景 (background): page_background
• 卡片边框 (border): card_border
• 默认图标 (icon): default_icon

日期与按钮

• 活动日期 (date): event_date
• 测试按钮 (button): action_button

分组与重复项

• FAQ 折叠组 (accordion): faq_group – 包含: 问题标题/问题答案
• 自定义链接列表 (repeater): links_repeater – 包含: 标题/链接 URL/缩略图

---

前端应用

读取选项数据

读取整个选项组

$options = XUN::get_option('b2child_options');

读取单个字段

$primary_color = XUN::get_option('b2child_options', 'primary_color', '#2f54eb');
$site_title = XUN::get_option('b2child_options', 'site_subtitle', '');

更新选项数据

XUN::set_option('b2child_options', 'primary_color', '#ff0000');

前端集成示例

1. 注入 CSS 变量

add_action('wp_head', function(){
    if (!class_exists('XUN')) return;
    $primary = XUN::get_option('b2child_options', 'primary_color', '#2f54eb');
    echo '<style>:root{--b2child-primary:' . esc_attr($primary) . ';}</style>';
}, 100);

2. 布局样式切换

$layout = XUN::get_option('b2child_options', 'layout_style', 'default');
echo '<div class="layout-' . esc_attr($layout) . '">';
// 内容
echo '</div>';

3. 自定义 CSS/JS 输出

// 自定义CSS
add_action('wp_head', function(){
    if (!class_exists('XUN')) return;
    $css = XUN::get_option('b2child_options', 'custom_css', '');
    if ($css) echo '<style id="b2child-custom-css">' . $css . '</style>';
}, 110);

// 自定义JS
add_action('wp_footer', function(){
    if (!class_exists('XUN')) return;
    $js = XUN::get_option('b2child_options', 'custom_js', '');
    if ($js) echo '<script id="b2child-custom-js">' . $js . '</script>';
}, 110);

4. 根据排序渲染模块

$order = XUN::get_option('b2child_options', 'homepage_blocks_order',
    array('hero','posts','products','links','footer'));
foreach ($order as $block) {
    get_template_part('template-parts/home/' . sanitize_key($block));
}

5. 条件显示模块

$enabled_modules = XUN::get_option('b2child_options', 'enabled_modules', array());
if (in_array('banner', $enabled_modules)) {
    get_template_part('template-parts/banner');
}

---

开发指南

添加新字段

1. 在现有分区添加字段

// 在 functions.php 的 b2child_register_theme_options() 函数中
XUN::createSection('b2child_options', array(
    'id' => 'basic_settings',
    'title' => '基本设置',
    'icon' => 'dashicons-admin-generic',
    'parent' => 'theme_root',
    'fields' => array(
        // 现有字段...
        array(
            'id' => 'new_field',
            'type' => 'text',
            'title' => '新字段',
            'default' => ''
        )
    )
));

2. 创建新分区

XUN::createSection('b2child_options', array(
    'id' => 'new_section',
    'title' => '新分区',
    'icon' => 'dashicons-admin-settings',
    'parent' => 'theme_root',
    'fields' => array(
        array(
            'id' => 'section_field',
            'type' => 'text',
            'title' => '分区字段',
            'default' => ''
        )
    )
));

创建自定义字段类型

1. 创建字段目录

framework/fields/custom_field/
└── custom_field.php

2. 实现字段类

<?php
if (!defined('ABSPATH')) {
    exit;
}

class XUN_Field_Custom_Field extends XUN_Fields
{
    public function __construct($field, $value = '', $unique = '', $where = '', $parent = '')
    {
        parent::__construct($field, $value, $unique, $where, $parent);
    }

    public function render()
    {
        $output = '<div class="xun-field-custom-field">';
        $output .= '<input type="text" name="' . $this->field_name() . '" value="' . $this->value . '" />';
        $output .= '</div>';

        echo $output;
    }
}

扩展框架功能

1. 添加自定义钩子

// 在框架初始化后执行
add_action('xun_init', function(){
    // 自定义逻辑
});

2. 覆盖默认样式

add_action('admin_enqueue_scripts', function(){
    wp_enqueue_style('custom-admin-style',
        get_stylesheet_directory_uri() . '/admin-custom.css');
});

---

常见问题

1. 后台没有"子主题设置"菜单？

可能原因:

• 子主题未正确激活
• 框架文件缺失或损坏
• 权限不足

解决方案:

1. 确认启用 b2child 子主题
2. 检查framework/xun-framework.php文件是否存在
3. 确认当前用户有manage_options权限
4. 清理缓存或更换浏览器

2. 字段不显示或保存失败？

可能原因:

• 字段 ID 重复
• 字段类型不存在
• 数据验证失败

解决方案:

1. 检查字段 ID 是否唯一
2. 确认字段类型在framework/fields/目录中存在
3. 查看浏览器控制台和 PHP 错误日志
4. 逐步注释新增字段定位问题

3. 媒体/画廊字段不可用？

解决方案:

• 框架会自动加载wp_enqueue_media()
• 如果被其他插件禁用，请恢复或手动加载

4. 如何导入/导出配置？

操作步骤:

1. 进入"子主题设置"页面
2. 使用顶部工具区的按钮：
   • "导入配置"：上传配置文件
   • "导出配置"：下载当前配置
   • "重置"：恢复默认设置

5. 性能优化建议

最佳实践:

• 避免在前端大量调用get_option()
• 合并读取多个选项值
• 使用缓存机制
• 谨慎使用 AJAX 保存

---

API 参考

核心类方法

XUN 类

// 创建选项页面
XUN::createOptions($id, $args);

// 创建设置分区
XUN::createSection($options_id, $args);

// 获取选项值
XUN::get_option($options_id, $field_id = '', $default = '');

// 设置选项值
XUN::set_option($options_id, $field_id, $value);

字段基类 (XUN_Fields)

// 获取字段名称
$this->field_name();

// 获取字段值
$this->value;

// 获取字段属性
$this->field;

// 渲染字段
$this->render();

钩子函数

框架钩子

// 框架初始化
add_action('xun_init', 'callback_function');

// 选项保存前
add_action('xun_before_save', 'callback_function');

// 选项保存后
add_action('xun_after_save', 'callback_function');

WordPress 钩子

// 加载父主题样式
add_action('wp_enqueue_scripts', 'parent_theme_enqueue_styles', 9);

// 加载子主题样式
add_action('wp_enqueue_scripts', 'child_theme_enqueue_styles', 99);

// 输出自定义CSS
add_action('wp_head', 'b2child_output_custom_css', 110);

// 输出自定义JS
add_action('wp_footer', 'b2child_output_custom_js', 110);

常量定义

// 子主题目录URL
define('B2_CHILD_URI', get_stylesheet_directory_uri());

// 子主题目录路径
define('B2_CHILD_DIR', get_stylesheet_directory());

// 框架版本
define('XUN_VERSION', '1.1.0');

// 框架文件路径
define('XUN_FILE', __FILE__);

// 框架目录路径
define('XUN_DIR', plugin_dir_path(__FILE__));

---

总结

B2 子主题开发文档提供了完整的开发指南，包括：

1. 完整的目录结构说明
2. 23 种字段类型的详细用法
3. 后台设置模块的配置
4. 前端集成的实际应用
5. 开发扩展的最佳实践
6. 常见问题的解决方案
7. 完整的 API 参考

通过这份文档，开发者可以：

• 快速了解 B2 子主题的架构
• 掌握各种字段类型的使用方法
• 实现前端与后台的无缝集成
• 扩展和定制主题功能
• 解决开发过程中的常见问题

希望这份文档能帮助您更好地使用和开发 B2 子主题！