主题支持

新的区块在所有主题中都包含基线支持，提供可选的增强功能，并具备扩展和自定义的能力。

构建主题时需要考虑几个新概念：

编辑器调色板 - 提供一组默认颜色，但主题可以注册自己的颜色，并可选地限制用户只能从定义的调色板中选择。
编辑器文字大小调色板 - 提供一组默认尺寸，但主题可以注册自己的尺寸，并可选地限制用户只能从预设尺寸中选择。
响应式嵌入 - 主题必须选择启用响应式嵌入。
前端与编辑器样式 - 为了充分利用区块，主题作者需要确保核心样式看起来良好并选择启用，或者编写自己的样式以最适合其主题。
区块工具 - 主题可以选择启用多种区块工具，如行高、自定义单位。
核心区块模式 - 主题可以选择退出默认区块模式。

默认情况下，区块提供其样式，以便在主题中无需任何更改即可实现对区块的基本支持。它们还提供可选的预设样式。主题可以添加/覆盖这些样式，或者完全不提供样式，完全依赖区块提供的样式。

一些高级区块功能需要主题本身选择启用支持，因为区块很难提供这些样式，它们可能需要主题本身进行一些架构设计，才能良好工作。

要选择启用这些功能之一，请在主题的 functions.php 文件中调用 add_theme_support。例如：

function mytheme_setup_theme_supported_features() {
	add_theme_support( 'editor-color-palette', array(
		array(
			'name'  => esc_attr__( 'strong magenta', 'themeLangDomain' ),
			'slug'  => 'strong-magenta',
			'color' => '#a156b4',
		),
		array(
			'name'  => esc_attr__( 'light grayish magenta', 'themeLangDomain' ),
			'slug'  => 'light-grayish-magenta',
			'color' => '#d0a5db',
		),
		array(
			'name'  => esc_attr__( 'very light gray', 'themeLangDomain' ),
			'slug'  => 'very-light-gray',
			'color' => '#eee',
		),
		array(
			'name'  => esc_attr__( 'very dark gray', 'themeLangDomain' ),
			'slug'  => 'very-dark-gray',
			'color' => '#444',
		),
	) );
}

add_action( 'after_setup_theme', 'mytheme_setup_theme_supported_features' );

可选功能

默认区块样式

核心区块包含默认的结构样式。这些样式默认在编辑器和前端同时加载。例如，控制分栏区块的 CSS 就是这类样式。若缺少这些规则，区块将呈现为完全不分栏的破碎布局。

主观性区块样式

区块编辑器允许主题在前端采用更具主观性的样式。这些样式的一个例子是引用区块左侧的默认彩色条。如果您希望在经典主题中使用这些主观性样式，请为主题添加对 wp-block-styles 的支持：

add_theme_support( 'wp-block-styles' );

您可以在区块库主题文件中查看将包含的 CSS。

对于区块主题或提供 theme.json 文件的主题，不建议使用此主题支持。相反，为确保全局样式规则与区块样式之间没有样式冲突，请将所需的区块样式添加到主题的 theme.json 文件中。

宽对齐：

某些区块（例如图像区块）可以通过向区块包装器添加相应的类名（alignwide 或 alignfull）来定义“宽”或“全宽”对齐。主题可以通过调用以下函数选择启用此功能：

add_theme_support( 'align-wide' );

有关此函数的更多信息，请参阅关于 add_theme_support() 的开发者文档。

宽幅对齐与浮动元素

要创建一个既能容纳宽幅图像、侧边栏、居中列，又能让浮动元素保持在居中列内的响应式布局，可能会比较困难。

区块编辑器为浮动图像添加了额外的标记，以便更轻松地进行样式设置。

以下是带标题的 Image 标记：

<figure class="wp-block-image">
	<img src="..." alt="" width="200px" />
	<figcaption>Short image caption.</figcaption>
</figure>

以下是左浮动图像的标记：

<div class="wp-block-image">
	<figure class="alignleft">
		<img src="..." alt="" width="200px" />
		<figcaption>Short image caption.</figcaption>
	</figure>
</div>

这里有一个 codepen 示例，使用上述标记实现了一个响应式布局，该布局包含侧边栏、宽幅图像以及带有限定标题的浮动元素。

区块调色板

不同区块可以自定义颜色。区块编辑器提供了默认调色板，但主题可以覆盖它并提供自己的调色板：

