设置

概述

WordPress 2.7中添加的 设置 API允许半自动管理包含设置表单的管理页面。它允许您定义设置页面、这些页面中的部分和部分中的字段。

新的设置页面可以连同其中的部分和字段一起注册。也可以通过在其中注册新的设置部分或字段来添加现有设置页面。

组织字段的注册和验证仍然需要使用设置 API 的开发人员付出一些努力，但可以避免对底层选项管理进行大量复杂的调试。

注意：使用 Settings API 时，提交的表单wp-admin/options.php会提供相当严格的功能检查。用户将需要manage_options能力（在 MultiSite 中必须是超级管理员）才能提交表单。

这些功能位于 wp-admin/includes/plugin.php 和 wp-admin/includes/template.php

功能参考

设置注册/注销：

  • register_setting()
  • unregister_setting()

添加字段/部分：

  • add_settings_field()
  • add_settings_section()

选项表单渲染：

  • settings_fields()
  • do_settings_sections()
  • do_settings_fields()

错误：

  • add_settings_error()
  • get_settings_errors()
  • settings_errors()

添加设置字段

您可以使用此功能将新的设置字段（基本上是wp_options数据库表中的一个选项，但完全由您管理）添加到现有的 WordPress 页面。您的回调函数只需要输出适当的 HTML 输入并用旧值填充它，保存将在幕后完成。add_settings_section() 您可以使用如下所述在现有页面上创建自己的部分 。

注意： 您必须注册您使用的任何选项 add_settings_field() ，否则它们将不会自动保存和更新。有关详细信息和示例，请参见下文。

add_settings_field( $id, $title, $callback, $page, $section = 'default', $args = array() )
  • $id – 用于标签的“id”属性的字符串。
  • $title – 字段标题。
  • $callback – 将所需输入作为较大表单的一部分填充字段的功能。输入的名称和 ID 应与提供给此函数的 $id 相匹配。该函数应回显其输出。
  • $page – 显示字段的设置页面类型（一般、阅读、写作……）。
  • $section – 显示框的设置页面部分（默认或您使用 add_settings_section 添加的部分，查看源中的页面以查看现有的部分。）
  • $args – 传递给回调函数的额外参数

添加设置部分

设置部分是您在具有共享标题的 WordPress 设置页面上看到的设置组。在您的插件中，您可以向现有设置页面添加新部分，而不是创建一个全新的页面。这使您的插件更易于维护，并创建更少的新页面供用户学习。您只需告诉他们更改相关现有页面上的设置即可。

add_settings_section( $id, $title, $callback, $page );
  • $id – 用于标签的“id”属性的字符串。
  • $title – 部分的标题。
  • $callback – 用所需内容填充部分的功能。该函数应回显其输出。
  • $page – 显示部分的设置页面类型（一般、阅读、写作、媒体等）

注册设置

register_setting( $option_group, $option_name, $args );

unregister_setting( $option_group, $option_name );

注意： register_setting() 以及上面提到的 add_settings_*() 函数都应该从动作钩子回调函数中调用 admin_init 。请参阅下面的“示例”部分。

选项表单渲染

使用 API 将设置添加到现有选项页面时，您无需关心表单本身，因为它已经为页面定义了。当您从头开始定义一个新页面时，您需要输出一个最小的表单结构，其中包含一些标签，这些标签又会输出页面的实际部分和设置。

为了显示隐藏字段并处理选项表单的安全性，Settings API 提供了 settings_fields()  函数。settings_fields( $option_group );

**$option_group**（字符串）（必填）：

设置组名称。这必须与中使用的组名相匹配 register_setting()，这是要显示表单的页面名称。默认值： 无

为了显示分配给页面的部分和其中包含的设置，设置 API 提供了 do_settings_sections()  函数。 do_settings_sections( $page );

**$page**（字符串）（必填）：

要输出其设置部分的页面的 slug 名称。这应该与中使用的页面名称相匹配 添加设置部分（）。默认值： 无

这 do_settings_fields()  函数用于输出分配给特定页面和部分的字段。您不应该直接调用此函数，而是用来 do_settings_sections() 输出 Section 内容以及关联的字段。

您的选项表单还需要一个提交按钮。您可以使用 submit_button()  函数来执行此操作。

最后，您需要输出定义 options.php 的操作目标和 POST 方法的 HTML <form> 标记。这是一个示例选项表单代码，用于生成添加到页面的所有部分和字段，该页面的 slug 名称是 my-page

<form method="POST" action="options.php">
<?php 
settings_fields( 'my-page' ); // pass slug name of page, also referred to in Settings API as option group name
do_settings_sections( 'my-page' );  // pass slug name of page
submit_button(); // submit button
?>
</form>

例子

添加一个带有新字段的设置部分

<?php 
/**
 * Add all your sections, fields and settings during admin_init
 */
 
function wporg_settings_api_init() {
 	// Add the section to reading settings so we can add our
 	// fields to it
 	add_settings_section(
		'wporg_setting_section',
		'Example settings section in reading',
		'wporg_setting_section_callback_function',
		'reading'
	);
 	
 	// Add the field with the names and function to use for our new
 	// settings, put it in our new section
 	add_settings_field(
		'wporg_setting_name',
		'Example setting Name',
		'wporg_setting_callback_function',
		'reading',
		'wporg_setting_section'
	);
 	
 	// Register our setting so that $_POST handling is done for us and
 	// our callback function just has to echo the <input>
 	register_setting( 'reading', 'wporg_setting_name' );
 } // wporg_settings_api_init()
 
 add_action( 'admin_init', 'wporg_settings_api_init' );
 
  
/**
 * Settings section callback function
 *
 * This function is needed if we added a new section. This function 
 * will be run at the start of our section
 */
 
 function wporg_setting_section_callback_function() {
 	echo '<p>Intro text for our settings section</p>';
 }
 
/*
 * Callback function for our example setting
 *
 * creates a checkbox true/false option. Other types are surely possible
 */
 
 function wporg_setting_callback_function() {
 	echo '<input name="wporg_setting_name" id="wporg_setting_name" type="checkbox" value="1" class="code" ' . checked( 1, get_option( 'wporg_setting_name' ), false ) . ' /> <label for="wporg_setting_name">Explanation text</label>';
 }

所有这些代码应该放在哪里的图形表示

外部参考

  • WordPress 设置 API， 作者：Konstantin Kovshenin，2012 年 10 月 23 日
  •  Chip Bennett在 WordPress 主题中整合设置 API ，2011 年 2 月
  •  David Gwyer解释的设置 API
  •  Otto 的WordPress 设置 API 教程
  •  使用 Ozh 的register_setting()处理插件选项
  •  BobGneu 的WordPress 设置 API 简介
  • 使用设置 API： 第 1 部分， 第 2 部分 作者：  Sarah Neuber
  •  Francis Yaconiello 的WordPress 基于类的设置
  • 在单个设置屏幕上添加多个部分， 作者：Mathieu Decaffmeyer
  • 在单个设置屏幕上添加多个表单， 作者：Mathieu Decaffmeyer
  •  Tom McFarlin 的WordPress 设置 API 完整指南，2012 年 1 月 31 日
  • WordPress 设置 API 速查表 ，作者：Kenneth Odle，2015 年 7 月 16 日

发电机

  • WordPress 设置 API（选项页面）生成器

PHP类

  • WordPress 设置 API 类