本文档介绍了与影响块编辑器中用户内容的样式相关的主要概念。它指出了相关的参考指南和教程,以供读者深入研究所提出的每一个想法。它的目的是阻止在块编辑器项目中工作的作者和人员。
通过在块编辑器中创建帖子,用户正在创建许多工件:一个HTML文档加上一些CSS样式表,嵌入到文档中或外部。
最终的HTML文档是以下几点的结果:
- 这个WordPress模板通过PHP(经典主题)或HTML模板(块主题)由主题提供(了解更多信息关于差异)
- 这个阻碍和带有预定义结构(HTML标记)的模式
- 用户修改内容:添加内容、转换现有内容(将给定段落转换为标题)或修改内容(将类或内联样式附加到块)
前端加载的样式表包括:
- 阻碍。块附带的样式表。在前端,您可以找到一个样式表,其中包含WordPress定义的所有块样式(
wp-block-library公司-*
)或每个使用中的块单独的样式表(如wp-block-group(wp-block组)-*
,wp-块-列-*
等)。请参见这个便条了解全部细节。
- 全局样式。这些样式是使用来自theme.json文件的数据动态生成的:请参阅笔记,参考、和如何引导具体来说,它合并了WordPress中的theme.json、主题中的themes.json(如果有)的内容,以及通过站点编辑器中的全局样式侧栏提供的用户数据。处理此数据的结果是一个嵌入的样式表,其id为
全局样式-内联-css
.
- 主题。历史上,主题已经将自己的样式表排入队列,其中id基于主题名称,如
二十二点二样式
。除了拥有自己的样式表外,他们现在还可以声明一个包含样式的theme.json文件,该文件将成为全局样式生成的样式表的一部分。
- 用户。编辑器中的一些用户操作将生成样式内容。这种情况适用于双色调、布局或链接颜色等功能。
- 其他.WordPress和插件也可以将样式表排队。
自从WordPress 5.0中引入块编辑器以来,用户可以使用一些工具向特定块“添加样式”。通过使用这些工具,用户可以将新类或内联样式附加到块,从而修改其视觉外观。
默认情况下,块带有给定的HTML标记。想想段落块,例如:
<p></p>
在其最简单的形式中,任何针对第页
选择器将对这个块应用样式,无论它来自块、主题等。
用户可以通过应用不同的样式来更改此块的状态:文本对齐、颜色、字体大小、行高等。这些状态以HTML属性的形式反映在块的HTML标记中,主要通过班
或风格
属性,尽管它可以是块作者认为合适的任何其他属性。
在用户对块进行一些修改后,初始标记可能如下所示:
<p class=“has-color has-green-color has-font-size has-small-font-size my-custom-class”style=“line-hight:1em”></p>
这就是我们所说的“用户提供的块样式”,也称为“本地样式”或“序列化样式”。基本上,每个工具(字体大小、颜色等)最终都会向块标记添加一些类和/或内联样式。这些类的CSS样式是块、全局或主题样式表的一部分。
修改块状态的能力,加上一个块可以存在于任何其他块中(想想一个组中的一段),创造了大量潜在的状态和风格可能性。
如果你遵循块教程你可以了解块API这里有更详细的介绍,还可以构建自己的块。这是对块如何允许用户编辑其状态的一般概念的介绍。
要构建如上所述的体验,区块作者需要几个部分:
- UI控件它为用户提供了一些选择,例如,可以更改块的字体大小。控件负责从块中读取数据(这个块已经分配了字体大小吗?)和它需要的其他数据(用户可以在这个块中使用什么字体大小?)。请参阅可用的组件库.
- 块属性。块需要保存数据,以了解应用了哪些修改:例如,是否已经为其指定了字体大小。查看块如何定义属性.
- 访问样式数据。控件可能需要有关给定块可用样式的外部信息:例如,颜色列表或字体大小列表。这些被称为“样式预设”,因为它们是通常由主题定义的样式的预选,尽管WordPress提供了一些默认设置。检查数据列表主题可以提供给编辑器,以及区块作者如何通过使用设置.
- 将用户样式序列化为HTML标记。在用户操作时,需要相应地更新块HTML标记(应用适当的类或内联样式)。此过程称为序列化,它是编辑,保存、和渲染器回调函数的职责:这些函数获取块数据并将其转换为HTML。
本质上,这些是块作者需要关心的基本机制,以便用户能够对其块进行样式设置。虽然这可以完全手动完成,但有一个API可以自动执行此过程以满足常见的样式需求:块支持。
块支架是一个API,允许块声明其支持的功能。通过向他们的block.json文件,该块告诉系统用户可以对其执行何种操作。
例如:
{“name”:“核心/段落”,"...": "...",“支架”:{“排版”:{“fontSize”:true}}}
该段落声明支持其块.json
。这意味着块将显示一个UI控件,供用户调整其字体大小,除非主题禁用了它(了解有关主题如何在中禁用UI控件的更多信息这个主题.json
参考). 系统还将负责设置UI控件数据(如果已分配块的字体大小,则为块的字体尺寸,以及要显示的可用字体尺寸列表),并在用户更改时将块数据序列化为HTML标记(适当地附加类和内联样式)。
通过使用块支撑机构块.json
块作者只需写几行就可以创建与以前相同的体验。检查块支持api用于向静态或动态块添加块支持。
除了为了达到同样的效果而减少工作量的好处外,还有其他一些优点:
- 块的样式信息可用于本地移动应用程序和服务器
- 该块将使用其他块用于相同样式的UI控件,创建更连贯的用户体验
- 块使用的UI控件将随着改进而自动更新,而块作者无需执行任何操作
虽然块支持API提供了价值,但块作者还需要注意一些限制。为了更好地可视化它们是什么,让我们使用以下表块示例:
<表格><头部><tr>标题</tr></thead><t车身><tr>第一个</tr><tr>秒</tr></tbody><tfoot><tr>页脚</tr></tfoot></表格>
- 每个块只有一种样式类型。
限制之一是,从所有可用的样式,块只能使用其中一个实例。按照示例,表块只能有一个字体大小。如果块作者想要有三种不同的字体大小(页眉、正文和页脚),那么不能使用当前块支持的API。请参见这个问题获取更多详细信息和前进方向。
- 样式被序列化到块的最外层HTML节点,即包装器。
该块只支持API将字体大小值序列化到包装器,从而生成以下HTML<table class=“has-small-font-size”>
。当前块支持API不将此值序列化到其他节点,例如<t车身>
.
这是一个你可以关注的工作领域在跟踪问题中。链接的建议正在探索一种不同的方式来序列化用户更改:而不是每个块都支持序列化其自己的数据(例如,类,例如has-small-font尺寸
,has-绿色
)其思想是块将获得单个类(例如,wp-样式-UUID
)并且该类的CSS样式将由WordPress在服务器中生成。
虽然该提案的工作仍在继续,但有一个逃生舱口,一个实验选项块作者可以使用。任何块支持都可以使用__实验性SkipSerialization
例如:
{“name”:“核心/段落”,"...": "...",“支架”:{“排版”:{“fontSize”:true,“__terialSkipSerialization”:true}}}
这意味着排版块支持将完成所有操作(创建UI控件、将块属性绑定到控件等),但将用户值序列化到HTML标记中除外。类和内联样式不会自动应用于包装器,块作者有责任在编辑
,节约
、和渲染器回调
功能。请参见这个问题例如,如何对WordPress提供的一些块执行此操作。
注意,如果__实验性SkipSerialization
为其影响的组(排版、颜色、间距)启用全部的此组中的块支持。在上面的示例中全部的中的属性印刷术
团队将受到影响(例如。字体大小
,线条高度
,字体系列
等)。
要启用单一的属性,则可以使用数组来声明要跳过的属性。在下面的示例中,只有字体大小
将跳过序列化,将其他项保留在印刷术
组(例如。线条高度
,字体系列
等)不受影响。
{“name”:“核心/段落”,"...": "...",“支架”:{“排版”:{“fontSize”:true,“lineHeight”:真,“__terialSkipSerialization”:[“fontSize”]}}}
对该功能的支持是已添加到此PR中.
全局样式是指生成站点范围样式的机制。与上一节中描述的块样式不同,这些样式没有序列化到帖子内容中,也没有附加到块HTML中。相反,这个系统的输出是一个带有id的新样式表全局样式-内联-css
.
这个机制是WordPress 5.8中引入当时,它只从WordPress和活动主题获取数据。WordPress 5.9扩展了系统,也可以从用户那里获取样式数据。
这是通用数据流:
生成样式表的过程本质上有三个步骤:
- 收集数据:
主题.json
文件与WordPress捆绑,的主题.json
活动主题的文件(如果存在),以及通过站点编辑器中的全局样式UI提供的用户样式。
- 合并数据:来自不同来源(WordPress默认值、主题和用户)的结构化信息被规范化并合并为单个结构。
- 将数据转换为样式表:将内部表示转换为CSS样式规则,并将其作为样式表排队。
数据可以来自三个不同的来源:WordPress默认值、活动主题或用户。他们三人都使用相同的主题.json
格式.
从WordPress和活动主题中检索数据主题.json
文件。来自用户的数据是从数据库中提取的,用户通过站点编辑器中的全局样式侧栏保存所做的更改后,数据将存储在数据库中。
这一阶段的目标是建立一个统一的结构。
在这个阶段有两个重要的过程。首先,系统需要规范化所有传入的数据,因为不同的来源可能使用不同版本的主题.json
格式。例如,主题可能使用第1版而WordPress库正在使用最新版本其次,系统需要决定如何将输入合并到单个结构中。这将是以下各节的重点。
样式
传入的不同部分主题.json
结构的处理方式不同。中存在的数据样式
部分按照以下逻辑混合在一起:用户数据覆盖主题数据,主题数据覆盖WordPress数据。
例如,如果我们有以下三个主题.json
分别来自WordPress、主题和用户的结构:
{“样式”:{“颜色”:{“background”:“<WordPress值>”},“排版”:{“fontSize”:“<WordPress值>”}}}
{“样式”:{“排版”:{“fontSize”:“<theme value>”,“lineHeight”:“<theme value>”}}}
{“样式”:{“排版”:{“lineHeight”:“<用户值>”}}}
合并后的结果是:
{“样式”:{“颜色”:{“background”:“<WordPress值>”},“排版”:{“fontSize”:“<theme value>”,“lineHeight”:“<用户值>”}}}
设置
这个设置
部分的工作方式与样式不同。大多数设置仅用于配置编辑器,对全局样式没有影响。只有少数是结果样式表的一部分:预设。
预设是在UI的不同部分向用户显示的预定义样式:例如调色板或字体大小。它们包括以下设置:颜色.色调
,颜色.渐变
,彩色套色
,typegraphy.fontFamilies字体系列
,印刷字体大小
。不同于样式
,来自原点的预设不会覆盖来自其他原点的值。相反,它们都存储在合并结构中。
例如,如果我们有以下内容主题.json
分别来自WordPress、主题和用户的结构:
{“设置”:{“颜色”:{“调色板”:[“<WordPress值>”],“梯度”:[“<WordPress值>”]}}}
{“设置”:{“颜色”:{“调色板”:[“<主题值>”]},“排版”:{“fontFamilies”:[“<theme values>”]}}}
{“设置”:{“颜色”:{“调色板”:[“<用户值>”]}}}
合并后的结果是:
{“设置”:{“颜色”:{“调色板”:{“默认”:[“<WordPress值>”],“主题”:[“<theme values>”],“用户”:[“<用户值>”]},“梯度”:{“默认”:[“<WordPress值>”]}},“排版”:{“fontFamilies”(字体系列):{“主题”:[“<theme values>”]}}}}
生成样式表的最后一个阶段是将合并数据转换为CSS样式规则。
样式到CSS规则
这个样式
节可以看作是CSS规则的结构化表示,每个块表示一个CSS规则:
- theme.json中的键/值映射到CSS声明(
属性:value
).
- 给定块的CSS选择器是根据其语义生成的:
- 顶级部分使用
身体
选择器。
- 顶级元素使用与它们表示的HTML元素匹配的ID选择器(例如,
小时1
或一
).
- 块使用它们生成的默认类名(
核心/组
成为.wp-block-组
)除非他们使用块.json
(核心/段落
成为第页
). 有关这方面的更多信息,请参阅“电流限制”部分。
- 块中的元素使用块和元素选择器的串联。
例如,以下内容主题.json
结构:
{“样式”:{“排版”:{“fontSize”:“<topal value>”},“元素”:{“h1”:{“排版”:{“fontSize”:“<h1值>”}}},“区块”:{“核心/段落”:{“颜色”:{“text”:“<段落值>”}},“核心/群体”:{“颜色”:{“text”:“<组值>”},“元素”:{“h1”:{“颜色”:{“text”:“组值内<h1>”}}}}}}}
转换为以下CSS:
车身{font-size:<顶级值>;}小时1{字体大小:<h1值>;}第页{颜色:<段落值>;}.wp-block-组{颜色:<组值>;}.wp-block-组h1{颜色:<h1组内值>;}
CSS规则设置
从设置
节中,任何给定预设的所有值都将转换为遵循此命名结构的CSS自定义属性:--wp—预设-->类别>-<slug>
。选择器遵循上面样式部分中描述的相同规则。
例如,以下主题.json
{“设置”:{“颜色”:{“调色板”:{“默认”:[{“slug”:“vivid-red”,“值”:“#cf2e2e”,“name”:“鲜红”}],“主题”:[{“slug”:“前台”,“值”:“#000”,“name”:“前景”}]}},“区块”:{“核心/现场时间”:{“颜色”:{“调色板”:{“主题”:[{“slug”:“前台”,“值”:“#1a4548”,“name”:“前景”}]}}}}}}
将转换为以下CSS样式规则:
车身{--wp——预设——颜色——鲜艳的红色:#cf2e2e;--wp--预设--颜色--前景:#000;}.wp块网站标题{--wp——预设——颜色——前景:#1a4548;}
除了CSS自定义属性之外,除了duotone之外的所有预设都会为每个值生成CSS类。上述示例还将生成以下CSS类:
/*活体阅读*/.has-vivid-red-color{color:var(--wp-preset--color--vivid-read)!重要;}.has-vivid-red-background-color{background-color:var(--wp-预设--color--vivid-read)!重要;}.has-vivid-red-border-color{border-color:var(--wp-预设--color--vivid-read)!重要;}/*前景*/.has-foreground-color{color:var(--wp-预设--color--前景)!important;}.has-forground-background-color{background-color:var(--wp-预设值--color--前景)!important;}.has-foreground-border-color{border-color:var(--wp-预设--color--前景)!important;}/*网站标题中的前景*/.wp-block-site-title.has-foreground-color{color:var(--wp-preset--color--foreground)!important;}.wp-block-site-title.has-forground-background-color{background-color:var(--wp-preset--color--foreground)!important;}.wp-block-site-title.has-foreground-border-color{border-color:var(--wp-preset--color--foreground)!important;}
1为块设置不同的CSS选择器需要服务器重新注册
默认情况下,分配给块的选择器为.wp-块-<块名称>
。但是,块可以根据需要更改此设置。它们可以通过__实验选择器
其中的属性块.json
.
如果块执行此操作,则需要使用块.json
否则,全局样式代码无法访问该信息,将使用块的默认CSS选择器。
2无法针对不同样式的不同HTML节点
每个样式块只能使用一个选择器。
如果块使用__实验性SkipSerialization
将不同的样式属性序列化到包装器以外的不同节点。有关更多信息,请参阅“块支持的当前限制”。
三。每个块只有一个属性
与块支持类似,块只能使用任何样式的一个实例。例如,块只能有一个字体大小。参见相关的“块支架的电流限制”。
4只有使用块支持的块才会显示在全局样式UI中
站点编辑器中的全局样式UI有一个针对每个块样式的屏幕。块列表是使用块.json
块中的。如果要在此处列出块,则需要使用块支持机制。
除了单个块级别和全局样式中的样式外,还有基于块和经典主题输出的布局样式的概念。
布局块支持输出用于创建布局的块之间共享的通用布局样式。布局样式对于为作为其他块容器的任何块提供通用样式都很有用。依赖于这些布局样式的块的示例包括组、行、列、按钮和社交图标。该功能通过布局
设置在支架
在一个街区块.json
文件。
输出布局样式的主要位置有两个:
基本布局样式是选择使用特定布局类型的所有块通用的样式。常见的基础布局样式示例包括设置显示:柔性
对于使用Flex布局类型的块(例如按钮和社交图标),并为受约束的布局提供默认的最大宽度。
基本布局样式从内部输出主PHP类它处理全局样式,并构成全局样式表的一部分。为了在经典主题中提供对核心块的支持,无论主题是否提供了自己的样式,这些样式始终是输出的主题.json
文件。
通用布局定义存储在核心布局块支持文件.
当呈现选择布局支持的块时,将处理两件事并通过添加到输出中布局.php
:
- 语义类名将添加到块标记中,以指示正在使用的布局设置。例如,
是layout-flow
用于使用默认/流布局的块(例如组),以及是内容证明是正确的
当用户将块设置为使用右对齐时添加。
- 将为在渲染的单个块上设置的非默认布局值生成单个样式。这些样式通过使用表单的容器类名附加到块
wp-container-$id
其中$id(美元)
是一个唯一编号.
当前使用的布局类型有四种:
- 默认/流动:项目垂直堆叠。父容器块设置为
显示:流量
子对象之间的间距通过垂直边距处理。
- 受约束:项目垂直堆叠,使用与Flow布局相同的间距逻辑。为子内容提供受约束的宽度,为标准内容大小和宽尺寸输出宽度。默认为使用全局
内容大小
和宽尺寸
中设置的值设置.布局
在中主题.json
.
- Flex:使用Flexbox布局显示项目。默认为水平方向。子对象之间的间距通过
缺口
CSS属性。
- 网格:使用网格布局显示项目。默认为
自动填充
列生成方法,但也可以设置为固定数量的列。儿童之间的间距通过缺口
CSS属性。
有关控制块之间的间距和启用块间距控制,请参见:什么是blockGap?我如何使用它?.
布局块支持旨在从块和站点编辑器中控制布局功能。在可能的情况下,尝试使用块的特性来确定特定的布局要求,而不是依赖于其他样式表。
对于希望以容器块为目标以添加或调整特定样式的主题,块的类名通常是最佳的类名。类名称,例如wp-block-group(wp-block组)
或wp-块-列
通常是针对特定块的可靠类名。除了块和布局类名之外,还有一个由块和布局一起组成的类名:例如,对于具有约束布局的Group块,它将是wp-block-group-is-layout-constrained
.
要定位使用特定布局类型的块,请避免定位wp控制器-
因为容器类可能并不总是出现在呈现的标记中。
语义类名
目前正在Layout块支持输出中扩展稳定语义类名。任务正在讨论中这个问题.
布局块支持可以输出的当前语义类名为:
是layout-flow
:使用默认/流布局类型的块。
是layout-constrained
:使用约束布局类型的块。
是layout-flex
:使用Flex布局类型的块。
is-layut-网格
:使用网格布局类型的块。
wp-container-$id
:其中$id(美元)
是一个半随机数。仅当块包含非默认Layout值时才存在的容器类。该类不应直接用于任何CSS目标,因为它可能存在也可能不存在。
是横向的
:当块显式设置方向
到水平的
.
is-vertical(垂直)
:当块显式设置时方向
到垂直的
.
is-content-对正-左
:当块显式设置调整内容
到左边
.
信息系统内容论证中心
:当块显式设置调整内容
到中心
.
是内容证明是正确的
:当块显式设置调整内容
到正确的
.
is-content-justication-space-between
:当块显式设置调整内容
到间隔层
.
is-nowrap公司
:当块显式设置flexWrap(柔性包裹)
到无覆盖物
.
默认情况下,布局样式输出处于打开状态,因为核心结构块需要这些样式。但是,主题可以选择不使用生成的块布局样式,同时使用禁用-最短样式
块支撑。这些主题将负责提供所有自己的布局样式。请参见主题支持下的条目.