创建 WordPress 插件设置页面的 5 种方法

WordPress 的可扩展性一直是其强项之一。不仅有数千个插件可用，您还可以构建自己的插件。在某些时候，您可能决定分发您的插件。这通常需要用插件未来用户可以设置的选项来替换硬编码数据。在本文中，我将讨论在 WordPress 插件中创建设置页面的五种不同方法。

WordPress 设置 API

WordPress 设置 API 在 WordPress 2.7 中添加，允许开发者在仪表板的现有设置表单上注册设置字段，以及创建新的设置表单，WordPress 将负责显示和处理数据保存：

它允许您定义设置页面、页面中的部分以及部分中的字段。

这绝对是本文讨论的方法中最手动的一个，但值得了解它的工作原理。在某些情况下，这是一个足够简单的方法，可能就是所需要的。

首先，我们需要注册一个新的菜单项和页面来包含我们的设置表单。让我们在 WordPress 仪表板的“设置”顶级菜单项下添加该页面：

<?php

function dbi_add_settings_page() {
    add_options_page( 'Example plugin page', 'Example Plugin Menu', 'manage_options', 'dbi-example-plugin', 'dbi_render_plugin_settings_page' );
}
add_action( 'admin_menu', 'dbi_add_settings_page' );

add_options_page 的第五个参数是用于显示页面内容的函数名，在本例中它将是设置表单。该函数需要一个表单元素和一些函数调用来与设置 API 通信：

<?php

function dbi_render_plugin_settings_page() {
    ?>
    <h2>Example Plugin Settings</h2>
    <form action="options.php" method="post">
        <?php
        settings_fields( 'dbi_example_plugin_options' );
        do_settings_sections( 'dbi_example_plugin' ); ?>
        <input name="submit" type="submit" value="<?php esc_attr_e( 'Save' ); ?>" />
    </form>
    <?php
}

函数 settings_fields 渲染代码以告诉表单要做什么，以及一个隐藏的输入以使用 nonce 使其安全。传递给函数的参数是稍后要注册的配置组名称。

函数 do_settings_sections 是表单的关键部分。这是所有部分和字段输出的地方——文本框、下拉框、复选框等——以便用户输入数据。同样，该函数参数是任意的但需要是唯一的。我们在注册字段时将使用它。

让我们这样做：

<?php

function dbi_register_settings() {
    register_setting( 'dbi_example_plugin_options', 'dbi_example_plugin_options', 'dbi_example_plugin_options_validate' );
    add_settings_section( 'api_settings', 'API Settings', 'dbi_plugin_section_text', 'dbi_example_plugin' );

add_settings_field( 'dbi_plugin_setting_api_key', 'API Key', 'dbi_plugin_setting_api_key', 'dbi_example_plugin', 'api_settings' );
    add_settings_field( 'dbi_plugin_setting_results_limit', 'Results Limit', 'dbi_plugin_setting_results_limit', 'dbi_example_plugin', 'api_settings' );
    add_settings_field( 'dbi_plugin_setting_start_date', 'Start Date', 'dbi_plugin_setting_start_date', 'dbi_example_plugin', 'api_settings' );
}
add_action( 'admin_init', 'dbi_register_settings' );

这里发生了三件事。首先，我们使用 register_setting 在 wp_options 表中为我们的设置创建一条新记录，以‘dbi_example_plugin_options’作为 option_name。

我们的各个设置将存储为序列化的数据数组。这非常适合将所有插件设置集中在一个地方，但数据序列化在迁移 WordPress 数据库时可能会导致问题，除非正确处理。第三个参数是处理保存选项时验证数据输入的函数名称。

例如，确保 API 密钥是一个只包含数字和字母的 32 字符字符串：

<?php

function dbi_example_plugin_options_validate( $input ) {
    $newinput['api_key'] = trim( $input['api_key'] );
    if ( ! preg_match( '/^[a-z0-9]{32}$/i', $newinput['api_key'] ) ) {
        $newinput['api_key'] = '';
    }

    return $newinput;
}

其次，我们正在为设置注册一个组部分，并将其绑定到该选项。最后，我们使用 add_settings_field 为该组注册三个字段。所有这些都是用于保存插件设置的单行文本字段。

