自定义API是面向对象的。定制对象有四种主要类型：面板，部分，设置和控件。设置关联UI元素（控件）与保存在数据库中的设置。部分是用于控制组织的UI容器。面板是部分的容器，可以将多个部分分组在一起。
每个定制对象由PHP类表示，所有对象均由自定义Manager对象管理，wp_customize_manager。
要添加，删除或修改任何自定义对象并访问自定义器管理器，请使用customize_register钩：
function themeslug_customize_register( $wp_customize ) {
// Do stuff with $wp_customize, the WP_Customize_Manager object.
}
add_action( 'customize_register', 'themeslug_customize_register' );Customizer Manager为每个定制器对象类型提供add_，get_和Remove_方法；每个都可以使用一个ID。GET_方法允许在添加控件时直接修改指定的参数。
add_action('customize_register','my_customize_register');
function my_customize_register( $wp_customize ) {
$wp_customize->add_panel();
$wp_customize->get_panel();
$wp_customize->remove_panel();
$wp_customize->add_section();
$wp_customize->get_section();
$wp_customize->remove_section();
$wp_customize->add_setting();
$wp_customize->get_setting();
$wp_customize->remove_setting();
$wp_customize->add_control();
$wp_customize->get_control();
$wp_customize->remove_control();
}注意：主题通常不应使用GET方法修改核心部分和面板，因为主题不应修改核心，主题不可能的功能。鼓励插件在必要时使用这些功能。主题不应“重新组织”主题添加的定制部分。
设置
设置处理定制对象的实时浏览，保存和消毒。每个设置都由控制对象管理。添加新设置时，有几个参数可用：
$wp_customize->add_setting( 'setting_id', array(
'type' => 'theme_mod', // or 'option'
'capability' => 'edit_theme_options',
'theme_supports' => '', // Rarely needed.
'default' => '',
'transport' => 'refresh', // or postMessage
'sanitize_callback' => '',
'sanitize_js_callback' => '', // Basically to_json.
) );widget_*，sidebars_widgets[*]，nav_menu[*]，或者nav_menu_item[*]。这些设置ID模式分别保留用于小部件实例，侧边栏，导航菜单和导航菜单项。如果您需要在设置ID中使用“小部件”，请将其用作后缀代替前缀，例如“homepage_widget”。设置有两种主要类型：选项和主题修改。选项直接存储在WordPress数据库的WP_Options表中，并应用于网站，无论活动主题如何。如果添加选项类型的设置，则很少会主题。另一方面，主题mod是特定主题的特定于特定主题的。大多数主题选项应该是them_mods。例如，自定义CSS插件可以将自定义主题CSS设置注册为theme_mod，允许每个主题具有独特的CSS规则集，而不会在切换主题然后切换后丢失CSS而不会丢失CSS。
通常最重要的是设置设置的默认值及其消毒回调，这将确保在数据库中不存储不安全的数据。典型的主题用法：
$wp_customize->add_setting( 'accent_color', array(
'default' => '#f72525',
'sanitize_callback' => 'sanitize_hex_color',
) );典型的插件用法：
$wp_customize->add_setting( 'myplugin_options[color]', array(
'type' => 'option',
'capability' => 'manage_options',
'default' => '#ff2525',
'sanitize_callback' => 'sanitize_hex_color',
) );请注意，自定义器可以使用选项类型处理存储的选项作为钥匙数组，以进行设置。这允许多个设置存储在不是主题模块的单个选项中。要检索和使用定制器选项的值，请使用get_theme_mod()和get_option()使用设置ID：
function my_custom_css_output() {
echo '<style type="text/css" id="custom-theme-css">' .
get_theme_mod( 'custom_theme_css', '' ) . '</style>';
echo '<style type="text/css" id="custom-plugin-css">' .
get_option( 'custom_plugin_css', '' ) . '</style>';
}
add_action( 'wp_head', 'my_custom_css_output');请注意，第二个论点get_theme_mod()和get_option()是默认值，在添加设置时应匹配您设置的默认值。
控件
控件是用于创建UI的主要定制对象。具体而言，每个控件都必须与设置关联，并且设置将将以用户输入的数据从控件中保存到数据库（除了在实时浏览中显示并对其进行清理）。Customizer Manager可以添加控件，并以最少的精力提供一组强大的UI选项：
$wp_customize->add_control( 'setting_id', array(
'type' => 'date',
'priority' => 10, // Within the section.
'section' => 'colors', // Required, core or custom.
'label' => __( 'Date' ),
'description' => __( 'This is a date control with a red border.' ),
'input_attrs' => array(
'class' => 'my-custom-class-for-js',
'style' => 'border: 1px solid #900',
'placeholder' => __( 'mm/dd/yyyy' ),
),
'active_callback' => 'is_front_page',
) );添加控件时最重要的参数是其类型 – 这确定了定制器将显示哪种类型的UI。Core提供了几种内置控制类型：
<input>具有任何允许类型的元素（见下文）checkboxtextarearadio（将值的键数=>标签传递给choices争论）select（将值的键数=>标签传递给choices争论）dropdown-pages（使用allow_addition参数允许用户从控件中添加新页面）
对于HTML支持的任何输入类型input元素，在添加控件时只需将类型属性值传递给类型参数即可。这允许支持控制类型，例如text，hidden，number，range，url，tel，email，search，time，date，datetime，和week，等待浏览器支持。
必须将控件添加到一个部分，然后再显示它们（并且部分必须包含要显示的控件）。这是通过在添加控件时指定截面参数来完成的。这是添加基本Textarea控件的示例：
$wp_customize->add_control( 'custom_theme_css', array(
'label' => __( 'Custom Theme CSS' ),
'type' => 'textarea',
'section' => 'custom_css',
) );这是基本范围（滑块）控件的示例。请注意，大多数浏览器不会显示此控件的数值，因为范围输入类型是为确切值不重要的设置而设计的。如果数字值很重要，请考虑使用数字类型。这input_attrs参数将映射属性的键数=>值将属性映射到输入元素上的属性，可用于从占位符文本到data-自定义脚本中的JavaScript引用数据。对于数字和范围控件，它允许我们设置最小，最大和步骤值。
$wp_customize->add_control( 'setting_id', array(
'type' => 'range',
'section' => 'title_tagline',
'label' => __( 'Range' ),
'description' => __( 'This is the range control description.' ),
'input_attrs' => array(
'min' => 0,
'max' => 10,
'step' => 2,
),
) );核心自定义控件
如果基本控制类型都不适合您的需求，则可以轻松创建和添加自定义控件。在本文的稍后，更充分地说明了自定义控件，但它们本质上是基础的子类WP_Customize_Control允许您可能需要的任何任意HTML标记和功能的对象。Core具有多种内置自定义控件，使开发人员可以轻松实现富JavaScript驱动的功能。可以添加彩色选择器控件如下：
$wp_customize->add_control( new WP_Customize_Color_Control( $wp_customize, 'color_control', array(
'label' => __( 'Accent Color', 'theme_textdomain' ),
'section' => 'media',
) ) );WordPress 4.1和4.2还增加了对任何类型的多媒体内容以及具有媒体控制的任何类型的支持。媒体控件实现了本机WordPress媒体管理器，允许用户从其库中选择文件或上传新文件。通过指定mime_type添加控件时，您可以指示媒体库显示为特定类型，例如图像或音频：
$wp_customize->add_control( new WP_Customize_Media_Control( $wp_customize, 'image_control', array(
'label' => __( 'Featured Home Page Image', 'theme_textdomain' ),
'section' => 'media',
'mime_type' => 'image',
) ) );$wp_customize->add_control( new WP_Customize_Media_Control( $wp_customize, 'audio_control', array(
'label' => _( 'Featured Home Page Recording', 'theme_textdomain' ),
'section' => 'media',
'mime_type' => 'audio',
) ) );请注意，设置与WP_Customize_Media_Control 保存关联的附件ID，而所有其他与媒体相关的控件（儿童WP_Customize_Upload_Control）将媒体文件URL保存到设置。 更多信息 可在Make WordPress Core上使用。
此外，WordPress 4.3引入了WP_Customize_Cropped_Image_Control，它提供了一个用于在选择图像后裁剪图像的接口。这对于需要特定纵横比的实例很有用。
部分
部分是用于定制器控件的UI容器。虽然您可以在核心部分添加自定义控件，但是如果您有多个选项，则可能需要添加一个或多个自定义部分。使用add_section方法的方法 wp_customize_manager 添加新部分的对象：
$wp_customize->add_section( 'custom_css', array(
'title' => __( 'Custom CSS' ),
'description' => __( 'Add custom CSS here' ),
'panel' => '', // Not typically needed.
'priority' => 160,
'capability' => 'edit_theme_options',
'theme_supports' => '', // Rarely needed.
) );您只需要包括要覆盖默认值的字段。例如，通常可以接受默认优先级（外观顺序），如果您的选项是自称的，则大多数部分不需要描述性文本。如果您确实想更改自定义部分的位置，则核心部分的优先级如下：
| 标题 | ID | 优先级（订单） |
| 网站标题和标语 | title_tagline | 20 |
| 颜色 | 颜色 | 40 |
| 标题图像 | header_image | 60 |
| 背景图 | 背景图 | 80 |
| 菜单（面板） | nav_menus | 100 |
| 小部件（面板） | 小部件 | 110 |
| 静态头版 | static_front_page | 120 |
| 默认 | 160 | |
| 其他CSS | custom_css | 200 |
在大多数情况下，只需指定一个或两个参数，就可以添加部分。这是添加与主题页脚有关的选项的示例：
// Add a footer/copyright information section.
$wp_customize->add_section( 'footer' , array(
'title' => __( 'Footer', 'themename' ),
'priority' => 105, // Before Widgets.
) );面板
自定义面板API是在WordPress 4.0中引入的，并允许开发人员创建超出控件和部分的层次结构层。面板不仅简单地分组控件的各个部分，还旨在为定制器提供不同的上下文，例如定制小部件，菜单或将来的编辑帖子。截面对象和面板对象之间存在重要的技术区别。
在大多数情况下，主题不应注册自己的面板。节确实如此不是需要嵌套在面板下，每个部分通常应包含多个控件。还应将控件添加到Core提供的各节中，例如在颜色部分添加颜色选项。还要确保您的选择尽可能流线和高效；看到 WordPress哲学。面板被设计为用于整个功能的上下文，例如小部件，菜单或帖子，而不是作为通用部分的包装器。如果您绝对必须使用面板，则会发现API与该部分几乎相同：
$wp_customize->add_panel( 'menus', array(
'title' => __( 'Menus' ),
'description' => $description, // Include html tags such as <p>.
'priority' => 160, // Mixed with top-level-section hierarchy.
) );
$wp_customize->add_section( $section_id , array(
'title' => $menu->name,
'panel' => 'menus',
) );面板必须至少包含一个部分，必须包含至少一个控件，以显示。如以上示例所示，可以将部分添加到面板中，类似于如何将控件添加到部分中。但是，与控件不同，如果面板参数在注册部分时为空，则将显示在主级别的自定义器上下文上，因为大多数部分不应包含面板。
自定义控件，部分和面板
自定义控件，部分和面板可以通过将与每个Customizer对象关联的PHP对象进行亚键来轻松创建：WP_Customize_Control，WP_Customize_Section，和WP_Customize_Panel（这也可以为WP_Customize_Setting，但是通常使用自定义设置类型更好地实现自定义设置，如下一部分中所述）。这是一个基本自定义控件的示例：
class WP_New_Menu_Customize_Control extends WP_Customize_Control {
public $type = 'new_menu';
/**
* Render the control's content.
*/
public function render_content() {
?>
<button class="button button-primary" id="create-new-menu-submit" tabindex="0"><?php _e( 'Create Menu' ); ?></button>
<?php
}
}通过划分基本控制类，您可以通过自定义功能覆盖任何功能，也可以根据您的需求使用核心功能。覆盖最常见的功能是render_content()因为它允许您使用HTML从头开始创建自定义UI。但是，应谨慎使用自定义控件，因为它们可能会引入与周围核心UI不一致的UI并引起用户混乱。可以添加自定义自定义对象，类似于默认控件，部分和面板的添加：
$wp_customize->add_control(
new WP_Customize_Color_Control(
$wp_customize, // WP_Customize_Manager
'accent_color', // Setting id
array( // Args, including any custom ones.
'label' => __( 'Accent Color' ),
'section' => 'colors',
)
)
);当添加控件映射到控制类中的类变量时传递的参数，因此您可以在不同实例中添加和使用自定义对象的某些部分不同的自定义。
在创建自定义控件，部分或面板时，强烈建议参考核心代码，以充分了解可以覆盖的可用功能。核心还包括每种类型的自定义对象的示例。这可以在 wp-rudes/class-wp-customize-control.php，wp-rudes/class-wp-customize section.php，和 wp-rudes/class-wp-customize-panel.php。每个定制器对象类型也有一个JavaScript API，可以使用自定义对象扩展；有关更多详细信息，请参见“ Customizer JavaScript API”部分。
定制UI标准
自定义定制器控件，部分和面板应尽可能匹配核心UI实践。这包括依靠WP-Admin的标准，例如使用.button和.button-primary例如，类。定制器也有一些特定的标准（从WordPress 4.7开始）：
- 使用白色背景颜色仅有的指示导航和可操作的项目（例如输入）
- 一般
#eee背景颜色提供了与白色元素的视觉对比度 1px #ddd边界将导航元素与背景边缘分开15px在需要视觉分离的元素之间提供了间距4px边界在导航元件的一侧使用，以显示悬停或焦点，颜色的颜色#0073aa- 定制文本使用
color: #555d66，和#0073aa悬停和重点是导航元素
自定义设置类型
默认情况下，定制器支持将设置作为选项或主题修改。但是，可以轻松地覆盖此行为，以手动保存和预览WordPress数据库WP_OPTIONS之外的设置，或应用其他自定义处理。要开始，请在添加设置时指定选项或theme_mod以外的其他类型（您几乎可以使用任何字符串）：
$wp_customize->add_setting( $nav_menu_setting_id, array(
'type' => 'nav_menu',
'default' => $item_ids,
) );在关联控件中更改其值时，将不再保存或预览设置。现在，您可以使用customize_update_$setting->type 和 customize_preview_$setting->type实现自定义保存和预览功能的动作。这是一个从菜单自定义器项目中保存菜单项的订单属性的示例（设置的值是菜单ID的有序数组）：
function menu_customizer_update_nav_menu( $value, $setting ) {
$menu_id = str_replace( 'nav_menu_', '', $setting->id );
// ...
$i = 0;
foreach( $value as $item_id ) { // $value is ordered array of item ids.
menu_customizer_update_menu_item_order( $menu_id, $item_id, $i );
$i++;
}
}
add_action( 'customize_update_nav_menu', 'menu_customizer_update_nav_menu', 10, 2 );这是同一插件为导航菜单项实施预览的方式（请注意，此示例需要PHP 5.3或更高）：
function menu_customizer_preview_nav_menu( $setting ) {
$menu_id = str_replace( 'nav_menu_', '', $setting->id );
add_filter( 'wp_get_nav_menu_items', function( $items, $menu, $args ) use ( $menu_id, $setting ) {
$preview_menu_id = $menu->term_id;
if ( $menu_id == $preview_menu_id ) {
$new_ids = $setting->post_value();
foreach ( $new_ids as $item_id ) {
$item = wp_setup_nav_menu_item( $item );
$item->menu_order = $i;
$new_items[] = $item;
$i++;
}
return $new_items;
} else {
return $items;
}
}, 10, 3 );
}
add_action( 'customize_preview_nav_menu', 'menu_customizer_preview_nav_menu', 10, 2 );