# 7.1 简介

设置 API 侧重于为我们提供了一种创建表单和管理表单数据的方式。

设置 API 包含设置表单的管理页面实现 “半自动工作”,允许定义整个管理页面、选项区域甚至具体的栏目。新的设置页面可与其中的选项区域和栏目一并注册。可通过注册新的选项区域或栏目的方法向现有的设置页面添加内容。组织设置栏目的注册和验证,仍需再设置 API 的框架下进行一些工作,但避免付出大量精力用于调试设置选项的管理。

在使用设置 API 时,表单应发送 POST 请求到 options.php。但 options.php 拥有较严格的权限管理机制,因此用户需要 “manage_options” 权限(相应地,在多站点的站点中,则需超级管理员权限)才可提交表单并得到处理。

# 为什么使用设置 API

我们可以开发自己的设置页面,而不是使用这个 API,这就出现了一个问题,设置 API 可以为我们带来什么好处,以下是一些好处的简要说明。

  • 视觉一致性

使用 API 生成界面元素,可以确保我们的自定义设置页面和 WordPress 默认管理界面一致,如果我们看到了一个风格是 5 年前的设置页面,这个页面肯定没有使用设置 API,如果使用了设置 API,自定义页面的风格会随着 WordPress 默认风格一起更新。所以,使用设置 API 一个很大好处就是,设计页面看起来就像该有的样子(和 WordPress 默认风格一致),感谢 WordPress 的天才设计师们,他们的工作看起来很棒。

  • 健壮性(面向未来)

由于设置 API 是 WordPress 核心的一部分,任何更新都将自动更新我们的设置页面,如果我们创建了自己的设置页面,WordPress 的内核更新可能会破坏我们的自定义设置。会有越来越多的开发者测试和维护这些设置 API 代码,所以他们会更加稳定。

  • 工作更轻松

当然,最直接的好处是 WordPress 的设置 API 在底层默默的为我们做了很多工作,以下是一些例子:

1.处理表单提交 – 让 WordPress 处理并存储 $_POST 提交

2.包括安全措施 – 可以让我们获得额外的安全措施,如随机数验证

3.清理数据 – 可以和 WordPress 其他部分一样,自动为我们清理数据,以确保提交的字符串可以安全的使用

# 函数参考

设置注册/注销注册 添加分节/字段 选项表单渲染 错误信息
register_setting()
unregister_setting()
add_settings_section()
add_settings_field()
settings_fields()
do_settings_sections()
do_settings_fields()
add_settings_error()
get_settings_errors()
settings_errors()

# 7.2 使用设置 API

# 添加设置

我们可以使用 register_setting() 来定义一个新的设置,此函数会在 {$wpdb->prefix}_options 数据表中插入一条记录。可以使用 add_settings_section() 在现有设置页面上添加新分节。可以使用 do_settings_fields() 将新字段添加到现有的分节上面。

register_setting() 以及所提及的 add_settings_*() 函数都应该添加到 admin_init
<?php
register_setting(
    string $option_group, 
    string $option_name, 
    callable $sanitize_callback = ''
);
1
2
3
4
5
6

有关参数的完整说明,请参阅关于 register_setting() 的函数参考。

# 添加分节

<?php
add_settings_section(
    string $id, 
    string $title, 
    callable $callback, 
    string $page
);
1
2
3
4
5
6
7

分节是我们在 WordPress 设置页面上看到的带有共享标题的设置组。在插件中,我们可以向现有的设置页面添加新分节,而不是创建一个新页面。这可以让我们的插件更容易维护,并降低用户的学习和使用成本。

有关参数的完整说明,请参阅关于 add_settings_section() 的函数参考。

# 添加字段

<?php
add_settings_field(
    string $id, 
    string $title, 
    callable $callback, 
    string $page
);
1
2
3
4
5
6
7

将新字段添加到设置页面的分节中。

# 获取设置

<?php
get_option(
    string $option,
    mixed $default = false
);
1
2
3
4
5

使用 https://developer.wordpress.org/reference/functions/get_option/ 函数可以获取设置数据,该函数接受两个参数:选项的名称和该选项的可选默认值。

<?php
// 获取我们上面使用 register_setting() 注册的选项值
$setting = get_option('mla_setting_name');
1
2
3

.e.g.

<?php
function mla_settings_init(){
   // 为 阅读 页面注册新设置
   register_setting('reading', 'mla_setting_name');

   // 在阅读页面上注册新分节
   add_settings_section(
      'mla_settings_section',
      'MLA Settings Section',
      'mla_settings_section_cb',
      'reading'
   );

   // 阅读页面中,在 the mla_settings_section 分节上注册新设置
   add_settings_field(
      'mla_settings_field',
      'MLA Setting',
      'mla_settings_field_cb',
      'reading',
      'mla_settings_section'
   );
}
 
/**
 * 注册 mla_settings_init 到 admin_init Action 钩子
 */
add_action('admin_init', 'mla_settings_init');
 

/**
 * 回调函数
 */
// 分节内容回调
function mla_settings_section_cb() {
   echo '<p>MLA Section Introduction.</p>';
}
 
// 字段内容回调
function mla_settings_field_cb() {
   // 获取我们使用 register_setting() 注册的字段的值
   $setting = get_option('mla_setting_name');
   // 输出字段
   ?>
   <input type=text name=mla_setting_name value=<?php echo isset( $setting ) ? esc_attr( $setting ) : ''; ?>>
   <?php
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46