跳转到正文

useBlockProps

默认情况下,Gutenberg 必须在区块外创建包装器,才能使区块在编辑器中具有交互性。对于容器或列等某些区块类型,这可能造成问题,因为编辑器与前端的标记会有所不同。useBlockProps 钩子可将区块模板中的某个元素标记为根元素,从而使编辑器与前端的标记保持一致。

用法

只需将 useBlockProps 属性添加到区块的根元素即可。

PHP
<div useBlockProps class="my-class">
  <!--
  This element will be rendered
  as the root element of your block
  in Gutenberg.
  -->
</div>

Blockstudio 会自动合并编辑器中的类和属性(例如对齐类)与区块模板中定义的内容。此过程在底层使用 get_block_wrapper_attributes。

blockstudio/blocks/components/use_block_props/render 过滤器会同时应用于前端和编辑器渲染路径中的包装器。因此,主题或单个实例集成添加的类也会出现在编辑器画布和已保存的前端标记中。

输出:

HTML
<div class="my-class wp-block-your-block-name alignright">
</div>

注意事项

Blockstudio 会阻止区块编辑器中的链接导航,包括 target="_blank"、按住修饰键单击、中键单击和键盘激活。 点击事件仍会传递给 Gutenberg,因此普通单击会选中区块。 RichText 仍可编辑。无论是否使用 useBlockProps,此行为都适用, 包括将锚点用作区块的根元素时。

前端链接和浏览器的上下文菜单命令保持不变。你无需从模板中移除链接,也无需根据 $isEditor 进行条件处理。

根元素

由于区块模板只能有一个根元素,使用 useBlockProps 时,区块模板必须只有一个根元素。例如,以下写法无法正常工作,Gutenberg 会在模板外创建包装器。

PHP
<div useBlockProps>
  First root element.
</div>
<span>
  Second root element.
</span>

同样,useBlockProps 在每个区块模板中只能使用一次。

@ 符号

Blockstudio 会使用 html-react-parser 将区块模板转换为 Gutenberg 中的有效 React 代码。受此限制影响,@ 字符不能用于 HTML 属性名称。

诸如 Alpine.js 这样的库会使用 @ 字符在 HTML 元素上定义指令。

PHP
<button useBlockProps @click="console.log('hi')">
  Click me
</button>

在 Gutenberg 中,此 @click 属性会从元素中剥离。(当然,它在前端仍会生效)

为解决此问题,你可以使用 Alpine.js 提供的替代语法。

PHP
<button useBlockProps x-on:click="console.log('hi')">
  Click me
</button>

上述写法在 Gutenberg 内和前端都能正常工作。

画布主体类

启用 assets.reset.enabled 后,Blockstudio 也会将 WordPress 的 body_class 过滤器返回的已清理类复制到区块编辑器画布。这样一来,诸如 .brand-a .site-card 这样的主题选择器就能在两处正常工作。

当编辑器需要更精简的类集合时,过滤最终类列表:

PHP
add_filter('blockstudio/editor/canvas/body_class', function(array $classes) {
  return array_values(array_diff($classes, ['logged-in']));
});

此过滤器仅控制复制到编辑器画布的类,不会更改前端主体类。