使用WordPress设置API构建自定义管理页面

In this guide, we’ll introduce the WordPress Settings API, and create a WordPress administration page where we demonstrate the use of this API.

在本指南中，我们将介绍WordPress设置API，并创建一个WordPress管理页面，在此演示该API的用法。

For the purposes of this tutorial, we’ll wrap this functionality into a plugin, but this can also be a part of a WordPress theme.

就本教程而言，我们将把此功能包装到一个插件中，但这也可以是WordPress主题的一部分。

As the WordPress Codex says, the Settings API was added in WordPress 2.7 to streamline adding different settings fields and sections in administration pages.

正如WordPress Codex所说，Settings API是在WordPress 2.7中添加的，以简化在管理页面中添加不同的设置字段和部分的过程。

创建插件 (Creating the Plugin)

To start, we’ll create and activate a plugin to encapsulate our options page. We’ll use WP CLI to simplify the creation, although this leaves us with way more files than this guide needs.

首先，我们将创建并激活一个插件来封装我们的选项页面。 我们将使用WP CLI简化创建过程，尽管这给我们留下了比本指南需要更多的文件。

As we can see, we use wp scaffold plugin pluginname to create the plugin. Once it’s created, we activate it — optionally also using WP CLI, with wp plugin activate pluginname.

如我们所见，我们使用wp scaffold plugin pluginname来创建插件。 创建完成后，我们将其激活-可选地还可以使用WP CLI，并使用wp plugin activate pluginname 。

Once it’s activated, we open the main plugin file — in this case sitepoint-settings-api.php.

激活后，我们将打开主插件文件-在本例中为sitepoint-settings-api.php 。

创建管理页面 (Creating the Admin Page)

It isn’t necessary to use WP CLI for this plugin. We could have simply created a directory with the name of the plugin, and the PHP file inside it with the same name. Anyhow, the creation of the plugin has left us with a sitepoint-settings-api.php which looks like this:

无需为此插件使用WP CLI。 我们可以简单地创建一个带有插件名称的目录，并在其中创建具有相同名称PHP文件。 无论如何，插件的创建给我们留下了一个sitepoint-settings-api.php ，如下所示：

/**
* Plugin Name: Sitepoint Settings Api
* Plugin URI: PLUGIN SITE HERE
* Description: PLUGIN DESCRIPTION HERE
* Author: YOUR NAME HERE
* Author URI: YOUR SITE HERE
* Text Domain: sitepoint-settings-api
* Domain Path: /languages
* Version: 0.1.0
*
* @package Sitepoint_Settings_Api
*/
~

Now we can simply add code after the comment end.

现在，我们只需在注释结束后添加代码即可。

To add our options page, we’ll use add_options_page() (more details about it here). This function takes arguments as follows:

要添加我们的选项页面，我们将使用add_options_page() ( 在此处了解更多信息)。 该函数采用以下参数：

add_options_page( $page_title, $menu_title, $capability,
$menu_slug, $function );

All the arguments are self-explanatory. $menu_slug must be a unique string that WordPress will use internally, but will also be reflected in the URL. $function is a string with a name of the function that will provide HTML output for our admin page.

所有的论点都是不言而喻的。 $menu_slug必须是WordPress将在内部使用的唯一字符串，但也将反映在URL中。 $function是一个带有函数名称的字符串，该函数将为我们的管理页面提供HTML输出。

We will, therefore, add the following code to our plugin file:

因此，我们将以下代码添加到我们的插件文件中：

add_action( 'admin_menu', 'sitepoint_settings_page' );
function sitepoint_settings_page() {
add_options_page( 'Settings API Page', 'Settings API Page', 'manage_options', 'settings-api-page', 'settings_api_page' );
}

After we’ve saved the file (presuming we activated our plugin), we’ll open our administration dashboard, and we’ll find our Settings API Page under Settings in the left side menu.

保存文件后(假设我们激活了插件)，我们将打开管理面板，然后在左侧菜单中的“设置”下找到“设置API页面 ” 。

We can control, to a degree, the order or position of the submenu item by adding a priority argument to our add_action() function:

通过在add_action()函数中添加优先级参数，我们可以在一定程度上控制子菜单项的顺序或位置：

add_action( 'admin_menu', 'sitepoint_settings_page', 1 );

If we want to have our menu item to be in the root menu — rather than the Settings submenu — we’ll use add_menu_page(), which takes similar arguments.

