使用Codestar Framework(CSF)框架作为WordPress插件主题的后台设置框架(中文demo)

CSF框架核心优势

• 支持WordPress6.4+及古腾堡编辑器；
• 提供几十种字段类型（如文本、颜色选择器、图片上传、代码编辑器等）；
• 支持字段依赖、数据验证与清洗；
• 支持多实例、无限框架配置；
• 内置CSS样式输出、字体加载等实用功能；

CSF框架插件下载与安装

Github发行版地址：https://github.com/Codestar/codestar-framework/releases

中文翻译版本：

你在Github下载的文件本来就是一个完整的WordPress插件，你可以直接放在/wp-content/plugins目录下解压

在已安装插件中激活Codestar Framework插件即可

在插件首页中可以激活演示，并查看演示页

CSF框架目录结构

CSF框架的目录结构清晰，便于开发者理解和扩展，核心文件及目录如下：

codestar-framework/
├── index.php                    # 啥都没有
├── codestar-framework.php       # 框架入口文件，定义插件信息并加载核心类，其它插件或主题需调用的文件
├── classes/                     # 核心类目录
│   └── setup.class.php          # 框架初始化类，处理常量定义、文件加载、钩子注册等
├── views/                       # 后台页面视图目录，没啥用，作为框架时可删除，就是介绍首页，激活后的设置页（已翻译为中文）
├── fields/                      # 可用字段目录，就是类型，你在设置页可以直接使用的通用字段，在demo文件中你可以看到他们的调用
│   ├── text/                    # 文本字段
│   ├── textarea/                # 文本域字段
│   ├── wp_editor/               # WordPress编辑器字段
│   └── ...（其他字段类型，如color、image、repeater共44个目录）
├── samples/                     # 示例代码目录
│   └── admin-options.php        # 后台选项示例，作为框架时可删除（已翻译为中文）
├── functions/                   # 工具函数目录，存放框架核心功能所需的各类辅助函数、处理逻辑、专用适配类，支撑全框架运行
│   ├── actions.php              # 动作处理函数，定义AJAX请求处理（如图标获取、数据导出/导入/重置、选择器数据加载等），支撑插件动态交互功能
│   ├── helpers.php              # 通用辅助函数，包含路径处理、数据格式化、字段渲染辅助、全局变量调用等工具方法，为框架各模块提供基础通用支持
│   ├── sanitize.php             # 数据清洗函数，对用户输入数据进行过滤处理（如防止XSS攻击、去除非法字符、转义特殊符号等），保障数据存储与调用安全
│   ├── validate.php             # 数据验证函数，检查数据是否符合预设规则（如格式、范围、必填项、唯一性等），确保输入数据的有效性和合法性
│   ├── customize.php            # WordPress定制器适配函数，专门对接WP原生「外观→自定义」面板，实现框架字段与WP定制器的无缝集成、字段渲染、数据同步与保存
│   └── walker.php               # 层级结构遍历渲染类，基于WP原生Walker类做二次封装，专供框架**多级/嵌套/树形结构**渲染（如多级导航、树形字段、嵌套选项组），处理层级数据的遍历与输出逻辑
├── LICENSE.md                   # 开源协议
└── README.md                    # 框架说明文档（包含安装、使用指南等）

• 核心类目录（classes）：包含框架初始化、字段处理等核心逻辑。
• 视图目录（views）：负责后台页面的 HTML 输出，包括导航、内容展示等。
• 字段目录（fields）：每种字段类型对应一个子目录，包含字段的渲染、数据处理逻辑。
• 示例目录（samples）：提供可直接参考的代码示例，帮助开发者快速上手。

事实上，你只需要知道codestar-framework.php是你需要调用的php文件，samples/admin-options.php是示例php文件即可。示例文件在免费版仅有这一个，高级版解锁后，还有8种示例文件包括其功能。

CSF框架使用示例

