当前浏览:首页 / WordPress函数 / add_settings_field()

add_settings_field( string $id, string $title, callable $callback, string $page, string $section = 'default', array $args = array() )

将新字段添加到设置页面的某个设置栏

addmore...

field 字段more...

settings 设置more...


描述

这是设置API的一部分。使用此函数可定义设置字段,该字段将显示为设置页面内设置栏的一部分。使用do_settings_sections()中的do_settings_fields()显示字段。

$callback参数应该是一个函数的名称,该函数呼应此设置字段的HTML输入标签。使用get_option()检索要显示的现有值。


参数

$id

(string)(必填) 用于标识字段的slug名称。用于标签的'id'属性。

$title

(string)(必填) 字段的格式化标题。显示为输出期间字段的label标签。

$callback

(callable)(必填) 用所需的表单input填充字段的函数。函数应回显其输出。

$page

(string)(必填) 要在其上显示设置栏(常规、阅读、撰写等)的设置页面的slug名称。

$section

(string)(可选) 要在其中显示字段框的设置页面设置栏的slug名称。

默认值: 'default'

$args

(array)(可选) 输出字段时使用的额外参数。

  • 'label_for'
    (string) 提供时,设置标题将包装在<label>元素中,其for属性将填充此值。
  • 'class'
    (string) 当输出字段时,要添加到<tr>元素的CSS类。

默认值: array()


更多信息

您必须使用register_setting()注册这个函数所使用的任何选项,否则这些选项将不会自动保存和更新。

回调函数需要输出适当的html input并用旧值填充,保存将在后台完成。

html input字段的name属性必须与register_setting()中的$option_name匹配,并且value可以使用get_option()

此函数还可用于向默认WP设置页面(如“媒体”或“常规”)添加额外的设置字段。您可以将这些字段添加到现有设置栏中,或使用add_settings_section()创建新设置栏以将字段添加到其中。

有关详细信息,请参见设置API



源码

查看源码 官方文档


更新日志

版本描述
4.2.0添加了$class参数。
2.7.0开始引入

用户贡献的笔记

  • 贡献者:Codex

    带label标签

    将id为myprefix_setting-id的设置添加到“常规设置”页面。myprefix应该是插件或主题的唯一字符串。设置label标签,以便可以单击设置标题以聚焦字段。

    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' ) );
    
    
  • 贡献者:tradesouthwest

    只需查找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
        }
    

    或者,您可以将“false”添加到任何条件(empty, null, '', 0)中。

  • 贡献者:princepink

    我怀疑标签的“id”属性中使用的可能会被重写为标签的“name”属性。
    我认为$id参数是用来识别被WP识别的字段,并显示该字段或获取其值。是否用作实际标签的id属性的值取决于具体情况(在$callback中)。
    通常情况下,name属性可能会被用于这个目的。
    我一直不明白这个参数的意思是为某些表单元素生成属性,但似乎不是。当把‘label_for’放入将被传递到$callback的$args中时,将自动生成带有属性的label标签。所以这个值应该和你写的$callback中的实际id的值一样。

  • 贡献者:tehlivi
    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';
    }
  • 贡献者:Bence Szalai

    $id参数描述说“用于标签的‘id’属性”,然而这意味着你必须确保这个$id被用作与字段相关的input元素的HTML id标签。 WP只使用这个$id来为你的字段在它的内部settings_field列表($wp_settings_fields)中提供一个唯一的键。
    由于WP不控制input元素被添加到你的管理页面HTML中的方式,你必须确保你输出的input元素的id$id标签相匹配。这可以通过将$callback配置为一个函数来完成,它将产生具有正确id标签的正确input元素。
    $args数组中的'label_for'元素也应该与相同的id相匹配,以便让浏览器了解哪个label属于哪个input字段。

    另外值得注意的是,input元素的id标记还应与register_setting()调用中使用的$option_name(第二个)参数匹配,否则设置API将无法将$_POST中浏览器发送的值与您的设置匹配,并且您的设置将永远不会保存。

    长话短说,我们有一堆不同的名称和参数,但基本上,add_settings_field()调用的$id$args['label_for'],以及register_setting()调用中的$option_name,再加上input字段回调中使用的id,都应该是相同、唯一的id。此外,在get_option($option)调用中,应将相同的id用作$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 '/>';
    }
    
  • 贡献者:tehliviAbhijit Rakas

    面向对象:

    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();