如果我们希望菜单项位于根菜单中，而不是“ 设置”子菜单中，那么我们将使用add_menu_page() ，它采用类似的参数 。

Now, if we open the page in our browser, all we’ll see is an empty page, because we still haven’t created the settings_api_page() function that we specified:

现在，如果我们在浏览器中打开页面，我们将看到的只是一个空白页面，因为我们还没有创建我们指定的settings_api_page()函数：

设置API (The Settings API)

The WordPress Settings API is an intricate mechanism that attempts to provide an easy way for developers to create settings pages.

WordPress设置API是一种复杂的机制，试图为开发人员提供一种轻松的方法来创建设置页面。

Before we go into a full-fledged example of the settings page displaying and saving a setting to the WordPress database, we’ll explain couple of crucial functions that WordPress provides as part of its Settings API.

在进入显示设置页面并将其保存到WordPress数据库的完整示例之前，我们将介绍WordPress作为其Settings API的一部分提供的几个关键功能。

register_setting() is a function we use to register a setting, which equals a row in wp_options table. Before we can create actual field (or fields, as setting can be an array of values), we need to register it. This way we’ll leverage the WordPress CRUD mechanism for settings. Function arguments are as follows:

register_setting()是我们用来注册设置的函数，该设置等于wp_options表中的一行。 在创建实际字段(或字段，因为设置可以是值的数组)之前，我们需要对其进行注册。 这样，我们将利用WordPress CRUD机制进行设置。 函数参数如下：

register_setting( string $option_group, string $option_name, array $args = array() )

The first two arguments are mandatory, the first one allowing us to assign fields to it, and $option_name, as we’ll see, is the actual option name in the WordPress database.

前两个参数是强制性的，第一个参数允许我们为其分配字段，而$option_name是WordPress数据库中的实际选项名称，我们将看到。

add_settings_section() defines/adds a section to an admin page. Its arguments are as follows:

add_settings_section()定义/将部分添加到管理页面。 其参数如下：

add_settings_section( string $id, string $title, callable $callback, string $page )

$callback is a function that outputs an HTL header of the section (it can be empty), and $page is the slug of the admin page we’ll display it on.

$callback是一个输出该部分的HTL标头的函数(它可以为空)，而$page是我们将在其上显示的管理页面的一部分。

add_settings_field() defines a settings field within a settings section in an admin options page. Arguments for it are:

add_settings_field()在管理选项页面的设置部分中定义一个设置字段。 它的参数是：

