1. 理解WordPress设置API与多值需求
在wordpress插件开发中，我们常用settings api来创建管理页面和保存插件设置。通常情况下，通过add_settings_field定义的单个输入字段，其name属性会映射到get_option获取到的一个键，并保存一个单一的标量值（如字符串或数字）。
例如，一个用于保存分类别名的字段可能定义如下：
add_settings_field(
'cat_slug', // ID
'Category Slug', // 标题
'cat_slug_render', // 渲染函数
'slug-configuration', // 页面
'configuration' // 区块
);
function cat_slug_render() {
$options = get_option( 'slug-configuration' );
?>
'>
这种方法只能保存一个分类别名。然而，在某些场景下，我们可能需要为一个设置键保存多个值，例如，为一个分类折扣插件保存多个分类别名及其对应的折扣百分比。此时，我们需要修改输入字段的name属性以支持数组形式的数据。
2. 修改输入字段以支持多值保存
要使一个输入字段能够保存多个值，关键在于修改其name属性，使其包含[]。当表单提交时，PHP会自动将所有具有相同name属性（且包含[]）的字段值解析为一个数组。
将原有的name='slug-configuration[cat_slug]'修改为name='slug-configuration[cat_slug][]'。
示例代码：
function cat_slug_render() {
// 始终为get_option提供一个默认值，以防选项尚未保存
$options = get_option( 'slug-configuration', array() );
?>
'>
通过这种方式，每次提交表单时，slug-configuration选项中的cat_slug键将不再是一个简单的字符串，而是一个包含所有提交值的数组。
3. 在前端展示已保存的多值数据
当cat_slug现在是一个数组时，我们需要决定在单个输入字段中显示哪个值。常见的策略是显示第一个值或最近（最后一个）保存的值。
3.1 策略一：显示数组中的第一个值
这是最直接的方式，适用于你希望用户每次看到并可能编辑第一个条目的场景。
function cat_slug_render_first_value() {
$options = get_option( 'slug-configuration', array() );
?>
'>
3.2 策略二：显示数组中最近（最后一个）保存的值
如果你希望用户总能看到他们最近一次输入的值，可以使用此策略。
function cat_slug_render_last_value() {
$options = get_option( 'slug-configuration', array() );
$category_slugs = $options['cat_slug'] ?? array(); // 确保是一个数组
$last_key = array_key_last( $category_slugs ); // 获取数组最后一个元素的键
?>
'>
重要提示：
- 安全性： 始终使用esc_html()对从数据库检索并显示在前端的数据进行HTML实体转义，以防止跨站脚本（XSS）攻击。
- 健壮性： 使用PHP 7+的空合并运算符??（Null Coalescing Operator）可以优雅地处理变量不存在或为null的情况，避免产生PHP通知或错误。例如$options['cat_slug'][0] ?? ''。
4. 检索和使用多值数据
一旦数据作为数组成功保存，你可以通过get_option函数获取到整个数组，然后使用foreach循环来遍历并处理每个值。
示例代码：
// 获取保存的配置选项
$options = get_option('slug-configuration', array());
// 从选项中获取分类别名数组，如果不存在则默认为空数组
$saved_category_slugs = $options['cat_slug'] ?? array();
if (!empty($saved_category_slugs) && is_array($saved_category_slugs)) {
echo '已保存的分类别名：
';
echo '- ';
foreach ($saved_category_slugs as $index => $slug) {
// 在这里处理每个分类别名，例如显示、应用折扣逻辑等
// 记得对输出的数据进行安全转义
echo '
- 分类 ' . ($index + 1) . ': ' . esc_html($slug) . ' '; // 假设这里可以根据 $slug 应用折扣 // apply_discount_for_category( $slug, $discount_percentage ); } echo '
暂无保存的分类别名。
'; }5. 注意事项与最佳实践
5.1 数据清洗（Sanitization）
当设置字段接收数组时，其对应的sanitize_callback函数必须能够正确处理数组输入。WordPress默认的sanitize_text_field等函数是为标量值设计的，直接应用于数组会导致错误或不期望的结果。你需要编写一个自定义的清洗函数，遍历数组中的每个元素并进行清洗。
示例自定义清洗函数：
function my_plugin_sanitize_array_fields( $input ) {
$sanitized_output = array();
if ( is_array( $input ) ) {
foreach ( $input as $key => $value ) {
// 根据需要对每个值进行清洗，例如：
$sanitized_output[ $key ] = sanitize_text_field( $value );
}
}
return $sanitized_output;
}
// 在 register_setting 中注册你的自定义清洗函数
register_setting(
'slug-configuration', // 设置组
'slug-configuration', // 选项名称
array(
'type' => 'array', // 告知WordPress这是一个数组类型
'sanitize_callback' => 'my_plugin_sanitize_array_fields', // 自定义清洗函数
'default' => array(),
)
);5.2 用户界面设计
虽然后端能够保存多个值，但前端默认只提供一个输入框。如果你的目标是实现“每次保存都插入新记录”的用户体验，通常需要更复杂的JavaScript逻辑来动态添加或删除输入框，从而允许用户一次性输入多个值。本教程侧重于后端数据处理，但一个友好的前端UI对于多值设置至关重要。
5.3 数据结构选择
对于更复杂的多值数据，例如同时保存分类别名和对应的折扣百分比，仅仅使用一个字符串数组可能不够。你可能需要将整个数据作为一个关联数组的数组来保存。
示例：
在这种情况下，get_option('slug-configuration')['discounts']将返回一个包含多个关联数组的数组，每个关联数组代表一个分类折扣项。
总结
通过在HTML输入字段的name属性中使用[]，我们可以轻松地让WordPress插件的单个设置字段保存多个值。这提供了一种灵活的方式来管理数组类型的数据。在实现过程中，务必注意数据在前端的展示策略、后端数据的安全清洗（通过自定义sanitize_callback）以及最终数据的使用方式。对于更复杂的多值输入场景，结合JavaScript进行动态UI交互将提供更好的用户体验。
