WordPress开发函数add_settings_field()

WordPress开发函数add_settings_field()，向设置页面的部分添加一个新字段。
用法：
add_settings_field( string $id, string $title, callable $callback, string $page, string $section = \’default\’, array $args = array() )
描述
设置API的一部分。使用它来定义一个设置字段，该字段将显示为设置页面内的设置部分的一部分。在do_settings-sections()中使用do_settings_fields()显示字段
$callback参数应该是响应此设置字段的HTML输入标记的函数名。使用get_option()来检索要显示的现有值。
参数：
$id
(string) (必需) Slug-name标识字段。用于标签的\’id\’属性。
$title
(string) (必需) 字段的格式化标题。显示为输出期间字段的标签。
$callback
(callable) (必需) 用所需的表单输入填充字段的函数。函数应该回显它的输出。
$page
(string) (必需) 设置页面的鼻涕虫名称，用于显示部分(一般，读取，写入，…)。
$section
(string) (可选) 设置页面中要显示框的部分的段名称。
默认值: \’default\’
$args
(array) (可选) 输出字段时使用的额外参数。
\’label_for\’
(string) 当提供时，设置标题将被包装在元素中，其for属性用这个值填充。
\’class\’
(string) 当字段输出时，添加到元素的CSS类。
默认值: array()
更多信息
您必须将此函数使用的任何选项注册到register_setting()中，否则它们不会被自动保存和更新。
回调函数需要输出适当的html输入，并用旧的值填充它，保存将在幕后完成。
html输入字段的name属性必须匹配register_setting()中的$option_name，值可以使用get_option()填充。
这个功能也可以用来添加额外的设置字段到默认的WP设置页面，如媒体或一般。您可以将它们添加到现有的节中，或者使用add_settings_section()创建一个新节，将字段添加到其中。
详情请参见设置API。
来源：
文件: wp-admin/includes/template.php
function add_settings_field( $id, $title, $callback, $page, $section = \’default\’, $args = array() ) {
global $wp_settings_fields;
if ( \’misc\’ === $page ) {
_deprecated_argument(
__FUNCTION__,
\’3.0.0\’,
sprintf(
/* translators: %s: misc */
__( \’The \”%s\” options group has been removed. Use another settings group.\’ ),
\’misc\’
)
);
$page = \’general\’;
}
if ( \’privacy\’ === $page ) {
_deprecated_argument(
__FUNCTION__,
\’3.5.0\’,
sprintf(
/* translators: %s: privacy */
__( \’The \”%s\” options group has been removed. Use another settings group.\’ ),
\’privacy\’
)
);
$page = \’reading\’;
}
$wp_settings_fields[ $page ][ $section ][ $id ] = array(
\’id\’ => $id,
\’title\’ => $title,
\’callback\’ => $callback,
\’args\’ => $args,
);
}
更新日志