add_theme_support( 'editor-color-palette', array(
	array(
		'name'  => esc_attr__( 'strong magenta', 'themeLangDomain' ),
		'slug'  => 'strong-magenta',
		'color' => '#a156b4',
	),
	array(
		'name'  => esc_attr__( 'light grayish magenta', 'themeLangDomain' ),
		'slug'  => 'light-grayish-magenta',
		'color' => '#d0a5db',
	),
	array(
		'name'  => esc_attr__( 'very light gray', 'themeLangDomain' ),
		'slug'  => 'very-light-gray',
		'color' => '#eee',
	),
	array(
		'name'  => esc_attr__( 'very dark gray', 'themeLangDomain' ),
		'slug'  => 'very-dark-gray',
		'color' => '#444',
	),
) );

name 是一个人类可读的标签（如上所示），它出现在工具提示中，并为用户提供颜色的有意义的描述。这对于依赖屏幕阅读器或难以感知颜色的人来说尤其重要。slug 是颜色的唯一标识符，用于生成区块编辑器调色板使用的 CSS 类。color 是指定颜色的十六进制代码。

有些颜色会动态变化——例如“主色”和“次色”——比如在 Twenty Nineteen 主题中，无法通过编程方式描述。尽管如此，仍然建议在适用时为至少默认值提供有意义的 name。

颜色将按顺序显示在调色板上，并且可以指定的颜色数量没有限制。

主题负责创建在不同上下文中应用颜色的类。核心区块使用“color”、“background-color”和“border-color”上下文。因此，要将“strong magenta”正确应用到核心区块的所有上下文，主题应自行实现这些类。类名的构建方式是：附加 'has-'，后跟使用短横线命名法的类名，并以上下文名称结尾。

.has-strong-magenta-color {
	color: #a156b4;
}

.has-strong-magenta-background-color {
	background-color: #a156b4;
}

.has-strong-magenta-border-color {
	border-color: #a156b4;
}

从 WordPress 5.9 开始，要覆盖核心定义的颜色值，没有 theme.json 的主题必须通过 CSS 自定义属性来设置它们的值，而不是提供类。CSS 自定义属性使用以下命名 --wp--preset--color--<slug>。更多信息请参见此开发说明。例如：

:root {
	--wp--preset--color--cyan-bluish-gray: <new_value>;
	--wp--preset--color--pale-pink: <new_value>;
}

区块渐变预设

不同区块可以从预定义的渐变列表中进行选择。区块编辑器提供默认的渐变预设，但主题可以覆盖它们并提供自己的预设：

add_theme_support(
	'editor-gradient-presets',
	array(
		array(
			'name'     => esc_attr__( '鲜艳的青蓝色到鲜艳的紫色', 'themeLangDomain' ),
			'gradient' => 'linear-gradient(135deg,rgba(6,147,227,1) 0%,rgb(155,81,224) 100%)',
			'slug'     => 'vivid-cyan-blue-to-vivid-purple'
		),
		array(
			'name'     => esc_attr__( '鲜艳的绿青色到鲜艳的青蓝色', 'themeLangDomain' ),
			'gradient' => 'linear-gradient(135deg,rgba(0,208,132,1) 0%,rgba(6,147,227,1) 100%)',
			'slug'     =>  'vivid-green-cyan-to-vivid-cyan-blue',
		),
		array(
			'name'     => esc_attr__( '浅绿青色到鲜艳的绿青色', 'themeLangDomain' ),
			'gradient' => 'linear-gradient(135deg,rgb(122,220,180) 0%,rgb(0,208,130) 100%)',
			'slug'     => 'light-green-cyan-to-vivid-green-cyan',
		),
		array(
			'name'     => esc_attr__( '明亮的鲜艳琥珀色到明亮的鲜艳橙色', 'themeLangDomain' ),
			'gradient' => 'linear-gradient(135deg,rgba(252,185,0,1) 0%,rgba(255,105,0,1) 100%)',
			'slug'     => 'luminous-vivid-amber-to-luminous-vivid-orange',
		),
		array(
			'name'     => esc_attr__( '明亮的鲜艳橙色到鲜艳的红色', 'themeLangDomain' ),
			'gradient' => 'linear-gradient(135deg,rgba(255,105,0,1) 0%,rgb(207,46,46) 100%)',
			'slug'     => 'luminous-vivid-orange-to-vivid-red',
		),
	)
);

name 是一个人类可读的标签（如上所示），它出现在工具提示中，并为用户提供渐变的含义描述。这对于依赖屏幕阅读器或在感知颜色方面有困难的用户尤其重要。gradient 是应用于区块背景图像的渐变 CSS 值。有效渐变类型的详细信息可以在 mozilla 文档中找到。slug 是渐变的唯一标识符，用于生成区块编辑器使用的 CSS 类。

主题负责创建应用渐变的类。因此，要正确应用“鲜艳的青蓝色到鲜艳的紫色”，主题应实现以下类：

