wordpress主题开发框架（灵狐框架），开发文档使用教程

Fox Framework 开发文档

一、下载与安装

1. 下载

从相应的资源库或者提供的渠道下载 Fox Framework 的压缩包。

2. 安装

将下载的压缩包解压后，把 fox - framework 文件夹上传到 WordPress 网站的 wp - content/plugins 目录下。登录 WordPress 后台，在“插件”菜单中找到 “Fox Framework” 并激活。

二、集成到主题或插件

1. 集成到主题

在主题的 functions.php 文件中添加以下代码：

require_once get_template_directory() . '/fox-framework/fox-framework.php';

2. 集成到插件

在插件的主文件中添加以下代码：

require_once plugin_dir_path(__FILE__) . 'fox-framework/fox-framework.php';

三、框架功能概述

1. 主题选项页面管理

提供直观的界面来创建和管理主题选项，通过左侧菜单切换不同的设置板块。

2. 多种字段类型支持

• 文本框（text）：用于输入单行文本。
• 文本区域（textarea）：用于输入多行文本。
• 开关（switch）：提供开/关的选择。
• 数字输入框（number）：用于输入数字，可设置最小值、最大值和步长。
• 媒体上传（media）：支持上传单个图片，并显示预览。
• 颜色选择器（color）：方便选择颜色。
• 图片集上传（gallery）：支持上传多个图片，并显示预览。
• 重复器（repeater）：可以重复添加一组字段。
• 字段组（group）：将多个字段组合在一起。
• 日期选择器（date）：用于选择日期。
• 手风琴（accordion）：将字段分组显示在可折叠的面板中。
• 富文本编辑器（rich_text_editor）：提供丰富的文本编辑功能。
• 字体选择器（font_manager）：用于选择字体。

3. 其他功能

• 菜单管理自定义字段：可以为菜单项目添加自定义字段。
• 元框：为文章等内容类型添加自定义元数据。
• 分类字段：为分类添加自定义字段。
• 用户字段：为用户添加自定义字段。
• 小部件：创建自定义小部件。
• REST API：支持通过 REST API 访问和管理选项。

四、引入框架

集成完成后，框架会自动加载所需的核心文件和类，无需额外操作即可使用框架提供的功能和类。

五、在主题中使用 Fox Framework 开发主题选项

1. 创建主题选项页面

在主题的 functions.php 文件中，使用 Fox_Framework 类的 createSection 方法创建主题选项页面和部分。示例如下：

Fox_Framework::createSection('my_theme_options', array(
    'page_title' => '我的主题设置',
    'sections' => array(
        array(
            'title' => '基本设置',
            'fields' => array(
                array(
                    'id' => 'site_name',
                    'title' => '网站名称',
                    'type' => 'text',
                    'default' => '默认网站名称'
                ),
                array(
                    'id' => 'site_color',
                    'title' => '网站主题颜色',
                    'type' => 'color',
                    'default' => '#000000'
                )
            )
        )
    )
));

2. 注册设置

框架会自动调用 Fox_Framework 类的 register_options 方法来注册选项，无需额外操作。

3. 渲染管理页面

框架会自动创建管理页面，你可以在 WordPress 后台的菜单中找到对应的主题选项页面。

4. 注册和使用不同字段类型

文本框（text）

array(
    'id' => 'text_field',
    'title' => '文本框示例',
    'type' => 'text',
    'default' => '默认文本'
)

文本区域（textarea）

array(
    'id' => 'textarea_field',
    'title' => '文本区域示例',
    'type' => 'textarea',
    'default' => '默认多行文本'
)

开关（switch）

array(
    'id' => 'switch_field',
    'title' => '开关示例',
    'type' => 'switch',
    'default' => 0
)

数字输入框（number）

array(
    'id' => 'number_field',
    'title' => '数字输入框示例',
    'type' => 'number',
    'default' => 10,
    'min' => 0,
    'max' => 100,
    'step' => 1
)

媒体上传（media）

array(
    'id' => 'media_field',
    'title' => '媒体上传示例',
    'type' => 'media',
    'default' => ''
)

颜色选择器（color）

array(
    'id' => 'color_field',
    'title' => '颜色选择器示例',
    'type' => 'color',
    'default' => '#ff0000'
)

图片集上传（gallery）

array(
    'id' => 'gallery_field',
    'title' => '图片集上传示例',
    'type' => 'gallery',
    'default' => ''
)

重复器（repeater）

array(
    'id' => 'repeater_field',
    'title' => '重复器示例',
    'type' => 'repeater',
    'fields' => array(
        array(
            'id' => 'sub_text',
            'title' => '子文本框',
            'type' => 'text',
            'default' => ''
        )
    )
)

字段组（group）

array(
    'id' => 'group_field',
    'title' => '字段组示例',
    'type' => 'group',
    'fields' => array(
        array(
            'id' => 'group_text',
            'title' => '组内文本框',
            'type' => 'text',
            'default' => ''
        )
    )
)

日期选择器（date）

array(
    'id' => 'date_field',
    'title' => '日期选择器示例',
    'type' => 'date',
    'default' => ''
)

手风琴（accordion）

array(
    'id' => 'accordion_field',
    'title' => '手风琴示例',
    'type' => 'accordion',
    'sections' => array(
        array(
            'title' => '部分 1',
            'fields' => array(
                array(
                    'id' => 'accordion_text_1',
                    'title' => '手风琴文本 1',
                    'type' => 'text',
                    'default' => ''
                )
            )
        )
    )
)

富文本编辑器（rich_text_editor）

array(
    'id' => 'rich_text_field',
    'title' => '富文本编辑器示例',
    'type' => 'rich_text_editor',
    'default' => ''
)

字体选择器（font_manager）

array(
    'id' => 'font_field',
    'title' => '字体选择器示例',
    'type' => 'font_manager',
    'fonts' => array('Arial', 'Times New Roman', 'Verdana'),
    'default' => 'Arial'
)

六、在前端调用主题选项

1. 简单调用示例

在主题的模板文件（如 header.php、footer.php 等）中，使用 get_option 函数获取主题选项的值。

// 获取网站名称
$site_name = get_option('my_theme_options')['site_name'];
echo $site_name;

// 获取网站主题颜色
$site_color = get_option('my_theme_options')['site_color'];
echo '<style>body { color: '. $site_color.'; }</style>';

// 获取媒体上传字段的值
$media_url = get_option('my_theme_options')['media_field'];
if ($media_url) {
    echo '<img src="'. $media_url.'" alt="上传的图片">';
}

2. 处理重复器字段

$repeater_items = get_option('my_theme_options')['repeater_field'];
if (is_array($repeater_items)) {
    foreach ($repeater_items as $item) {
        echo $item['sub_text'];
    }
}

七、注意事项

• 确保在使用框架前，已经正确加载和初始化框架。
• 在创建主题选项时，注意字段类型的正确使用，不同的字段类型有不同的输入和显示方式。
• 在前端调用主题选项时，要确保选项名称和键名的一致性，避免出现获取不到值的情况。
• 对于富文本编辑器字段，在输出时要注意安全过滤，防止 XSS 攻击。例如：

$rich_text = get_option('my_theme_options')['rich_text_field'];
echo wp_kses_post($rich_text);