下面通过一个简单案例，演示如何使用CSF框架在插件中创建自定义后台选项。

安装与初始化：

1. 下载CSF框架资源zip包；
2. 将文件解压到你所开发的插件某个资源目录中，例如lib目录中；
3. 在插件或主题的主文件中初始化框架，并加载设置视图文件：

//加载CSF框架核心入口
require_once "插件目录/lib/codestar-framework/codestar-framework.php";
//以及调用你的设置视图文件，我这边用demo文件当示例
require_once "插件目录/lib/codestar-framework/samples/admin-options.php";

创建自定义后台选项：

在插件目录创建设置视图页面php文件admin-options.php中添加以下代码，创建一个包含CSF字段的后台设置选项页面：

// 检查 CSF 类是否存在，避免错误
if (class_exists('CSF')) {

  // 定义唯一标识（前缀）
  $prefix = 'my_plugin_options';//设置保存的数据库位置，用get_option('my_plugin_options')调用设置保存值

  // 创建选项页面
  CSF::createOptions($prefix, array(
    'menu_title' => '插件设置',  // 菜单标题
    'menu_slug'  => 'my-plugin-options',  // 菜单别名（URL中显示）
    'menu_type'  => 'menu',  // 作为顶级菜单显示
    'position'   => 58,  // 菜单位置
  ));

  // 添加第一个选项卡（section）
  CSF::createSection($prefix, array(
    'title'  => '基本设置',  // 选项卡标题
    'fields' => array(
      // 文本字段：网站副标题
      array(
        'id'    => 'site_subtitle',  // 字段唯一 ID
        'type'  => 'text',  // 字段类型，这个就是fields文件夹下的类型
        'title' => '网站副标题',  // 字段标题
        'desc'  => '显示在网站标题下方的描述文字',  // 字段描述
        'default' => '专注于优质内容创作',  // 默认值
      ),
    )
  ));

  // 添加第二个选项卡（section）
  CSF::createSection($prefix, array(
    'title'  => '底部设置',
    'fields' => array(
      // 文本域字段：页脚版权信息
      array(
        'id'    => 'footer_copyright',
        'type'  => 'textarea',
        'title' => '页脚版权信息',
        'desc'  => '支持 HTML 标签',
        'default' => '© 2025 王先生笔记 版权所有',
      ),
    )
  ));

}

字段可用类型，详细如何使用，你可以对比demo代码和显示的内容对比，在demo搜索以下字段就可以知道它在演示页面的哪个分类中。

文本 (text)
手风琴 (accordion)
背景 (background)
备份 (backup)
图标 (icon)
文本域 (textarea)
重复器 (repeater)
标题 (heading)
日期 (date)
代码编辑器 (code_editor)
复选框 (checkbox)
分组 (group)
图像选择 (image_select)
滑块 (slider)
内容 (content)
下拉选择 (select)
图库 (gallery)
通知 (notice)
字段集 (fieldset)
排版 (typography)
开关 (switcher)
排序器 (sorter)
链接颜色 (link_color)
副标题 (subheading)
上传 (upload)
颜色选择器 (color)
媒体 (media)
单选按钮 (radio)
选项卡 (tabbed)
可视化编辑器 (wp_editor)
边距 (spacing)
边框 (border)
调色板 (palette)
数字微调 (spinner)
尺寸 (dimensions)
可排序 (sortable)
按钮组 (button_set)
回调(callback)
颜色组(color_group)
日期和时间datetime)
链接(link)
地图(map)
数值约束(number)
选项提示(submessage)

在插件主文件中就可以调用设置了，依据CSF设置页面保存的值，做一些判断等等的功能。

// 获取整个选项集（参数为前面定义的前缀）
$plugin_options = get_option('my_plugin_options');

// 显示网站副标题（使用字段ID读取）
if (!empty($plugin_options['site_subtitle'])) {
  echo '<p class="site-subtitle">' . esc_html($theme_options['site_subtitle']) . '</p>';
}

