新的WordPress编辑器(代号Gutenberg)将于5.0版中发布。 现在是掌握它的完美时机,然后它才能进入WordPress核心。 在本系列中,我将向您展示如何使用Block API并创建自己的内容块,您可以使用这些内容块来构建帖子和页面。
如果您还记得的话,我们的自定义块在前端和后端的显示方式有所不同,以证明您完全控制了块在编辑器中的呈现方式以及网站访问者如何看到该块。
![图片:https://cms-assets.tutsplus.com/uploads/users/1527/posts/31057/image/2.1.png Default views for our custom block](https://i-blog.csdnimg.cn/blog_migrate/1d09c74dc68d9e0d0fc74a38a1eb0d62.png)
如果您一直在遵循,请打开/ wp-content / plugins / my-custom-block / src / block文件夹,该文件夹位于块源代码所在的位置。 该文件夹包含一个JavaScript文件和两个Sass文件,它们控制该块的行为以及它在编辑器内部和前端的呈现方式。
![图片:https://cms-assets.tutsplus.com/uploads/users/1527/posts/31057/image/2.2.png Block source code files](https://i-blog.csdnimg.cn/blog_migrate/dc678a004adfcf3123d197081c35a155.png)
block.js
JavaScript文件包含JSX ,它在构建过程中被转换为有效JavaScript。 同样,两个Sass文件都转换为标准CSS。
在构建过程中,需要对这些文件进行处理,以在插件的dist /文件夹中创建分发文件。 这些是WordPress排队的实际文件,因为它们包含所有浏览器都可以理解的有效JavaScript和CSS。
幸运的是, create-guten-block
工具包通过监视对我们的块文件的更改来为我们处理构建和编译。 这是一个非常不错的功能,因为我们不必担心。 我们可以只专注于编写我们的块代码(和样式),并且插件文件将全部自动更新。 真好!
只要确保您从插件根文件夹内部运行npm start
命令即可触发文件监视。
是时候编辑一些代码了!
不必担心block.js
JSX代码的细节,因为稍后我们将对其进行详细介绍。 现在,我们只专注于对前端视图和后端视图的块输出进行一些简单的更改。
打开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;
}
您可以在下面的屏幕截图中看到这些更改如何影响块的渲染,具体取决于我们是在编辑器窗口中还是在前端中查看它。
![图片:https://cms-assets.tutsplus.com/uploads/users/1527/posts/31057/image/backend-change.png Updated editor view](https://i-blog.csdnimg.cn/blog_migrate/0f81d17bc995fb4373ec37d20164e347.png)
![图片:https://cms-assets.tutsplus.com/uploads/users/1527/posts/31057/image/frontend-change.png Updated frontend view](https://i-blog.csdnimg.cn/blog_migrate/c5fd68ec16368242e586056d849ba85a.png)
我们现在还不会介绍排队的块脚本,但是现在足以知道editor.scss样式仅应用于编辑器窗口和style.scss 被添加到编辑器窗口和前端两者 。 因此,可以从style.scss中省略在编辑器和前端中使用的样式。
注意,在Sass文件中,我们如何引用一个冗长CSS选择器来定位我们的块元素。
.wp-block-cgb-block-my-custom-block
Gutenberg会自动将该类添加到前端的块容器元素中,但是我们必须在编辑器窗口中手动应用它才能获得相同的类,如下面的edit
方法所示。
<div className={ props.className }>
<!-- Block code goes here -->
</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
方法的内容时,下次刷新该编辑器窗口时似乎会发生一些奇怪的事情。
为了证明这一点,我在save
方法中添加了一个新列表项( <li>Indigo</li>
),然后刷新了帖子编辑器(当然,在必须再次清除缓存之后!)。 结果如下:
如果选择“ 转换为块”或“ 编辑为HTML”,则会显示save
方法的内容,该方法应在前端而不是在编辑器中查看。
这非常令人困惑,并且使事情恢复正常的唯一明显方法是从编辑器窗口中删除该块,然后再次将其重新插入。 正如我在上一篇文章中提到的,古腾堡(Gutenberg)仍在开发中,这就是一个很好的例子!
希望在将来的版本中将使此操作更加直观,但是现在仅需注意。 更改save
功能时,准备删除编辑器窗口中的相关块,然后再次添加它们。
如前所述, save
和edit
方法的输出可以完全不同。 但是,在大多数情况下,您可能希望前端输出与编辑器输出匹配,以使编辑体验与前端渲染尽可能一致。
在上面的人为设计示例中,我仅出于演示目的在编辑器和前端视图中添加了不同的内容和样式。
块API概述
Block API由添加到全局wp
admin对象的一组JavaScript对象组成。 而且由于wp
是全局的,因此我们不需要在源代码中专门导入它-它可以按需提供。
wp
可用的对象取决于您当前正在查看的管理页面。 例如,如果您要自定义网站,则wp
包含主要的自定义程序API对象。
但是,当前,Gutenberg Block API仅在帖子编辑器上可用。 我预计,将来随着帖子编辑器和网站定制程序之间的集成越来越紧密,这种情况将会改变。
您可以通过打开Gutenberg编辑器并在浏览器控制台中输入wp
来查看wp
的结构。
![图片:https://cms-assets.tutsplus.com/uploads/users/1527/posts/31057/image/new-js-objects.png Block API objects added to global wp JavaScript object](https://i-blog.csdnimg.cn/blog_migrate/0e1bb2bcd334aa4e7c51ca2c534ddb4d.png)
如您所见, wp
包含许多对象,但是我们最感兴趣的对象是:
这些对象使您可以访问创建一些非常复杂的块所需的所有工具。 尝试在浏览器控制台中键入其完整的对象名称,以进一步探索这些对象。
例如,如果键入wp.blocks
并展开对象,您将看到可用的功能之一是registerBlockType()
。 这是一项非常重要的功能,我们将在下一篇文章中深入介绍
wp.elements
对象
该对象是React(和ReactDom)之上的抽象层,以可预测和一致的方式公开React功能。 即使基础实现已更改或完全更改,也是如此。
只要接口保持不变,与Block API交互的插件将来就不会受到影响。
wp.blocks
对象
wp.blocks
包含创建块的核心功能( registerBlockType()
)以及常规块管理所需的其他功能,例如:
-
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' );
结论
在本教程中,我们实现了一个基本块并编辑了代码。 我们还看到,我们可以完全控制块渲染,并且与前端相比,编辑器中可以具有不同的块视图。
编辑器仍然存在一些问题,可能会不时使您感到惊讶-这提醒您古腾堡(Gutenberg)仍在开发中,可能尚未准备好在生产现场使用。
最后,我们对块API进行了概述,该API在全局wp
JavaScript对象上引入了几个新对象来创建和管理块。
在下一篇文章中,我们将加快步伐并创建一个更全面的模块。 为此,我们将深入探讨registerBlockType()
函数。 我们还将仔细研究如何正确地使您的块脚本入队。
翻译自: https://code.tutsplus.com/tutorials/wordpress-gutenberg-block-api-part-2--cms-31057