wordpress 自定义
One thing WordPress users have grown accustomed to, is easy, no code required theme customization options. The idea is: download a theme, activate it in the Themes panel, access the Customize panel, and start tweaking the theme’s colors, layout, fonts, etc., with just a mouse click.
WordPress用户已经习惯了一件事，很容易，不需要代码就可以使用主题自定义选项。 这个想法是：下载一个主题，在“主题”面板中将其激活，访问“自定义”面板，然后只需单击鼠标即可开始调整主题的颜色，布局，字体等。
WordPress offers theme developers the Customizer API. This is a clean, object-oriented set of methods that facilitate the creation of a consistent customization interface. On the Customize panel, users can easily make changes and live-preview them without having to mess with PHP or CSS code.
WordPress为主题开发人员提供了Customizer API 。 这是一组干净的，面向对象的方法，可帮助创建一致的自定义界面。 在“定制”面板上，用户可以轻松进行更改并实时预览它们，而无需弄乱PHP或CSS代码。
Developing theme options using the Customizer API, while being a straightforward and logical process, involves writing a certain amount of repetitive code. To cut down on some of the steps required to build functioning and safe Customizer options, Aristeides Stathopoulos has been developing a free and open-source plugin, Kirki.
使用Customizer API开发主题选项虽然是一个简单而合理的过程，但需要编写一定数量的重复代码。 为了减少构建功能和安全的Customizer选项所需的某些步骤， Aristeides Stathopoulos已开发了一个免费的开源插件Kirki 。
In this post I’m going to show how to integrate Kirki into your WordPress theme and how to use it to build a few Customizer options.
在这篇文章中，我将展示如何将Kirki集成到您的WordPress主题中，以及如何使用它来构建一些Customizer选项。
Let’s hear what Kirki is about from the developer behind it:
让我们从背后的开发人员那里了解Kirki的含义：
Kirki is not a framework. It’s a toolkit allowing WordPress developers to use the Customizer and take advantage of its advanced features and flexibility by abstracting the code and making it easier for everyone to create beautiful and meaningful user experiences.
Kirki不是框架。 它是一个工具包，可让WordPress开发人员使用定制程序，并通过抽象化代码并使所有人更轻松地创建美丽而有意义的用户体验，来利用其高级功能和灵活性。
Kirki Documentation
Kirki文档
I’d like to drive home two points about this toolkit.
关于这个工具包，我想讲两点。
Kirki does not replace the WordPress Customizer API. It creates a “wrapper for the default WordPress methods, simplifying the syntax and allowing you to write more with less code”. You can still use native Customizer methods alongside the Kirki API. Even better, you’re warmly advised to familiarize yourself with the Customizer API before approaching Kirki. If you’re looking for a useful introduction to the Customizer object, head over to Getting Started with the WordPress Theme Customization API by Narayan Prusty.
Kirki 不更换WordPress的定制API。 它为“默认的WordPress方法创建了一个包装器，简化了语法并允许您用更少的代码编写更多内容”。 您仍然可以将本机Customizer方法与Kirki API一起使用。 更好的是，我们建议您在接触Kirki之前先熟悉Customizer API。 如果您正在寻找有关Customizer对象的有用介绍，请转到Narayan Prusty 的WordPress主题定制API入门。
Kirki is in a state of constant evolution and improvement, not unlike the WordPress Customizer itself. Therefore, any bug reports, or requests for new features, have their place in the GitHub repo, where you can download the development version of the plugin and contribute to its development.
Kirki处于不断发展和完善的状态，与WordPress Customizer本身不同。 因此，任何错误报告或对新功能的请求均位于GitHub存储库中 ，您可以在其中下载该插件的开发版本并为该插件的开发做出贡献。
It’s time to see Kirki in action. If you want to follow along, have a WordPress theme ready or grab the Superminimal demo theme that contains all the code discussed in this post.
现在是时候看到Kirki了。 如果您想继续学习，请准备一个WordPress主题，或获取包含本文中讨论的所有代码的Superminimal演示主题 。
Kirki is packaged as a WordPress plugin. As such, you can download it from the WordPress.org plugins repository, or directly from the backend of your WordPress installation, unzip it and activate it.
Kirki被打包为WordPress插件。 这样，您可以从WordPress.org插件存储库中下载它，也可以直接从WordPress安装的后端下载它，然后解压缩并激活它。
If you prefer to include Kirki in your theme as a library, follow the steps outlined below.
如果您希望将Kirki作为库包含在主题中，请遵循以下步骤。
Copy the kirki directory into your theme’s folder. In the demo theme for this article, the Kirki files are located inside a directory called inc.
将kirki目录复制到主题的文件夹中。 在本文的演示主题中，Kirki文件位于名为inc的目录内。
Make your theme ‘talk’ with Kirki by adding this line to functions.php (make sure you adjust the path to the kirki folder to match your theme’s file structure).
将此行添加到functions.php使您的主题与Kirki进行“交谈”(确保您调整了kirki文件夹的路径以匹配您主题的文件结构)。
if ( ! class_exists( 'Kirki' ) ) { include_once( dirname( __FILE__ ) . '/inc/kirki/kirki.php' ); }Add a function to include the Kirki configuration options and hook it to the kirki/config filter. It’s up to you what you want to add to this function. For this post, let’s keep it to a minimum by adding the code Kirki needs in order to be ‘made aware’ of its new location, i.e. the theme’s folder rather than the plugin’s folder.
添加一个包含Kirki配置选项的功能，并将其挂接到kirki/config过滤器。 您要添加到此功能的内容取决于您。 对于这篇文章，让我们通过添加Kirki所需的代码来使其最小化，以便“了解”其新位置，即主题文件夹而不是插件文件夹。
function superminimal_customizer_config() { $args = array( // Only use this if you are bundling the plugin with your theme 'url_path' => get_stylesheet_directory_uri() . '/inc/kirki/', ); return $args; } add_filter( 'kirki/config', 'superminimal_customizer_config' );It’s inside this configuration function that you can control the look and feel of the WordPress Customizer to match your theme. Most importantly, it’s here that you add the code necessary to make all strings used by the plugin translatable from within your theme. Have a look inside the Superminimal demo theme or the Kirki documentation page for some guidance on how to accomplish this.
在此配置功能的内部，您可以控制WordPress Customizer的外观以匹配您的主题。 最重要的是，在这里您添加了必要的代码，以使插件使用的所有字符串都可以在主题内进行翻译。 在Superminimal演示主题或Kirki文档页面中查看有关如何完成此操作的一些指导。
Kirki is now ready to help us build some Customizer options. You can use functions.php or create a dedicated file for the task, it’s up to you.
Kirki现在准备帮助我们构建一些Customizer选项。 您可以使用functions.php或为任务创建专用文件，这取决于您。
Customizer options live inside Sections, which are optionally located inside Panels. In this article’s demo project I group all Sections inside a dedicated Panel using native Customizer methods, like so.
定制程序选项位于Sections内部，可以选择位于Panel内部。 在本文的演示项目中，我使用本机的Customizer方法将所有Sections分组在一个专用的Panel中。
function superminimal_demo_panels_sections( $wp_customize ) { /** * Add Panel */ $wp_customize->add_panel( 'sitepoint_demo_panel', array( 'priority' => 10, 'title' => __( 'SitePoint Demo Panel', 'superminimal' ), 'description' => __( 'Kirki integration for SitePoint demo', 'superminimal' ), ) ); //More code to come } add_action( 'customize_register', 'superminimal_demo_panels_sections' );Next, add Sections for the site text colors, the site layout, and the footer text options respectively by placing this code just below the previous add_panel Customizer method.
接下来，通过将代码放置在先前的add_panel Customizer方法下面，分别为网站文本颜色 ，网站布局和页脚文本选项添加Sections。
/** * Add a Section for Site Text Colors */ $wp_customize->add_section( 'superminimal_text_colors', array( 'title' => __( 'Site Text Colors', 'superminimal' ), 'priority' => 10, 'panel' => 'sitepoint_demo_panel', 'description' => __( 'Section description.', 'superminimal' ), ) ); /** * Add a Section for Site Layout */ $wp_customize->add_section( 'superminimal_site_layout', array( 'title' => __( 'Site Layout', 'superminimal' ), 'priority' => 10, 'panel' => 'sitepoint_demo_panel', 'description' => __( 'Section description.', 'superminimal' ), ) ); /** * Add a Section for Footer Text */ $wp_customize->add_section( 'superminimal_footer_text', array( 'title' => __( 'Footer Text', 'superminimal' ), 'priority' => 10, 'panel' => 'sitepoint_demo_panel', 'description' => __( 'Section description.', 'superminimal' ), ) );Now you’re ready to add the first Kirki-powered option.
现在，您准备添加第一个Kirki驱动的选项。
All your options-related code is to be placed inside a function. This function is then filtered through the kirki/fields filter.
您所有与选项相关的代码都将放置在一个函数中。 然后通过kirki/fields过滤器过滤此功能。
function superminimal_demo_fields( $fields ) { //Add code here return $fields; } add_filter( 'kirki/fields', 'superminimal_demo_fields' );Let’s give your WordPress theme users an easy way to change text color. This is quickly done with Kirki. Add the following code snippet inside the superminimal_demo_fields() function, just above the return $fields; statement.
让我们为您的WordPress主题用户提供一种更改文本颜色的简便方法。 Kirki可以很快完成此操作。 在superminimal_demo_fields()函数内的return $fields;上方添加以下代码段return $fields; 声明。
/** * Add a Field to change the body text color in the Text Colors Section */ $fields[] = array( 'type' => 'color', 'setting' => 'superminimal_body_color', 'label' => __( 'Body Color', 'superminimal' ), 'description' => __( 'Description here', 'superminimal' ), 'section' => 'superminimal_text_colors', 'priority' => 10, 'default' => '#555555', 'output' => array( array( 'element' => 'body, p', 'property' => 'color' ), );Kirki offers a condensed syntax to add both a setting and a related control in one go.
Kirki提供了一种压缩语法，可以一次性添加设置和相关控件。
Let’s break down the $fields[] array.
让我们分解$fields[]数组。
type refers to the specific control where users enter the value of their chosen option, in this case the Color control.
type是指特定的控件，用户可以在其中输入所选选项的值，在本例中为“颜色”控件。
setting refers to the id of the Customizer setting that handles live-previewing, saving, and sanitization of the Customizer objects.
setting是指Customizer设置的id ，该id用于处理Customizer对象的实时预览，保存和清理。
label and description are there to communicate with users. The label displays a title for the option and the description offers some indication of what the option does.
label和description在那里与用户交流。 标签会显示该选项的标题，说明中会提供一些有关该选项功能的指示。
section refers to the id of the Section that hosts this specific Color control.
section是指托管此特定Color控件的Section的id 。
priority refers to the position of this specific Color control with respect to other controls inside the same Section.
priority是指此特定Color控件相对于同一Section内其他控件的位置。
default is set to the default CSS color value.
default设置为默认CSS颜色值。
Finally, output is the awesome Kirki way of applying the setting’s value. Just feed it the CSS selector and property, and Kirki handles all the necessary operations.
最后， output是应用设置值的绝佳Kirki方法。 只需将其提供给CSS选择器和属性，Kirki便会处理所有必要的操作。
Following the example above, you could go ahead and add a color option for links as well.
按照上面的示例，您可以继续为链接添加颜色选项。
Next, let’s give users of your theme the option to customize the site layout.
接下来，让您为主题的用户提供自定义网站布局的选项。
Kirki offers a bunch of sophisticated Customizer controls. My favorite one is the radio image control.
Kirki提供了许多复杂的Customizer控件。 我最喜欢的是无线电图像控件。
Here’s how you can add it to your theme to offer users the option of changing the layout of their site.
您可以通过以下方法将其添加到主题中，为用户提供更改其网站布局的选项。
/** * Add a Field to change the site layout */ $fields[] = array( 'type' => 'radio-image', 'setting' => 'superminimal_layout', 'label' => __( 'Site Layout', 'superminimal' ), 'description' => __( 'Description here', 'superminimal' ), 'section' => 'superminimal_site_layout', 'default' => 'fullwidth', 'priority' => 10, 'choices' => array( 'sidebar-left' => trailingslashit( get_template_directory_uri() ) . 'inc/kirki/assets/images/2cl.png', 'fullwidth' => trailingslashit( get_template_directory_uri() ) . 'inc/kirki/assets/images/1c.png', 'sidebar-right' => trailingslashit( get_template_directory_uri() ) . 'inc/kirki/assets/images/2cr.png', ), );Place the code above just after the previous $fields[] array snippet. Notice how no output parameter has been added to the code. This is so because the value of each radio image input is not a CSS property value.
将代码放在前面的$fields[]数组片段之后。 请注意，没有将output参数添加到代码中。 之所以如此，是因为每个无线电图像输入的值都不是CSS属性值。
The way you can extract the value from the superminimal_layout setting is by the native Customizer get_theme_mod method. You then use that value as a class attribute’s value of a suitable HTML element in the template file. Finally, it’s just a matter of writing the appropriate CSS to achieve the desired layout for the .fullwidth, .sidebar-left, and .sidebar-right classes in your stylesheet.
从superminimal_layout设置中提取值的方法是通过本机Customizer的get_theme_mod方法。 然后，您可以将该值用作模板文件中合适HTML元素的类属性值。 最后，只需编写适当CSS即可为样式表中的.fullwidth ， .sidebar-left和.sidebar-right类实现所需的布局。
Check out the details of how to implement the layout option in the Superminimal demo theme.
在“ 最小演示”主题中查看有关如何实现布局选项的详细信息。
How many times have you come across WordPress theme users asking you to help them replace whatever developers stuff in their theme’s footer area? Adding an option to let users easily manage the footer text from the Customizer takes a couple of minutes with Kirki. Here’s the code.
您遇到过WordPress主题用户多少次，要求您帮助他们替换主题页脚区域中的所有开发人员资料？ 添加选项使用户可以轻松地从“定制程序”管理页脚文本，而Kirki则需要花费几分钟的时间。 这是代码。
/** * Add a Field to change the footer text only if checkbox is checked */ $fields[] = array( 'type' => 'textarea', 'setting' => 'superminimal_footer_text', 'label' => __( 'Footer Text', 'superminimal' ), 'description' => __( 'Add some text to the footer', 'superminimal' ), 'section' => 'superminimal_footer_text', 'default' => 'Superminimal Theme – Kirki Toolkit Demo for SitePoint', 'priority' => 20, ), );The code above outputs a textarea where users can write copyright notices, credits, etc.
上面的代码输出一个文本区域，用户可以在其中编写版权声明，信用证等。
To extract and display the text entered in the textarea, use the native Customizer method get_theme_mod in footer.php as follows.
要提取并显示在textarea中输入的文本，请使用footer.php的本机Customizer方法get_theme_mod 。
<footer id="footer"> <?php echo get_theme_mod( 'superminimal_footer_text', __( 'Default text here', 'superminimal' ) ); ?> <?php wp_footer(); ?> </footer>Next, let’s check out what more Kirki can do to improve the user experience with the WordPress Customizer.
接下来，让我们看看Kirki还可以做些什么来改善WordPress Customizer的用户体验。
As a theme designer, you don’t like to overwhelm users with a plethora of confusing options. Some choices don’t need to be made until users pick some specific option. The Customizer offers the handy active_callback parameter for Panels, Sections and Controls. You can set this parameter to a specific condition that must be met before a Panel, Section, or Control is displayed in the Customizer.
作为主题设计师，您不喜欢用太多令人困惑的选项让用户不知所措。 在用户选择某些特定选项之前，无需做出某些选择。 定制器为面板，部分和控件提供了方便的active_callback参数。 您可以将此参数设置为在“定制器”中显示“面板”，“部分”或“控件”之前必须满足的特定条件。
What has Kirki to offer in this respect?
Kirki在这方面能提供什么？
The Kirki API uses the required parameter to hide or show a control in the Customizer on the basis of the value of another control.
Kirki API使用必需的参数根据另一个控件的值在定制程序中隐藏或显示控件。
For example, let’s say you’d like to show the textarea to let users modify the footer text only if they check a checkbox. To accomplish this, add the following code to the superminimal_footer_text control.
例如，假设您要显示文本区域，以使用户仅在选中复选框后才可以修改页脚文本。 为此，请将以下代码添加到superminimal_footer_text控件中。
'required' => array( array( 'setting' => 'superminimal_reveal_footer_text', 'operator' => '==', 'value' => 1, ), ),Adding the snippet above to the code for the textarea control ensures that the superminimal_reveal_footer_text control’s value is to be equal to 1 before the textarea control is displayed in the Customizer. Let’s add the superminimal_reveal_footer_text control to the superminimal_demo_fields() function.
将上面的代码段添加到textarea控件的代码中可确保在将textarea控件显示在定制程序中之前， superminimal_reveal_footer_text控件的值应等于1。 让我们将superminimal_reveal_footer_text控件添加到superminimal_demo_fields()函数中。
$fields[] = array( 'type' => 'checkbox', 'setting' => 'superminimal_reveal_footer_text', 'label' => __( 'Change Footer Text', 'superminimal' ), 'description' => __( 'Description here', 'superminimal' ), 'section' => 'superminimal_footer_text', 'default' => 0, 'priority' => 10, );The superminimal_reveal_footer_text control is a checkbox that by default is set to 0, that is, it’s unchecked. This prevents the textarea from being displayed.
superminimal_reveal_footer_text控件是一个复选框，默认情况下设置为0，即未选中。 这样可以防止显示文本区域。
Only after checking the checkbox, that is, by changing its value from 0 to 1, does the textarea appear in the Customizer.
仅在选中复选框后，即通过将其值从0更改为1，文本区域才会出现在定制程序中。
The Customizer comes with a powerful JavaScript API to add AJAX capability to the preview area. This enhancement allows users to check their modifications in real time without waiting for the entire Customizer preview page to refresh.
Customizer带有强大的JavaScript API ，可将AJAX功能添加到预览区域。 此增强功能使用户可以实时检查其修改，而无需等待整个Customizer预览页面刷新。
We can accomplish the same result with Kirki simply by adding a few handy parameters to the $fields[] array.
我们只需在$fields[]数组中添加一些方便的参数，就可以使用Kirki完成相同的结果。
For example, to add an ajaxified live preview to the superminimal_body_color setting, append the following snippet to the appropriate $fields[] array.
例如，要将ajaxified实时预览添加到superminimal_body_color设置中，请将以下代码段附加到适当的$fields[]数组中。
'transport' => 'postMessage', 'js_vars' => array( array( 'element' => 'body, p', 'function' => 'css', 'property' => 'color', ), )Let me explain what the code above does.
让我解释一下上面的代码的作用。
First, the code above changes the transport method from Refresh (the default), to postMessage. This signals to the Customizer that it must use JavaScript for the live preview.
首先，上面的代码将传输方法从Refresh (默认)更改为postMessage 。 这表明定制器必须使用JavaScript进行实时预览。
Next, the js_vars parameter values indicate that the body and p elements are to be modified using the CSS color property.
接下来， js_vars参数值指示将使用CSS color属性修改body和p元素。
Kirki offers two pre-defined values for the function parameter. Use the css value if the setting you’re adding stores CSS rules like background-color, color, font-size, etc. Use the html value if the setting stores a string of HTML markup to be inserted into the page.
Kirki为function参数提供了两个预定义的值。 如果要添加的设置存储CSS规则(例如background-color ， color ， font-size等)，则使用css值。如果设置存储要插入到页面中HTML标记字符串，则使用html值。
As example of how you can use the html value, let’s add AJAX live preview functionality to the setting that manages changes to the footer text. Append this snippet at the end of the $fields[] array that contains the superminimal_footer_text setting.
作为如何使用html值的示例，让我们向管理页脚文本更改的设置中添加AJAX实时预览功能。 将此代码段附加在包含superminimal_footer_text设置的$fields[]数组的末尾。
'transport' => 'postMessage', 'js_vars' => array( array( 'element' => 'footer', 'function' => 'html' ), ),That’s it, go and try writing something in the textarea inside the superminimal_footer_text section. You’ll soon notice the corresponding footer text in the preview screen change accordingly without a complete page reload. Cool!
就是这样，去尝试在superminimal_footer_text部分内的textarea中写一些东西。 您很快就会注意到预览屏幕中相应的页脚文本会相应更改，而无需重新加载完整的页面。 凉！
There may be cases where neither css nor html are a good fit for the function parameter that enables AJAX live preview. A case in point is the setting for changing the site layout. Using css as the value for the function parameter doesn’t make much sense because the setting in question doesn’t store any CSS property value. Likewise, using html doesn’t quite cut it. In fact, it’ll only end up spitting out fullwidth, sidebar-left, or sidebar-right on the preview page, depending on which radio-image control button is selected. But this can’t be what you’d like to accomplish.
在某些情况下， css和html都不适合启用AJAX实时预览的function参数。 一个典型的例子是用于更改站点布局的设置。 使用css作为function参数的值没有多大意义，因为相关设置不会存储任何CSS属性值。 同样，使用html并不能完全消除它。 实际上，它最终只会在预览页面上吐出fullwidth ， sidebar-left或sidebar-right ，这取决于选择了哪个无线电图像控制按钮。 但这不是您想要完成的。
The good news is that you can plug in a custom JavaScript function name as the value of the function parameter and it works!
好消息是，您可以插入自定义JavaScript函数名称作为function参数的值，它可以正常工作！
'js_vars' => array( array( 'element' => '#content', 'function' => 'superminimal_customizer_live_preview' ), ),You’ll need to enqueue the JavaScript file where your custom function lives and hook it to the customize_preview_init action hook.
您需要将自定义函数所在JavaScript文件放入队列，并将其挂钩到customize_preview_init操作挂钩。
function superminimal_customizer_live_preview() { wp_enqueue_script( 'superminimal_css_preview', get_template_directory_uri().'/js/superminimal-customizer-preview.js', array( 'customize-preview', 'jquery' ), '', true ); } add_action( 'customize_preview_init', 'superminimal_customizer_live_preview' );Finally, write the JavaScript function that handles the live preview using the native Customizer JavaScript API.
最后，使用原生的Customizer JavaScript API编写处理实时预览JavaScript函数。
(function( $ ) { "use strict"; wp.customize( 'superminimal_layout', function( value ) { value.bind( function( to ) { $( '#content' ).removeClass().addClass( to + ' clearfix' ); } ); }); })( jQuery );The great thing about Kirki is that you can use it together with, rather than in place of, the WordPress Customizer API. Therefore, where the situation requires it, you can easily switch between the two APIs in no time.
Kirki的优点在于您可以将其与WordPress Customizer API结合使用，而不是代替它。 因此，在情况需要时，您可以立即在两个API之间轻松切换。
Hungry for more? Here’s some great resources.
渴望更多？ 这里有一些很棒的资源。
Kirki Toolkit Documentation.
Kirki工具包文档 。
Building WordPress Themes Using the Kirki Customizer, by Aristeides Stathopoulos.
使用Kirki Customizer构建WordPress主题 ，作者：Aristeides Stathopoulos。
Theme Options – The Customizer API, from the WordPress.org Theme Handbook.
主题选项– WordPress.org主题手册中的Customizer API 。
I’ve shown how to integrate the Kirki Toolkit into a WordPress theme.
我已经展示了如何将Kirki Toolkit集成到WordPress主题中。
Kirki is actively being developed and supported. Its API and custom controls already significantly optimize the time it takes to develop Customizer theme options. This becomes especially important if you’re looking to have your theme listed in the WordPress.org themes repository. In fact, themes that provide customization options are required to do so via the Customizer rather than custom options pages.
Kirki正在积极开发和支持。 它的API和自定义控件已经大大优化了开发Customizer主题选项所需的时间。 如果您希望在WordPress.org主题存储库中列出您的主题，则这尤其重要。 实际上， 需要通过定制程序而不是定制选项页面来提供提供定制选项的主题。
To delve into the details of the code discussed in this post, feel free to download the Superminimal demo theme from GitHub.
要深入研究本文中讨论的代码的细节，请随时从GitHub下载Superminimal演示主题 。
I look forward to your feedback!
期待您的反馈！
翻译自: https://www.sitepoint.com/fast-wordpress-customizer-options-development-with-kirki/
wordpress 自定义
