设置
设置
WordPress 提供了两个核心 API,使管理界面易于构建、安全并与 WordPress 管理的设计保持一致。
设置API专注于为开发人员提供一种创建表单和管理表单数据的方法。
Options API专注于使用简单的键/值系统管理数据。
快速参考
请参阅使用设置 API 和选项 API构建自定义设置页面的完整示例。
设置接口
WordPress 2.7 中添加的设置 API 允许半自动管理包含设置表单的管理页面。它允许您定义设置页面、这些页面中的部分以及这些部分中的字段。
新的设置页面可以连同其中的部分和字段一起注册。还可以通过在其中注册新的设置部分或字段来添加现有设置页面。
组织字段的注册和验证仍然需要开发人员付出一些努力,但避免了底层选项管理的大量复杂调试。
wp-admin/options.php
提供相当严格的功能检查。用户需要具备manage_options
提交表单的能力(在多站点中必须是超级管理员)。为什么要使用设置 API?
开发人员可以忽略此 API,并在没有它的情况下编写自己的设置页面。这就引出了一个问题,这个 API 给桌面带来了什么好处?以下是一些好处的简要概述。
视觉一致性
使用 API 生成界面元素可确保您的设置页面看起来与其他管理内容相似。您的界面将遵循相同的样式指南,并且看起来像它所属的,并且感谢才华横溢的 WordPress 设计师团队,它看起来会很棒!
稳健性(面向未来!)
由于 API 是 WordPress 核心的一部分,任何更新都会自动考虑您插件的设置页面。如果您在不使用设置 API 的情况下创建自己的界面,WordPress 核心更新更有可能破坏您的自定义设置。还有更广泛的受众测试和维护该 API 代码,因此它往往会更加稳定。
减少工作量!
当然,最直接的好处是 WordPress API 在幕后为您做了很多工作。除了应用美观的集成设计之外,这里还有一些设置 API 的功能示例。
- 处理表单提交 –让 WordPress 处理检索和存储您的 $_POST 提交。
- 包括安全措施 –您免费获得额外的安全措施,例如随机数等。
- 清理数据 –您可以使用 WordPress 其余部分使用的相同方法来确保字符串可以安全使用。
功能参考
设置注册/取消注册 | 添加字段/部分 |
---|---|
注册设置() 取消注册设置() |
add_settings_section() add_settings_field() |
选项表单渲染 | 错误 |
---|---|
设置字段() do_settings_sections() do_settings_fields() |
add_settings_error() get_settings_errors() settings_errors() |
使用设置 API
添加设置
您必须使用register_setting()定义新设置,它将在{$wpdb->prefix}_options
表中创建一个条目。
您可以使用add_settings_section()在现有页面上添加新部分。
您可以使用add_settings_field()将新字段添加到现有部分。
添加设置
register_setting(
string $option_group,
string $option_name,
callable $sanitize_callback = ''
);
请参阅有关register_setting()的函数参考 以获取有关所使用参数的完整说明。
添加一个部分
add_settings_section(
string $id,
string $title,
callable $callback,
string $page
);
部分是您在 WordPress 设置页面上看到的具有共享标题的设置组。在您的插件中,您可以向现有设置页面添加新部分,而不是创建一个全新的页面。这使得您的插件更易于维护,并创建更少的新页面供用户学习。
有关所用参数的完整说明,请参阅有关add_settings_section()的函数参考。
添加字段
add_settings_field(
string $id,
string $title,
callable $callback,
string $page,
string $section = 'default',
array $args = []
);
有关所用参数的完整说明,请参阅有关add_settings_field()的函数参考。
例子
function wporg_settings_init() {
// register a new setting for "reading" page
register_setting('reading', 'wporg_setting_name');
// register a new section in the "reading" page
add_settings_section(
'wporg_settings_section',
'WPOrg Settings Section', 'wporg_settings_section_callback',
'reading'
);
// register a new field in the "wporg_settings_section" section, inside the "reading" page
add_settings_field(
'wporg_settings_field',
'WPOrg Setting', 'wporg_settings_field_callback',
'reading',
'wporg_settings_section'
);
}
/**
* register wporg_settings_init to the admin_init action hook
*/
add_action('admin_init', 'wporg_settings_init');
/**
* callback functions
*/
// section content cb
function wporg_settings_section_callback() {
echo '<p>WPOrg Section Introduction.</p>';
}
// field content cb
function wporg_settings_field_callback() {
// get the value of the setting we've registered with register_setting()
$setting = get_option('wporg_setting_name');
// output the field
?>
<input type="text" name="wporg_setting_name" value="<?php echo isset( $setting ) ? esc_attr( $setting ) : ''; ?>">
<?php
}
获取设置
获取设置是通过get_option() 函数完成的。
该函数接受两个参数:选项的名称和该选项的可选默认值。
例子
// Get the value of the setting we've registered with register_setting()
$setting = get_option('wporg_setting_name');
选项 API
WordPress 1.0 中添加的选项 API 允许创建、读取、更新和删除 WordPress 选项。与设置 API结合使用,它可以控制设置页面中定义的选项。
选项存储在哪里?
选项存储在{$wpdb->prefix}_options
表中。由文件中设置的变量$wpdb->prefix
定义。$table_prefix
wp-config.php
选项如何存储?
选项可以通过以下两种方式之一存储在 WordPress 数据库中:作为单个值或作为值数组。
单值
当保存为单个值时,选项名称指的是单个值。
// add a new option
add_option('wporg_custom_option', 'hello world!');
// get an option
$option = get_option('wporg_custom_option');
值数组
当保存为值数组时,选项名称指的是一个数组,该数组本身可以由键/值对组成。
// array of options
$data_r = array('title' => 'hello world!', 1, false );
// add a new option
add_option('wporg_custom_option', $data_r);
// get an option
$options_r = get_option('wporg_custom_option');
// output the title
echo esc_html($options_r['title']);
如果您正在使用大量相关选项,将它们存储为数组可以对整体性能产生积极影响。
功能参考
添加选项 | 获取选项 | 更新选项 | 删除选项 |
---|---|---|---|
add_option() | get_option() | update_option() | delete_option() |
add_site_option() | get_site_option() | update_site_option() | delete_site_option() |
自定义设置页面
创建自定义设置页面包括以下组合:创建管理菜单、使用设置 API和选项 API。
通过遵循注释,可以使用下面的示例来快速参考这些主题。
完整示例
完整的示例添加了一个名为 的顶级菜单WPOrg
,注册了一个名为 的自定义选项wporg_options
,并使用设置 API 和选项 API(包括显示错误/更新消息)执行 CRUD(创建、读取、更新、删除)逻辑。
/**
* @internal never define functions inside callbacks.
* these functions could be run multiple times; this would result in a fatal error.
*/
/**
* custom option and settings
*/
function wporg_settings_init() {
// Register a new setting for "wporg" page.
register_setting( 'wporg', 'wporg_options' );
// Register a new section in the "wporg" page.
add_settings_section(
'wporg_section_developers',
__( 'The Matrix has you.', 'wporg' ), 'wporg_section_developers_callback',
'wporg'
);
// Register a new field in the "wporg_section_developers" section, inside the "wporg" page.
add_settings_field(
'wporg_field_pill', // As of WP 4.6 this value is used only internally.
// Use $args' label_for to populate the id inside the callback.
__( 'Pill', 'wporg' ),
'wporg_field_pill_cb',
'wporg',
'wporg_section_developers',
array(
'label_for' => 'wporg_field_pill',
'class' => 'wporg_row',
'wporg_custom_data' => 'custom',
)
);
}
/**
* Register our wporg_settings_init to the admin_init action hook.
*/
add_action( 'admin_init', 'wporg_settings_init' );
/**
* Custom option and settings:
* - callback functions
*/
/**
* Developers section callback function.
*
* @param array $args The settings array, defining title, id, callback.
*/
function wporg_section_developers_callback( $args ) {
?>
/**
* @internal never define functions inside callbacks.
* these functions could be run multiple times; this would result in a fatal error.
*/
/**
* custom option and settings
*/
function wporg_settings_init() {
// Register a new setting for "wporg" page.
register_setting( 'wporg', 'wporg_options' );
// Register a new section in the "wporg" page.
add_settings_section(
'wporg_section_developers',
__( 'The Matrix has you.', 'wporg' ), 'wporg_section_developers_callback',
'wporg'
);
// Register a new field in the "wporg_section_developers" section, inside the "wporg" page.
add_settings_field(
'wporg_field_pill', // As of WP 4.6 this value is used only internally.
// Use $args' label_for to populate the id inside the callback.
__( 'Pill', 'wporg' ),
'wporg_field_pill_cb',
'wporg',
'wporg_section_developers',
array(
'label_for' => 'wporg_field_pill',
'class' => 'wporg_row',
'wporg_custom_data' => 'custom',
)
);
}
/**
* Register our wporg_settings_init to the admin_init action hook.
*/
add_action( 'admin_init', 'wporg_settings_init' );
/**
* Custom option and settings:
* - callback functions
*/
/**
* Developers section callback function.
*
* @param array $args The settings array, defining title, id, callback.
*/
function wporg_section_developers_callback( $args ) {
?>
<p id="<?php echo esc_attr( $args['id'] ); ?>"><?php esc_html_e( 'Follow the white rabbit.', 'wporg' ); ?></p>
<?php
}
/**
* Pill field callbakc function.
*
* WordPress has magic interaction with the following keys: label_for, class.
* - the "label_for" key value is used for the "for" attribute of the <label>.
* - the "class" key value is used for the "class" attribute of the <tr> containing the field.
* Note: you can add custom key value pairs to be used inside your callbacks.
*
* @param array $args
*/
function wporg_field_pill_cb( $args ) {
// Get the value of the setting we've registered with register_setting()
$options = get_option( 'wporg_options' );
?>
<select
id="<?php echo esc_attr( $args['label_for'] ); ?>"
data-custom="<?php echo esc_attr( $args['wporg_custom_data'] ); ?>"
name="wporg_options[<?php echo esc_attr( $args['label_for'] ); ?>]">
<option value="red" <?php echo isset( $options[ $args['label_for'] ] ) ? ( selected( $options[ $args['label_for'] ], 'red', false ) ) : ( '' ); ?>>
<?php esc_html_e( 'red pill', 'wporg' ); ?>
</option>
<option value="blue" <?php echo isset( $options[ $args['label_for'] ] ) ? ( selected( $options[ $args['label_for'] ], 'blue', false ) ) : ( '' ); ?>>
<?php esc_html_e( 'blue pill', 'wporg' ); ?>
</option>
</select>
<p class="description">
<?php esc_html_e( 'You take the blue pill and the story ends. You wake in your bed and you believe whatever you want to believe.', 'wporg' ); ?>
</p>
<p class="description">
<?php esc_html_e( 'You take the red pill and you stay in Wonderland and I show you how deep the rabbit-hole goes.', 'wporg' ); ?>
</p>
<?php
}
/**
* Add the top level menu page.
*/
function wporg_options_page() {
add_menu_page(
'WPOrg',
'WPOrg Options',
'manage_options',
'wporg',
'wporg_options_page_html'
);
}
/**
* Register our wporg_options_page to the admin_menu action hook.
*/
add_action( 'admin_menu', 'wporg_options_page' );
/**
* Top level menu callback function
*/
function wporg_options_page_html() {
// check user capabilities
if ( ! current_user_can( 'manage_options' ) ) {
return;
}
// add error/update messages
// check if the user have submitted the settings
// WordPress will add the "settings-updated" $_GET parameter to the url
if ( isset( $_GET['settings-updated'] ) ) {
// add settings saved message with the class of "updated"
add_settings_error( 'wporg_messages', 'wporg_message', __( 'Settings Saved', 'wporg' ), 'updated' );
}
// show error/update messages
settings_errors( 'wporg_messages' );
?>
<div class="wrap">
<h1><?php echo esc_html( get_admin_page_title() ); ?></h1>
<form action="options.php" method="post">
<?php
// output security fields for the registered setting "wporg"
settings_fields( 'wporg' );
// output setting sections and their fields
// (sections are registered for "wporg", each field is registered to a specific section)
do_settings_sections( 'wporg' );
// output save settings button
submit_button( 'Save Settings' );
?>
</form>
</div>
<?php
}