新的wordpress编辑器古腾堡(代号 Gutenberg)将于 5.0 版中发布。现在是在它登陆 WordPress 核心之前掌握它的最佳时机。在本系列中,我将向您展示如何使用 Block api并创建您自己的内容块,您可以使用这些内容块来构建您的帖子和页面。
如果您还记得,我们的自定义块在前端和后端呈现不同,以证明您可以完全控制块在编辑器中的呈现方式以及站点访问者如何查看块。
如果您一直在关注,请打开 块源代码所在的/wp-content/plugins/my-custom-block/src/block文件夹。该文件夹包含一个javascript文件和两个 Sass 文件,它们控制块的行为以及它在编辑器和前端的呈现方式。
block.js
JavaScript 文件包含jsx,它在构建过程中被转译成有效的 javaScript 。同样,这两个 Sass 文件被转换为标准css。
在构建过程中,这些文件需要处理以在插件的dist/ 文件夹中创建分发文件。这些是 WordPress 排队的实际文件,因为它们包含所有浏览器都可以理解的有效 JavaScript 和 CSS。
幸运的是,该create-guten-block
工具包通过监视块文件的更改来为我们处理构建和转译。这是一个非常好的功能,因为它是我们需要担心的一件事。我们可以只专注于编写我们的代码块(和样式),插件文件都会自动更新。好的!
只需确保npm start
从插件根文件夹中运行命令即可触发文件监视。
是时候编辑一些代码了!
暂时不要担心jsx代码的block.js
细节,稍后我们将详细介绍。现在,让我们专注于对前端和后端视图的块输出进行一些简单的更改。
打开block.js,找到edit
传递给 的第二个参数的对象的方法registerBlockType()
,并将其替换为以下内容:
edit: function( props ) { return ( <div className={ props.className }> <h3>Editor View</h3> <p>This is our custom block inside the editor.</p> <p>Let's add an unordered list!</p> <ul> <li>Apple</li> <li>Orange</li> <li>Pear</li> <li>Plum</li> </ul> </div> ); },
此方法控制块在编辑器窗口中的呈现方式。现在找到该save
方法并将其替换为:
save: function( props ) { return ( <div> <h3>Frontend View</h3> <p>This is our custom block as seen by site visitors.</p> <p>Let's add an ordered list!</p> <ol> <li>Red</li> <li>Blue</li> <li>Pink</li> <li>Brown</li> </ol> </div> ); },
此方法用于在前端渲染块输出。
在style.scss中,将所有样式替换为:
.wp-block-cgb-block-my-custom-block { background: #a7d9f1; color: #ffffff; border: 1px solid #62afd4; border-radius: 15px; margin: 0 auto; max-width: 740px; padding: 1.5rem; ol, ul { margin-left: 20px !important; } li { margin-bottom: 0; } h3 { color: #ffffff; margin-top: 0; } }
然后,在editor.scss中,将所有样式替换为:
.wp-block-cgb-block-my-custom-block { background: #cba7f1; border: 1px solid #a170d6; }
您可以在下面的屏幕截图中看到这些更改如何影响我们的块的渲染,具体取决于我们是在编辑器窗口还是前端查看它。
我们暂时不会介绍对块脚本进行排队,但现在知道editor.scss 样式仅应用于编辑器窗口并且style.scss 被添加到编辑 器窗口和前端就足够了。因此,可以从style.scss中省略同时在编辑器和前端中使用的 样式。
注意在 Sass 文件中我们如何引用一个冗长的 CSS 选择器来定位我们的块元素。
.wp-block-cgb-block-my-custom-block
这个类由 Gutenberg 自动添加到前端的块容器元素中,但我们必须在编辑器窗口中手动应用它才能获得相同的类,如下面的edit
方法所示。
<div className={ props.className }> <!-- 块代码放在这里 --></div>
Gutenberg 生成的类名确定如下: wp-block-[block namespace]-[block name
.
在我们的例子中,我们使用create-guten-block
工具包来创建我们的块,它cgb
默认用于命名空间,并且block-my-custom-block
基于我们指定的块名称。这导致 CSS 类名称wp-block-cgb-block-my-custom-block
被添加到块容器中。Gutenberg 内部使用命名空间和块名称来唯一标识块。
在那里进行更改以阻止文件时,我发现了一些值得一提的痛点。
首先,在对方法进行更改时edit
,我发现自己必须在刷新编辑器窗口之前清除浏览器缓存才能看到最新的更改。这种情况并非一直发生,但经常发生。如果您发现同样的事情发生在您身上,只需清除浏览器缓存并重试。
其次,在编辑save
方法的内容时,下次刷新时编辑器窗口似乎发生了一些奇怪的事情。
为了证明这一点,我<li>Indigo</li>
在方法中添加了一个新的列表项 ( ),save
然后刷新了帖子编辑器(当然,在必须再次清除缓存之后!)。结果如下:
如果您选择转换为块 或编辑为 html, 那么您将看到方法的内容,该save
方法旨在在前端而不是在编辑器中查看。
这非常令人困惑,使事情恢复正常的唯一明显方法是从编辑器窗口中删除该块并重新插入。正如我在上一篇文章中提到的,古腾堡仍在进行中,这是一个很好的例子!
希望这将在未来的版本中变得更加直观,但现在这只是需要注意的事情。更改save
功能时,请准备好删除编辑器窗口中的相关块并重新添加它们。
如前所述,save
andedit
方法的输出可能完全不同。但是,在大多数情况下,您可能希望前端输出与编辑器输出匹配,以便编辑体验与前端渲染尽可能一致。
在我们上面的人为示例中,我只是在编辑器和前端视图中添加了不同的内容和样式,用于演示目的。
块 API 概述
Block API 由一组添加到全局wp
管理对象的 JavaScript 对象组成。而且因为wp
是全球性的,我们不需要在我们的源代码中专门导入它——它可以按需提供。
可用的对象wp
取决于您当前正在查看的管理页面。例如,如果您正在自定义您的站点,则wp
包含主自定义程序 API 对象。
然而,目前,Gutenberg Block API 仅在帖子编辑器上可用。我预计,当帖子编辑器和站点定制器之间的集成越来越紧密时,这将在未来发生变化。
您可以wp
通过打开 Gutenberg 编辑器并wp
在浏览器控制台中输入来查看结构。
如您所见, wp
包含许多对象,但我们最感兴趣的是:
wp.elements
wp.blocks
wp.components
wp.data
wp.i18n
这些对象使您可以访问创建一些非常复杂的块所需的所有工具。尝试在浏览器控制台中输入它们的完整对象名称以进一步探索这些对象。
例如,如果您输入wp.blocks
并展开对象,您会看到其中一个可用的函数是registerBlockType()
. 这是一个非常重要的功能,我们将在下一篇文章中深入介绍
wp.elements
对象_
这个对象是 react(和 React dom )之上的抽象层,它以可预测和一致的方式公开 React 功能。即使底层实现被完全改变或改变,这仍然是正确的。
只要界面保持不变,以后与 Block API 交互的插件就不会受到影响。
wp.blocks
对象_
创建块 ( registerBlockType()
)的核心功能wp.blocks
与一般块管理所需的其他功能一起包含在其中,例如:
getBlockType()
getBlockContent()
getBlockAttributes()
hasBlockSupport()
isValidBlock()
此对象还包含一组可重用的块,您可以将它们包含在自己的块中,以提供无需额外开销的功能。这些开箱即用的块可以显着加快块开发,我们将在下一篇文章中使用其中一些,因为我们将进一步深入研究块创建。
一些可用的有:
wp.components
对象_
该wp.components
对象还包含可重用的组件,但这些组件更通用,通常用于在编辑器窗口中创建其他 UI 元素,例如用于块设置的控制面板。
这些包括:
按钮
复选框
代码编辑器
破折号图标
约会时间
落下
菜单项
单选按钮
范围控制
wp.data
对象_
数据模块管理 Gutenberg 编辑器中的应用程序状态,其中包括存储每个块的设置。我们将在本系列的最后一篇文章中介绍可以将设置添加到块的不同方法。
wp.data
是在redux之上实现的,所以当 Gutenberg 与 core 合并时,我们不仅可以访问 React,还可以访问由 Redux 提供支持的完整集中式数据存储!
wp.i18n 对象
多年来,插件和主题已经能够轻松地翻译php字符串,并且由于该wp.i18n
对象,也可以使用类似的方法在 JavaScript 中翻译字符串。这意味着您的块中包含的所有字符串(包括块名称、关键字和标签)都可以翻译成任何语言。
如果您以前使用过标准的 PHP 翻译功能,那么您会感到宾至如归,因为过程几乎相同。我认为这是一个聪明的举措,因为它将鼓励开发人员从一开始就在他们的块中启用字符串翻译。
在您的块代码中,翻译字符串非常简单:
wp.i18n.__( 'This string is translatable', 'text-domain' );
结论
在本教程中,我们实现了一个基本块并编辑了代码。我们还看到我们可以完全控制块渲染,并且与前端相比,在编辑器中可以有不同的块视图。
编辑器仍然有一些问题不时让您感到惊讶——这提醒您,古腾堡仍在开发中,可能还没有准备好在生产站点上使用。
最后,我们以块 API 的概述结束,它在全局wp
JavaScript 对象上引入了几个新对象来创建和管理块。
- wp.elements对象_
- wp.blocks对象_
- wp.components对象_
- wp.data对象_
- wp.i18n 对象