register_setting()
最后更新于:2021-11-27 21:37:20
register_setting( string$option_group, string$option_name, array$args=array())Registers a setting and its data.
参数
- $option_group
-
(string) (Required) A settings group name. Should correspond to an allowed option key name. Default allowed option key names include ‘general’, ‘discussion’, ‘media’, ‘reading’, ‘writing’, ‘misc’, ‘options’, and ‘privacy’.
- $option_name
-
(string) (Required) The name of an option to sanitize and save.
- $args
-
(array) (Optional) Data used to describe the setting when registered.
-
‘type’
(string) The type of data associated with this setting. Valid values are ‘string’, ‘boolean’, ‘integer’, ‘number’, ‘array’, and ‘object’. -
‘description’
(string) A description of the data attached to this setting. -
‘sanitize_callback’
(callable) A callback function that sanitizes the option’s value. -
‘show_in_rest’
(bool|array) Whether data associated with this setting should be included in the REST API. When registering complex settings, this argument may optionally be an array with a ‘schema’ key. -
‘default’
(mixed) Default value when callingget_option()
.
Default value: array()
-
‘type’
源文件
文件: gc-includes/option.php
function register_setting( $option_group, $option_name, $args = array() ) {
global $new_allowed_options, $gc_registered_settings;
/*
* In 5.5.0, the `$new_whitelist_options` global variable was renamed to `$new_allowed_options`.
* Please consider writing more inclusive code.
*/
$GLOBALS['new_whitelist_options'] = &$new_allowed_options;
$defaults = array(
'type' => 'string',
'group' => $option_group,
'description' => '',
'sanitize_callback' => null,
'show_in_rest' => false,
);
// Back-compat: old sanitize callback is added.
if ( is_callable( $args ) ) {
$args = array(
'sanitize_callback' => $args,
);
}
/**
* Filters the registration arguments when registering a setting.
*
* @since 4.7.0
*
* @param array $args Array of setting registration arguments.
* @param array $defaults Array of default arguments.
* @param string $option_group Setting group.
* @param string $option_name Setting name.
*/
$args = apply_filters( 'register_setting_args', $args, $defaults, $option_group, $option_name );
$args = gc_parse_args( $args, $defaults );
// Require an item schema when registering settings with an array type.
if ( false !== $args['show_in_rest'] && 'array' === $args['type'] && ( ! is_array( $args['show_in_rest'] ) || ! isset( $args['show_in_rest']['schema']['items'] ) ) ) {
_doing_it_wrong( __FUNCTION__, __( 'When registering an "array" setting to show in the REST API, you must specify the schema for each array item in "show_in_rest.schema.items".' ), '5.4.0' );
}
if ( ! is_array( $gc_registered_settings ) ) {
$gc_registered_settings = array();
}
if ( 'misc' === $option_group ) {
_deprecated_argument(
__FUNCTION__,
'3.0.0',
sprintf(
/* translators: %s: misc */
__( 'The "%s" options group has been removed. Use another settings group.' ),
'misc'
)
);
$option_group = 'general';
}
if ( 'privacy' === $option_group ) {
_deprecated_argument(
__FUNCTION__,
'3.5.0',
sprintf(
/* translators: %s: privacy */
__( 'The "%s" options group has been removed. Use another settings group.' ),
'privacy'
)
);
$option_group = 'reading';
}
$new_allowed_options[ $option_group ][] = $option_name;
if ( ! empty( $args['sanitize_callback'] ) ) {
add_filter( "sanitize_option_{$option_name}", $args['sanitize_callback'] );
}
if ( array_key_exists( 'default', $args ) ) {
add_filter( "default_option_{$option_name}", 'filter_default_option', 10, 3 );
}
/**
* Fires immediately before the setting is registered but after its filters are in place.
*
* @since 5.5.0
*
* @param string $option_group Setting group.
* @param string $option_name Setting name.
* @param array $args Array of setting registration arguments.
*/
do_action( 'register_setting', $option_group, $option_name, $args );
$gc_registered_settings[ $option_name ] = $args;
}
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', ) ); }
const PLUGIN_SLUG = 'MyPlugin'; /* * Setup Plug-In Hooks (Namespaced Example) */ add_action( 'gc_loaded', __NAMESPACE__.'on_gc_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.gechiui.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. }
add_action( 'admin_init', 'gcdocs_foo_register_settings' ); add_action( 'rest_api_init', 'gcdocs_foo_register_settings' ); function gcdocs_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, 'gcdocs_admin_post_save_data' ), ) ); }
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', ), ), ), ), ) );