设置

设置

WordPress 提供了两个核心 API，使管理界面易于构建、安全并与 WordPress 管理的设计保持一致。

设置API专注于为开发人员提供一种创建表单和管理表单数据的方法。

Options API专注于使用简单的键/值系统管理数据。

快速参考

请参阅使用设置 API 和选项 API构建自定义设置页面的完整示例。

设置接口

WordPress 2.7 中添加的设置 API 允许半自动管理包含设置表单的管理页面。它允许您定义设置页面、这些页面中的部分以及这些部分中的字段。

新的设置页面可以连同其中的部分和字段一起注册。还可以通过在其中注册新的设置部分或字段来添加现有设置页面。

组织字段的注册和验证仍然需要开发人员付出一些努力，但避免了底层选项管理的大量复杂调试。

警报：使用 Settings API 时，表单 POSTwp-admin/options.php提供相当严格的功能检查。用户需要具备manage_options提交表单的能力（在多站点中必须是超级管理员）。

为什么要使用设置 API？

开发人员可以忽略此 API，并在没有它的情况下编写自己的设置页面。这就引出了一个问题，这个 API 给桌面带来了什么好处？以下是一些好处的简要概述。

视觉一致性

使用 API 生成界面元素可确保您的设置页面看起来与其他管理内容相似。您的界面将遵循相同的样式指南，并且看起来像它所属的，并且感谢才华横溢的 WordPress 设计师团队，它看起来会很棒！

稳健性（面向未来！）

由于 API 是 WordPress 核心的一部分，任何更新都会自动考虑您插件的设置页面。如果您在不使用设置 API 的情况下创建自己的界面，WordPress 核心更新更有可能破坏您的自定义设置。还有更广泛的受众测试和维护该 API 代码，因此它往往会更加稳定。

减少工作量！

当然，最直接的好处是 WordPress API 在幕后为您做了很多工作。除了应用美观的集成设计之外，这里还有一些设置 API 的功能示例。

功能参考

设置注册/取消注册 添加字段/部分
注册设置()
取消注册设置()		 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() 以及提到的add_settings_*()函数都应该添加到admin_init操作挂钩中。

添加设置


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_prefixwp-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
}