// 显示页脚版权信息
if (!empty($plugin_options['footer_copyright'])) {
  echo '<div class="footer-copyright">' . wp_kses_post($theme_options['footer_copyright']) . '</div>';
}

高级功能，依赖显示：

CSF支持字段之间的依赖关系（如"当A字段选择某值时，显示B字段"），以及自定义数据验证。例如以下

// 带依赖的字段示例
array(
  'id'      => 'show_banner',
  'type'    => 'switcher',
  'title'   => '显示头部横幅',
  'default' => true,
),
array(
  'id'      => 'banner_text',
  'type'    => 'text',
  'title'   => '横幅文字',
  'desc'    => '仅当"显示头部横幅"开启时可见',
  // 依赖规则：当show_banner为true时显示
  'dependency' => array('show_banner', '==', true),
)

注意事项

1. codestar-framework/classes/setup.class.php文件中有外部链接，是CSF框架所需静态资源，建议修改为镜像加速，如果按WordPress开发规范来说，这些外部资源需要本地化。Font Awesome图标是必须要替换的，Google相关的，是排版字段(typography)的功能，如果非要使用，加载慢就自己解决吧。

例如Font Awesome图标就是外部资源，这并不规范，这里只提供这一个例子：

替换为：

// 加载 Font Awesome 7
wp_enqueue_style( 
    'csf-font-awesome', 
    self::include_plugin_url( 'assets/css/all.min.css' ), // 对应你的文件路径
    array(), 
    '7.0.0', // 根据实际FA版本调整
    'all' 
);

Font Awesome 7.0.0 免费版下载：

2. codestar-framework/assets/css/style.min.css这个CSS文件是CSF框架设置选择后台页面样式，你可以复制它，并放在插件或主题的资源路径，并依据原来的样式新增样式，定义CSF框架样式主题名，例如增加样式light，在主启动php文件中载入这个你新增的CSS文件，在创建选项页面时加入'theme' => 'light'，来使用你自定义的样式

// 创建设置页面 - 顶部信息
    CSF::createOptions($prefix, [
        'menu_title'      => '文本盲水印',
        'menu_slug'       => $prefix, // 使用前缀作为菜单标识
        'menu_type'       => 'menu',
        'menu_icon'       => 'dashicons-shield',
        'menu_position'   => 58,
        'framework_title' => '<small style="color: #fff;">v1.1.1</small>'),
        'footer_text'     => '王先生笔记',
        'show_bar_menu'   => false,
        'theme'           => 'light',//此处定义使用的样式
        'show_in_customizer' => false,
    ]);

3. codestar-framework/codestar-framework文件夹需要放进你的插件或主题的三方资源目录中，而不是以插件安装的，需要插件或主题主文件中加载/codestar-framework/codestar-framework.phpCSF入口文件接入。

4. 其中的codestar-framework/languages目录是为CSF框架服务的，例如字段的部分提示，保存等按钮的语言，内置多种语言，如果你的插件要多语言化，需要在主文件中增加文本域和语言域目录，而不是只用CSF文本域，你可以只保留中文

5. 当你的插件或主题调用框架时，codestar-framework/classes/setup.class.php下的welcome.php是不需要加载的，这是CSF插件的设置首页代码，可在setup.class.php删除加载行，并删除welcome.php指向的PHP文件，例如samples(demo文件)，views(tab页)目录

CSF框架中文插件展示

CSF框架总结

CSF框架以轻量、高效、易上手为核心优势，完美适配WordPress后台开发需求，无论是简单的插件配置页，还是复杂的主题参数面板，都能快速落地。结合我提供的中文Demo使用，可彻底解决英文界面门槛与重复开发问题，大幅缩短WP后台设置功能的开发周期，是WordPress开发者必备的实用框架之一。

原文链接(非王先生笔记发布均为盗版)：https://wxsnote.cn/7063.html