WordPress自定义控件
Posted
tags:
中文标题：WordPress自定义控件 原文标题：WordPress Customizer Custom Controls 项目评级：Star:372 Fork:120 下载地址：https://github.com/maddisondesigns/customizer-custom-controls 详情介绍自定义程序自定义控件
作者：Anthony Hortin
作者URI:https://maddisondesigns.com
许可证：GNU通用公共许可证v2或更高版本
许可证URI:http://www.gnu.org/licenses/gpl-2.0.html
版本：1.2.2
描述
Customizer内置了几种不同类型的基本核心控件，可以直接使用。其中包括文本、复选框、文本区域、单选、选择和下拉页面控件。WordPress的后期版本还引入了颜色、媒体、图像和裁剪图像控件。如果没有一个基本的核心控件适合您的需要，您可以创建和添加自己的自定义控件。
此示例代码显示如何将Customizer功能合并到主题（或插件）中，包括如何创建面板、分区以及如何更新Live Preview窗口的示例。除了显示（内置）核心控件的用法外，还有许多已经构建的自定义控件，欢迎您使用。
customizer.php中的示例代码将在自定义程序中创建一个名为Header & Navigation的新面板，该面板包含三个部分（Social Icons、Contact和Search）。它还创建了两个新的Section。其中一个名为Sample Custom Controls，其中包含我创建的所有自定义控件的示例。另一个新的部分，Default Controls，包含了WordPress附带的所有核心控件的示例。
如果你想了解更多关于Customizer开发的信息，请查看我的《Customizer Developers Guide》：
WordPress自定义程序-开发者指南（第1部分）
WordPress自定义程序-开发者指南（第2部分）
您可以通过以下链接下载一个示例主题和插件，展示如何实现这些控件。不过请注意，由于示例主题和示例插件都使用相同的Customizer Controls代码，因此不要试图在激活示例主题的同一网站上激活示例插件。这将导致一个错误，因为您将尝试安装具有相同名称的类，因为它们都使用相同的代码库：
https://github.com/maddisondesigns/Customizer-Custom-Controls-Sample-Theme
https://github.com/maddisondesigns/Customizer-Custom-Controls-Sample-Plugin
核心控制
输入控件（文本、电子邮件、URL、数字、隐藏、日期）
复选框控件
选择控件
无线电控制
下拉页面控件
文本区域控件
色彩管理
媒体控制
图像控制
裁剪图像控件
日期时间控制（WP 4.9+）
自定义控件
此代码包括以下自定义控件：
切换开关
滑块
可分拣中继器
图像单选按钮
文本单选按钮
图像复选框
单手风琴
简单通知
下拉选择2
下拉式帖子
TinyMCE编辑器
谷歌字体选择
Alpha颜色
WPColorPicker Alpha颜色
可排序药丸复选框自定义控件
Upsell部分
切换开关
切换开关自定义控件基本上只是一种花哨的复选框类型。它允许两种状态，关闭或打开。
用法
add_control（$id，$args）；
参数
$id-（字符串）（必需）自定义控件对象或与此控件关联的设置的id。默认值：无
$args-（数组）（可选）包含设置参数的关联数组。默认值：空数组
$args的参数
标签-可选。将显示的标签。默认值：空白
第节-必填项。应出现控制的部分
实例
$wp_customize->add_setting( 'sample_toggle_switch',
array(
'default' => 0,
'transport' => 'refresh',
'sanitize_callback' => 'skyrocket_switch_sanitization'
)
);
$wp_customize->add_control( new Skyrocket_Toggle_Switch_Custom_control( $wp_customize, 'sample_toggle_switch',
array(
'label' => esc_html__( 'Toggle switch' ),
'section' => 'sample_custom_controls_section'
)
) );
滑块
使用“滑块自定义控件”可以在水平条上拖动控制柄以增加或减少数值。控件还有一个重置按钮，允许您将值重置回默认值。随附的输入字段向您显示滑块的值，同时还可以手动输入值。
您可以指定滑块的最小值和最大值以及步长，步长是最小值与最大值之间每个间隔的大小。
用法
add_control（$id，$args）；
参数
$id-（字符串）（必需）自定义控件对象或与此控件关联的设置的id。默认值：无
$args-（数组）（可选）包含设置参数的关联数组。默认值：空数组
$args的参数
标签-可选。将显示的标签默认值：空白
第节-必填项。应出现控制的部分
input_attrs-必需。控件输出的自定义输入属性列表。
最小值-必需。滑块的最小值
max-必需。滑块的最大值
步骤-必需。的大小
滑块在最小值和最大值之间的每个间隔或步长
实例
$wp_customize->add_setting( 'sample_slider_control',
array(
'default' => 48,
'transport' => 'postMessage',
'sanitize_callback' => 'skyrocket_sanitize_integer'
)
);
$wp_customize->add_control( new Skyrocket_Slider_Custom_Control( $wp_customize, 'sample_slider_control',
array(
'label' => esc_html__( 'Slider Control (px)' ),
'section' => 'sample_custom_controls_section',
'input_attrs' => array(
'min' => 10, // Required. Minimum value for the slider
'max' => 90, // Required. Maximum value for the slider
'step' => 1, // Required. The size of each interval or step the slider takes between the minimum and maximum values
),
)
) );
可分拣中继器
可排序中继器自定义控件允许您从一个或多个输入字段中收集值。除此之外，只需拖放每个字段，就可以对字段进行重新排序。该控件提供了一个用于轻松拖放重新排序的图标句柄、一个用于删除行的按钮和一个用于添加新行的按钮。
此特定控件是为收集一个或多个URL而设计的，并将验证这些字段。如果缺少“https://”，它还会自动将其添加到任何url中。如果您想收集其他类型的数据，如纯文本，只需复制此控件并根据需要进行修改。
此控件的设置将保存为URL的逗号分隔字符串。要在主题中使用此设置，我建议使用PHPexplode()函数将逗号分隔的字符串转换为字符串数组。
用法
add_control（$id，$args）；
参数
$id-（字符串）（必需）自定义控件对象或与此控件关联的设置的id。默认值：无
$args-（数组）（可选）包含设置参数的关联数组。默认值：空数组
$args的参数
标签-可选。将显示的标签默认值：空白
description-可选。要在标签下显示的说明。默认值：空白。
第节-必填项。应出现控制的部分
button_labels（按钮标签）-可选。包含控件标签列表的数组
add-可选。添加按钮的按钮标签。默认值：添加
实例
$wp_customize->add_setting( 'sample_sortable_repeater_control',
array(
'default' => '',
'transport' => 'refresh',
'sanitize_callback' => 'skyrocket_url_sanitization'
)
);
$wp_customize->add_control( new Skyrocket_Sortable_Repeater_Custom_Control( $wp_customize, 'sample_sortable_repeater_control',
array(
'label' => __( 'Sortable Repeater' ),
'description' => esc_html__( 'This is the control description.' ),
'section' => 'sample_custom_controls_section',
'button_labels' => array(
'add' => __( 'Add Row' ), // Optional. Button label for Add button. Default: Add
)
)
) );
图像单选按钮
图像单选按钮的工作原理与普通单选按钮控件相同，因为您只能从多个项目中选择一个项目。不同之处在于，它允许您为每个选择显示图像。这在图像为用户提供比简单文本更好的指示符的情况下很有用。这种类型的控件的一个常见用途是用户可以选择其站点的布局。
添加控件时，可以指定要显示的图像的url、将光标悬停在图像上时要显示的标题文本以及每个项目的值。
与普通单选按钮一样，保存到数据库中的设置是您为每个单选按钮选项指定的值
用法
add_control（$id，$args）；
参数
$id-（字符串）（必需）自定义控件对象或与此控件关联的设置的id。默认值：无
$args-（数组）（可选）包含设置参数的关联数组。默认值：空数组
$args的参数
标签-可选。将显示的标签默认值：空白
description-可选。要在标签下显示的说明。默认值：空白。
第节-必填项。应出现控制的部分
选项-必需。自定义选项列表。
key-必需。将为设置存储的数据
image-必需。要显示的图像的URL
name-必填项。要显示的标题文本
实例
$wp_customize->；add_setting（“sample_image_radio_button”，
阵列(
“默认”=>；“边带'，
“运输”=>；“刷新'，
“消毒_回调”=>；'飙升_文本_动画化'
);
$wp_自定义->；add_control（新Skyrocket_Image_Radio_Button自定义控件（$wp_customize，'sample_Image_Radio_Button'，
阵列(
“标签”=>__（“图像单选按钮控制”），
“描述”=>；esc_html__（'示例自定义控件描述'），
'节'=>；'sample_ custom_controls_section’，
“选项”=>；阵列(
'sidebarleft'=>；array（//此特定单选按钮选项的必需值
图像'=>；trailingslashit（get_template_directory_uri（））。'images/边栏left.png'，//必需。图像的URL
“名称”=>__（“左侧栏”）//必需。要显示的标题文本
),
'sidbarnone'=>；阵列(
“图像”=>；trailingslashit（get_template_directory_uri（））。'images/边栏none.png'，
“名称”=>__（“无边栏”）
),
'边带'=>；阵列(
“图像”=>；trailingslashit（get_template_directory_uri（））。'images/边栏右侧.png'，
“名称”=>__（“右侧栏”）
) );
文本单选按钮
文本单选按钮是另一种类型的单选按钮，其工作原理与普通单选按钮控件相同。文本单选按钮只是在一行紧凑的文本中显示选择。
添加控件时，可以为每个选项指定要显示的文本以及为每个项目指定设置。
与普通单选按钮一样，保存到数据库中的设置是您为每个单选按钮选项指定的值。
用法
add_control（$id，$args）；
参数
$id-（字符串）（必需）自定义控件对象或与此控件关联的设置的id。默认值：无
$args-（数组）（可选）包含设置参数的关联数组。默认值：空数组
$args的参数
标签-可选。将显示的标签默认值：空白
description-可选。要在标签下显示的说明。默认值：空白。
第节-必填项。应出现控制的部分
选项-必需。自定义选项列表。
key-必需。将为设置存储的数据
value-必需。为单选按钮选项显示的数据
实例
$wp_customize->add_setting( 'sample_text_radio_button',
array(
'default' => 'right',
'transport' => 'refresh',
'sanitize_callback' => 'skyrocket_text_sanitization'
)
);
$wp_customize->add_control( new Skyrocket_Text_Radio_Button_Custom_Control( $wp_customize, 'sample_text_radio_button',
array(
'label' => __( 'Text Radio Button Control' ),
'description' => esc_html__( 'Sample custom control description' ),
'section' => 'sample_custom_controls_section',
'choices' => array(
'left' => __( 'Left' ), // Required. Setting for this particular radio button choice and the text to display
'centered' => __( 'Centered' ), // Required. Setting for this particular radio button choice and the text to display
'right' => __( 'Right' ) // Required. Setting for this particular radio button choice and the text to display
)
)
) );
图像复选框
图像复选框的工作原理与普通复选框控件相同，因为您可以从多个项目中选择一个或多个项目。不同之处在于，它允许您为每个选择显示图像。这在图像为用户提供比简单文本更好的指示符的情况下很有用。这种类型的控件的一个常见用途是用户可以选择字体的重量（例如粗体、斜体等）。
添加控件时，可以指定要显示的图像的url、将光标悬停在图像上时要显示的标题文本以及每个项目的值。
保存到数据库中的设置是一个逗号分隔的字符串，其中包含所选每个项目的值。
用法
add_control（$id，$args）；
参数
$id-（字符串）（必需）自定义控件对象或与此控件关联的设置的id。默认值：无
$args-（数组）（可选）包含设置参数的关联数组。默认值：空数组
$args的参数
标签-可选。将显示的标签默认值：空白
description-可选。要在标签下显示的说明。默认值：空白。
第节-必填项。应出现控制的部分
选项-必需。自定义选项列表。
key-必需。将为设置存储的数据
image-必需。要显示的图像的URL
name-必填项。要显示的标题文本
实例
$wp_customize->；add_setting（“sample_image_checkbox”，
阵列(
“默认”=>；“stylebold，styleallcaps'，
“运输”=>；“刷新'，
“消毒_回调”=>；'飙升_文本_动画化'
);
$wp_自定义->；add_control（新的Skyrocket_Image_checkbox_Custom_control（$wp_customize，'sample_Image_checkbox'，
阵列(
“标签”=>__（“图像复选框控件”），
“描述”=>；esc_html__（'示例自定义控件描述'），
'节'=>；'sample_ custom_controls_section’，
“选项”=>；阵列(
“stylebold”=>；array（//必需。此特定单选按钮选项的设置
“图像”=>；trailingslashit（get_template_directory_uri（））。'images/Bold.png'，//必需。图像的URL
“名称”=>__（“粗体”）//必需。要显示的标题文本
),
“样式斜体”=>；阵列(
“图像”=>；trailingslashit（get_template_directory_uri（））。'images/Itic.png'，
“名称”=>__（“斜体”）
),
'样式帽
s’=>；阵列(
“图像”=>；trailingslashit（get_template_directory_uri（））。'images/AllCaps.png'，
“名称”=>__（“所有大写字母”）
),
“样式下划线”=>；阵列(
“图像”=>；trailingslashit（get_template_directory_uri（））。'images/下划线.png'，
“名称”=>__（“下划线”）
) );
单手风琴
Single Accordion控件允许您显示一大块文本，如教学信息，同时在单击之前将其隐藏或最小化。单击控件时，内容将变为可见，再次单击时，内容将会隐藏。
没有为该控件保存任何设置，它只是用于显示/隐藏一个内容块。
您可以向它传递一个键/值对数组或纯文本内容（包括基本的html标签a、br、em、strong、i）。
用法
add_control（$id，$args）；
参数
$id-（字符串）（必需）自定义控件对象或与此控件关联的设置的id。默认值：无
$args-（数组）（可选）包含设置参数的关联数组。默认值：空数组
$args的参数
标签-可选。将显示的标签默认值：空白
description-必填项。隐藏在手风琴下的文本，作为数组或字符串传递
第节-必填项。应出现控制的部分
实例
$sampleIconsList = array(
'Behance' => __( '<i class="fa fa-behance"></i>', 'skyrocket' ),
'Bitbucket' => __( '<i class="fa fa-bitbucket"></i>', 'skyrocket' ),
'CodePen' => __( '<i class="fa fa-codepen"></i>', 'skyrocket' ),
'DeviantArt' => __( '<i class="fa fa-deviantart"></i>', 'skyrocket' ),
'Dribbble' => __( '<i class="fa fa-dribbble"></i>', 'skyrocket' ),
'Etsy' => __( '<i class="fa fa-etsy"></i>', 'skyrocket' ),
'Facebook' => __( '<i class="fa fa-facebook"></i>', 'skyrocket' ),
'Flickr' => __( '<i class="fa fa-flickr"></i>', 'skyrocket' ),
'Foursquare' => __( '<i class="fa fa-foursquare"></i>', 'skyrocket' ),
'GitHub' => __( '<i class="fa fa-github"></i>', 'skyrocket' ),
);
$wp_customize->add_setting( 'sample_single_accordion',
array(
'default' => '',
'transport' => 'refresh',
'sanitize_callback' => 'skyrocket_text_sanitization'
)
);
$wp_customize->add_control( new Skyrocket_Single_Accordion_Custom_Control( $wp_customize, 'sample_single_accordion',
array(
'label' => __( 'Single Accordion Control' ),
'description' => $sampleIconsList, // Required. Passing an array of key/values pairs which are displayed in a list
'section' => 'sample_custom_controls_section'
)
) );
$wp_customize->add_setting( 'another_sample_single_accordion',
array(
'default' => '',
'transport' => 'refresh',
'sanitize_callback' => 'skyrocket_text_sanitization'
)
);
$wp_customize->add_control( new Skyrocket_Single_Accordion_Custom_Control( $wp_customize, 'another_sample_single_accordion',
array(
'label' => __( 'Another Single Accordion Control' ),
'description' => 'This is some simple text with an <a href="http://google.com">html link</a> included.', // Required. Passing some text with some basic html content
'section' => 'sample_custom_controls_section'
)
) );
简单通知
简单通知控件允许您显示文本块，例如说明信息。此控件没有保存任何设置，它只是用于显示一个内容块。
文本内容可以包括a、br、em、strong、i、span和code等基本html标签。
用法
add_control（$id，$args）；
参数
$id-（字符串）（必需）自定义控件对象或与此控件关联的设置的id。默认值：无
$args-（数组）（可选）包含设置参数的关联数组。默认值：空数组
$args的参数
标签-可选。将显示的标签默认值：空白
description-必填项。要显示的文本
第节-必填项。应出现控制的部分
实例
$wp_customize->add_setting( 'sample_simple_notice',
array(
'default' => '',
'transport' => 'postMessage',
'sanitize_callback' => 'skyrocket_text_sanitization'
)
);
$wp_customize->add_control( new Skyrocket_Simple_Notice_Custom_control( $wp_customize, 'sample_simple_notice',
array(
'label' => __( 'Simple Notice Control' ),
'description' => __('This Custom Control allows you to display a simple title and description to your users. You can even include <a href="http://google.com" target="_blank">basic html</a>.' ),
'section' => 'sample_custom_controls_section'
)
) );
下拉选择2
Select2是基于jQuery的select替换
盒。Select2为您提供了一个可自定义的选择框，支持搜索、标记、远程数据集、无限滚动和许多其他常用选项。
下拉菜单Select2自定义控件提供了一种在自定义程序中实现Select2下拉菜单的简单方法。与常规下拉菜单相比，使用Select2下拉菜单的主要好处之一是，它提供了一个方便的输入字段，允许您键入和搜索要查找的项目。当你的下拉列表非常长，并且滚动列表变得很麻烦时，这真的很方便。当你有一个国家或时区列表时，你可能想在常规的下拉列表中使用它。基本上，任何超过十几个条目的下拉列表都将受益于使用此Select2自定义控件而非常规下拉控件。
此控件的另一个好处是能够处理多选列表。也就是说，如果您愿意，它可以让您轻松地在列表中选择多个条目，而不仅仅是一个条目。这可以简单地通过将'multiselect' => true包含在input_attrs中来实现。
Dropdown Select2 Custom Control通过使用'choices'参数将条目作为数组传递，来处理条目的直接列表。或者，如果您希望您的下拉列表显示选项组（即将列表分组到不同部分的能力），那么您也可以将数组数组传递到'choices'。
如果要选择默认值，请在使用控件选择单个条目时传递一个简单字符串。将控件用作mutli选择时，传递一个字符串数组以选择多个默认值。
要清除控件数据，请使用myskyrocket_text_sanitization函数或任何其他可以清除简单字符串和一系列逗号分隔字符串的函数。值得注意的是，多选下拉列表将保存单个字符串或一系列逗号分隔的字符串，具体取决于下拉列表中选择的条目数。
如果只选择了一个条目，即使使用多选下拉菜单，该设置也将作为单个字符串保存到数据库中。如果您使用多选下拉菜单（即'multiselect' => true），并且您选择了多个条目，它们将以一系列逗号分隔的字符串的形式保存到数据库中。
用法
add_control（$id，$args）；
参数
$id-（字符串）（必需）自定义控件对象或与此控件关联的设置的id。默认值：无
$args-（数组）（可选）包含设置参数的关联数组。默认值：空数组
$args的参数
标签-可选。将显示的标签默认值：空白
description-必填项。要显示的文本
第节-必填项。应出现控制的部分
input_attrs-可选。自定义选项列表。
占位符-可选。要显示的占位符值。Select2要求在使用clearall选项时设置占位符值。默认值=“请选择…”
multiselect-可选。从下拉列表中选择一个条目或选择多个条目。要么是真的，要么是假的。默认值=false
选项-必需。自定义选项列表。
key-必需。将为设置存储的数据
value-必需。要在控件中显示的文本
实例
＜code＞//下拉选择2控件测试（单选）
$wp_自定义->；add_setting（‘sample_dropdown_select2_control_single’，
阵列(
“默认”=>；“vic’，
“运输”=>；“刷新'，
“消毒_回调”=>；'飙升_文本_动画化'
);
$wp_自定义->；add_control（新Skyrocket_Dropdown_Select2_Custom_control（$wp_customize，'sample_Dropdown_Select2_control_single'，
阵列(
“标签”=>__（“下拉选择2控制”、“飙升”），
“描述”=>；esc_html__（'样品下拉选择2自定义控件（单选）'，'飙升'），
'节'=>；'sample_ custom_controls_section’，
“input_attrs”=>；阵列(
“占位符”=>__（“请选择一个状态…”，“飙升”），
“多选”=>；错误，
),
“选项”=>；阵列(
“nsw”=>__（“新南威尔士州”，“飞涨”），
“vic”=>__（“维多利亚”，“天价”），
“qld”=>__（“昆士兰”，“飞涨”），
“wa”=>__（“西澳大利亚”，“飞涨”），
“sa”=>__（“南澳大利亚”，“飞涨”），
“塔斯”=>__（“塔斯马尼亚”、“飞涨”），
“动作”=>__（“澳大利亚首都地区”，“飞涨”），
“nt”=>__（“北领地”，“飞涨”），
) );
//带有选项组的下拉式Select2控件（多选）的测试
$wp_自定义->；add_setting（‘sample_dropdown_select2_control_multi’，
阵列(
“默认”=>；阵列（“南极洲/麦克默多”、“澳大利亚/墨尔本”、“澳洲/布罗肯希尔”），
“运输”=>；“刷新'，
“消毒_回调”=>；'飙升_文本_动画化'
);
$wp_客户
omize->；add_control（新Skyrocket_Dropdown_Select2_Custom_control（$wp_customize，'sample_Dropdown_Select2_control_multi'，
阵列(
“标签”=>__（“下拉选择2控制”、“飙升”），
“描述”=>；esc_html__（'样品下拉选择2自定义控件（多选）'，'飙升'），
'节'=>；'sample_ custom_controls_section’，
“input_attrs”=>；阵列(
“多选”=>；是的，
),
“选项”=>；阵列(
__（“南极洲”，“暴涨”）=>；阵列(
“南极洲/凯西”=>__（“凯西”、“天价”），
“南极洲/戴维斯”=>__（“Davis”，“扶摇直上”），
“南极洲/杜蒙特杜维尔”=>__（“DumontDUrville”，“飞涨”），
“南极洲/麦格理”=>__（“麦格理”、“暴涨”），
“南极洲/莫森”=>__（“Mawson”，“扶摇直上”），
“南极洲/麦克默多”=>__（“麦克默多”，“天价”），
“南极洲/帕尔默”=>__（《帕默》、《扶摇直上》），
“南极洲/罗瑟拉”=>__（“Rothera”，“扶摇直上”），
“南极洲/锡奥瓦”=>__（“Syowa”，“扶摇直上”），
“南极洲/巨魔”=>__（“巨魔”、“暴涨”），
“南极洲/沃斯托克”=>__（“沃斯托克”，“天价”），
),
__（“大西洋”，“暴涨”）=>；阵列(
“大西洋/亚速尔群岛”=>__（“亚速尔群岛”，“天价”），
“大西洋/百慕大”=>__（“百慕大”、“暴涨”），
“大西洋/加那利群岛”=>__（“金丝雀”，“飞升”），
'大西洋/海角_Verde'=>__（“佛得角”，“飞涨”），
“大西洋/法罗群岛”=>__（“法罗群岛”、“飙升”），
“大西洋/马德拉”=>__（“马德拉”，“天价”），
“大西洋/雷克雅未克”=>__（“雷克雅未克”，“飞涨”），
“大西洋/南方_Georgia”=>__（“南乔治亚州”，“飞涨”），
“大西洋/斯坦利”=>__（“斯坦利”，“天价”），
“大西洋/圣海伦娜”=>__（“圣赫勒拿”，“天价”），
),
__（“澳大利亚”，“飞涨”）=>；阵列(
'澳大利亚/阿德莱德'=>__（“阿德莱德”，“飞涨”），
“澳大利亚/布里斯班”=>__（“布里斯班”，“飞涨”），
'澳大利亚/Broken_Hill'=>__（《破碎的山丘》、《扶摇直上》），
“澳大利亚/咖喱”=>__（“咖喱”、“飞涨”），
“澳大利亚/达尔文”=>__（“达尔文”，“天价”），
“澳大利亚/欧几里得”=>__（“欧几里得”、“飞天”），
“澳大利亚/霍巴特”=>__（《霍巴特》、《扶摇直上》），
“澳大利亚/林德曼”=>__（“林德曼”，“天价”），
“澳大利亚/Lord_Howe”=>__（“豪勋爵”，“天价”），
“澳大利亚/墨尔本”=>__（“墨尔本”，“飞涨”），
“澳大利亚/珀斯”=>__（“珀斯”，“飙升”），
“澳大利亚/悉尼”=>__（“悉尼”，“天价”），
) );
下拉式帖子
下拉帖子自定义控件允许您显示帖子的下拉列表。添加控件时，您可以使用input_attrs数组显示所有帖子或仅显示一个选择。
这种控制非常灵活。你不仅可以显示你的典型（博客）帖子列表，而且它实际上可以显示任何类型的帖子，例如WooCommerce产品，甚至页面。您可以传递一个要包含的帖子ID数组、一个要包括的帖子IDNOT数组、要检索的帖子数量、帖子类型（例如，您可以对WooCommerce产品使用product）和一长串其他选项。要查看使用input_attrs数组可以传递的值的完整列表，请参阅WordPress Codex中的WP_Query:：parse_Query（）。
保存到数据库的设置是Post ID。
用法
add_control（$id，$args）；
参数
$id-（字符串）（必需）自定义控件对象或与此控件关联的设置的id。默认值：无
$args-（数组）（可选）包含设置参数的关联数组。默认值：空数组
$args的参数
标签-可选。将显示的标签默认值：空白
description-可选。要在标签下显示的说明。默认值：空白。
第节-必填项。应出现控制的部分
input_attrs-可选。帖子选项列表。下面列出的选项是最常见的。有关完整列表，请参阅WordPress Codex中的WP_Query:：parse_Query（）。
post_per_page-可选。要检索的帖子数。使用-1检索所有帖子。默认值：5
orderby（订购方）-可选。对检索到的帖子进行排序的顺序。接受“none”、“name”、“author”、《date》、“title”、“modified”、“menu_Order”、“parent”、“ID”、“rand”等。默认值：“日期”
订单-可选。指定帖子的升序或降序。接受“ASC”或“DESC”。默认值：“DESC”
cat-可选。类别ID或逗号分隔的ID列表。默认值：0
post__in-可选。要检索的帖子ID数组（将包括粘性帖子）
post__not_in-可选。不检索的帖子ID的数组注意：逗号分隔的ID字符串将不起作用
post_type-可选。柱状段塞（串）或柱状段塞列。默认值：“post”
实例
$wp_customize->；add_setting（“sample_dropdown_posts_control”，
阵列(
“默认”=>；“”，
“运输”=>；“postMessage’，
“消毒_回调”=>；'绝对值
);
$wp_自定义->；add_control（新的Skyrocket_Dropdown_Posts_Custom_control（$wp_customize，'sample_Dropdown_Posts_control'，
阵列(
“标签”=>__（“Dropdown Posts Control”、“through”），
“描述”=>；esc_html__（“Sample Dropdown Posts custom control description”（示例下拉发布自定义控件描述），
'节'=>；'sample_ custom_controls_section’，
“input_attrs”=>；阵列(
'post_per_page'=>-1.
'orderby'=>；'名称'，
“订单”=>；“ASC’，
),
) );
TinyMCE编辑器
TinyMCE编辑器的工作原理与创建页面或帖子时使用的标准TinyMCE editor相同。你会注意到的唯一区别是它有一个极简主义的工具栏。这主要是因为您不太可能像创建页面或帖子时那样需要功能齐全的工具栏。这在一定程度上也是由于Customizer侧边栏中可用的屏幕空间有限。像标准的Page/Post TinyMCE编辑器一样，您可以添加文本&；链接，以及各种样式，如粗体、斜体和许多其他样式。
添加控件时，还可以指定要显示的工具栏图标。可以有一个工具栏行，也可以有两个工具栏行。如果没有指定任何工具栏，默认情况下显示一个带有粗体、斜体、项目符号列表、数字列表、向左对齐、居中对齐、向右对齐和链接按钮的工具栏。
TinyMCE官方网站上提供了可用工具栏按钮的完整列表。他们的例子&；演示页面还有许多示例，显示了每个工具栏按钮的显示方式。值得注意的是，一些工具栏按钮需要额外的TinyMCE插件，但在TinyMCE的WordPress版本中，并不是所有插件都默认可用。
您还可以选择显示或隐藏“添加媒体”按钮，从而可以轻松地将图像添加到TinyMCE控件中。默认情况下，“添加媒体”按钮将被隐藏。
在清除设置时，您可以简单地使用核心的wp_kses_post（）函数，该函数将清除内容中允许的HTML标记以用于发布内容。
保存到数据库的设置将是一个字符串，其中允许的HTML标记和属性保持不变。
请注意：TinyMCE编辑器自定义控件只能在WordPress 4.8及以上版本中使用，因为其使用所需的JavaScript功能仅在WP 4.8中添加。
用法
add_control（$id，$args）；
参数
$id-（字符串）（必需）自定义控件对象或与此控件关联的设置的id。默认值：无
$args-（数组）（可选）包含设置参数的关联数组。默认值：空数组
$args的参数
标签-可选。将显示的标签默认值：空白
description-可选。要在标签下显示的说明。默认值：空白。
第节-必填项。应出现控制的部分
input_attrs-可选。自定义选项列表。
工具栏1-可选。包含要显示在第一个工具栏行上的工具栏按钮列表的字符串。默认值：“bold italic bullist numlist alignleft alignenter alignright link”
工具栏2-可选。包含要显示在第二个工具栏行上的工具栏按钮列表的字符串。默认值：空白
media按钮-可选。显示或隐藏“添加媒体”按钮。要么是真的，要么是假的。默认值：false
实例
$wp_customize->add_setting( 'sample_tinymce_editor',
array(
'default' => '',
'transport' => 'postMessage',
'sanitize_callback' => 'wp_kses_post'
)
);
$wp_customize->add_control( new Skyrocket_TinyMCE_Custom_control( $wp_customize, 'sample_tinymce_editor',
array(
'label' => __( 'TinyMCE Control' ),
'description' => __( 'This is a TinyMCE Editor Custom Control' ),
'section' => 'sample_custom_controls_section',
'input_attrs' => array(
'toolbar1' => 'bold italic bullist numlist alignleft aligncenter alignright link',
'toolbar2' => 'formatselect outdent indent | blockquote charmap',
'mediaButtons' => true,
)
)
) );
谷歌字体选择
我发现许多主题和插件中的谷歌字体控件存在的一个问题是，它们不允许使用斜体和粗体权重。他们会将常规文本更改为所选的字体，但任何粗体或斜体的文本都会恢复为原始字体。其中一个原因是，在从谷歌检索字体时，他们没有指定必要的斜体和粗体权重。
谷歌字体控件将允许您选择谷歌字体，并指定常规、斜体和粗体的权重。Google字体选项列表存储在通过调用Google Webfonts API生成的json文件中。为了避免在主题中包含您自己的Google Fonts API Key，您应该在添加主题选项之前生成此字体列表。你可以通过调用获得谷歌字体的完整列表，按流行程度排序https://www.googleapis.c
om/webfonts/v1/webfonts？sort=受欢迎程度&；key=YOUR-API-key。可以通过检索按字母顺序排序的字体的完整列表https://www.googleapis.com/webfonts/v1/webfonts?key=YOUR-API-KEY（不要忘记在适当的位置包含您自己的谷歌字体API密钥）。
在定义控件时，可以指定要显示的字体数以及它们的显示顺序（按字母顺序或按流行程度）。如果您的默认字体或当前保存的字体不包括在您显示的字体列表中，它将自动作为默认字体添加到列表的开头。例如，如果指定“Open Sans”作为默认字体，但只选择只显示按字母顺序排列的前10种字体，则控件中显示的字体列表中将自动添加“Open Sans”。
Font Family下拉列表还实现了Select2控件，它添加了一个输入字段，允许您键入和搜索所需的字体。这使得查找字体比在谷歌字体名称的长列表中滚动更容易。
该设置以json字符串的形式保存到数据库中。在主题中使用这些数据的最简单方法是使用json_decode()PHP函数将json字符串转换为数组。从那里，可以很容易地获得字体名称、常规字体重量、斜体、粗体和字体类别，这对指定后备字体很有用。
用法
add_control（$id，$args）；
参数
$id-（字符串）（必需）自定义控件对象或与此控件关联的设置的id。默认值：无
$args-（数组）（可选）包含设置参数的关联数组。默认值：空数组
$args的参数
标签-可选。将显示的标签默认值：空白
description-必填项。要显示的文本
第节-必填项。应出现控制的部分
input_attrs-可选。自定义选项列表。
font_count-可选。要从json文件中显示的字体数。正整数或“all”。默认值=“全部”
orderby（订购方）-可选。字体列表排序顺序。要么是“阿尔法”，要么是“流行”。默认值=“alpha”
实例
$wp_customize->add_setting( 'sample_google_font_select',
array(
'default' => '"font":"Open Sans","regularweight":"regular","italicweight":"italic","boldweight":"700","category":"sans-serif"',
),
'sanitize_callback' => 'skyrocket_google_font_sanitization'
);
$wp_customize->add_control( new Skyrocket_Google_Font_Select_Custom_Control( $wp_customize, 'sample_google_font_select',
array(
'label' => __( 'Google Font Control' ),
'description' => esc_html__( 'Sample custom control description' ),
'section' => 'sample_custom_controls_section',
'input_attrs' => array(
'font_count' => 'all',
'orderby' => 'alpha',
),
)
) );
Alpha颜色
这个控制的所有道具都归布拉德·马丁所有。我在这里（也在我的示例代码中）包含了它，因为它非常有用，而且我认为它比内置在核心中的标准颜色控制更好。你可以查看Braad写的关于这个控件的原始帖子，也可以在他的Github回购中查看。
Alpha颜色控件与内置在核心中的颜色控件非常相似。与默认控件相比，此控件的好处在于，它允许您指定所选颜色的不透明度，这允许您指定RGBa颜色，而不仅仅是实心十六进制颜色。
保存到数据库的设置将是RGBa颜色值（例如RGBa（0158,39,0.8））或纯实心十六进制颜色（例如#009e27）。
用法
add_control（$id，$args）；
参数
$id-（字符串）（必需）自定义控件对象或与此控件关联的设置的id。默认值：无
$args-（数组）（可选）包含设置参数的关联数组。默认值：空数组
$args的参数
标签-可选。将显示的标签默认值：空白
description-必填项。要显示的文本
第节-必填项。应出现控制的部分
show_ocapacity（显示容量）-可选。显示或隐藏不透明度滑块控制柄上的不透明度值。默认值：true
调色板-可选。允许您指定调色板中使用的颜色。可以设置为false以隐藏调色板。默认值：WP颜色控制调色板
实例
$wp_customize->；add_setting（“sample_alpha_color”，
阵列(
“默认”=>；“rgba（209,0,55,0.7）’，
“运输”=>；“后消息'
);
$wp_自定义->；add_control（新Skyrocket_Customize_Alpha_Color_control（$wp_Customize，'sample_Alpha_Color_picker'，
阵列(
“标签”=>__（“Alpha颜色选择器控件”），
“描述”=>；esc_html__（'示例自定义控件描述'），
'节'=>；'sample_ custom_controls_section’，
“显示容量”=>；true，//可选。显示或隐藏不透明度滑块控制柄上的不透明度值。默认值：true
“调色板”=>；array（//可选。选择颜色f
或调色板。默认值：WP颜色控制调色板
'#000',
“#fff”，
‘#df312c’，
‘#df9a23’，
'#eef000'，
‘#7ed934’，
“#1571c1”，
“#8309e7”
) );
WPColorPicker Alpha颜色
WPColorPicker Alpha Color是另一个支持Alpha通道选择的自定义颜色控件（例如rgba（0158,39,0.8））。此控件使用支持Alpha通道选择的WordPress颜色选择器脚本的修改版本。尽管Customizer自定义控件是我自己创建的，但这个修改后的WPColorPicker脚本的所有道具都归Sergio所有。
Alpha颜色控件与内置在核心中的颜色控件非常相似。与默认控件相比，此控件的好处在于，它允许您指定所选颜色的不透明度，这允许您指定RGBa颜色，而不仅仅是实心十六进制颜色。
定义控件时，可以指定一个由8个颜色值组成的数组用于调色板颜色，调色板颜色显示为控件底部的小样本。可以使用十六进制值、RGB值或RGBa值指定颜色。我建议不要混合Hex/RGB和RGBa颜色，因为WPColorPicker脚本在处理这一问题时存在问题。使用所有HEX/RGB值或所有RGBa值。
定义控件时，可以指定Alpha通道是否重置（返回1）或是否保持相同值（默认值为重置，即true）。设置'resetalpha' => false将确保每次选择调色板颜色时，alpha通道中的值不会重置回1。设置'resetalpha' => true（或不使用此选项）将确保每次选择调色板颜色之一时，alpha通道值重置回1。
WPColorPicker脚本在调色板中混合HEX颜色和RGBa颜色时出现问题。如果'resetalpha' => false，并且您从调色板中选择一种阿尔法值小于1的RGBa颜色，则会选择正确的颜色。但是，如果随后从调色板中选择一个十六进制值，则alpha通道值将保持与上次选择的值相同，从而导致选择不正确的颜色。
在Palette中指定所有Hex值时，最好设置'resetalpha' => true（或者不要指定此选项，因为默认值为true）。当使用调色板中的所有RGBa值时，最好设置'resetalpha' => false。
保存到数据库的设置将是RGBa颜色值（例如RGBa（0158,39,0.8））或纯实心十六进制颜色（例如#009e27）。
用法
add_control（$id，$args）；
参数
$id-（字符串）（必需）自定义控件对象或与此控件关联的设置的id。默认值：无
$args-（数组）（可选）包含设置参数的关联数组。默认值：空数组
$args的参数
标签-可选。将显示的标签默认值：空白
description-必填项。要显示的文本
第节-必填项。应出现控制的部分
input_attrs-可选。自定义选项列表。
resetalpha-可选。这将在每次从调色板中选择新颜色时将Alpha通道重置回1。默认值=“true”
调色板-可选。允许您指定调色板中使用的8种颜色。默认值：WP颜色控制调色板
示例1
$wp_customize->add_setting( 'sample_wpcolorpicker_alpha_color',
array(
'default' => 'rgba(209,0,55,0.7)',
'transport' => 'postMessage',
'sanitize_callback' => 'skyrocket_hex_rgba_sanitization'
)
);
$wp_customize->add_control( new Skyrocket_Alpha_Color_Control( $wp_customize, 'sample_wpcolorpicker_alpha_color',
array(
'label' => __( 'Alpha Color Picker Control' ),
'description' => esc_html__( 'Sample color control with Alpha channel' ),
'section' => 'sample_custom_controls_section',
'input_attrs' => array(
'palette' => array(
'#000000',
'#ffffff',
'#dd3333',
'#dd9933',
'#eeee22',
'#81d742',
'#1e73be',
'#8224e3',
)
),
)
) );
示例2
$wp_customize->add_setting( 'sample_wpcolorpicker_alpha_color2',
array(
'default' => 'rgba(209,0,55,0.7)',
'transport' => 'postMessage',
'sanitize_callback' => 'skyrocket_hex_rgba_sanitization'
)
);
$wp_customize->add_control( new Skyrocket_Alpha_Color_Control( $wp_customize, 'sample_wpcolorpicker_alpha_color2',
array(
'label' => __( 'Alpha Color Picker Control' ),
'description' => esc_html__( 'Sample color control with Alpha channel' ),
'section' => 'sample_custom_controls_section',
'input_attrs' => array(
'resetalpha' => false,
'palette' => array(
'rgba(99,78,150,1)',
'rgba(67,78,150,1)',
'rgba(34,78,150,.7)',
'rgba(3,78,150,1)',
'rgba(7,110,230,.9)',
'rgba(234,78,150,1)',
'rgba(99,78,150,.5)',
'rgba(190,120,120,.5)',
),
),
)
) );
可排序药丸复选框自定义控制
可排序药丸复选框的工作原理类似于普通的复选框控件，因为您可以从多个项目中选择一个或多个项目。此控件将把每个项目显示为一个小的“药丸”，而不是复选框。当选中每个药丸/复选框并更改颜色时，所选项目也会显示一个勾号，以提高可访问性，并使项目是否被选中更加明显。这些药丸复选框还可以选择使用拖放进行排序。如果您希望为用户提供一组选项，并为他们提供控制这些选项顺序的能力，这将非常有用。最后，你也可以选择全宽显示，而不是大小不等的小药丸。这将显示每个药丸的大小相同，而不是每个药丸都有可变的宽度。这种类型的控件的一个常见用途是，您可以允许用户为其博客文章选择要显示的元内容，并允许他们更改每个项目的显示顺序。
添加控件时，您可以通过设置'sortable' => true（默认为不可排序，即false）来指定是否希望药丸可排序。您也可以通过设置'fullwidth' => true（默认为可变宽度，即false）来指定是否希望药丸显示全宽。
保存到数据库中的设置是一个逗号分隔的字符串，其中包含所选每个项目的值。
用法
add_control（$id，$args）；
参数
$id-（字符串）（必需）自定义控件对象或与此控件关联的设置的id。默认值：无
$args-（数组）（可选）包含设置参数的关联数组。默认值：空数组
$args的参数
标签-可选。将显示的标签默认值：空白
description-可选。要在标签下显示的说明。默认值：空白。
第节-必填项。应出现控制的部分
input_attrs-可选。控制选项列表。
可排序-可选。允许使用拖放方式对药片进行分拣。默认值=“false”
全宽-可选。显示药丸的全宽，而不是可变宽度。默认值=“false”
选项-必需。自定义选项列表。
key-必需。将为设置存储的数据
value-必需。要在控件中显示的文本
示例1
// Test of Pill Checkbox Custom Control
$wp_customize->add_setting( 'sample_pill_checkbox',
array(
'default' => 'tiger,elephant,hippo',
'transport' => 'refresh',
'sanitize_callback' => 'skyrocket_text_sanitization'
)
);
$wp_customize->add_control( new Skyrocket_Pill_Checkbox_Custom_Control( $wp_customize, 'sample_pill_checkbox',
array(
'label' => __( 'Pill Checkbox Control', 'skyrocket' ),
'description' => esc_html__( 'This is a sample Pill Checkbox Control', 'skyrocket' ),
'section' => 'sample_custom_controls_section',
'input_attrs' => array(
'sortable' => false,
'fullwidth' => false,
),
'choices' => array(
'tiger' => __( 'Tiger', 'skyrocket' ),
'lion' => __( 'Lion', 'skyrocket' ),
'giraffe' => __( 'Giraffe', 'skyrocket' ),
'elephant' => __( 'Elephant', 'skyrocket' ),
'hippo' => __( 'Hippo', 'skyrocket' ),
'rhino' => __( 'Rhino', 'skyrocket' ),
)
)
) );
示例2
// Test of Pill Checkbox Custom Control with Sortable option
$wp_customize->add_setting( 'sample_pill_checkbox2',
array(
'default' => 'captainmarvel,msmarvel,squirrelgirl',
'transport' => 'refresh',
'sanitize_callback' => 'skyrocket_text_sanitization'
)
);
$wp_customize->add_control( new Skyrocket_Pill_Checkbox_Custom_Control( $wp_customize, 'sample_pill_checkbox2',
array(
'label' => __( 'Pill Checkbox Control', 'skyrocket' ),
'description' => esc_html__( 'This is a sample Sortable Pill Checkbox Control', 'skyrocket' ),
'section' => 'sample_custom_controls_section',
'input_attrs' => array(
'sortable' => true,
'fullwidth' => false,
),
'choices' => array(
'captainamerica' => __( 'Captain America', 'skyrocket' ),
'ironman' => __( 'Iron Man', 'skyrocket' ),
'captainmarvel' => __( 'Captain Marvel', 'skyrocket' ),
'msmarvel' => __( 'Ms. Marvel', 'skyrocket' ),
'Jessicajones' => __( 'Jessica Jones', 'skyrocket' ),
'squirrelgirl' => __( 'Squirrel Girl', 'skyrocket' ),
'blackwidow' => __( 'Black Widow', 'skyrocket' ),
'hulk' => __( 'Hulk', 'skyrocket' ),
)
)
) );
示例3
＜code＞//测试Pill复选框自定义控件的可排序和全宽选项
$wp_自定义->；add_setting（“sample_pill_checkbox3”，
阵列(
“默认”=>；“作者，类别，评论'，
“运输”=>；“刷新'，
“消毒_回调”=>；'飙升_文本_动画化'
);
$wp_自定义->；add_control（新Skyrocket_Pill_Checkbox_Custom_control（$wp_customize，'sample_Pill_checkbox3'，
阵列(
“标签”=>__（“药丸复选框控制”、“飙升”），
“描述”=>；esc_html__（'这是一个示例可排序全角药丸复选框控件'，'飙升'），
'节'=>；'sample_ custom_controls_section’，
“input_attrs”=>；阵列(
“可排序”=>；是的，
“全宽”=>；是的，
),
“选项”=>；阵列(
“日期”=>__（“日期”、“飙升”），
“作者”=>__（“作者”、“飙升”），
“类别”=>__（“类别”、“飙升”），
“标记”=>__（“标签”、“飙升”），
“注释”=>__（“评论”、“暴涨”），
) );
Upsell部分
Upsell部分是一个自定义部分，允许您提供指向外部URL（如主题网站）的链接。如果您正在追加销售高级主题或插件，此部分非常有用。
Upsell部分类似于标准的核心Customizer部分，只是它不能够导航到该部分，而只是提供了一个指向外部URL的链接。由于这是一个Section而不是自定义控件，您可能希望将其添加到定义其他Section的同一函数中。
定义分区时，您可以指定URL、用于链接的文本以及分区的背景和文本颜色。定义颜色的功能使您可以用自己的品牌颜色显示此部分，并使此链接在自定义程序中更引人注目。
由于这是一个自定义节，而不是自定义控件，因此没有保存到数据库中的值。
用法
add_section（$id，$args）；
参数
$id-（字符串）（必需）自定义节对象或节id。默认值：无
$args-（数组）（可选）包含设置参数的关联数组。默认值：空数组
$args的参数
title-节的可见名称
优先级-可选。这控制了此部分在“主题自定义程序”侧边栏中的显示顺序
url-要链接到的外部url
背景颜色-可选。该部分的背景色。默认值：#fff
textcolor-可选。标题的文本颜色。默认值：#555d66
实例
$wp_customize->add_section( new Skyrocket_Upsell_Section( $wp_customize, 'upsell_section',
array(
'title' => __( 'Premium Addons Available', 'skyrocket' ),
'url' => 'https://skyrocketthemes.com',
'backgroundcolor' => '#344860',
'textcolor' => '#fff',
'priority' => 0,
)
) );
进一步阅读
有关更多详细信息，请查看我的《自定义开发人员指南》：
WordPress自定义程序-开发者指南（第1部分）
WordPress自定义程序-开发者指南（第2部分）
您可以通过以下链接下载一个示例主题和插件，展示如何实现这些控件。不过请注意，由于示例主题和示例插件都使用相同的Customizer Controls代码，因此不要试图在激活示例主题的同一网站上激活示例插件。这将导致一个错误，因为您将尝试安装具有相同名称的类，因为它们都使用相同的代码库：
https://github.com/maddisondesigns/Customizer-Custom-Controls-Sample-Theme
https://github.com/maddisondesigns/Customizer-Custom-Controls-Sample-Plugin
变更日志
= 1.2.2 =
= 1.2.1 =
= 1.2.0 =
= 1.1.9 =
= 1.1.8 =
= 1.1.7 =
= 1.1.6 =
= 1.1.5 =
= 1.1.4 =
= 1.1.3 =
= 1.1.2 =
= 1.1.1 =
= 1.1.0 =
= 1.0.13 =
= 1.0.12 =
= 1.0.11 =
= 1.0.10 =
= 1.0.9 =
= 1.0.8 =
= 1.0.7 =
= 1.0.6 =
= 1.0.5 =
= 1.0.4 =
= 1.0.3 =
= 1.0.2 =
= 1.0.1 =
= 1.0 =
=2018年6月25日=
=2018年6月17日=
=2018年6月16日=
=2018年4月5日=
=2018年4月2日=
=2018年3月31日=
=2018年3月16日=
=2017年11月27日=
=2017年11月21日=
=2017年10月4日=
=2017年9月29日=
=2017年9月13日=
=2017年9月9日=
=2017年8月21日=
=2017年8月20日=
=2017年6月18日=
=2017年5月17日=
=2017年5月16日=
=2017年5月14日=
=2017年5月11日=
=2017年5月8日=
=2017年5月6日=
=2017年5月5日=