这个块.json
文件简化了定义和注册块的过程,方法是使用JSON格式的同一块定义在服务器和客户端上注册块(块编辑器)。
下图详细说明了块.json
文件。
除了简化块的注册之外,使用块.json
有几个好处,包括改进的性能。
这个block.json中的元数据文档中有一个关于您可以在块.json
块的文件。本文将介绍最常见的选项,这些选项允许您指定:
- 块的基本元数据。
- 指示块的功能、外观和输出的文件。
- 数据在块中的存储方式。
- 用户界面中的块设置面板。
使用块.json
属性,可以定义块的唯一标识方式以及块编辑器中显示的信息。这些属性包括:
api版本
:指定美国石油学会块使用的版本。除非您有特定要求,否则请使用最新版本。
名称
:块的唯一名称,包括名称空间(例如。,my-plugin/my-custom-block
).
标题
:块的显示标题,显示在插入器中。
类别
:块显示在插入器中的类别。常见类别包括文本
,媒体
,设计
,小部件
、和主题
.
偶像
:表示插入器中块的图标。这可以是一个仪表盘图标slug或自定义SVG图标。
描述
:块的简短描述,提供比标题更多的上下文。
关键字
:一组关键字,用于帮助用户在搜索时查找块。
文本域
:块的文本域,用于国际化。
这个块.json
文件还允许您指定块功能的基本文件:
编辑器脚本
:仅在块编辑器中使用的一个或多个JavaScript文件。
编辑器样式
:用于在块编辑器中设置样式的CSS文件。
脚本
:块编辑器和前端中加载的一个或多个JavaScript文件。
风格
:在块编辑器和前端中应用的一个或多个CSS文件。
查看脚本
:仅用于前端的一个或多个JavaScript文件。
对于所有这些属性,您可以提供文件路径(从开始文件:
),一个手柄已使用注册的wp_注册_脚本
或wp注册样式
或组合这两个选项的数组。
此外提供
属性,WordPress 6.1引入,指定负责生成动态渲染块的前端标记。如果$render_callback
函数未提供给寄存器块类型()
功能。
块属性是分配给块的设置或数据。它们可以确定块的各个方面,例如其内容、布局、样式以及需要与块结构一起存储的任何其他特定信息。如果用户更改块,例如修改字体大小,则需要一种方法来保持这些更改。属性就是解决方案。
注册新块类型时属性
的属性块.json
描述了块所需的自定义数据以及它们在数据库中的存储方式。这允许块编辑器正确解析这些值并传递属性
到街区编辑
组件和节约
功能。
下面是中定义的三个属性的示例块.json
:
“属性”:{“回退CurrentYear”:{“type”:“字符串”},“showStartingYear”(显示开始年份):{“type”:“boolean”},“startingYear”(开始年份):{“type”:“字符串”}},
块使用包含特定JSON类属性的HTML样式注释标记进行“分隔”。使用这些分隔符,可以在块编辑器中渲染帖子内容或编辑帖子时识别块边界并解析块属性。
下面的代码示例演示了块分隔符中定义的属性。
<!-- wp:block-development-examples/corpyright-date-block-09aac3{“fallbackCurrentYear”:“2023”,“showStartingYear”:true,“startingYear”:“2020”}-->©2020–2023年</p><!-- /wp:区块开发示例/版权日期块-09aac3-->
默认情况下,所有属性都被序列化并存储在块的分隔符中,但可以根据需要进行配置。查看了解块属性文章了解更多信息。
这些属性被传给街区编辑
将要在块编辑器中显示的组件反应到节约
函数用于生成存储在数据库中的标记,以及生成块的任何服务器端呈现定义。
这个编辑
组件唯一拥有通过集合属性
功能。
下图详细说明了如何在典型块中存储、读取和更新属性。
查看如何将属性传递给编辑
组件节约
功能,以及渲染.php
在这个完整块示例.
有关属性以及如何在自定义块中使用这些属性的详细信息,请访问属性API参考页。
许多块(包括核心块)提供了类似的自定义选项,例如背景色、文本颜色和填充调整。
这个支架
中的属性块.json
允许块声明对这些常见自定义选项的支持。启用后,块的用户可以直接从设置边栏调整颜色或填充等内容。
利用这些预定义的块支持有助于确保块的行为与核心块一致,无需从头开始重新创建类似功能。
下面是中定义的颜色支持示例块.json
:
“支持”:{“颜色”:{“文本”:true,“link”:true,“background”(背景):true}}
使用块支持生成一组需要手动添加到块的包装元素。这确保它们作为块数据的一部分正确存储,并在生成将交付到前端的块标记时考虑在内。
下面的代码演示了如何将启用块支持生成的属性和CSS类存储在块的标记表示中。
<!-- wp:block-development-examples/block-supports-6aa4dd{“backgroundColor”:“对比度”,“文本颜色”:“口音-4”}-->Hello World(你好世界)</p><!-- /wp:block-development示例/块支持-6aa4dd-->
请参阅完整块示例的以上代码.
有关支持以及如何在自定义块中使用它们的详细信息,请访问支持API参考页。