用户贡献的笔记
（由Codex – 6年前贡献）
与标签
将id为myprefix_setting-id的设置添加到常规设置页面。myprefix应该是你的插件或主题的唯一字符串。设置一个标签，以便单击设置标题以聚焦于字段。
add_settings_field( \’myprefix_setting-id\’,
\’This is the setting title\’,
\’myprefix_setting_callback_function\’,
\’general\’,
\’myprefix_settings-section-name\’,
array( \’label_for\’ => \’myprefix_setting-id\’ ) );
（由本斯·萨拉2年前贡献）
$id参数描述说:“在标签的‘id’属性中使用”，然而，这意味着您必须确保这个$id被用作与字段相关的输入元素的HTML id标签。WP只使用这个$id在它的内部settings_field列表($wp_settings_fields)中为你的字段有一个唯一的键。
由于WP不控制将input元素添加到管理HTML的方式，所以您必须确保使用与$id标签匹配的id输出input元素。这可以通过将$callback配置到一个函数来实现，该函数将产生具有正确id标记的正确输入元素。
$args数组中的\’ label_for \’元素也应该匹配相同的id，以便浏览器能够理解哪个标签属于哪个输入字段。
它也值得注意,输入元素的id标签也应该匹配option_name美元(2)参数你正在使用register_setting()调用,否则设置API将无法匹配值发送$ _POST你的浏览器设置,和永远不会保存你的设置。
长话短说,我们有很多不同的名称和参数,但基本上id和args美元[\’ label_for \’] add_settings_field()调用和register_setting option_name美元()调用加上id您在输入字段中使用回调,都应该是相同的,唯一的id。也应该使用相同的id选项参数get_option美元(美元选项)调用得到的值设置。
register_setting( \’mygroup\’, \’mynewcheckboxID\’ );
add_settings_field(
\’mynewcheckboxID\’,
\’My New Checkbox\’,
\’callback_input_myid\’,
\’myAdminPage\’,
\’myAdminSection\’,
[
\’label_for\’ => \’mynewcheckboxID\’
] );
function callback_input_myid() {
echo \”<input type=\’checkbox\’ id=\’mynewcheckboxID\’ value=\’1\’\”
if ( get_option(\’mynewcheckboxID\’) == \’1\’ ) {
echo \’ checked\’;
}
echo \’/>\’;
}
（由tradessouthwest提供- 1年前）
只需查找isset，就可以在前端检查复选框设置字段。不需要添加额外的检查，如1,0,true, false….如果没有设置复选框，则返回false。
/* **************** CHECKBOXES **************** */
// settings checkbox
add_settings_field(
\’wpdevref_removestyles_field\’,
esc_attr__(\’Remove Plugin Styles\’, \’wpdevref\’),
\’wpdevref_removestyles_field_cb\’,
\’wpdevref_options\’,
\’wpdevref_options_section\’,
array(
\’type\’ => \’checkbox\’,
\’option_group\’ => \’wpdevref_options\’,
\’name\’ => \’wpdevref_removestyles_field\’,
\’label_for\’ => \’wpdevref_removestyles_field\’,
\’value\’ => (empty(get_option(\’wpdevref_options\’)[\’wpdevref_removestyles_field\’]))
? 0 : get_option(\’unitizr_options\’)[\’wpdevref_removestyles_field\’],
\’description\’ => __( \’Check to remove preset plugin overrides.\’,
\’wpdevref\’ ),
\’checked\’ => (!isset(get_option(\’wpdevref_options\’)[\’wpdevref_removestyles_field\’]))
? 0 : get_option(\’wpdevref_options\’)[\’wpdevref_removestyles_field\’],
// Used 0 in this case but will still return Boolean not[see notes below]
\’tip\’ => esc_attr__( \’Use if plugin fields drastically changed when installing this plugin.\’, \’wpdevref\’ )
)
);
然后回调函数会这样添加:
/**
* switch for \’remove styles\’ field
* @since 2.0.1
* @input type checkbox
*/
function wpdevref_removestyles_field_cb($args)
{
$checked = \’\’;
$options = get_option($args[\’option_group\’]);
$value = ( !isset( $options[$args[\’name\’]] ) )
? null : $options[$args[\’name\’]];
if($value) { $checked = \’ checked=\”checked\” \’; }
// Could use ob_start.
$html = \’\’;
$html .= \'<input id=\”\’ . esc_attr( $args[\’name\’] ) . \’\”
name=\”\’ . esc_attr( $args[\’option_group\’] . \'[\’.$args[\’name\’].\’]\’) .\’\”
type=\”checkbox\” \’ . $checked . \’/>\’;
$html .= \'<span class=\”wndspan\”>\’ . esc_html( $args[\’description\’] ) .\'</span>\’;
$html .= \'<b class=\”wntip\” data-title=\”\’. esc_attr( $args[\’tip\’] ) .\’\”> ? </b>\’;
echo $html;
}
检查在正面渲染动作将使用:
// Options getter could be a function with arguments.
$options = get_option(\’wpdevref_options\’);
$value = ( !isset($options[\’wpdevref_removestyles_field\’] ) )
? \’\’ : $options[\’wpdevref_removestyles_field\’];
if ( !$value ) {
// Do some magic
}
也可以在任意条件(empty, null， \”， 0)中添加\’ false \’。
（6年前由princepink提供）
我怀疑在标签的\’ id \’属性中使用的可能被重写为在标签的\’ name \’属性中使用。
我认为$id参数是用来识别被WP识别的字段，并显示字段或得到那的值。是否被用作实际标记的属性id的值取决于具体情况(在$callback中)。通常，name属性可以用于此目的。
我只是对这个参数感到困惑，它的意思是为某个表单元素生成属性，但似乎不是这样。当将\’ label_for \’放入$args中，它将被传递给$callback，这会自动生成带有属性for的label标签。因此，这个值应该与您编写的$回调函数中的实际id值相同。
（由特利维贡献- 3年前）
add_action(\’admin_init\’, \’your_function\’);
function your_function(){
add_settings_field(
\’myprefix_setting-id\’,
\’This is the setting title\’,
\’myprefix_setting_callback_function\’,
\’general\’,
\’default\’,
array( \’label_for\’ => \’myprefix_setting-id\’ )
);
}
function myprefix_setting_callback_function($args){
echo \’Content here\’;
}
（由特利维贡献- 3年前）
面向对象:
class ClassName {
public function __construct() {
add_action( \’admin_init\’, array( $this, \’your_function\’ ) );
}
function your_function() {
add_settings_field(
\’myprefix_setting-id\’,
\’This is the setting title\’,
array( $this, \’myprefix_setting_callback_function\’ ),
\’general\’,
\’default\’,
array( \’label_for\’ => \’myprefix_setting-id\’ ),
);
}
function myprefix_setting_callback_function( $args ) {
echo \’Content here\’;
}
}
$ClassName = new ClassName();