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

使用示例

• 示例1

  关于$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' 元素就足够了。其他的都会被忽略。

• 示例2

  /**
  * 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' );
  

• 示例3

  基本示例

  /**
   * 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' );
  

• 示例4

  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.
  }

• 示例5

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

• 示例6

  如果希望设置显示在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',
  		)
  	);
  }
  

• 示例7

  数组设置的示例。如果要在“设置”中保存数组，并在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' ),
  		)
  	);
  }
  

• 示例8

  object和array类型的示例：

  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',
  					),
  				),
  			),
  		),
  	)
  );
  

• 示例9

  // 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
  }