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

register_setting( string $option_group, string $option_name, array $args = array() )

注册设置及其数据

registermore...

settings 设置more...


参数

$option_group

(string)(必填) 设置组名称,应对应于允许的选项键名称。默认允许的选项键名称包括'general'、'discussion'、'media'、'reading'、'writing'和'options'。

$option_name

(string)(必填) 要清理和保存的选项的名称。

$args

(array)(可选) 注册时用于描述设置的数据。

  • 'type'
    (string) 与此设置关联的数据类型。有效值为'string'、'boolean'、'integer'、'number'、'array'和'object'。
  • 'description'
    (string) 附加到此设置的数据说明。
  • 'sanitize_callback'
    (callable) 清理选项值的回调函数。
  • 'show_in_rest'
    (bool|array) 与此设置关联的数据是否应包含在REST API中。注册复杂设置时,此参数可以是带有'schema'键的数组。
  • 'default'
    (mixed) 当调用get_option()时的默认值。

默认值: array()



源码

查看源码 官方文档


更新日志

版本描述
5.5.0$new_whitelist_options已重命名为$new_allowed_options。请考虑编写更具包容性的代码。
4.7.0register_meta()类似,可以将$args传递给设置上的设置标志。
3.5.0privacy选项组已弃用。
3.0.0misc选项组已弃用。
2.7.0开始引入

