云策 WordPress 开发者社区

函数文档

add_settings_section()

查看官方原文 ↗
💡 云策文档标注

概述

add_settings_section() 是 WordPress Settings API 的一部分，用于在管理设置页面中添加新的设置区域。开发者需在 admin_init 钩子中调用此函数，并通过 do_settings_sections() 显示区域，使用 add_settings_field() 添加字段。

关键要点

  • 函数属于 Settings API，用于定义管理页面的设置区域。
  • 参数包括 $id（区域标识）、$title（区域标题）、$callback（回调函数）、$page（设置页面标识）和可选的 $args（自定义参数）。
  • 回调函数用于在区域顶部输出内容，可接收包含 id、title 和 callback 的数组参数。
  • 内置设置页面包括 'general'、'reading' 等，也可通过 add_options_page() 创建自定义页面。
  • 从 WordPress 6.1.0 开始，$args 参数支持 before_section、after_section 和 section_class 以自定义 HTML 包装。
  • 注意：$page 参数应为 add_settings_field() 和 do_settings_sections() 使用的标识符，不一定是通过 add_submenu_page() 创建的页面。

代码示例

add_settings_section(
    'eg_setting_section',
    'Example settings section in reading',
    'eg_setting_section_callback_function',
    'reading'
);
function eg_setting_section_callback_function( $arg ) {
    echo 'id: ' . $arg['id'] . '';
    echo 'title: ' . $arg['title'] . '';
    echo 'callback: ' . $arg['callback'] . '';
}

注意事项

  • 在 WordPress 3.0.0 和 3.5.0 中，'misc' 和 'privacy' 页面已被弃用，分别重定向到 'general' 和 'reading'。
  • 回调函数和标题参数可设为 null 以简化流程，不会引发错误。
  • 使用 $args 参数时，必须通过 do_settings_sections() 显示区域，否则参数无效。
📄 原文内容

Adds a new section to a settings page.

Description

Part of the Settings API. Use this to define new settings sections for an admin page.
Show settings sections in your admin page callback function with do_settings_sections() .
Add settings fields to your section with add_settings_field() .

The $callback argument should be the name of a function that echoes out any content you want to show at the top of the settings section before the actual fields. It can output nothing if you want.

Parameters

$idstringrequired
Slug-name to identify the section. Used in the 'id' attribute of tags.
$titlestringrequired
Formatted title of the section. Shown as the heading for the section.
$callbackcallablerequired
Function that echos out any content at the top of the section (between heading and fields).
$pagestringrequired
The slug-name of the settings page on which to show the section. Built-in pages include 'general', 'reading', 'writing', 'discussion', 'media', etc. Create your own using add_options_page() ;
$argsarrayoptional
Arguments used to create the settings section.

  • before_section string
    HTML content to prepend to the section’s HTML output.
    Receives the section’s class name as %s.
  • after_section string
    HTML content to append to the section’s HTML output.
  • section_class string
    The class name to use for the section.

Default:array()

More Information

The callback function receives a single optional argument, which is an array with three elements. Example:

add_settings_section(
'eg_setting_section',
'Example settings section in reading',
'eg_setting_section_callback_function',
'reading'
);
function eg_setting_section_callback_function( $arg ) {
// echo section intro text here
echo '<p>id: ' . $arg['id'] . '</p>';             // id: eg_setting_section
echo '<p>title: ' . $arg['title'] . '</p>';       // title: Example settings section in reading
echo '<p>callback: ' . $arg['callback'] . '</p>'; // callback: eg_setting_section_callback_function
}

Source

function add_settings_section( $id, $title, $callback, $page, $args = array() ) {
	global $wp_settings_sections;

	$defaults = array(
		'id'             => $id,
		'title'          => $title,
		'callback'       => $callback,
		'before_section' => '',
		'after_section'  => '',
		'section_class'  => '',
	);

	$section = wp_parse_args( $args, $defaults );

	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_sections[ $page ][ $id ] = $section;
}

View all references View on Trac View on GitHub

Uses Description
__()wp-includes/l10n.php

Retrieves the translation of $text.
_deprecated_argument()wp-includes/functions.php

Marks a function argument as deprecated and inform when it has been used.
wp_parse_args()wp-includes/functions.php

Merges user defined arguments into defaults array.

Show 1 moreShow less

Changelog

Version Description
6.1.0 Added an $args parameter for the section’s HTML wrapper and class name.
2.7.0 Introduced.

User Contributed Notes

  1. Skip to note 6 content


    Navarro


    You must log in to vote on the helpfulness of this noteVote results for this note: 6You must log in to vote on the helpfulness of this note

    Description of $page parameter may be misleading. It can be interpreted as if needs to be the slug name of the admin page created through add_submenu_page() or one of its wrappers (such as add_theme_page() or add_plugins_page()). Instead, it only needs to be a slug-formatted name used by add_settings_field() and do_settings_sections().

  2. Skip to note 7 content


    Ivan Shulev


    You must log in to vote on the helpfulness of this noteVote results for this note: 5You must log in to vote on the helpfulness of this note

    Example usage
    The callback function receives a single optional argument, which is an array with three elements.

    add_settings_section(
	'eg_setting_section',
	__( 'Example settings section in reading', 'textdomain' ),
	'wpdocs_setting_section_callback_function',
	'reading'
);

/**
 * Settings section display callback.
 *
 * @param array $args Display arguments.
 */ 
function wpdocs_setting_section_callback_function( $args ) {
	// echo section intro text here
	echo '<p>id: ' . esc_html( $args['id'] ) . '</p>';                         // id: eg_setting_section
	echo '<p>title: ' . apply_filters( 'the_title', $args['title'] ) . '</p>'; // title: Example settings section in reading
	echo '<p>callback: ' . esc_html( $args['callback'] ) . '</p>';             // callback: eg_setting_section_callback_function
}

  3. Skip to note 8 content


    Dhaval Kasavala


    You must log in to vote on the helpfulness of this noteVote results for this note: 4You must log in to vote on the helpfulness of this note

    Example add_settings_section with php class 

    class custom_setting {

	function __construct() {
		/**
		 * register wp_setting_init to the admin_init action hook
		 */
		add_action('admin_init', array($this,'wp_setting_init'));		
	}

	function wp_setting_init() {
	    // register a new setting for "reading" page
	    register_setting('reading', 'page_limit');
	 
	    // register a new section in the "reading" page
	    add_settings_section(
	        'wp_custom_setting_section',
	        'WP Custom Setting Section',
	        array($this,'wp_custom_setting_section_cb'),
	        'reading'
	    );
	}
	 
	/**
	 * callback functions
	 */
	 
	// section content cb
	function wp_custom_setting_section_cb() {
	    esc_html_e('Page limit is 10','text-domain');
	}
 
}

new custom_setting();