add_settings_field( string $id, string $title, callable $callback, string $page, string $section = 'default', array $args = array()

Of these, $id, $title, $callback and $page are required. The $callback function should output the HTML of the input field.

其中$id ， $title ， $callback和$page是必需的。 $callback函数应输出输入字段HTML。

The Settings API provides $page argument for add_settings_section and add_settings_field as a means to add sections and fields to existing settings pages. We’ll use stpPlugin for both our option group — in register_setting() — and for attaching the settings section and settings fields to a ‘stpPlugin’ page in the add_settings_section() and add_settings_field() functions. We’ll then “quote it” in the next two functions in our example, to output relevant HTML.

设置API为add_settings_section和add_settings_field提供$page参数，作为将部分和字段添加到现有设置页面的一种方法。 我们将stpPlugin用于我们的选项组(在register_setting() ，以及将设置部分和设置字段附加到add_settings_section()和add_settings_field()函数中的“ stpPlugin”页面上。 然后，在示例中的下两个函数中将其“引用”，以输出相关HTML。

settings_fields() outputs “nonce, action, and option_page fields for a settings page”. It takes the $option_group argument, used in register_setting().

settings_fields()输出“设置页面的nonce，action和option_page字段”。 它采用$option_group register_setting()使用的$option_group参数。

do_settings_sections() outputs all the sections, with their respective fields, registered for a specific $page.

do_settings_sections()输出为特定$ page注册的所有节及其各自的字段。

$page is the only argument here.

$page是这里唯一的参数。

Having explained these functions, we now proceed to some actual code. The previous PHP code we added to the sitepoint-settings-api.php file we replace with the following:

在解释了这些功能之后，我们现在进入一些实际代码。 我们添加到sitepoint-settings-api.php文件中的先前PHP代码将替换为以下内容：

add_action( 'admin_menu', 'stp_api_add_admin_menu' );
add_action( 'admin_init', 'stp_api_settings_init' );
function stp_api_add_admin_menu( ) {
add_options_page( 'Settings API Page', 'Settings API Page', 'manage_options', 'settings-api-page', 'stp_api_options_page' );
}
function stp_api_settings_init( ) {
register_setting( 'stpPlugin', 'stp_api_settings' );
add_settings_section(
'stp_api_stpPlugin_section',
__( 'Our Section Title', 'wordpress' ),
'stp_api_settings_section_callback',
'stpPlugin'
);
add_settings_field(
'stp_api_text_field_0',
__( 'Our Field 0 Title', 'wordpress' ),
'stp_api_text_field_0_render',
'stpPlugin',
'stp_api_stpPlugin_section'
);
add_settings_field(
'stp_api_select_field_1',
__( 'Our Field 1 Title', 'wordpress' ),
'stp_api_select_field_1_render',
'stpPlugin',
'stp_api_stpPlugin_section'
);
}
function stp_api_text_field_0_render( ) {
$optiOns= get_option( 'stp_api_settings' );
?>
'>
}
function stp_api_select_field_1_render( ) {
$optiOns= get_option( 'stp_api_settings' );
?>

>Option 1
>Option 2

}
function stp_api_settings_section_callback( ) {
echo __( 'This Section Description', 'wordpress' );
}
function stp_api_options_page( ) {
?>



Sitepoint Settings API Admin Page

Here we hook the stp_api_settings_init() function to the admin_init hook. There we define and register our settings, sections and fields.

在这里，我们将stp_api_settings_init()函数挂钩到admin_init挂钩。 在那里，我们定义并注册我们的设置，部分和字段。

stp_api_text_field_0_render() and stp_api_select_field_1_render() define HTML output of our two fields, text and select field, both belonging to the same stpPlugin group and stp_api_settings option — or setting — in the wp_options table in the database.

stp_api_text_field_0_render()和stp_api_select_field_1_render()定义了我们两个字段(文本和选择字段stp_api_select_field_1_render() HTML输出，它们都属于数据库的wp_options表中的同一个stpPlugin组和stp_api_settings选项(或设置)。

Lastly, we define stp_api_options_page(), which outputs the HTML for our admin options page. We incorporate the settings sections and fields in it. We’ve referred to this function at the top of our file, in the stp_api_add_admin_menu() function, where we registered the admin (options) page.

最后，我们定义stp_api_options_page() ，它为我们的管理选项页面输出HTML。 我们在其中合并了设置部分和字段。 我们在文件顶部的stp_api_add_admin_menu()函数中引用了此函数，在该函数中注册了admin(选项)页面。

When we now go, again, to our settings page, we’ll see that it’s no longer empty:

现在，当我们再次进入设置页面时，我们将看到它不再为空：

If we try changing and saving these fields, we will see, upon refresh, that it works! WordPress abstracts away the database transactions for us, nonces, etc.

如果我们尝试更改和保存这些字段，则刷新后会看到它有效！ WordPress为我们，nonce等提取数据库事务。

We could further add some validation functionality, further styling of this page, and other things.

我们可以进一步添加一些验证功能，此页面的其他样式以及其他内容。

If we go to WP CLI and try to run wp option get stp_api_settings — after we’ve changed some values for these two fields — we’ll get this:

如果我们转到WP CLI并尝试运行wp option get stp_api_settings (在我们更改了这两个字段的某些值之后)，我们将获得以下信息：

This shows us that these two fields were saved in our wp_options database as fields of an array, as stp_api_settings setting.

这向我们展示了这两个字段作为stp_api_settings设置保存在wp_options数据库中作为数组的字段。

If we now go to WP CLI shell, we can try out the code we’ll use to fetch these options in our plugin or theme files:

如果现在转到WP CLI shell，我们可以尝试将用于在插件或主题文件中获取这些选项的代码：

结论 (Conclusion)

WordPress has become prominent in the web industry because of its ease of use and its gentle learning curve for developers. The Settings API is one example of this user-friendliness.

WordPress因其易用性和对开发人员的柔和学习曲线而在网络行业中广为人知。 设置API是这种用户友好性的一个示例。

In this guide, we’ve introduced the WordPress Settings API. Much more can be said on this topic, but the intro we’ve presented here should demystify the topic to enable resourceful hackers to build their own solutions starting from this.

在本指南中，我们介绍了WordPress设置API。 关于这个话题，可以说更多的话，但是我们在这里介绍的介绍应该使这个话题神秘化，从而使机智的黑客可以以此为基础构建自己的解决方案。

翻译自: https://www.sitepoint.com/wordpress-settings-api-build-custom-admin-page/