gutenbergdocs/how-to-guides/themes/theme-support.md

## 链接颜色控制

链接颜色支持已在 WordPress 5.8 版本中趋于稳定。该功能默认处于关闭状态（`false`），主题可通过 [theme.json 文件](/docs/how-to-guides/curating-the-editor-experience/theme-json.md)启用：

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

> 替代方案：若已启用 Gutenberg 插件，传统的实验性支持 `add_theme_support( 'experimental-link-color' )` 仍可生效。当 Gutenberg 插件要求最低 WordPress 版本为 5.9 时，此备用方案将被移除。

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

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

其中：
- `<uuid>` 为随机生成的数字
- `<link-color>` 可以是 `var(--wp--preset--color--slug)`（当用户选择预设值时）或原始颜色值（当用户选择自定义值时）

区块将被附加 `.wp-elements-<uuid>` 类名。

## 外观工具

通过此设置启用以下全局样式配置项：

- 边框：颜色、圆角、样式、宽度
- 颜色：链接色彩
- 间距：区块间隙、外边距、内边距
- 排版：行高
- 尺寸：宽高比、最小高度
- 定位：粘性定位

```php
add_theme_support( 'appearance-tools' );
```

## 边框

启用完整边框设置功能：

```php
add_theme_support( 'border' );
```

## 链接颜色

启用链接颜色设置功能：

```php
add_theme_support( 'link-color' );
```

## 区块化模板部件

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

```php
add_theme_support( 'block-template-parts' );
```

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

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

