想象一下,你的代理刚接了一个新客户。这个客户经营着一个书评网站,需要彻底检修。他们需要添加一些自定义字段来与每本书相关联,例如评级、作者、长度和Goodreads的精美链接。
您的机构也正在从基于经典的WordPress开发过渡到完全包含块编辑器提供的所有功能。但作业参数并不能让您为每一位元数据构建自定义块,也不能自定义客户端需要的块。你需要一个效率更高的解决方案。
这就是块绑定API的用武之地。我在前两篇文章中介绍了此API的基本介绍:
但块绑定的真正威力在于与WordPress中的各种其他API和系统相结合,如块变体、模式等。一旦你开始把它们拼凑在一起,你可以在块系统上实现的潜力几乎是无限的。
因此,让我们一起为客户的书评网站奠定基础。然后,我会让你接管并微调它。
前提条件
本教程将涵盖很多基础知识,如果不让每一行代码变得过于复杂,我无法详细解释每一行。因此,您至少需要粗略了解以下概念。本系列的目标是展示如何统一使用WordPress中的各种API。
- 节点和npm:你一定有已安装Node.js和npm在您的本地机器上,按照本教程操作。
- JavaScript编程:你应该吃点基线知识需要阅读、编写和理解中间JavaScript。
- 块编辑器开发:你应该觉得构建运行在WordPress中的代码很舒服块编辑器.
- 主题开发:你应该能够构建块主题,从其工作
函数.php
文件,以及设置生成过程.
- 构建工具:您必须知道如何从命令行界面(CLI)编写命令,例如
npm运行<命令>
.
设置您的项目
对于此项目,您将为创建子主题二十二点二十四分命名为TT4书评。这样你就不必为了让事情顺利进行而重新创建主题的每个部分。您可以查看完整构建的示例通过其存储库.
我建议导入示例内容直接安装到干净的开发设备中。请注意,用于帖子的元键具有主题塞_
本教程中使用的前缀。
还有一个使用WordPress Playground进行现场演示如果要查看最终结果:
文件结构
创建名为的新文件夹tt4-书评
在您的/wp-content/themes(wp-content/主题)
目录。此外,继续在主题中添加以下子文件夹和文件:
/图案
/公众
/资源
/模板
函数.php
package.json包
样式表
webpack.config.js
这看起来可能很多,但您要添加的大多数文件都只有很少的代码。他们只是为了特定的目的而分开。
主样式表和函数文件
因为你要把它作为子主题在默认的二十四小时主题中,您首先需要创建样式表
并添加一个文件头,以便WordPress识别它。
将此代码添加到您的样式表
文件:
/*!*主题名称:TT4书评*描述:书评网站的子主题。*版本:1.0.0*模板:二十二点二十四分*标签:全站编辑*文本域:主题拖动*测试达到:6.5*要求至少:6.5*需要PHP:7.4*许可证:GNU通用公共许可证v2.0或更高版本*许可证URI:https://www.gnu.org/licenses/gpl-2.0.html网址*/
你还将与函数.php
在本教程中,最好也设置这个文件。
将此代码添加到主题函数.php
文件:
<?php(电话)//在此处添加您的自定义代码。
现在访问外观>主题在WordPress管理员的屏幕上,找到新的TT4书评主题,并激活它。
生成脚本
本教程需要一些JavaScript,因此在早期阶段设置构建过程也是一个好主意。此过程之前已在除了块样式,第1部分:使用带有主题的WordPress脚本包。在生成过程主题手册中的文档。
打开主题package.json包
文件,以添加项目名称和这些脚本:
{“name”:“your-project-name”,“脚本”:{“start”:“wp-scripts start--webpack-src-dir=resources--output-path=public”,“build”:“wp-scripts build--webpack-src-dir=resources--output-path=public”}}
现在,导航到您的wp-content/themes/tt4-书评
目录,然后键入以下命令以安装必要的软件包:
npm install@wordpress/scripts@wordpress/icons路径webpack-remove-empty-scripts--save-dev
您的package.json包
文件现在应该如下所示:
{“name”:“your-project-name”,“脚本”:{“start”:“wp-scripts start--webpack-src-dir=resources--output-path=public”,“build”:“wp-scripts build--webpack-src-dir=resources--output-path=public”},“devDependencies”:{“@wordpress/icons”:“^9.46.0”,“@wordpress/scripts”:“^27.6.0”,“路径”:“^0.12.7”,“webpack-remove-empty-scripts”:“^1.0.4”}}
为了让构建过程与主题一起工作,您还需要采取另一个步骤,那就是设置主题的webpack配置文件。对于本教程,您只需要在构建编辑器脚本时使用此选项。
打开主题webpack.config.js
文件并将此代码添加到其中:
const defaultConfig=require('@wordpress/scripts/config/webpack.config');const RemoveEmptyScriptsPlugin=require('webpack-remove-empty-scripts');const path=require(“path”);模块导出={…默认配置,...{条目:{“js/editor”:路径.resolve(process.cwd(),“resources/js”,“editor.js”)},插件:[//包括WP的插件配置。…默认配置插件,//删除webpack生成的空“.js”文件,但//在WP生成其`*.asset.php`文件后设置。新的RemoveEmptyScriptsPlugin({阶段:RemoveEmptyScriptsPlugin。阶段_ FTER_PROCESS_PLUGINS} )]}};
注册自定义字段
在考虑将自定义字段连接到块之前,必须先注册要使用的每个元键。对于这个书评网站,让我们坚持您的客户需要的四个字段:
主题日志_图书作者
:这本书的作者姓名。
主题ug_book_rating
:用户对该书的星级评定。
主题lug_book_length
:书中的页数。
主题lug_book_goodreads_url
:Goodreads.com上该书页面的URL。
确定了元密钥后,是时候通过标准注册它们了寄存器_元数据()
功能。将此代码添加到主题函数.php
文件:
add_action('init','themeslug_register_meta');函数themeslug_register_meta(){register_meta('帖子','主题lug_book_author'[“show_in_rest”=>真,“single”=>真,“type”=>“string”,“sanitize_callback”=>“wp_filter_nohtml_kses”] );register_meta('帖子','主题lug_book_rating'[“show_in_rest”=>真,“single”=>真,“type”=>“string”,“消毒_回调”=>“wp_filter_nohtml_kses”] );register_meta('帖子','主题lug_book_length'[“show_in_rest”=>真,“single”=>真,“type”=>“string”,“sanitize_callback”=>“wp_filter_nohtml_kses”] );register_meta('帖子','主题lug_book_goodreads_url'[“show_in_rest”=>真,“single”=>真,“type”=>“string”,“sanitize_callback”=>“esc_url_raw”] );}
为了使这些字段与Block Bindings API一起工作,您需要确保这两个参数的每个注册的元密钥都设置为真的
:
显示_重置
:这对于自定义字段在块编辑器使用的REST API上可用是必要的。
单一的
:块绑定API当前不支持单个键的多个元值,因此需要将其设置为单个值。
你们中目光敏锐的人可能已经注意到,有几个作为整数的元键被定义为字符串:主题日志_图书_评级
和主题lug_book_length
这是一个令人遗憾的限制,即当与需要字符串属性的块一起使用时,在编辑器中显示值。稍后当我们进入元输入控件时,我们将解决这个问题。
问题和解决方案:将自定义字段连接到块
WordPress 6.5+支持通过核心/后元
默认情况下绑定源。这意味着您不必担心通过块绑定API注册任何内容。
但是,如中所述块绑定简介,第1部分:连接自定义字段,将绑定块插入编辑器的唯一方法是手动切换到代码编辑器查看并键入块标记。
例如,下面是绑定主题日志_图书作者
段落块的自定义字段:
<!-- wp:段落{“元数据”:{“绑定”:{“内容”:{“源”:“核心/后元”,“参数”:{“key”:“主题lug_book_author”}}}}} --><p></p><!-- /wp:段落-->
输入自定义元值的唯一方法是启用自定义字段面板并手动键入键和值:
作为一名声誉良好的开发人员,你永远不会想把这种体验交给客户,让他们投入到所有的工作中。但这些限制在块绑定API的第一个版本中是意料之中的。在WordPress 6.5发布之前,没有足够的时间来构建UI和完善用户体验。
块绑定API有望在未来获得更精细的用户体验,但这将在多个WordPress版本中实现。订阅区块绑定API跟踪票据跟随或参与这个过程。
作为一名开发人员,你能做什么来开始使用?我的意思是真正地将此API用于将传递给客户端的真实项目?这就是我在本系列教程中要回答的问题,下面的部分将深入探讨解决方案。
使用块变体插入绑定块
如果您可以像插入任何其他块一样插入绑定块,而不需要进行代码编辑,该怎么办?您完全可以通过块变体API.
块变体只不过是块的替代版本,与原始块具有不同的默认属性集。绑定块只是一个定义了元数据绑定
属性。
这意味着可以将这两个概念结合起来。例如,您可以看到表示在此屏幕截图中先前注册的自定义字段的变体:
您可以像其他任何块一样设置用于插入块的变体,而不是每次希望绑定块的属性时手动键入块标记。这对你和你的客户来说都不会那么头痛。
注册绑定块的变体
要集成绑定和变体,必须通过JavaScript(PHP注册方法不支持活动()
检查此技术所需的)。
如果您还没有这样做,请在命令行程序中键入以下内容来启动构建过程:
npm运行启动
这将在/公众
您之前创建的文件夹。
在深入JavaScript之前,必须先将新生成的/public/js/editor.js
编辑器中的文件。将此代码添加到您的函数.php
文件:
add_action(“enqueue_block_editor_assets”,“themeslug_editor_assets”);函数themeslug_editor_assets(){$script_asset=包含get_theme_file_path('public/js/editor.asset.php');wp_排队_脚本('主题日志编辑器',get_theme_file_uri('public/js/editor.js'),$script_asset[“依赖关系”],$script_asset[“版本”],真的);}
现在将此代码添加到您的编辑器.js
中的文件/资源/js
导入空变量.js
脚本:
导入”/变化';
有了这段代码,您可以开始为要绑定到自定义字段的任何块注册自定义变体。对于本教程,您将把每个自定义字段绑定到单个块属性:
自定义字段 | 块 | 属性 |
---|
主题日志_图书作者 | 段落 | 内容 |
主题日志_图书_评级 | 段落 | 内容 |
主题lug_book_length | 段落 | 内容 |
主题lug_book_goodreads_url | 按钮 | 网址 |
当然,您可以将自定义字段绑定到项目所需的任意数量的块。
首先,打开您的变量.js
文件并添加以下代码以导入所需的依赖项并定义Goodreads图标:
从“@wordpress/blocks”导入{registerBlockVariation};从'@wordpress/i18n'导入{__};从“@wordpress/icons”导入{page,pencil,starFilled};const-goodreadsIcon=(<svg width=“24”height=“24“viewBox=“0 0 24 24”version=“1.1”><路径d=“M17.3,17.5c-0.2,0.8-0.5,1.4-1,1.9c-0.4,0.5-1,0.9-1.7,1.2C13.9,20.9,13.1,21,1,21c-0.6,0-1.3-0.1.9-0.2 c-0.6-0.1.1-0.4-1.6-0.7c-0.5-0.3-0.9-0.7-1.2-1.2c-0.3-0.5-0.5-0.5-1.1-0.5-1.7h1.5c0.1,0.5,0.2,0.9,0.5,1.2c0.2,0.3,0.5,0.6,0.9,0.8c0.3,0.2,0.7,0.3,1.1,0.4c0.4,0.1,0.8,0.1,1.2,0.1c1.4,0,2.5-0.4,3.1-1.2c0.6-0.8,1-2,1-3.5v-1.7h0 c-0.4,0.8-0.9,1.4 1。6,1.9c-0.7,0.5-1.5,0.7-2.4,0.7c-1,0-1.9-0.2-2.6-0.5C8.7,15,8.1,4.5,7.7,14c-0.5-0.6-0.8-1.3-2.1 c-0.2-0.8-0.3-1.6-2.5c0-0.9,0.1-1.7,0.4-2.5c0.3-0.8,0.6-15,1.1-2c0.5-0.6,1.1-1,1.8-1.4C10.3,2.2,11.1,3,12,3 c0.5,0.9,0.1,1.3,0.2c0.4,0.1,0.8,0.3,1.1,0.5c0.3,0.2,0.6,0.5,0.9c0.3,0.3,0.5,0.6,0.6,1h0V3.4h1.5V15 C17.6,15.9,15.9 7.5、16.7、17.3、17.5赫兹M13.8,14.1c0.5-0.3,0.9-0.7,1.3-1.1c0.3-0.5,0.6-1,0.8-1.6c0.2-0.6,0.3-1.2,0.3-1.9 c0-0.6-0.1-1.2-0.2-1.9c-0.1-0.6-0.4-1.7-1.7c-0.3-0.5-0.7-0.9-1.3-1.2c-0.3-1.0.5-1.9-0.5s-1.4,0.2-1.9,0.5 c-0.5,0.3-1,0.7-1.3-1.3,1.2C8.5,6.4,8.3,7,7.6C8,8.9,8.9,1.9c0,0.6,0.1,1.3,0.2,1.9C8.3,12,8.6,12.5,8.91,3c0.3,0.5,0.8,0.8,1.3,1.1c0.5,0.3,1.1,0.4,1.9,0.4C12.7,14.5,13.3,14.4,13.8,14.1z“/></svg>);
从这里开始,您必须为每个绑定块注册变体。首先为名为“Book Author”的段落块创建变体:
registerBlockVariation('核心/段落'{name:'themeslug/book-author',标题:__(‘图书作者’,‘主题词’),description:__('显示图书作者。','themeslug'),类别:“小部件”,关键词:['book','author'],图标:铅笔,范围:[“插入器”],属性:{元数据:{绑定:{内容:{source:'核心/后元',参数:{key:'主题lug_book_author'}}}},占位符:__('书籍作者','主题标签')},示例:{},激活:(块属性)=>'themeslug_book_author'===块属性?。元数据?。绑定?。内容?。参数?。钥匙});
在大多数情况下,您可以随意定义此变体,但有两个属性需要特别注意:
属性
:
元数据
:您必须设置绑定
属性的方法与使用核心/后元
源和关联的post元密钥(主题日志_图书作者
对于上述变化)。
占位符
: (可选)设置占位符时,只要用户尚未设置元数据,文本就会出现在编辑器中。
活动()
:此回调检查块是否具有当前变体。因此,它检查定义的元数据绑定内容args.key
值存在并与post元键匹配。
现在,对图书长度、图书评级和图书Goodreads按钮变体重复相同的过程:
registerBlockVariation('核心/段落'{name:'themeslug/book-length',title:__(“书长”,“主题”),description:__('以页数显示书本长度。','主题标签'),类别:“小部件”,关键词:['book','pages','length'],图标:页面,范围:[“插入器”],属性:{元数据:{绑定:{内容:{来源:'核心/后元',参数:{key:'themeslug_book_length'}}}},占位符:__('书本长度','主题标签')},示例:{},激活:(块属性)=>'themeslug_book_length'===块属性?。元数据?。绑定?。内容?。参数?。钥匙});registerBlockVariation('核心/段落'{name:'themeslug/book-rating',title:__(‘图书评级’,‘主题词’),description:__('显示图书评级。','themeslug'),类别:“小部件”,关键词:['book','rating','review'],图标:starFilled,范围:[“插入器”],属性:{元数据:{绑定:{内容:{source:'核心/后元',参数:{key:'主题lug_book_rating'}}}},占位符:__('图书评级','主题标签')},示例:{},激活:(块属性)=>'themeslug_book_rating'===块属性?。元数据?。绑定?。内容?。参数?。钥匙});registerBlockVariation('核心/按钮'{名称:“主题标签/书籍goodreads按钮”,title:__(“图书Goodreads按钮”,“主题标签”),description:__('显示一个链接到Goodreads图书URL的按钮。','themeslug'),类别:“小部件”,关键词:['book','author'],图标:良好阅读图标,范围:[“插入器”],属性:{text:__(“查看Goodreads&rarr;”,“主题日志”),元数据:{绑定:{网址:{source:'核心/后元',参数:{key:'themeslug_book_goodreads_url'}}}}},示例:{},激活:(块属性)=>'themeslug_book_goodreads_url'===块属性?。元数据?。绑定?。网址?。参数?。钥匙});
从现在开始,您不再需要在代码编辑器中手动键入块绑定。您可以像插入其他块一样插入它们。
还有一个主要问题需要解决。要输入自定义字段值,用户必须知道如何打开自定义字段并正确键入键和值字段。
让我们通过在侧边栏中添加自定义控件来解决这个问题:
首先,将此代码添加到您的编辑.js
中的文件/资源/js
导入空元.js
脚本:
导入”/元';
然后打开您的元.js
文件并导入以下依赖项:
从“@wordpress/core-data”导入{useEntityProp};从“@wordpress/data”导入{useSelect};从“@wordpress/edit-post”导入{PluginDocumentSettingsPanel};从'@wordpress/i18n'导入{__};从“@wordpress/icons”导入{starFilled};从“@wordpress/plugins”导入{registerPlugin};导入{范围控制,__experialInputControl作为InputController,__experialNumberControl作为NumberController,__实验VStack作为VStack}来自“@wordpress/components”;
上述代码使用了一些实验组件,这些组件是为元输入添加自定义控件所必需的。当前有一个打开的跟踪票据这将从我们正在使用的每种类型中删除实验名称。如果您不喜欢使用实验组件,可以始终使用自定义组件创建输入。
要向帖子侧栏添加控件,最好的选择是使用寄存器插件()
JavaScript函数及其提供
回调属性。别担心,你没有注册用户必须安装和激活的插件。您正在创建一个编辑器插件。
正常开放元.js
并添加以下代码:
registerPlugin(“tt4-book-reviews”{渲染:()=>{//在此处添加自定义代码。}} );
从现在开始,剩下的代码将进入提供
回调。
由于您不希望为编辑器的每个实例输出自定义控件,因此首先需要检查当前的post类型,以确定这是否是正确的编辑器。您可以使用使用选择()
挂钩。在这种情况下,您只希望控件在邮递
是当前帖子类型。如果不是提供
回调将返回无效的
.
您还需要使用使用实体属性()
挂钩到获取和设置元值通过分配几个常量:元
和setMeta(设置元数据)
.
将此代码添加到您的提供
回调:
const postType=使用选择((select)=>select('core/editor').getCurrentPostType(),[]);const[meta,setMeta]=useEntityProp('postType',postType,'meta');if('post'!==postType){返回null;}
从这一点来看,这只是返回组件以输出元控件的问题。最重要的是使用插件文档设置面板
插槽填充,以便将它们添加到编辑器中的正确位置。
对于此侧栏面板,您将使用以下组件并将其与元键关联:
在您的提供
回调:
返回(<插件文档设置面板title={__('书评','主题词')}><V堆栈><范围控制label={__('评级','主题标签')}beforeIcon={starFilled}当前输入={0}initialPosition={0}最小值={0}最大值={5}步骤={1}值={parseInt(meta?.themeslug_book_rating,10)}onChange={(值)=>setMeta({…元,主题lug_book_rating:`${value}`||null} ) }/><输入控制label={__('作者','主题词')}value={meta?.themeslug_book_author}onChange={(值)=>setMeta({…元,主题lug_book_author:value | | null} ) }/><数字控制label={__('总页数','themeslug')}最小值={0}value={parseInt(meta?.themeslug_book_length,10)}onChange={(值)=>setMeta({…元,主题lug_book_length:`${value}`||null} ) }/><输入控制label={__(“Goodreads URL”,“themeslug”)}值={meta?.themeslug_book_goodreads_url}onChange={(值)=>setMeta({…元,主题lug_book_goodreads_url:value||null} ) }/></V堆栈></PluginDocumentSettingsPanel>);
对于额定值和总页数控制:
这些控件处理整数值,但在设置meta时返回字符串。看看这些是如何为评级处理的:
值={parseInt(meta?.themeslug_book_rating,10)}onChange={(值)=>setMeta({…元,主题lug_book_rating:`${value}`||null} ) }
请注意,它使用parseInt()
对于价值
属性将整数传递给控件。对于onChange(更改时)
属性价值
变量被传递给模板文本,以便它被视为字符串。这是值在编辑器中显示并正确保存所必需的。
当您向元字段添加数据时,您应该会看到,对于编辑器内容区域中的任何绑定块,它们都会自动出现:
接下来的步骤
我认为我们迄今为止所取得的成就是“困难”的部分。现在,您已经准备好了所有部件,可以进行前端设计等有趣的工作。
请继续关注开发者博客,了解本系列的下一篇文章。我接下来将介绍的一些项目包括:
- 通过查询循环块逐元显示帖子。
- 将自定义字段集成到主题模板中。
- 用于显示自定义字段的建筑图案。
道具到@前列腺增生和@自我查看本教程和@韦尔奇用于代码示例。