自定义对象

自定义API是面向对象的。有四种主要类型的自定义器对象：面板、剖面、设置和控件。设置将UI元素（控件）与保存在数据库中的设置相关联。节是控件的UI容器，用于改进其组织。面板是节的容器，允许将多个节组合在一起。

每个Customizer对象都由一个PHP类表示，所有对象都由Customize Manager对象管理，WP_自定义管理器.

要添加、删除或修改任何Customizer对象，并访问Customize Manager，请使用customize_reregister（自定义寄存器）挂钩：

函数themeslug_customize_reregister（$wp_customise）{//使用$wp_customize，即wp_customize_Manager对象执行操作。}add_action（'自定义注册'，'主题lug_customize_reregister'）；

Customizer Manager为每个Customize对象类型提供add_、get_和remove_方法；每个方法都使用一个id。get_方法允许在添加控件时直接修改指定的参数。

添加操作（'customize_reregister'，'my_customize_reRegister'）；函数my_customize_reregister（$wp_customise）{$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”，数组('type'=>'theme_mod'，//或'option'“功能”=>“edit_theme_options”，“theme_supports”=>“”，//很少需要。“默认”=>“”，“transport”=>“refresh”，//或postMessage“sanitize_callback”=>“”，“sanitize_js_callback”=>“”，//基本上为_json。) );

有两种主要类型的设置：选项和主题修改。选项直接存储在WordPress数据库的wp_Options表中，并应用于站点，而不考虑活动主题。主题应该很少添加选项类型的设置。另一方面，主题模块是特定于特定主题的。大多数主题选项都应该是theme_mods。例如，自定义CSS插件可以将自定义主题CSS设置注册为theme_mode，允许每个主题都有一组唯一的CSS规则，而不会在切换主题后再切换回来时丢失CSS。

通常最重要的是设置设置的默认值及其清理回调，这将确保数据库中没有存储不安全的数据。典型主题用法：

$wp_customize->add_setting（'accent_color'，数组(“默认”=>“#f72525”，“sanitize_callback”=>“sanitizer_hex_color”，) );

典型插件用法：

$wp_customize->add_setting（“myplugin_options[color]”，数组(“type”=>“option”，“功能”=>“管理选项”，“默认”=>“#ff2525”，“sanitize_callback”=>“sanitizer_hex_color”，) );

请注意，Customizer可以处理存储为键控数组的选项，以便使用选项类型进行设置。这允许多个设置存储在一个不是主题模块的选项中。要检索和使用“自定义设置”选项的值，请使用获取主题模块（）和获取选项（_O）设置id为：

函数my_custom_css_output（）{echo'<style type=“text/css”id=“custom-theme-css”>'。get_theme_mod（'custom_theme_css'，''）。'</样式>'；echo'<style type=“text/css”id=“custom-plugin-css”>'。get_option（'custom_plugin_css'，''）。'</样式>'；}add_action（'wp_head'，'my_custom_css_output'）；

请注意，的第二个参数获取时间模式（）和获取选项（_O）是默认值，应与添加设置时设置的默认值相匹配。

控制

控件是创建UI的主要Customizer对象。具体来说，每个控件都必须与一个设置相关联，该设置将用户输入的数据从控件保存到数据库中（除了在live-preview中显示和清理数据之外）。自定义管理器可以添加控件，并以最小的工作量提供一组健壮的UI选项：

$wp_customize->add_control（“setting_id”，数组(“type”=>“date”，“priority”=>10，//在节内。“section”=>“colors”，//必需，核心或自定义。“标签”=>__（“日期”），“description”=>__（“这是一个带红色边框的日期控件。”），'input_attrs'=>数组(“class”=>“my-custom-class-for-js”，“style”=>“border:1px solid#900”，“占位符”=>__（'mm/dd/yyyy'），),“active_callback”=>“is_front_page”，) );

添加控件时最重要的参数是其类型，这决定了Customizer将显示的UI类型。Core提供了几种内置控件类型：

• <输入>具有任何允许类型的元素（见下文）
• 复选框
• 文本区域
• 收音机（将值=>标签的键控数组传递给选择参数）
• 选择（将值=>标签的键控数组传递给选择论点）
• 下拉页面（使用允许添加（_A）参数允许用户从控件添加新页面）

对于html支持的任何输入类型输入元素，只需在添加控件时将type属性值传递给type参数。这允许支持控件类型，例如文本,隐藏,数,范围,网址,电话,电子邮件,搜索,时间,日期,日期时间、和周，待定的浏览器支持。

控件必须添加到节中才能显示（节中必须包含要显示的控件）。这是通过在添加控件时指定节参数来完成的。下面是添加基本文本区域控件的示例：

$wp_customize->add_control（'custom_theme_css'，数组('label'=>__（'自定义主题CSS'），“type”=>“textarea”，“section”=>“custom_css”，) );

下面是一个基本范围（滑块）控件的示例。请注意，大多数浏览器都不会显示此控件的数值，因为范围输入类型是为精确值不重要的设置而设计的。如果数值很重要，请考虑使用数字类型。这个输入属性参数将attributes=>值的键控数组映射到输入元素上的属性，可以用于从占位符文本到数据-JavaScript在自定义脚本中引用数据。对于数字和范围控件，它允许我们设置最小值、最大值和步长值。

$wp_customize->add_control（“setting_id”，数组('类型'=>'范围'，“section”=>“title_tagline”，“标签”=>__（“范围”），'说明'=>__（'这是范围控制说明。'），“input_atrs”=>数组(“最小值”=>0，“最大值”=>10，“步骤”=>2，),) );

核心自定义控件

如果没有一种基本控件类型适合您的需要，您可以轻松创建和添加自定义控件。自定义控件将在本文后面进行更全面的解释，但它们本质上是基的子类WP_自定义_控制对象，该对象允许您可能需要的任何任意html标记和功能。核心功能是几个内置的自定义控件，允许开发人员轻松实现丰富的JavaScript驱动功能。可以按如下方式添加颜色选择器控件：

$wp_customize->add_control（新的wp_customize_Color_control(“label”=>__（“强调色”，“theme_textdomain”），“节”=>“媒体”，) ) );

WordPress 4.1和4.2还通过Media控件添加了对任何类型多媒体内容的支持。媒体控件实现了原生WordPress媒体管理器，允许用户从其库中选择文件或上传新文件。通过指定mime_type参数添加控件时，可以指示媒体库显示特定类型，如图像或音频：

$wp_customize->add_control（新的wp_customize_Media_control('label'=>__（'特色主页图像'，'theme_textdomain'），“节”=>“媒体”，“mime_type”=>“图像”，) ) );

