WordPress中文开发手册

  2. Home
  4. Docs
  6. WordPress中文开发手册
  8. WordPress主题开发
  10. 主题选项 – 自定义API
  12. JavaScript / Underscore.js渲染的自定义控件

JavaScript / Underscore.js渲染的自定义控件

WordPress 4.1还增加了JavaScript的重载和/或高数量控件的支持。 这允许更多的动态行为，特别是与动态添加的控件相关。 核心的Color和Media控件目前正在利用此API，而所有核心控件最终将在未来使用它。 基于PHP的控制API不会消失，但是在将来，大多数控件可能会使用新的API，因为它为用户和开发人员提供了更快的体验。 JS模板化部分和面板的类似API被引入WordPress 4.3; 然而，在Word中，JS中动态创建对象的容易性仍然存在一些差距，见＃30741。

注册控制类型

为了引入一个具有相同类型的多个Customizer控件的模板的概念，我们需要引入一种使用Customize Manager注册控件类型的方法。 以前，仅当使用WP_Customize_Manager :: add_control（）添加了自定义控件时才会遇到自定义控件对象。 但检测添加的控件类型以每种类型呈现一个模板将不允许动态创建新的控件，如果没有加载该类型的其他实例。 WP_Customize_Manager :: register_control_type（）解决这个问题：

add_action( 'customize_register', 'prefix_customize_register' );
function prefix_customize_register( $wp_customize ) {
  // Define a custom control class, WP_Customize_Custom_Control.
  // Register the class so that its JS template is available in the Customizer.
  $wp_customize->register_control_type( 'WP_Customize_Custom_Control' );
}

所有注册的控件类型都将模板打印到定制器中

WP_Customize_Manager::print_control_templates().

发送PHP控制数据到JavaScript

虽然Customizer控件的数据一直被传递给控件JS模型，并且一直能够被扩展，但在使用JS模板时，更有可能需要发送数据。 您需要在PHP中的render_content（）中访问的任何内容都需要导出到JavaScript才能在控件模板中访问。 WP_Customize_Control默认导出以下控件类变量：

  • type
  • label
  • description
  • active (boolean state)

您可以通过覆盖自定义控件子类中的WP_Customize_Control :: to_json（）来添加特定于您的自定义控件的其他参数。 在大多数情况下，您还需要调用父类'to_json（）方法，以确保所有核心变量也被导出。 以下是核心颜色控制的一个例子：

public function to_json() {
  parent::to_json();
  $this->json['statuses'] = $this->statuses;
  $this->json['defaultValue'] = $this->setting->default;
}

JS /下划线模板

将自定义控件类注册为控件类型并导出任何自定义类变量后，可以创建将呈现控件UI的模板。 您将覆盖WP_Customize_Control :: content_template（）（默认为空）作为WP_Customize_Control :: render_content（）的替代。 渲染内容仍然被调用，所以请确保在子类中使用空的函数覆盖它。

下划线风格的自定义控件模板与PHP非常相似。 随着越来越多的WordPress核心成为JavaScript驱动，这些模板越来越普遍。 核心中的一些示例模板代码可以在媒体，修订版本，主题浏览器以及Twenty Fifteen主题中找到，其中使用JS模板来同时保存配色方案数据，并立即预览定制程序中的配色方案更改。 了解这些模板如何工作的最好方法是研究核心中的类似代码，因此，这里是一个简单的例子：

class WP_Customize_Color_Control extends WP_Customize_Control {
  public $type = 'color';
// ...
  /**
   * Render a JS template for the content of the color picker control.
   */
  public function content_template() {
    ?>
    <# var defaultValue = '';
    if ( data.defaultValue ) {
      if ( '#' !== data.defaultValue.substring( 0, 1 ) ) {
        defaultValue = '#' + data.defaultValue;
      } else {
        defaultValue = data.defaultValue;
      }
      defaultValue = ' data-default-color=' + defaultValue; // Quotes added automatically.
    } #>
    <label>
      <# if ( data.label ) { #>
        <span class="customize-control-title">{{{ data.label }}}</span>
      <# } #>
      <# if ( data.description ) { #>
        <span class="description customize-control-description">{{{ data.description }}}</span>
      <# } #>
      <div class="customize-control-content">
        <input class="color-picker-hex" type="text" maxlength="7" placeholder="<?php esc_attr_e( 'Hex Value' ); ?>" {{ defaultValue }} />
      </div>
    </label>
    <?php
  }
}

在上述核心自定义颜色控件的模板中，您可以看到在关闭PHP标签后，我们有一个JS模板。 用于评估语句的符号 - 在大多数情况下，这用于条件。 我们导出到JS的所有控件实例数据存储在data对象中，我们可以使用double（转义）或三（未转义）括号表示法{{}}打印一个变量。 正如我之前所说，获得这种写作控制的最佳方式是阅读现有的例子。 WP_Customize_Upload_Control最近更新了，以利用此API，并且与媒体管理器的实现方式完美结合，并从最少量的代码中挤出大量功能。 如果您想要一些非常好的做法，请尝试转换一些其他核心控件来使用此API，当然也可以将修补程序提交给核心。

放在一起

以下是在自定义定制程序控件子类中使用新API所需的内容的摘要：

使你的render_content（）函数为空（但它需要存在才能覆盖默认值）。
创建一个新的函数content_template（），并将render_content（）的旧内容放在那里。
通过修改to_json（）函数（参见WP_Customize_Color_Control作为示例）），将控件导出到浏览器中的JavaScript（JSON数据）所需的任何自定义类变量。
将PHP从render_content（）转换为JS模板，使用JS语句来评估和{{}}关于要打印的变量。 PHP类变量在数据对象中可用;例如，可以使用{{data.label}}打印标签。
注册自定义控件类/类型。此关键步骤告诉Customizer打印此控件的模板。这与所添加的所有控件的打印模板不同，因为这些想法是可以从一个模板呈现该控件类型的许多实例，并且任何已注册的控件类型将在将来可用于动态控制创建。只要做一些像$ wp_customize-> register_control_type（'WP_Customize_Color_Control'）;.
自定义API中仅PHP的部分仍然完全支持，使用非常好。但是，为了使定制工具更加灵活，在定制程序中切换主题而没有页面加载的长期目标，强烈建议您在可行的情况下为所有自定义定制器对象使用JS / Underscore模板。