块变化是扩展WordPress并为用户策划编辑体验的最有力方法之一。在本文中,您将学习如何有效地创建块变体并发现将它们纳入工作流程中的方法。让我们开始吧。
目录
块变化API
块变化API允许您创建其他版本的现有块的其他版本,这些版本因一组初始属性或内部块而不同。
变体由包含一组属性的对象定义。我将介绍本文中许多最重要的属性,您可以在 块变化API 文档。
- 名称(类型字符串) – 唯一且可读的名称。
- 标题(可选,类型字符串) – 人类可读变体标题。
- 图标(可选,类型字符串|对象) – 编辑UI中变化的图标。
- 属性(可选,类型对象) – 覆盖原始块的默认属性的值。
- InnerBlocks(可选,类型Array []) – 嵌套块的初始配置。
- isDefault(可选,键入布尔值) – 默认为false。指示当前变化是否为默认变化。
- ISACTIVE(可选的,类型函数| String []) – 用于确定块时变化是否活动的函数或块属性数组。功能接受
blockAttributes
和variationAttributes
。
定义后,可以使用函数创建变体registerBlockVariation()
或未注册unregisterBlockVariation()
。下面的示例演示了如何使用两者。
在块注册期间,也可以声明变化。参考 块注册API 更多细节。如果您要构建自定义块并希望提供其他变体,则此方法很有用。
设置
块变体在JavaScript中注册,因此您首先需要创建一个JavaScript文件。
我将假设您想在主题中添加块变体,但是这种方法可以很容易地适应插件。唯一真正的区别是文件和功能的位置。现在,让我们创建variations.js
并将文件放在我们的主题中assets/js
文件夹。
接下来,您需要入选variations.js
使用 enqueue_block_editor_assets
钩子和标准 wp_equeue_script()
功能。此代码通常应放在您的主题中functions.php
文件,除非您具有更高级的设置。
function example_enqueue_block_variations() {
wp_enqueue_script(
'example-enqueue-block-variations',
get_template_directory_uri() . '/assets/js/variations.js',
array( 'wp-blocks', 'wp-dom-ready' ),
wp_get_theme()->get( 'Version' ),
false
);
}
add_action( 'enqueue_block_editor_assets', 'example_enqueue_block_variations' );
注意wp-blocks
和wp-dom-ready
被列为依赖项。这些将用于在以下步骤中注册和注册块变化,但是现在的设置已完成。
WordPress开发人员博客通常使用 esnext语法 用于JavaScript示例。但是,由于通常会在不包括一个主题中添加块变体 构建过程,此处的示例将使用普通的JavaScript。如果您的项目已经具有构建过程,请随时使用Esnext。可以在 超越块样式,第1部分:使用WordPress脚本包与主题。
创建块变化
与variation.js
提示的文件,您现在可以使用 registerBlockVariation()
功能。此功能来自 wp-blocks
我较早地添加到临界函数的依赖性,可以通过将函数的前缀与wp.block.
,或像这样:
const { registerBlockVariation } = wp.blocks;
registerBlockVariation( ... );
使用您喜欢哪种方法 – 我会使用wp.blocks.registerBlockVariation()
在本文中。
这registerBlockVariation()
函数接受原始块的名称和定义要创建的变化的对象。让我们看看一个例子。
wp.blocks.registerBlockVariation(
'core/media-text',
{
name: 'media-text-custom',
title: 'Media & Text Custom',
attributes: {
align: 'wide',
backgroundColor: 'tertiary'
},
}
);
上面的代码注册了媒体和文本块的块变化(core/media-text
)。我给了它一个独特的name
和title
,并设置了一些属性值。当将此变化插入编辑器时,它将是宽对齐的媒体和文本块,背景颜色设置为tertiary
。
尽管我建议反对这种做法,但您可以从技术上创建一个无唯一名称的块变化。一个特别的name
允许编辑器区分您的变化和可能存在的其他变化。
当使用二十三个主题时,这种变化将出现这样的变化:
您可能已经注意到,媒体和文本块和“媒体和文本自定义”变体都出现在插入器中。这是正确的结果,但是您可以添加属性isDefault: true
用您的变化代替原始块。当您想修改核心块或第三方块的初始状态时,此方法会派上用场。
让我们更新示例,以使变化成为默认值。通过这种更改,媒体和文本块始终宽对齐,并在插入时具有背景颜色。
wp.blocks.registerBlockVariation(
'core/media-text',
{
name: 'media-text-default',
title: 'Media & Text',
attributes: {
align: 'wide',
backgroundColor: 'tertiary'
},
isDefault: true
}
);
由于现在的变化为默认值,因此我将标题更改回“媒体和文本”,而插入者现在只会显示一个媒体和文本块。从用户角度来看,他们只是使用默认块。
当您使用时还有其他注意事项isDefault
,特别是如果该块已经将另一个变体设置为isDefault
。参考 文档 了解更多信息。
未注册的块变化
许多核心WordPress块实际上都是变化。例如,组块具有 四个变化:组,行,堆栈和网格(实验)。嵌入和社交图标块也是一个很好的例子。
有时,您可能不需要网站上的某些块变化。删除这些选择可以简化插入器并改善用户体验。为了实现这一目标,请使用 unregisterBlockVariation
功能。只需提供原始块名和变体name
您想删除。
以下代码未注册堆栈块。
wp.domReady( () => {
wp.blocks.unregisterBlockVariation( 'core/group', 'group-stack' );
});
使用 wp.domReady
在不注册核心块时需要。没有它,功能启动过早,并且变化永远不会删除。尽管wp.domReady
不需要注册某些第三方块,这是一个好主意,最好始终如一地使用它。注册块变化不需要wp.domReady
。
用内部块创建变体
现在,让我们返回上面的媒体和文本示例。虽然此块变体设置了align
和backgroundColor
属性,如果要将默认内容添加到块的文本部分,该怎么办?
我们可以使用innerBlocks
属性,该属性使您可以指定一个块数组,以包含在插入后的变化中。您还可以设置这些内部块的属性。
在下面的示例中,我在原始示例中添加了标头和一个段落块。这些中的每一个都有一个占位符。这将帮助用户更加一致地创建内容。
wp.blocks.registerBlockVariation(
'core/media-text',
{
name: 'media-text-default',
title: 'Media & Text',
attributes: {
align: 'wide',
backgroundColor: 'tertiary'
},
innerBlocks: [
[
'core/heading',
{
level: 3,
placeholder: 'Heading'
}
],
[
'core/paragraph',
{
placeholder: 'Enter content here...'
}
],
],
isDefault: true,
}
);
插入时,块变化现在看起来像这样:
这innerBlocks
属性仅适用于包含其他块的块。但是,当与块和模板锁定结合使用时,此功能可能会非常强大。虽然锁定超出了本文的范围,但您可以在 策划编辑体验 指导。
使用isActive
财产
接下来是isActive
属性,可以帮助编辑器确定变化是否活跃。
为了说明该属性的工作原理,让我们创建一个称为文本和媒体的新块变体。它将类似于上一个示例,但是当插入时,文本将在左侧,右侧的图像。此行为是使用属性定义的mediaPosition: 'right'
。
wp.blocks.registerBlockVariation(
'core/media-text',
{
name: 'text-media',
title: 'Text & Media',
attributes: {
align: 'wide',
backgroundColor: 'tertiary',
mediaPosition: 'right'
}
}
);
该变化将按预期出现在插入器中与默认媒体和文本块一起出现。但是,插入变化后,如果用户再次选择块,它将标记为“媒体和文本”而不是“文本和媒体”。
这种错误标签之所以发生,是因为编辑器无法区分变化和原始媒体和文本块。如果变化具有自定义,则问题会加剧description
和icon
属性,可能会给用户造成混乱。
这isActive
属性提供解决方案,并接受函数或属性字符串。我将在这里使用数组符号,但是您可以参考 块变化API 功能示例的文档。
文本和媒体变化在很大程度上由mediaPosition
属性,让我们设置isActive: [ ‘mediaPosition’ ]
。
wp.blocks.registerBlockVariation(
'core/media-text',
{
name: 'text-media',
title: 'Text & Media',
attributes: {
align: 'wide',
backgroundColor: 'tertiary',
mediaPosition: 'right'
},
isActive: [ 'mediaPosition' ]
}
);
使用此属性,编辑器将将所选媒体和文本块的属性与任何注册变体进行比较。如果发现有一个变化mediaPosition
与所选块匹配的属性,mediaPosition: 'right'
在这种情况下,它将了解用户选择文本和媒体变化。该块的描述性信息将相应更新。
如果您在数组中列出了多个属性,则将检查每个属性。当它们都匹配时,这种变化只会被视为“活动”。
添加自定义图标
为了保持简单,以前的示例没有自定义图标。但是,给出块变化的图标是提高其在插入者中发现性的好方法。您可以使用icon
属性,将字符串或对象。
使用字符串时,必须与 达西孔。没有其他字符串会起作用。例如,WordPress图标的dashicon slug是dashicons-wordpress
。去除dashicons-
前缀和设置icon: ‘wordpress’
使用此图标。结果看起来像这样:
在大多数情况下,您可能需要添加自定义SVG图标而不是dashicon。这可以通过将对象传递给icon
财产。
回顾前面创建的文本和媒体示例,图标并不能准确代表块变化的默认状态。媒体应在右边,而不是左边。
图像右侧的图标是使用原始媒体和文本图标创建的,并在无花果中进行了一些操纵。请注意,自定义图标通常应为24像素平方。以下是SVG代码。
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
<path d="M21 17.5L21 6L13 6L13 17.5L21 17.5ZM10 14.5L3 14.5L3 16L10 16L10 14.5ZM3 11L10 11L10 12.5L3 12.5L3 11ZM10 7.5L3 7.5L3 9L10 9L10 7.5Z"></path>
</svg>
您可以浏览完整的WordPress图标库 组件故事书,然后使用浏览器检查器提取SVG代码。
下一步是将此SVG添加到icon
属性作为对象。使用普通JavaScript而不是Esnext注册块变化时,此符号可能很棘手。您可以在GitHub上探索核心块的源代码,以获取大量ESNEXT 语法示例,在这种情况下不会涵盖。
使用普通JavaScript添加自定义SVG的最简单解决方案是利用WordPress的内置组件和功能 – 类似于您已经在做的事情registerBlockVariation
,unregisterBlockVariation
,和domReady
。
在您的顾问功能中functions.php
文件,添加依赖项 wp-element
和 wp-primitives
。然后您可以使用createElement
,SVG
,和Path
创建图标对象。
const textMediaIcon = wp.element.createElement(
wp.primitives.SVG,
{ xmlns: "http://www.w3.org/2000/svg", viewBox: "0 0 24 24" },
wp.element.createElement(
wp.primitives.Path,
{
d: "M21 17.5L21 6L13 6L13 17.5L21 17.5ZM10 14.5L3 14.5L3 16L10 16L10 14.5ZM3 11L10 11L10 12.5L3 12.5L3 11ZM10 7.5L3 7.5L3 9L10 9L10 7.5Z",
}
)
);
该代码看起来可能有些复杂,但将其与上面的原始SVG标记进行比较,您将能够发现相似之处。
最后,设置icon: textMediaIcon
,结果看起来像这样:
将所有这些放在一起
结合本文的所有示例,您的最终variations.js
文件将:
- 添加具有内部块和彩色背景的媒体和文本块变化
isDefault
。 - 使用自定义图标添加文本和媒体块变化
isActive
。 - 取消注册组块的核心堆栈变体。
这是完整的文件:
// Register a new default Media & Text block variation.
wp.blocks.registerBlockVariation(
'core/media-text',
{
name: 'media-text-default',
title: 'Media & Text',
attributes: {
align: 'wide',
backgroundColor: 'tertiary'
},
innerBlocks: [
[
'core/heading',
{
level: 3,
placeholder: 'Heading'
}
],
[
'core/paragraph',
{
placeholder: 'Enter content here...'
}
],
],
isDefault: true,
}
);
// Define the icon for the Text & Media block variation.
const textMediaIcon = wp.element.createElement(
wp.primitives.SVG,
{ xmlns: "http://www.w3.org/2000/svg", viewBox: "0 0 24 24" },
wp.element.createElement(
wp.primitives.Path,
{
d: "M21 17.5L21 6L13 6L13 17.5L21 17.5ZM10 14.5L3 14.5L3 16L10 16L10 14.5ZM3 11L10 11L10 12.5L3 12.5L3 11ZM10 7.5L3 7.5L3 9L10 9L10 7.5Z",
}
)
);
// Register the Text & Media block variation.
wp.blocks.registerBlockVariation(
'core/media-text',
{
name: 'text-media',
title: 'Text & Media',
icon: textMediaIcon,
attributes: {
align: 'wide',
backgroundColor: 'tertiary',
mediaPosition: 'right'
},
isActive: [ 'mediaPosition' ]
}
);
// Unregister the Stack block variation.
wp.domReady( () => {
unregisterBlockVariation( 'core/group', 'group-stack' );
});
最后,这个variations.js
应该在您的主题的functions.php
提交必要的依赖项。
function example_enqueue_block_variations() {
wp_enqueue_script(
'example-enqueue-block-variations',
get_template_directory_uri() . '/assets/js/variations.js',
array( 'wp-blocks', 'wp-dom-ready', 'wp-element', 'wp-primitives' ),
wp_get_theme()->get( 'Version' ),
false
);
}
add_action( 'enqueue_block_editor_assets', 'example_enqueue_block_variations' );
本文仅刮擦了可以通过块变化来完成的表面,但是您现在拥有基础知识,因此是时候开始尝试自己了。考虑如何在下一个项目中使用变化,并与社区分享您的实现。
如果您想查看本文的后续示例,请在评论中告诉我。