自定义设置页

创建自定义设置页面包括以下组合：创建管理菜单，使用设置API和选项API。

下面的示例及其注释可以作为这些专题的快速参考。

完整示例

完整示例，添加名为WPOrg的顶级菜单，注册名为wporg_options的自定义选项，并使用设置API和选项API执行CRUD（创建、读取、更新、删除）逻辑（包括显示error/update消息）。

<?php
/**
 * @internal never define functions inside callbacks.
 * these functions could be run multiple times; this would result in a fatal error.
 */

/**
 * 自定义选项和设置
 */
function wporg_settings_init() {
	// 为 "wporg" 页面注册一个新的设置
	register_setting( 'wporg', 'wporg_options' );

	// 为 "wporg" 页面注册一个新的设置栏
	add_settings_section(
		'wporg_section_developers',
		__( 'The Matrix has you.', 'wporg' ), 'wporg_section_developers_callback',
		'wporg'
	);

	// 在 "wporg" 页面内的 "wporg_section_developers" 设置栏中注册新一个字段
	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',
		)
	);
}

/**
 * 注册 wporg_settings_init 到 admin_init 动作钩子
 */
add_action( 'admin_init', 'wporg_settings_init' );


/**
 * 自定义选项和设置:
 *  - 回调函数
 */


/**
 * "wporg_section_developers"设置栏的回调函数
 *
 * @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字段的回调函数
 *
 * 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
}

/**
 * 添加顶级菜单页
 */
function wporg_options_page() {
	add_menu_page(
		'WPOrg',
		'WPOrg Options',
		'manage_options',
		'wporg',
		'wporg_options_page_html'
	);
}


/**
 * 注册 wporg_options_page 到 admin_menu 动作钩子
 */
add_action( 'admin_menu', 'wporg_options_page' );


/**
 * 顶级菜单的回调函数
 */
function wporg_options_page_html() {
	// 检测用户能力
	if ( ! current_user_can( 'manage_options' ) ) {
		return;
	}

	// 添加 error/update 信息

	// 检测如果用户有提交设置
	// WordPress将添加 $_GET 参数 "settings-updated" 到 url
	if ( isset( $_GET['settings-updated'] ) ) {
		// 添加设置保存信息，类为 "updated"
		add_settings_error( 'wporg_messages', 'wporg_message', __( 'Settings Saved', 'wporg' ), 'updated' );
	}

	// 显示 error/update 信息
	settings_errors( 'wporg_messages' );
	?>
	<div class="wrap">
		<h1><?php echo esc_html( get_admin_page_title() ); ?></h1>
		<form action="options.php" method="post">
			<?php
			// 为注册的设置 "wporg" 输出安全字段
			settings_fields( 'wporg' );
			// 输出设置栏和它们的字段
			// (设置栏注册到 "wporg" 设置, 每个字段则是注册到特定的设置栏)
			do_settings_sections( 'wporg' );
			// 输出保存设置按钮
			submit_button( 'Save Settings' );
			?>
		</form>
	</div>
	<?php
}