您可在[主题手册的区块模板与模板部件章节](https://developer.wordpress.org/themes/block-themes/templates-and-template-parts/#block-c5fa39a2-a27d-4bd2-98d0-dc6249a0801a)中了解更多关于区块化模板部件的信息。

# 主题支持

新版区块功能为所有主题提供了基础支持，同时包含可选的增强功能以及扩展和自定义能力。

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

- **编辑器调色板** - 系统提供默认颜色集，但主题可以注册自己的颜色，并可选地将用户选择限制在预设调色板范围内。
- **编辑器字号面板** - 系统提供默认字号集，但主题可以注册自己的字号，并可选地将用户选择限制在预设字号范围内。
- **响应式嵌入内容** - 主题需主动启用响应式嵌入功能。
- **前端与编辑器样式** - 为充分发挥区块功能，主题开发者需确保核心样式正常显示并启用，或编写与自身主题最适配的自定义样式。
- **区块工具** - 主题可选择启用多种区块工具，如行高设置、自定义单位等。
- **核心区块模式** - 主题可选择禁用默认区块模式。

默认情况下，区块会提供自身样式以确保在未修改的主题中正常显示。同时它们还[提供可选的预设样式](#默认区块样式)。主题可以添加/覆盖这些样式，也可以完全不提供样式，完全依赖区块自带的样式。

某些高级区块功能需要主题本身启用支持，因为这些样式难以由区块直接提供，可能需要主题本身进行架构层面的调整才能完美适配。

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

```php
function mytheme_setup_theme_supported_features() {
	add_theme_support( 'editor-color-palette', array(
		array(
			'name'  => esc_attr__( '强品红色', 'themeLangDomain' ),
			'slug'  => 'strong-magenta',
			'color' => '#a156b4',
		),
		array(
			'name'  => esc_attr__( '浅灰品红色', 'themeLangDomain' ),
			'slug'  => 'light-grayish-magenta',
			'color' => '#d0a5db',
		),
		array(
			'name'  => esc_attr__( '极浅灰色', 'themeLangDomain' ),
			'slug'  => 'very-light-gray',
			'color' => '#eee',
		),
		array(
			'name'  => esc_attr__( '深灰色', 'themeLangDomain' ),
			'slug'  => 'very-dark-gray',
			'color' => '#444',
		),
	) );
}

add_action( 'after_setup_theme', 'mytheme_setup_theme_supported_features' );
```

## 可选功能

## 默认区块样式

核心区块包含默认的结构样式。这些样式默认会在编辑器和前端同时加载。例如控制分栏区块的CSS规则，若缺少这些规则，该区块将呈现破碎布局且无法显示分栏效果。

### 预设区块样式

区块编辑器允许主题为前端启用更具设计主张的样式。例如引用区块左侧的默认彩色条。若要在经典主题中使用这些预设样式，请添加对 `wp-block-styles` 的主题支持：

```php
add_theme_support( 'wp-block-styles' );
```

您可以在[区块库主题文件](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/theme.scss)中查看将被引入的CSS代码。

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

### 宽对齐功能：

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

```php
add_theme_support( 'align-wide' );
```

有关此功能的更多信息，请参阅[关于 `add_theme_support()` 的开发文档](https://developer.wordpress.org/reference/functions/add_theme_support/)。

### 支持自定义单位

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

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

主题还可对可用自定义单位进行筛选。

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

### 禁用默认区块模式

WordPress 内置了多种区块模式，主题可通过以下代码选择不启用捆绑模式，转而提供自有模式集：

```php
remove_theme_support( 'core-block-patterns' );
```

## 编辑器样式

区块编辑器支持主题的[编辑器样式](https://codex.wordpress.org/Editor_Style)，但其运作方式与经典编辑器略有不同。

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

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

由于其运作方式不同，您需要在`add_editor_style`函数之外，额外在主题中添加以下代码片段来启用此功能：

```php
add_theme_support( 'editor-styles' );
```

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

### 载入编辑器样式

使用`add_editor_style`函数在编辑器界面载入CSS样式。对于经典编辑器，这是为编辑器添加样式的唯一必要函数。对于新版区块编辑器，您需要先添加前述的`add_theme_support( 'editor-styles');`。

```php
add_editor_style( 'style-editor.css' );
```

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

### 基础色彩

您可以像设置普通网页那样设置编辑器样式。以下是将背景色和字体颜色改为蓝色的方法：

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

### 调整编辑器宽度

要更改编辑器的主列宽，请将以下CSS添加至`style-editor.css`：

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

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

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

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

扩展阅读：[使用样式表应用样式](/docs/how-to-guides/block-tutorial/applying-styles-with-stylesheets.md)。

## 响应式嵌入内容

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

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

为使内容在保持长宽比的同时自适应尺寸，`<body>`元素需要具有`wp-embed-responsive`类。该样式类默认未设置，需要主题通过声明支持`responsive-embeds`功能来启用：

```php
add_theme_support( 'responsive-embeds' );
```

## 间距控制

部分区块可配备内边距控制功能。此功能默认关闭，需要主题通过声明支持来启用：

```php
add_theme_support( 'custom-spacing' );
```

### 区块字体大小

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

```php
add_theme_support( 'editor-font-sizes', array(
	array(
		'name' => esc_attr__( '小号', 'themeLangDomain' ),
		'size' => 12,
		'slug' => 'small'
	),
	array(
		'name' => esc_attr__( '常规', 'themeLangDomain' ),
		'size' => 16,
		'slug' => 'regular'
	),
	array(
		'name' => esc_attr__( '大号', 'themeLangDomain' ),
		'size' => 36,
		'slug' => 'large'
	),
	array(
		'name' => esc_attr__( '超大号', 'themeLangDomain' ),
		'size' => 50,
		'slug' => 'huge'
	)
) );
```

字体大小将按照主题提供的顺序显示在字体大小选择器中。

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

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

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

<div class="callout callout-info">
<strong>注意：</strong>标识符 `default` 和 `custom` 为保留字，主题不可使用。
</div>

自 WordPress 5.9 起，要覆盖核心定义的字体大小值，没有 `theme.json` 的主题必须通过 CSS 自定义属性设置其值，而非提供类。CSS 自定义属性使用以下命名方式 `--wp--preset--font-size--<slug>`。更多信息请参阅[此开发说明](https://make.wordpress.org/core/2022/01/08/updates-for-settings-styles-and-theme-json/)。例如：

```css
:root {
	--wp--preset--font-size--small: <新值>;
	--wp--preset--font-size--large: <新值>;
}
```

### 禁用自定义字体大小

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

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

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

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

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

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

```php
add_theme_support( 'disable-custom-colors' );
```

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

### 禁用自定义渐变

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

```php
add_theme_support( 'disable-custom-gradients' );
```

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

### 禁用基础布局样式

_**注意：**自 WordPress 6.1 起。_

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

```php
add_theme_support( 'disable-layout-styles' );
```

对于希望自定义 `blockGap` 样式或区块间距的主题，请参阅[关于全局设置和样式的开发者文档](/docs/how-to-guides/themes/global-settings-and-styles.md#what-is-blockgap-and-how-can-i-use-it)。

### 支持自定义行高

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

```php
add_theme_support( 'custom-line-height' );
```

### 宽对齐与浮动元素

要创建一个能够同时适应宽幅图像、侧边栏、居中列以及限定在居中列内的浮动元素的响应式布局，可能会遇到一些困难。

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

以下是一个带标题的 `Image` 标记示例：

```html
<figure class="wp-block-image">
	<img src="..." alt="" width="200px" />
	<figcaption>简短图片标题。</figcaption>
</figure>
```

以下是一个左浮动图像的标记示例：

```html
<div class="wp-block-image">
	<figure class="alignleft">
		<img src="..." alt="" width="200px" />
		<figcaption>简短图片标题。</figcaption>
	</figure>
</div>
```

这里有一个使用上述标记实现响应式布局的 [codepen](https://codepen.io/joen/pen/zLWvrW) 示例，该布局包含侧边栏、宽幅图像以及带有限定标题的浮动元素。

### 区块调色板

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

```php
add_theme_support( 'editor-color-palette', array(
	array(
		'name'  => esc_attr__( '强品红色', 'themeLangDomain' ),
		'slug'  => 'strong-magenta',
		'color' => '#a156b4',
	),
	array(
		'name'  => esc_attr__( '浅灰品红色', 'themeLangDomain' ),
		'slug'  => 'light-grayish-magenta',
		'color' => '#d0a5db',
	),
	array(
		'name'  => esc_attr__( '极浅灰色', 'themeLangDomain' ),
		'slug'  => 'very-light-gray',
		'color' => '#eee',
	),
	array(
		'name'  => esc_attr__( '极深灰色', 'themeLangDomain' ),
		'slug'  => 'very-dark-gray',
		'color' => '#444',
	),
) );
```

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

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

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

主题负责创建在不同上下文中应用颜色的类。核心区块使用“颜色”、“背景颜色”和“边框颜色”上下文。因此，为了正确地将“强品红色”应用于核心区块的所有上下文，主题应自行实现这些类。类名的构建方式是在“has-”后附加使用短横线命名法的类名，并以上下文名称结尾。

```css
.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>`。更多信息请参阅 [此开发说明](https://make.wordpress.org/core/2022/01/08/updates-for-settings-styles-and-theme-json/)。例如：

```css
:root {
	--wp--preset--color--cyan-bluish-gray: <新值>;
	--wp--preset--color--pale-pink: <新值>;
}
```

### 区块渐变预设

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

```php
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 文档](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Images/Using_CSS_gradients) 中找到。`slug` 是渐变的唯一标识符，用于生成区块编辑器使用的 CSS 类。

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

```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>`。更多信息请参阅 [此开发说明](https://make.wordpress.org/core/2022/01/08/updates-for-settings-styles-and-theme-json/)。例如：

```css
:root {
	--wp--preset--gradient--vivid-cyan-blue-to-vivid-purple: <新值>;
	--wp--preset--gradient--light-green-cyan-to-vivid-green-cyan: <新值>;
}
```