.has-vivid-cyan-blue-to-vivid-purple-gradient-background {
	background: linear-gradient(
		135deg,
		rgba( 6, 147, 227, 1 ) 0%,
		rgb( 155, 81, 224 ) 100%
	);
}

从 WordPress 5.9 开始，要覆盖核心定义的渐变值，没有 theme.json 的主题必须通过 CSS 自定义属性来设置它们的值，而不是提供类。CSS 自定义属性使用以下命名 --wp--preset--gradient--<slug>。更多信息请参阅此开发说明。例如：

:root {
	--wp--preset--gradient--vivid-cyan-blue-to-vivid-purple: <new_value>;
	--wp--preset--gradient--light-green-cyan-to-vivid-green-cyan: <new_value>;
}

区块字体大小

区块可能允许用户配置所使用的字体大小，例如段落区块。区块提供一组默认的字体大小，但主题可以覆盖它并提供自己的设置：

add_theme_support( 'editor-font-sizes', array(
	array(
		'name' => esc_attr__( 'Small', 'themeLangDomain' ),
		'size' => 12,
		'slug' => 'small'
	),
	array(
		'name' => esc_attr__( 'Regular', 'themeLangDomain' ),
		'size' => 16,
		'slug' => 'regular'
	),
	array(
		'name' => esc_attr__( 'Large', 'themeLangDomain' ),
		'size' => 36,
		'slug' => 'large'
	),
	array(
		'name' => esc_attr__( 'Huge', 'themeLangDomain' ),
		'size' => 50,
		'slug' => 'huge'
	)
) );

字体大小会按照主题提供的顺序在字体大小选择器中渲染。

主题负责创建应用正确字体大小样式的类。类名的构建方式是：添加 'has-' 前缀，后接使用短横线命名法的字体大小名称，并以 -font-size 结尾。

以常规字体大小为例，主题可以提供以下类。

.has-regular-font-size {
	font-size: 16px;
}

注意： 别名 `default` 和 `custom` 是保留的，主题不能使用。

从 WordPress 5.9 开始，要覆盖核心定义的字体大小值，没有 theme.json 的主题必须通过 CSS 自定义属性来设置其值，而不是提供类。CSS 自定义属性使用以下命名方式 --wp--preset--font-size--<slug>。更多信息请参阅此开发说明。例如：

:root {
	--wp--preset--font-size--small: <new_value>;
	--wp--preset--font-size--large: <new_value>;
}

禁用自定义字体大小

主题可以通过以下代码禁用设置自定义字体大小的功能：

add_theme_support( 'disable-custom-font-sizes' );

设置后，用户将被限制使用区块编辑器提供的默认字体大小，或通过 editor-font-sizes 主题支持设置提供的字体大小。

在区块调色板中禁用自定义颜色

默认情况下，区块提供的调色板允许用户选择与编辑器或主题默认颜色不同的自定义颜色。

主题可以通过以下方式禁用此功能：

add_theme_support( 'disable-custom-colors' );

此标志将确保用户只能从主题提供的 editor-color-palette 中选择颜色，如果主题未提供调色板，则只能从编辑器默认颜色中选择。

禁用自定义渐变

主题可以通过以下代码禁用设置自定义渐变的功能：

add_theme_support( 'disable-custom-gradients' );

设置后，用户将被限制使用区块编辑器提供的默认渐变或通过 editor-gradient-presets 主题支持设置提供的渐变。

禁用基础布局样式

注意： 自 WordPress 6.1 起。

主题可以选择退出生成的区块布局样式，这些样式为核心区块（包括群组、列、按钮和社交图标）提供默认的结构样式。通过使用以下代码，这些主题承诺提供自己的结构样式，因为使用此功能将导致核心区块在编辑器和网站前端显示不正确：

add_theme_support( 'disable-layout-styles' );

对于希望自定义 blockGap 样式或区块间距的主题，请参阅关于全局设置与样式的开发者文档。

支持自定义行高

某些区块（如段落和标题）支持自定义行高。主题可通过以下代码启用此功能支持：

add_theme_support( 'custom-line-height' );

支持自定义单位

除了像素外，用户还可以使用其他单位来定义尺寸、内边距等。可用的单位包括：px、em、rem、vh、vw。主题可以通过以下代码禁用此功能：

add_theme_support( 'custom-units', array() );

主题也可以筛选可用的自定义单位。

add_theme_support( 'custom-units', 'rem', 'em' );

禁用默认区块模式。

WordPress 内置了多种区块模式，主题可以通过以下代码选择不使用捆绑的模式，并提供自己的模式集：

remove_theme_support( 'core-block-patterns' );

编辑器样式

区块编辑器支持主题的编辑器样式，但其工作方式与经典编辑器略有不同。