接下来，我们需要创建函数来显示该部分的帮助文本并在表单上渲染这些字段：

<?php

function dbi_plugin_section_text() {
    echo '<p>在这里您可以设置使用 API 的所有选项</p>';
}

function dbi_plugin_setting_api_key() {
    $options = get_option( 'dbi_example_plugin_options' );
    echo "<input name='dbi_example_plugin_options[api_key]' type='text' value='" . esc_attr( $options['api_key'] ) . "' />";
}

function dbi_plugin_setting_results_limit() {
    $options = get_option( 'dbi_example_plugin_options' );
    echo "<input name='dbi_example_plugin_options[results_limit]' type='text' value='" . esc_attr( $options['results_limit'] ) . "' />";
}

function dbi_plugin_setting_start_date() {
    $options = get_option( 'dbi_example_plugin_options' );
    echo "<input name='dbi_example_plugin_options[start_date]' type='text' value='" . esc_attr( $options['start_date'] ) . "' />";
}

呼！就是这样，我们有了一个设置页面：

在代码中使用设置就是使用 get_name='dbi_example_plugin_options' 并使用数组键来获取我们需要的设置。

这里有相当多的部分需要注册，这个和那个，重复代码，并确保它正确组合在一起。这不是最容易使用甚至解释的 WordPress API。所以毫不奇怪，有一些封装库致力于简化向 WordPress 插件添加设置页面的过程。

当我创建我的 Instagram WordPress 插件时，我使用 WordPress Settings Framework（由 Gilbert Pellegrom 创建）构建了设置页面。

自定义字段框架

说到 PHP 框架，我想展示一种不使用 WordPress Settings API 来创建设置页面的替代方法。当我构建网站时，如果需要设置页面，我默认使用 Advanced Custom Fields 来创建选项页面，然后使用 ACF 定义字段。

这是我喜欢使用 ACF 的众多原因之一：它把复杂的 WordPress 功能变得简单。你甚至可以使用 ACF Blocks 来为块编辑器注册块，而无需接触 React。

但是，当构建要分发的插件或主题时，你无法依赖用户已安装 ACF。你可以通过 Composer 让你的插件要求安装 ACF，但这并不是 WordPress 插件要求另一个插件的最佳实践。

这就是 Carbon Fields 框架的用武之地。与 ACF 不同，Carbon Fields 不是一个插件，通常作为库安装在插件内部，他们的推荐方法是使用 Composer。

安装后，确保你已经引入了 Composer 的 autoload.php 文件，你需要启动 Carbon Fields 库：

<?php

function dbi_load_carbon_fields() {
    Carbon_FieldsCarbon_Fields::boot();
}
add_action( 'after_setup_theme', 'dbi_load_carbon_fields' );

要复制我们上面使用 WordPress Settings API 完成的功能，只需使用以下代码即可：

<?php

use Carbon_FieldsContainer;
use Carbon_FieldsField;

function dbi_add_plugin_settings_page() {
    Container::make( 'theme_options', __( 'Example Plugin Page' ) )
        ->set_page_parent( 'options-general.php' )
        ->add_fields( array(
            Field::make( 'text', 'dbi_api_key', 'API Key' )
                ->set_attribute( maxLength, 32 ),
            Field::make( 'text', 'dbi_results_limit', 'Results Limit' )
                ->set_attribute( 'min', 1 )
                ->set_attribute( 'max', 100 )
                ->set_default_value( 10 ),
            Field::make( 'date', 'dbi_start_date', 'Start Date' ),
        ) );
}
add_action( 'carbon_fields_register_fields', 'dbi_add_plugin_settings_page' );

正如你所见，这个框架让字段变得更加用户友好变得非常简单，比如为”Results Limit”字段添加默认值、最小值和最大值，还能将”Start Date”字段变成日期选择器——这在使用 Settings API 时需要相当多的编码才能实现。

要使用设置的保存数据，你需要使用 carbon_get_theme_option() 函数：

<?php

$api_key = carbon_get_theme_option( 'dbi_api_key' );

对于较小规模的项目来说，框架可能有些过度，但它们是用更少代码实现更多功能的好方法，让你能够专注于为你的插件编写代码，而不是通过构建另一个设置页面来重复造轮子。

使用代码生成器

