云策 WordPress 开发者社区

函数文档

do_settings_fields()

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

概述

do_settings_fields() 是 WordPress Settings API 的一部分，用于在设置页面输出特定设置节的字段。通常由 do_settings_sections() 调用，而非直接使用。

关键要点

  • 函数属于 Settings API，用于渲染设置字段。
  • 接受两个必需参数：$page（管理页面 slug）和 $section（设置节 slug）。
  • 内部遍历 $wp_settings_fields 全局变量，调用每个字段的回调函数。
  • 支持通过 $field['args']['class'] 添加 CSS 类，以及 $field['args']['label_for'] 处理标签。

代码示例

if ($_GET['action'] !== 'test') {
  settings_fields('stripe_payment_settings');
  echo '<table class="form-table">';
  do_settings_fields('stripe-payment', 'stripe_payment_settings_section');
  echo '</table>';
} else {
  settings_fields('stripe_payment_test');
  echo '<table class="form-table">';
  do_settings_fields('stripe-payment', 'stripe_payment_test_section');
  echo '</table>';
}

注意事项

  • 通常通过 do_settings_sections() 间接调用，以确保正确输出整个设置页面。
  • 使用时需确保 $page 和 $section 参数与注册的设置匹配，否则函数可能无输出。
  • 在自定义设置页面中，可结合条件逻辑（如 URL 参数）动态加载不同节。
📄 原文内容

Prints out the settings fields for a particular settings section.

Description

Part of the Settings API. Use this in a settings page to output a specific section. Should normally be called by do_settings_sections() rather than directly.

Parameters

$pagestringrequired
Slug title of the admin page whose settings fields you want to show.
$sectionstringrequired
Slug title of the settings section whose fields you want to show.

Source

function do_settings_fields( $page, $section ) {
	global $wp_settings_fields;

	if ( ! isset( $wp_settings_fields[ $page ][ $section ] ) ) {
		return;
	}

	foreach ( (array) $wp_settings_fields[ $page ][ $section ] as $field ) {
		$class = '';

		if ( ! empty( $field['args']['class'] ) ) {
			$class = ' class="' . esc_attr( $field['args']['class'] ) . '"';
		}

		echo "<tr{$class}>";

		if ( ! empty( $field['args']['label_for'] ) ) {
			echo '<th scope="row"><label for="' . esc_attr( $field['args']['label_for'] ) . '">' . $field['title'] . '</label></th>';
		} else {
			echo '<th scope="row">' . $field['title'] . '</th>';
		}

		echo '<td>';
		call_user_func( $field['callback'], $field['args'] );
		echo '</td>';
		echo '</tr>';
	}
}

View all references View on Trac View on GitHub

Uses Description
esc_attr()wp-includes/formatting.php

Escaping for HTML attributes.
Used by Description
do_settings_sections()wp-admin/includes/template.php

Prints out all settings sections added to a particular settings page.

Changelog

Version Description
2.7.0 Introduced.

User Contributed Notes

  1. Skip to note 2 content


    Khoi Pro


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

    To load multiple tabs in custom page settings, you will need to use this function.

    For example, if I wish to have these settings pages:

    • /options-general.php?page=stripe-payment – Default page
    • /options-general.php?page=stripe-payment&action;=test – Test page

    So you must have two different sections and call it like:

    if ($_GET['action'] !== 'test') {
  settings_fields('stripe_payment_settings');
  echo '<table class="form-table">'; // Must to add this wrapper to keep it like WordPress default UI
  do_settings_fields('stripe-payment, 'stripe_payment_settings_section');
  echo '</table>';
} else {
  settings_fields('stripe_payment_test');
  echo '<table class="form-table">';
  do_settings_fields('stripe-payment, 'stripe_payment_test_section');
  echo '</table>';
}