在经典编辑器中，编辑器样式表会直接加载到所见即所得编辑器的 iframe 中，不做任何更改。然而，区块编辑器不使用 iframe。为确保您的样式仅应用于编辑器内容，我们会通过选择性重写或调整某些 CSS 选择器来自动转换您的编辑器样式。这也使得区块编辑器能够在区块变体预览中利用您的编辑器样式。

例如，如果您在编辑器样式中编写 body { ... }，这将被重写为 .editor-styles-wrapper { ... }。这也意味着您不应直接针对任何编辑器类名。

由于其工作方式略有不同，除了使用 add_editor_style 函数外，您还需要在主题中添加额外代码片段来启用此功能：

add_theme_support( 'editor-styles' );

您无需过多更改编辑器样式；大多数主题只需添加上面的代码片段，即可在经典编辑器和区块编辑器中获得类似效果。

加入编辑器样式

使用 add_editor_style 函数在编辑器屏幕上加入并加载 CSS。对于经典编辑器，这是为编辑器添加样式所需的唯一函数。对于新的区块编辑器，您首先需要如上所述的 add_theme_support( 'editor-styles');。

add_editor_style( 'style-editor.css' );

将此代码添加到您的 functions.php 文件中，会将样式表 style-editor.css 加入编辑器待加载的样式表队列。

基础颜色

你可以像设置其他网页一样自定义编辑器样式。以下是如何将背景色和字体颜色改为蓝色：

/* 将此代码添加到你的 `style-editor.css` 文件中 */
body {
	background-color: #d3ebf3;
	color: #00005d;
}

调整编辑器宽度

要更改编辑器的主列宽度，请将以下 CSS 代码添加到 style-editor.css 文件中：

/* 主列宽度 */
.wp-block {
	max-width: 720px;
}

/* "宽"区块的宽度 */
.wp-block[data-align='wide'] {
	max-width: 1080px;
}

/* "全宽"区块的宽度 */
.wp-block[data-align='full'] {
	max-width: none;
}

您可以使用这些编辑器宽度值来匹配主题中的设置。可以使用任何 CSS 宽度单位，包括 % 或 px。

扩展阅读：使用样式表应用样式。

响应式嵌入内容

嵌入区块会自动为嵌入内容应用样式，以反映在 iFrame 中嵌入内容的长宽比。应用了长宽比响应式样式的区块示例如下：

<figure class="wp-embed-aspect-16-9 wp-has-aspect-ratio">...</figure>

为使内容能够调整大小并保持其长宽比，<body> 元素需要添加 wp-embed-responsive 类。此设置默认未启用，需要主题选择启用 responsive-embeds 功能：

add_theme_support( 'responsive-embeds' );

间距控制

某些区块可以拥有内边距控制功能。此功能默认关闭，需要主题通过声明支持来启用：

add_theme_support( 'custom-spacing' );

链接颜色控制

链接支持功能已在 WordPress 5.8 中稳定发布。默认值为 false，主题可以通过 theme.json 文件启用：

{
	"settings": {
		"color": {
			"link": true
		}
	}
}

或者，在启用 Gutenberg 插件的情况下，旧的遗留支持 add_theme_support( 'experimental-link-color' ) 也有效。当 Gutenberg 插件要求 WordPress 5.9 作为最低版本时，此回退方案将被移除。

当用户设置区块的链接颜色时，将添加以下形式的新样式：

.wp-elements-<uuid> a {
	color: <link-color> !important;
}

其中：

<uuid> 是一个随机数
<link-color> 是 var(--wp--preset--color--slug)（如果用户选择了预设值）或原始颜色值（如果用户选择了自定义值）

该区块将附加 .wp-elements-<uuid> 类。

外观工具

使用此设置可启用以下全局样式设置：

边框：颜色、半径、样式、宽度
颜色：链接
间距：块间距、外边距、内边距
排版：行高
尺寸：宽高比、高度、最小高度、宽度
位置：粘性定位

add_theme_support( 'appearance-tools' );

边框

使用此功能启用所有边框设置：

add_theme_support( 'border' );

链接颜色

使用此功能启用链接颜色设置：

add_theme_support( 'link-color' );

区块化模板部件

区块化模板部件允许管理员使用区块编辑网站的特定部分。此功能默认关闭，需要主题通过声明支持来启用：

add_theme_support( 'block-template-parts' );

此功能仅对非区块化主题有意义，因为区块化主题已通过站点编辑器支持区块化模板部件。

独立的模板部件编辑器不允许编辑者创建新的或删除现有的模板部件。这是因为主题需要在 PHP 模板中手动包含模板部件。

您可以在主题手册的区块模板和模板部件章节中了解更多关于区块化模板部件的信息。

这篇文档对你有帮助吗？