另一种利用 WordPress Settings API 以及框架易用性的方法是使用 WordPress 代码生成器，如 WordPress Option Page Generator 或 GenerateWP 的高级版本。

让我们使用 WordPress Option Page Generator 重新创建我们的设置页面。它仅支持少数几种字段类型：text、textarea、select、radio、checkbox，所以也没有日期选择器。

这是我可以直接在插件中使用的生成的代码，并以与 WordPress Settings API 相同的方式使用数据。

生成器是非常有用的工具，可以帮助您启动一个包含现成设置页面的插件，无需大量编码即可进行调整。它们也非常适合学习工作原理，分解现有代码并查看它们如何组合在一起。但是，对于需要频繁更改设置代码的插件，长期来看它们可能不是最佳选择。

使用 REST API

WordPress REST API 的众多出色用途之一是改进您的插件或主题设置页面。

在这篇优秀的文章中，Josh Pollock深入介绍了如何使用 REST API 和 jQuery 创建设置页面。我不会用这种技术重新创建设置页面，因为这篇文章是一个非常详尽的教程。

与传统的 admin-ajax.php 请求相比，REST API 可以提供性能优势，再加上点击”保存”按钮后设置在后台保存而无需刷新页面的改进用户体验，这种方法比 WordPress Settings API 更具现代感。

Josh 指出，随着您添加设置并且表单变得更复杂，”您将需要用 jQuery 做越来越多的工作，这些工作很难管理，如果使用 VueJS 或 React 会更简单，并提供更好的用户体验”，这正好引出了下一个方法，一个由 VueJS 驱动的设置页面。

使用 VueJS

在收购我的 WordPress 会员插件的过程中，我调查了代码库以查看它的编写方式，发现设置页面是由使用 REST API 和 VueJS 的包驱动的——wp-optionskit：

该包可以使用 Composer 安装，可以使用此处找到的代码实例化和配置设置页面。这是我们示例设置页面的样子：

我喜欢这种方法的地方在于，它允许您生成复杂的设置页面，具有多个选项卡和子部分，只需在 PHP 中配置数据数组即可。与其他一些方法一样，设置数据存储在选项表的一条记录中，因此这是一种熟悉的检索和使用保存数据的方法。

使用 React

正如我们在 wp-optionskit 中看到的，使用 REST API 为在 WordPress 管理后台广泛使用 VueJS 或 React 打开了大门。

我在 2020 年写了第一版文章，那时候还没有太多 React 框架可选。如今，你已经有不少选择可以考虑了。事实上，你可能已经有了一个偏好的 React 框架可以使用。不过，最简单的方法是直接使用 wp-scripts。这是一套专用于为 WordPress 构建 React 应用的脚本和工具。

它专门为构建 WordPress 插件和主题而设计，因此内置了对 WordPress API 和约定的支持。如果你选择这条路，我强烈建议深入研究 @wordpress/scripts 的文档，但基本流程如下：

安装 wp-scripts： 运行 npm install @wordpress/scripts 来安装 wp-scripts。
创建新插件： 运行 npx @wordpress/scripts create-plugin my-plugin 来创建一个具有基本结构的新插件。
构建你的插件： 运行 npm run build 来构建你的插件。
入队你的脚本： 使用 wp_enqueue_script 函数在 WordPress 管理区域入队你的脚本。

总结

与所有开发相关的事物一样，达到同样目的的方法有很多，你在一个项目中采用的方法可能与另一个项目不同。我个人目前最喜欢的是 wp-optionskit，因为它允许多个设置标签页和子部分，以及更好的保存用户体验。

你为插件创建 WordPress 设置页面的方法是什么？我是否遗漏了任何流行的选项？请在评论中告诉我们。

原文链接：https://deliciousbrains.com/create-wordpress-plugin-settings-page/

小狸科技

创建 WordPress 插件设置页面的 5 种方法

WordPress 设置 API

自定义字段框架

使用代码生成器

使用 REST API

使用 VueJS

使用 React

总结

留下评论取消回复

WordPress 设置 API

自定义字段框架

使用代码生成器

使用 REST API

使用 VueJS

使用 React

总结

相关文章

2026 年最佳 WordPress 备份插件

无障碍网页设计的 WordPress 无障碍插件

更快WordPress网站的SQL查询优化

留下评论取消回复