用户贡献的笔记

  • 贡献者:Bence Szalai

    关于$args参数中元素的一些注意事项:

    'type'

    • 仅当设置了'show_in_rest'时才有效。因此,如果'show_in_rest'为false或不是$args的一部分,则无需设置'type'
    • 仅由REST API用于定义与设置关联的模式,并在REST API上实现清理。
    • 对管理页面的工作方式或选项API处理设置的方式没有影响。(也就是说,虽然您可能不应该提交,但可以从管理表单中提交设置的字符串值,该设置的'type'设置为"boolean"。WP不会报错,并将该值存储在选项表中。但是,这会导致REST API出现问题,因此请小心!)
    • 在本页列出的值之上,它还接受以下值:'array''object'

    'description'

    • 仅当设置了'show_in_rest'时才有效。因此,如果'show_in_rest'为false或不是$args的一部分,则无需设置'description'
    • 仅由REST API使用。

    'default'

    • 影响选项API(例如get_option())和REST API。

    总之:如果你不打算在REST API中包含你的设置,只在$args数组中设置 'default' 和 'sanitize_callback' 元素就足够了。其他的都会被忽略。

  • 贡献者:Farhan Noor
    /**
    * Registers a text field setting for Wordpress 4.7 and higher.
    **/
    function register_my_setting() {
    	$args = array(
    			'type' => 'string', 
    			'sanitize_callback' => 'sanitize_text_field',
    			'default' => NULL,
    			);
        register_setting( 'my_options_group', 'my_option_name', $args ); 
    } 
    add_action( 'admin_init', 'register_my_setting' );
    
  • 贡献者:Codex

    基本示例

    /**
     * Registers a setting.
     */
    function wpdocs_register_my_setting() {
    	register_setting( 'my_options_group', 'my_option_name', 'intval' ); 
    } 
    add_action( 'admin_init', 'wpdocs_register_my_setting' );
    
  • 贡献者:Andy SchmidtBence Szalai

    sanitize回调将启动两次!因此,如果清理涉及任何性能关键任务或单一任务,则必须在回调中采取措施,以避免重复执行这些部分。

    const	PLUGIN_SLUG =	'MyPlugin';
    
    /*
     *	Setup Plug-In Hooks (Namespaced Example)
     */
    \add_action( 'wp_loaded', __NAMESPACE__.'\on_wp_loaded' );
    
    if ( is_blog_admin() ) {
    	\register_activation_hook( __FILE__,  __NAMESPACE__.'\on_activate' );
    	\register_deactivation_hook( __FILE__,  __NAMESPACE__.'\on_deactivate' );
    	
    	\add_action( 'admin_menu', __NAMESPACE__.'\on_admin_menu' );
    	\add_action( 'admin_init', __NAMESPACE__.'\on_admin_init' );
    	\add_filter( 'plugin_action_links_' . plugin_basename( __FILE__ ), __NAMESPACE__.'\action_links' );
    }
    return;
    
    /*
     *	Add custom options to whitelist, allowing valiated settings to be saved by form.
     */
    function on_admin_init(): void 
    {
    	\register_setting( PLUGIN_SLUG, PLUGIN_SLUG, [ 'sanitize_callback' => __NAMESPACE__.'\sanitize_settings' ] ); 
    }
    
    /*
     *	Sanitize the form input.
     */
    function sanitize_settings( $input = NULL ):  
    {
    	// Detect multiple sanitizing passes.
    	// Accomodates bug: https://core.trac.wordpress.org/ticket/21989
    	static $pass_count = 0; $pass_count++;
    
    	if ( $pass_count <= 1 ) {
    		// Handle any single-time / performane sensitive actions.
    
    	}
    
    	// Insert regular santizing code here.
    }
  • 贡献者:Corey Salzano

    如果计划在REST API中使用设置,请在调用register_setting()时同时使用rest_api_initadmin_init挂钩,而不仅仅是admin_init。当单独连接到admin_init时,show_in_rest参数无效。

  • 贡献者:Ian Dunn

    如果希望设置显示在wp-json/wp/v2/settings端点中,除了正常的admin_init动作外,还需要在rest_api_init动作上调用register_setting()

    add_action( 'admin_init',    'foo_register_settings' );
    add_action( 'rest_api_init', 'foo_register_settings' );
    
    function foo_register_settings() {
    	register_setting(
    		'foo',
    		'foo_my_setting',
    		array(
    			'type'              => 'string',
    			'show_in_rest'      => true,
    			'sanitize_callback' => 'sanitize_text_field',
    		)
    	);
    }
    
  • 贡献者:Suman

    数组设置的示例。如果要在“设置”中保存数组,并在wp-json/wp/v2/settings端点中显示数组设置,则必须注册show_in_rest架构。

    add_action( 'admin_init',    'wpdocs_foo_register_settings' );
    add_action( 'rest_api_init', 'wpdocs_foo_register_settings' );
    function wpdocs_foo_register_settings() {
    	register_setting( 'general_setting', 'id' );
    	register_setting( 'general_setting', 'order' );
    	register_setting(
    		'general_setting',
    		'slider-data',
    		array(
    			'show_in_rest' => array(
    				'name' => 'images_slide',
    				'schema' => array(
    					'type'  => 'array',
    					'items' => array(
    						'id'    => 'string',
    						'order' => 'string',
    					),
    				),
    			),
    			'type' => 'array',
    			'sanitize_callback' => array( $this, 'wpdocs_admin_post_save_data' ),
    		)
    	);
    }
    
  • 贡献者:Cloud Stone

    objectarray类型的示例:

    register_setting(
    	'dp_example_settings_group',
    	'dp_example_array_settings',
    	array(
    		'type'         => 'object',
    		'default'      => array(
    			'A',
    			'B',
    			'C',
    		),
    		'show_in_rest' => array(
    			'schema' => array(
    				'type'  => 'object',
    				'items' => array(
    					'type' => 'string',
    				),
    			),
    		),
    	)
    );
    
    register_setting(
    	'dp_example_settings_group',
    	'dp_example_object_settings',
    	array(
    		'type'         => 'object',
    		'default'      => array(
    			'some_str' => 'A',
    			'some_int' => 3,
    		),
    		'show_in_rest' => array(
    			'schema' => array(
    				'type'       => 'object',
    				'properties' => array(
    					'some_str' => array(
    						'type' => 'string',
    					),
    					'some_int' => array(
    						'type' => 'integer',
    					),
    				),
    			),
    		),
    	)
    );
    
  • 贡献者:kyajfx
    // Registering the field
    function wpdocs_add_option_field_to_general_admin_page() {
    
    	register_setting( 'general', 'Field_Name_To_Add' );
    
    	add_settings_field( 
    		'field_id-to-add', 
    		'Field Name To Display', 
    		'wpdocs_setting_callback_function', //Function to Call
    		'general', 
    		'default', 
    		array( 
    			'id' => 'field_id-to-add', 
    			'option_name' => 'Field_Name_To_Add' 
    		)
    	);
    }
    
    // Adding options to registered field
    add_action( 'admin_menu', 'wpdocs_add_option_field_to_general_admin_page' ); // CallBack Function
    
    function wpdocs_setting_callback_function( $val ) {
    	$id = $val['id'];
    	$option_name = $val['option_name'];
    	?>
    	<input 
    		type="tel" //this can be any HTML input type: date, number, text etc.
    		name="<?php echo esc_attr( $option_name ) ?>"
    		id="<?php echo esc_attr( $id ) ?>" 
    		value="<?php echo esc_attr( get_option( $option_name ) ) ?>" // Displays the value stored in DB
    	/> 
    	<?php
    }