概述

设置 API 于 WordPress 2.7 版本中引入，允许半自动地管理包含设置表单的管理员页面。它使您能够定义设置页面、这些页面内的部分以及部分内的字段。

新的设置页面可以与其中包含的部分和字段一起注册。现有的设置页面也可以通过在其中注册新的设置部分或字段来扩展。

使用设置 API 时，字段的注册和验证仍需开发人员付出一定努力，但这避免了大量对底层选项管理的复杂调试。

注意：使用设置 API 时，表单将提交到 wp-admin/options.php，该文件提供了相当严格的能力检查。用户需要具有 manage_options 能力（在 Multisite 模式下必须是超级管理员）才能提交表单。

这些函数位于 wp-admin/includes/plugin.php 和 wp-admin/includes/template.php 中。

函数参考

设置注册/取消注册：

添加字段/部分：

选项表单渲染：

错误处理：

添加设置字段

您可以使用此函数向现有的 WordPress 页面添加新的设置字段（基本上是 wp_options 数据库表中的一个选项，但完全由系统为您管理）。您的回调函数只需输出适当的 HTML 输入控件并填充旧值，保存操作将在后台完成。您可以使用 add_settings_section() 在现有页面上创建自己的部分，如下所述。

注意： 您必须使用 add_settings_field() 注册任何您使用的选项，否则它们将无法自动保存和更新。详见下文及示例。

add_settings_field( $id, $title, $callback, $page, $section = 'default', $args = array() )
  • $id – 用于标签 'id' 属性的字符串。
  • $title – 字段的标题。
  • $callback – 作为更大表单的一部分填充所需输入的函数。输入的名称和 ID 应与此函数传入的 $id 匹配。该函数应输出其内容。
  • $page – 显示该字段的设置页面类型（general、reading、writing 等）。
  • $section – 显示该框的设置页面部分（default 或使用 add_settings_section 添加的部分，查看源代码中的页面以了解现有的部分）。
  • $args – 传递给回调函数的额外参数

添加设置部分

设置部分是您在 WordPress 设置页面上看到的具有共享标题的设置组。在您的插件中，您可以向现有的设置页面添加新部分，而不是创建一个全新的页面。这使得您的插件更易于维护，并且减少了用户需要学习的新页面数量。您只需告诉他们更改相关现有页面上的设置即可。

add_settings_section( $id, $title, $callback, $page );
  • $id – 用于标签 'id' 属性的字符串。
  • $title – 部分的标题。
  • $callback – 用所需内容填充部分的函数。该函数应输出其内容。
  • $page – 显示该部分的设置页面类型（general、reading、writing、media 等）。

注册设置

register_setting( $option_group, $option_name, $args );
unregister_setting( $option_group, $option_name );

注意： register_setting() 以及上述提到的 add_settings_*() 函数都应从 admin_init 动作钩子回调函数中调用。请参阅下面的“示例”部分。

选项表单渲染

当使用 API 向现有选项页面添加设置时，您无需担心表单本身，因为它已经为该页面定义好了。当您从头开始定义一个新页面时，您需要输出一个最小化的表单结构，其中包含一些标签，这些标签进而输出页面的实际部分和设置。

为了显示隐藏字段并处理选项表单的安全性，设置 API 提供了 settings_fields() 函数。settings_fields( $option_group );

$option_group (string) (required):

设置组名称。这必须与 register_setting() 中使用的组名称匹配，即表单要出现的页面 slug 名称。默认值：无

为了显示分配给页面的部分及其包含的设置，设置 API 提供了 do_settings_sections() 函数。 do_settings_sections( $page );

$page (string) (required):

您要输出其设置部分的页面的 slug 名称。这应与 add_settings_section() 中使用的页面名称匹配。默认值：无

do_settings_fields() 函数用于输出分配给特定页面和部分的所有字段。您不应直接调用此函数，而应使用 do_settings_sections() 来输出部分内容以及关联的字段。

您的选项表单还需要一个提交按钮。您可以使用 submit_button() 函数来实现这一点。

最后，您需要输出 HTML <form> 标签，定义 options.php 的动作目标和 POST 方法。以下是生成添加到 slug 名称为 my-page 的页面的所有部分和字段的示例选项表单代码：

<form method="POST" action="options.php">
<?php 
settings_fields( 'my-page' ); // 传递页面的 slug 名称，在 Settings API 中也称为 option group name
do_settings_sections( 'my-page' );  // 传递页面的 slug 名称
submit_button(); // 提交按钮
?>
</form>

示例

添加一个带有新字段在内的设置部分

<?php 
/**
 * 在 admin_init 期间添加所有部分、字段和设置
 */
 
function wporg_settings_api_init() {
 	// 将部分添加到阅读设置中，以便我们可以向其添加我们的
 	// 字段
 	add_settings_section(
		'wporg_setting_section',
		'阅读设置中的示例设置部分',
		'wporg_setting_section_callback_function',
		'reading'
	);
 	
 	// 添加带有名称和使用函数的字段以用于我们的新
 	// 设置，将其放入我们的新部分中
 	add_settings_field(
		'wporg_setting_name',
		'示例设置名称',
		'wporg_setting_callback_function',
		'reading',
		'wporg_setting_section'
	);
 	
 	// 注册我们的设置，以便 $_POST 处理由我们完成，
 	// 并且我们的回调函数只需输出 <input>
 	register_setting( 'reading', 'wporg_setting_name' );
 } // wporg_settings_api_init()
 
 add_action( 'admin_init', 'wporg_settings_api_init' );
 
  
/**
 * 设置部分回调函数
 *
 * 如果我们添加了新部分，则需要此函数。此函数
 * 将在我们的部分开始时运行
 */
 
 function wporg_setting_section_callback_function() {
 	echo '<p>设置部分的介绍文本</p>';
 }
 
/*
 * 示例设置的回调函数
 *
 * 创建复选框 true/false 选项。其他类型肯定也是可能的
 */
 
 function wporg_setting_callback_function() {
 	echo '<input name="wporg_setting_name" id="wporg_setting_name" type="checkbox" value="1" class="code" ' . checked( 1, get_option( 'wporg_setting_name' ), false ) . ' /> <label for="wporg_setting_name">解释文本</label>';
 }

所有代码应放置位置的图形表示

设置

外部参考

生成器

PHP Class