为 Bricks 元素添加自定义控制字段

在本教程中，我们将学习如何为元素添加一个自定义控制字段，并在编辑器内动态修改某个 CSS 属性。如果你需要把代码放进 functions.php 或代码片段插件，可参考 在 Bricks 中使用 WPCodeBox 管理专属代码片段。

前言

在我看来，Bricks 中最被低估的过滤器之一就是 bricks/elements/{element_name}/controls。借助它，你几乎可以为任何已有元素添加任意控制字段，从而在需要某些尚未集成进编辑器的 CSS 属性时填补空白。

我在用 Bricks 建站时非常需要的一个 CSS 属性就是图片上的 aspect-ratio。可惜核心里并没有对应的控制。没关系，我们自己造一个！

可定制的元素清单

以下是你可以在 Bricks 中定制的全部元素：

// Layout
'container',
'section', // @since 1.5
'block', // @since 1.5
'div', // @since 1.5

// Basic
'heading',
'text-basic', // @since 1.3.6
'text',
'button',
'icon',
'image',
'video',

// General
'divider',
'icon-box',
'social-icons', // @since 1.4 (Label: Icon List)
'list',
'accordion',
'accordion-nested',
'tabs',
'tabs-nested', // @since 1.5
'form',
'map',
'alert',
'animated-typing',
'countdown',
'counter',
'pricing-tables',
'progress-bar',
'pie-chart',
'team-members',
'testimonials',
'html',
'code',
'template',
'logo',
'facebook-page',

// Media
'image-gallery',
'audio',
'carousel',
'slider',
'slider-nested',
'svg',

// WordPress
'wordpress',
'posts',
'pagination',
'nav-menu',
'sidebar',
'search',
'shortcode',

// Single
'post-title',
'post-excerpt',
'post-meta',
'post-content',
'post-sharing',
'related-posts',
'post-author',
'post-comments',
'post-taxonomy',
'post-navigation',

要定位我们想要修改的元素，只需在下面的函数中把 {element_name} 替换为上面清单里的某个名字：

add_filter( 'bricks/elements/{element_name}/controls', function( $controls ) {}

所以，既然我们的目标是给 image 元素添加一个新控制，我们的过滤器就是：add_filter( 'bricks/elements/image/controls', function( $controls ) {} 。

控制字段类型

Bricks 中共有 34 种不同的控制字段，从基础的数字控制，到日期选择器、滑块控制都有。你可以在这里找到完整的控制清单：https://academy.bricksbuilder.io/article/element-controls/ 。想了解每种控制的具体细节，点击表格里的任意标签即可。

在我们的示例中，我们将使用 number（数字）控制。

完整代码

我会通过在每一行上方加注释的方式，拆解这个过滤器的基本用法。

把下面的代码添加到你的 functions.php 文件，或你的代码片段插件中：

//change the {element_name} to the element you want to target
add_filter( 'bricks/elements/image/controls', function( $controls ) {
  // Set a name to the new control field - this has no impact on the builder experience
  $controls['aspectRatio'] = [
      // Tab under which to show the control. Accepts: content or style.
      'tab'      => 'content',
      // Set the label that will show up in the builder
      'label'    => esc_html__( 'Aspect Ratio', 'bricks' ),
      // Choose a type of field
      'type'     => 'number',
      // Set your CSS property and Selector
      'css'         => [
        [
          // the CSS property you want to add
          'property' => 'aspect-ratio',
          // the CSS selector where the property should be applied - blank targets the root of the element
          'selector' => '',
        ],
        // You can target multiple selectors at once. Now we'll target the img tag
        [
          'property' => 'aspect-ratio',
          'selector' => 'img',
        ],
      ],
      // Set false for unitless
      'units' => false,
      // Set the increasing/decreasing value
      'step' => '0.01',
      // Set the default control value.
      'default' => 1,
      // Set to true to show control label and input on the same line.
      'inline' => false,
  ];

  return $controls;
} );

效果与取值

现在刷新编辑器，我们就能在 image 元素的 content（内容）标签页里看到新添加的 Aspect Ratio（宽高比）控制：

恭喜！你刚刚创建了自己在 Bricks 中的第一个自定义控制！

用户在控制字段中输入的值，可以通过

$element->settings["aspectRatio"]

在 bricks/element/settings 过滤器的函数中取出，用于元素的输出。

小结

bricks/elements/{name}/controls 过滤器是扩展 Bricks 编辑器能力的关键入口：你只需声明控制的 tab、label、type 以及对应的 css 属性与选择器，就能为任意元素补齐官方未集成的 CSS 控制（如 aspect-ratio）。要取用用户输入的值，则通过 $element->settings["aspectRatio"] 即可。

站长

Ray Chan

WordPress Developer & Bricks Specialist

WordPress developer with 10+ years of client builds. Switched to Bricks in 2023 — now builds fast WordPress sites and migrates legacy Elementor/Divi projects.

获取报价 →浏览全部教程