$wp_customize->add_control（新的wp_customize_Media_control('label'=>_（'特色主页录制'，'theme_textdomain'），“节”=>“媒体”，“mime_type”=>“音频”，) ) );

请注意，与WP_自定义_媒体_控制保存关联的附件ID，而所有其他与媒体相关的控件（WP_自定义上传控制)将媒体文件URL保存到设置。更多信息在Make WordPress Core上提供。

此外，WordPress 4.3引入了WP_自定义_裁剪_图像_控制，它提供了一个在选择图像后裁剪图像的界面。这对于需要特定纵横比的情况很有用。

小节

节是自定义程序控件的UI容器。虽然您可以向核心部分添加自定义控件，但如果您有多个选项，则可能需要添加一个或多个自定义部分。使用添加节（_S）方法WP_自定义管理器对象添加新节：

$wp_customize->add_section（'custom_css'，数组(“title”=>__（“自定义CSS”），“description”=>__（“在此处添加自定义CSS”），“panel”=>“”，//通常不需要。“优先级”=>160，“功能”=>“edit_theme_options”，“theme_supports”=>“”，//很少需要。) );

您只需要包含要覆盖默认值的字段。例如，默认优先级（外观顺序）通常是可以接受的，如果您的选项是自我解释的，则大多数部分都不需要描述性文本。如果您确实想更改自定义节的位置，则核心节的优先级如下：

标题	身份证件	优先级（顺序）
网站标题和标语	标题_标签	20
颜色	颜色	40
标题图像	标题_图像	60
背景图像	背景_图像	80
菜单（面板）	导航菜单（_M）	100
小工具（面板）	小部件	110
静态首页	static_front_page（统计_正面_页面）	120
违约		160
其他CSS	自定义css	200

在大多数情况下，只需指定一个或两个参数即可添加节。下面是一个为与主题页脚相关的选项添加节的示例：

//添加页脚/版权信息部分。$wp_customize->add_section（“页脚”，数组('标题'=>__（'页脚'，'主题名'），“priority”=>105，//在小部件之前。) );

面板

自定义面板API在WordPress 4.0中引入，允许开发人员在控件和节之外创建额外的层次结构层。不仅仅是对控件的部分进行分组，面板的设计还为Customizer提供了不同的上下文，例如Customizing Widgets、Menus，或者在将来编辑文章。节对象和面板对象之间有一个重要的技术区别。

在大多数情况下，主题不应注册自己的面板.节do不需要嵌套在面板下，并且每个部分通常应包含多个控件。还应将控件添加到核心提供的节中，例如将颜色选项添加到颜色节中。还要确保您的选项尽可能精简高效；请参阅WordPress哲学。面板被设计为整个功能（如小工具、菜单或帖子）的上下文，而不是通用部分的包装器。如果您绝对必须使用Panels，您会发现API与Sections的API几乎相同：

$wp_customize->add_panel（“菜单”，数组('标题'=>__（'菜单'），'description'=>$description，//包括html标记，如<p>。“priority”=>160，//与顶级分区层次结构混合。) );$wp_customize->add_section（$section_id，数组(“title”=>$menu->name，“面板”=>“菜单”，) );

面板必须包含至少一个要显示的节，该节必须包含至少1个控件。正如您在上面的示例中看到的那样，可以将“截面”添加到“面板”，类似于将“控件”添加到截面的方式。但是，与控件不同的是，如果在注册“剖面”时“面板”参数为空，则它将显示在主要的顶级“自定义程序”上下文中，因为大多数剖面不应包含在面板中。

自定义控件、节和面板

通过将与每个Customizer对象关联的PHP对象子类化，可以轻松创建自定义控件、节和面板：WP_自定义_控制, WP_自定义_部分、和WP_自定义面板（这也可以用于WP_自定义_设置，但如下一节所述，使用自定义设置类型通常可以更好地实现自定义设置）。下面是一个基本自定义控件的示例：

类WP_New_Menu_Customize_Control扩展了WP_Customise_Control{public$type='new_menu'；/***渲染控件的内容。*/公共函数render_content（）{?><button class=“button button-primary”id=“create-new-menu-submit”tabindex=“0”><？php_e（“创建菜单”）；？></按钮><?php程序}}

通过对基本控件类进行子类化，可以使用自定义功能覆盖任何功能，也可以根据需要使用核心功能。覆盖最常见的功能是render_content（）因为它允许您使用HTML从头开始创建自定义UI。然而，使用自定义控件时应谨慎，因为它们可能会引入与周围核心UI不一致的UI，并给用户造成混淆。添加自定义自定义器对象的方式与添加默认控件、节和面板的方式类似：

$wp_customize->add_control(新WP_Customize_Color_Control($wp_customize，//wp_customize_Manager'accent_color'，//设置id数组（//参数，包括任何自定义参数。“标签”=>__（“强调色”），“section”=>“colors”，)));

添加控件时传递的参数映射到控件类中的类变量，因此您可以在自定义对象的某些部分在不同实例中不同的情况下添加和使用自定义对象。

在创建自定义控件、节或面板时，强烈建议参考核心代码，以便完全理解可以覆盖的可用功能。Core还包括每种类型的自定义对象的示例。这可以在中找到wp-includes/class-wp-customize-control.php,wp-includes/class-wp-customize-section.php、和wp-includes/class-wp-customize-panel.php。每个Customizer对象类型都有一个JavaScript API，可以用自定义对象进行扩展；有关更多详细信息，请参阅Customizer JavaScript API部分。

自定义用户界面标准

自定义自定义程序控件、节和面板应尽可能与核心UI实践相匹配。这包括依赖wp-admin的标准，例如使用.按钮和.按钮-主例如类。还有一些特定于定制程序的标准（从WordPress 4.7开始）：

• 使用白色背景色只有指示导航和可操作项（例如输入）
• 将军#电子电气设备背景色与白色元素形成视觉对比
• 1像素#ddd边框将导航元素与背景边距以及彼此分隔开
• 15像素在需要视觉分隔的元素之间提供间距
• 4像素在导航元素的一侧使用边框来显示悬停或焦点，颜色为#0073aa个
• 自定义文本使用颜色：#555d66，使用#0073aa个用于导航元素的悬停和焦点状态

自定义设置类型

默认情况下，Customizer支持将设置保存为选项或主题修改。但这种行为很容易被覆盖，以便在WordPress数据库的wp_options表之外手动保存和预览设置，或应用其他自定义处理。要开始，请在添加设置时指定option或theme_mod以外的类型（几乎可以使用任何字符串）：

$wp_customize->add_setting（$nav_menu_setting_id，数组('类型'=>'导航菜单'，“default”=>$item_id，) );

当相关控件中的设置值发生更改时，将不再保存或预览该设置。现在，您可以使用customize_update_$设置->类型和customize_preview_$设置->类型实现自定义保存和预览功能的操作。以下是从menu Customizer项目保存菜单项的order属性的示例（该设置的值是菜单ID的有序数组）：

函数菜单customizer_update_nav_menu（$value，$setting）{$menu_id=str_replace（'nav_menu_'，''，$setting->id）；// ...$i=0；foreach（$value作为$itemid）{//$value是项id的有序数组。菜单自定义器更新菜单项顺序（$menu_id，$item_id，$i）；$i++；}}add_action（‘customize_update_nav_menu’，‘menu_customizer_update_nav_menu‘，10，2）；

下面是同一插件如何实现导航菜单项的预览（请注意，此示例需要PHP 5.3或更高版本）：

函数菜单customizer_preview_nav_menu（$setting）{$menu_id=str_replace（'nav_menu_'，''，$setting->id）；add_filter（'wp_get_nav_menu_items'，函数（$items，$menu，$args）use（$menu_id，$setting）{$preview_menu_id=$menu->term_id；if（$menu_id==$preview_menu_id）{$new_id=$setting->post_value（）；foreach（$new_ids作为$item_id）{$item=wp_setup_nav_menu_item（$item）；$item->menu_order=$i；$new_items[]=$item；$i++；}返回$new_items；}其他{返回$items；}}, 10, 3 );}add_action（'customize_preview_nav_menu'，'menu_customizer_preview_nav_menu]，10，2）；