1166 lines
34 KiB
Markdown
1166 lines
34 KiB
Markdown
## 拆分功能
|
||
|
||
当设置为 `true` 时，按下 `Enter` 键会将当前区块分割为两个独立区块。请注意，此功能仅适用于简单文本区块（例如包含单个 `RichText` 字段的段落和标题）。在 `edit` 函数中的 RichText 组件_必须_包含与文本属性键相匹配的 `identifier` 属性，这样才能正确更新选区定位，并确保系统能准确识别拆分位置。
|
||
|
||
# 支持功能
|
||
|
||
区块支持功能是一套 API，允许区块声明对特定功能的支持。
|
||
|
||
启用这些功能中的任意一项，都会在区块上注册额外属性，并提供操作这些属性的用户界面。
|
||
|
||
为了让属性应用到区块上，生成的属性会被添加到区块的包装元素中。这些属性会被添加到通过 `useBlockProps` 钩子函数返回的对象中。
|
||
|
||
`BlockEdit` 函数：
|
||
|
||
```js
|
||
function BlockEdit() {
|
||
const blockProps = useBlockProps();
|
||
|
||
return <div { ...blockProps }>Hello World!</div>;
|
||
}
|
||
```
|
||
|
||
`save` 函数：
|
||
|
||
```js
|
||
function BlockEdit() {
|
||
const blockProps = useBlockProps.save();
|
||
|
||
return <div { ...blockProps }>Hello World!</div>;
|
||
}
|
||
```
|
||
|
||
对于通过 PHP 中的 `render_callback` 渲染的动态区块，可以使用 `get_block_wrapper_attributes()` 函数。该函数返回一个包含所有生成属性的字符串，需要输出到区块包装元素的开始标签中。
|
||
|
||
`render_callback` 函数：
|
||
|
||
```php
|
||
function render_block() {
|
||
$wrapper_attributes = get_block_wrapper_attributes();
|
||
|
||
return sprintf(
|
||
'<div %1$s>%2$s</div>',
|
||
$wrapper_attributes,
|
||
'Hello World!'
|
||
);
|
||
}
|
||
```
|
||
|
||
## allowedBlocks
|
||
|
||
_**注意：** 自 WordPress 6.9 起可用。_
|
||
|
||
- 类型：`boolean`
|
||
- 默认值：`false`
|
||
|
||
此属性添加用户界面控件，使用户能够为区块容器选择允许的子区块。要使用此功能，请在 `useInnerBlocksProps` 的选项对象中将 `attributes.allowedBlocks` 作为 `allowedBlocks` 属性传递。
|
||
|
||
```js
|
||
supports: {
|
||
allowedBlocks: true
|
||
}
|
||
```
|
||
|
||
```jsx
|
||
import { useBlockProps, useInnerBlocksProps } from '@wordpress/block-editor';
|
||
|
||
function Edit( { attributes } ) {
|
||
const { allowedBlocks } = attributes;
|
||
const blockProps = useBlockProps();
|
||
const innerBlocksProps = useInnerBlocksProps( blockProps, {
|
||
allowedBlocks
|
||
} );
|
||
return <div { ...innerBlocksProps } />;
|
||
}
|
||
```
|
||
|
||
## anchor
|
||
|
||
- 类型：`boolean`
|
||
- 默认值：`false`
|
||
|
||
锚点功能允许您直接链接到页面上的特定区块。此属性添加一个用于定义区块 ID 的字段和一个复制直接链接的按钮。_重要提示：目前尚不适用于动态区块。_
|
||
|
||
```js
|
||
// 声明支持锚点链接。
|
||
supports: {
|
||
anchor: true
|
||
}
|
||
```
|
||
|
||
## auto_register
|
||
|
||
- 类型：`boolean`
|
||
- 默认值：`false`
|
||
|
||
启用[仅限 PHP 的区块](/docs/getting-started/fundamentals/registration-of-a-block.md#php-only-blocks-with-auto-registration)自动出现在区块编辑器中，无需进行 JavaScript 注册。当设置为 `true` 时，在服务器上通过 `render_callback` 注册的区块将自动在编辑器中注册并使用 `ServerSideRender`。这些区块默认使用区块 API 版本 3，如果使用旧版本，则会自动升级。
|
||
|
||
```php
|
||
register_block_type( 'my-plugin/server-block', array(
|
||
'render_callback' => function( $attributes ) {
|
||
$wrapper_attributes = get_block_wrapper_attributes();
|
||
|
||
return sprintf(
|
||
'<div %1$s>服务器内容</div>',
|
||
$wrapper_attributes
|
||
);
|
||
},
|
||
'supports' => array(
|
||
'auto_register' => true,
|
||
),
|
||
) );
|
||
```
|
||
|
||
## align
|
||
|
||
- 类型：`boolean` 或 `array`
|
||
- 默认值：`false`
|
||
|
||
此属性添加区块控件，支持更改区块的对齐方式。
|
||
|
||
```js
|
||
supports: {
|
||
// 声明支持区块对齐。
|
||
// 这将支持所有选项：
|
||
// 左对齐、居中对齐、右对齐、宽对齐和全宽对齐。
|
||
align: true
|
||
}
|
||
```
|
||
|
||
```js
|
||
supports: {
|
||
// 声明支持特定的对齐选项。
|
||
align: [ 'left', 'right', 'full' ]
|
||
}
|
||
```
|
||
|
||
当区块声明支持 `align` 时，属性定义会扩展为包含一个 `string` 类型的 align 属性。默认情况下，不分配任何对齐方式。区块可以通过指定自己的 `align` 属性并设置默认值来应用默认对齐方式。例如：
|
||
|
||
```js
|
||
attributes: {
|
||
align: {
|
||
type: 'string',
|
||
default: 'right'
|
||
}
|
||
}
|
||
```
|
||
|
||
## alignWide（宽对齐）
|
||
|
||
- 类型：`boolean`（布尔值）
|
||
- 默认值：`true`
|
||
|
||
此属性可为您的主题启用[宽对齐](/docs/how-to-guides/themes/theme-support.md#wide-alignment)功能。若需对单个区块禁用此功能，请将该标志设为 `false`。
|
||
|
||
```js
|
||
supports: {
|
||
// 移除宽对齐功能支持
|
||
alignWide: false
|
||
}
|
||
```
|
||
|
||
## ariaLabel（无障碍标签）
|
||
|
||
- 类型：`boolean`（布尔值）
|
||
- 默认值：`false`
|
||
|
||
ARIA标签可用于为元素定义无障碍访问标签。此属性支持为区块定义aria-label，且无需暴露用户界面字段。
|
||
|
||
```js
|
||
supports: {
|
||
// 启用无障碍标签支持
|
||
ariaLabel: true
|
||
}
|
||
```
|
||
|
||
## background（背景）
|
||
|
||
_**注意：** 自WordPress 6.5版本起支持。*
|
||
|
||
- 类型：`Object`（对象）
|
||
- 默认值：`null`
|
||
- 子属性说明
|
||
- `backgroundImage`：类型为 `boolean`，默认值 `false`
|
||
- `backgroundSize`：类型为 `boolean`，默认值 `false`
|
||
|
||
此值表示区块支持部分与背景相关的CSS样式属性。当启用时，若[主题声明支持](/docs/how-to-guides/themes/global-settings-and-styles.md#opt-in-into-ui-controls)，区块编辑器将显示用户界面控件供用户设置数值。
|
||
|
||
`backgroundImage` 添加用户界面控件，允许用户选择背景图像。
|
||
`backgroundSize` 添加焦点选择器用于选择背景图像位置，并允许用户选择背景尺寸（覆盖、包含、固定）。
|
||
|
||
```js
|
||
supports: {
|
||
background: {
|
||
backgroundImage: true, // 启用背景图像控制
|
||
backgroundSize: true // 启用背景图像+尺寸控制
|
||
}
|
||
}
|
||
```
|
||
|
||
当区块声明支持特定背景属性时，其属性定义将扩展至包含 `style` 属性。
|
||
|
||
当选定背景图像时，图像数据将存储在 `style.background.backgroundImage` 中。
|
||
|
||
当选定背景图像并调整其位置或尺寸时，背景位置将存储在 `style.background.backgroundPosition` 中，背景尺寸则存储在 `style.background.backgroundSize` 属性中。
|
||
|
||
- `style`：类型为 `object` 的属性，无默认值。当声明 `backgroundImage` 或 `backgroundSize` 支持时添加，用于存储用户设置的自定义值。
|
||
- `background`：类型为 `object` 的属性。
|
||
- `backgroundImage`：类型为 `object` 的属性，包含所选图像的信息
|
||
- `url`：类型为 `string`，图像URL地址
|
||
- `id`：类型为 `int`，媒体附件ID
|
||
- `source`：类型为 `string`，目前唯一值为 `file`
|
||
- `title`：类型为 `string`，媒体附件标题
|
||
- `backgroundPosition`：类型为 `string` 的属性，定义背景图像位置，由焦点选择器选定并作为 [`background-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/background-position) 值在CSS中使用
|
||
- `backgroundSize`：类型为 `string` 的属性，定义CSS [`background-size`](https://developer.mozilla.org/en-US/docs/Web/CSS/background-size) 值
|
||
|
||
区块可通过指定带默认值的自身属性来应用默认背景图像、位置和尺寸。例如：
|
||
|
||
```js
|
||
attributes: {
|
||
style: {
|
||
background: {
|
||
backgroundImage: {
|
||
"url":"图像URL"
|
||
},
|
||
backgroundPosition:"50% 50%",
|
||
backgroundSize: "cover"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## className（类名）
|
||
|
||
- 类型：`boolean`（布尔值）
|
||
- 默认值：`true`
|
||
|
||
默认情况下，类名 `.wp-block-your-block-name` 会添加到已保存标记的根元素中。这有助于为主题和插件所依赖的区块样式提供一致的机制。若因故不需要在标记中添加类名，可禁用此功能。
|
||
|
||
```js
|
||
supports: {
|
||
// 移除生成类名的支持
|
||
className: false
|
||
}
|
||
```
|
||
|
||
## html
|
||
|
||
- 类型：`boolean`
|
||
- 默认值：`true`
|
||
|
||
默认情况下，区块的标记可以单独编辑。要禁用此行为，请将 `html` 设置为 `false`。
|
||
|
||
```js
|
||
supports: {
|
||
// 移除对 HTML 模式的支持。
|
||
html: false
|
||
}
|
||
```
|
||
|
||
## inserter
|
||
|
||
- 类型：`boolean`
|
||
- 默认值：`true`
|
||
|
||
默认情况下，所有区块都会出现在插入器、区块转换菜单、样式手册等界面中。若要将某个区块从用户界面的所有部分隐藏，使其只能通过编程方式插入，请将 `inserter` 设置为 `false`。
|
||
|
||
```js
|
||
supports: {
|
||
// 在插入器中隐藏此区块。
|
||
inserter: false
|
||
}
|
||
```
|
||
|
||
## interactivity
|
||
|
||
- 类型：`boolean` 或 `object`
|
||
- 默认值：`false`
|
||
- 子属性：
|
||
- `clientNavigation`：类型 `boolean`，默认值 `false`
|
||
- `interactive`：类型 `boolean`，默认值 `false`
|
||
|
||
指示区块是否使用交互性 API 功能。
|
||
|
||
`clientNavigation` 子属性指示区块是否与交互性 API 的客户端导航兼容。
|
||
仅当区块为非交互式，或使用交互性 API 实现交互时，才将其设置为 true。若区块具有交互性但使用原生 JS、jQuery 或其他非交互性 API 的 JS 框架/库，则设置为 false。
|
||
|
||
`interactive` 子属性指示区块是否使用交互性 API 指令。
|
||
|
||
## layout
|
||
|
||
- 类型：`boolean` 或 `Object`
|
||
- 默认值：null
|
||
- 子属性：
|
||
- `default`：类型 `Object`，默认值 null
|
||
- `allowSwitching`：类型 `boolean`，默认值 `false`
|
||
- `allowEditing`：类型 `boolean`，默认值 `true`
|
||
- `allowInheriting`：类型 `boolean`，默认值 `true`
|
||
- `allowSizingOnChildren`：类型 `boolean`，默认值 `false`
|
||
- `allowVerticalAlignment`：类型 `boolean`，默认值 `true`
|
||
- `allowJustification`：类型 `boolean`，默认值 `true`
|
||
- `allowOrientation`：类型 `boolean`，默认值 `true`
|
||
- `allowCustomContentAndWideSize`：类型 `boolean`，默认值 `true`
|
||
|
||
此值仅适用于作为内部区块容器的区块。若设置为 `true`，布局类型将为 `flow`。对于其他布局类型，需要在 `default` 对象内显式设置 `type`。
|
||
|
||
### layout.default
|
||
|
||
- 类型：`Object`
|
||
- 默认值：null
|
||
|
||
允许设置 `type` 属性以定义区块的默认布局类型，以及该布局类型固有属性的默认值。例如，对于 `flex` 布局，可以为 `flexWrap` 设置默认值。
|
||
|
||
### layout.allowSwitching
|
||
|
||
- 类型：`boolean`
|
||
- 默认值：`false`
|
||
|
||
暴露一个切换器控件，允许在所有现有布局类型之间切换。
|
||
|
||
### layout.allowEditing
|
||
|
||
- 类型：`boolean`
|
||
- 默认值：`true`
|
||
|
||
决定区块侧边栏中布局控件的显示。若设置为 false，布局控件将被隐藏。
|
||
|
||
### layout.allowInheriting
|
||
|
||
- 类型：`boolean`
|
||
- 默认值：`true`
|
||
|
||
仅适用于 `flow` 布局类型，决定“内部区块使用内容宽度”切换开关的显示。
|
||
|
||
### layout.allowSizingOnChildren
|
||
|
||
- 类型：`boolean`
|
||
- 默认值：`false`
|
||
|
||
仅适用于 `flex` 布局类型，决定在弹性布局区块的所有子区块上显示尺寸控件（适应/填充/固定）。
|
||
|
||
### layout.allowVerticalAlignment
|
||
|
||
- 类型：`boolean`
|
||
- 默认值：`true`
|
||
|
||
仅适用于 `flex` 布局类型，决定区块工具栏中垂直对齐控件的显示。
|
||
|
||
### layout.allowJustification
|
||
|
||
- 类型：`boolean`
|
||
- 默认值：`true`
|
||
|
||
对于 `flex` 布局类型，决定区块工具栏和区块侧边栏中对齐控件的显示。对于 `constrained` 布局类型，决定区块侧边栏中对齐控件的显示。
|
||
|
||
### layout.allowOrientation
|
||
|
||
- 类型：`boolean`
|
||
- 默认值：`true`
|
||
|
||
仅适用于 `flex` 布局类型，决定区块工具栏中方向控件的显示。
|
||
|
||
## color（颜色）
|
||
|
||
- 类型：`Object`
|
||
- 默认值：null
|
||
- 子属性：
|
||
- `background`：类型为 `boolean`，默认值 `true`
|
||
- `button`：类型为 `boolean`，默认值 `false`
|
||
- `enableContrastChecker`：类型为 `boolean`，默认值 `true`
|
||
- `gradients`：类型为 `boolean`，默认值 `false`
|
||
- `heading`：类型为 `boolean`，默认值 `false`
|
||
- `link`：类型为 `boolean`，默认值 `false`
|
||
- `text`：类型为 `boolean`，默认值 `true`
|
||
|
||
该值表示区块支持与颜色相关的部分属性。当存在此值时，区块编辑器将显示用户界面控件供用户设置这些属性的值。
|
||
|
||
请注意，`background` 和 `text` 键的默认值为 `true`，因此如果存在 `color` 属性，它们也会被视为启用状态：
|
||
|
||
```js
|
||
supports: {
|
||
color: {
|
||
// 同时启用文本和背景 UI 控件
|
||
gradients: true // 启用渐变 UI 控件
|
||
}
|
||
}
|
||
```
|
||
|
||
也可以单独禁用它们：
|
||
|
||
```js
|
||
supports: {
|
||
color: { // 文本 UI 控件处于启用状态
|
||
background: false, // 禁用背景 UI 控件
|
||
gradients: true // 启用渐变 UI 控件
|
||
}
|
||
}
|
||
```
|
||
|
||
### color.background
|
||
|
||
此属性添加用户界面控件，允许用户为区块设置纯背景颜色。
|
||
|
||
当声明颜色支持时，此属性默认启用（与文本颜色同时启用），因此仅设置 color 就会启用背景颜色支持。
|
||
|
||
```js
|
||
supports: {
|
||
color: true // 启用背景和文本颜色支持
|
||
}
|
||
```
|
||
|
||
若要在保持其他颜色支持启用的同时禁用背景支持，请设置为 `false`。
|
||
|
||
```js
|
||
supports: {
|
||
color: {
|
||
// 禁用背景支持，文本颜色支持仍处于启用状态
|
||
background: false
|
||
}
|
||
}
|
||
```
|
||
|
||
当区块声明支持 `color.background` 时，属性定义会扩展以包含两个新属性：`backgroundColor` 和 `style`：
|
||
|
||
- `backgroundColor`：一个 `string` 类型的属性，未分配默认值。
|
||
|
||
当用户从预设背景颜色列表中选择时，预设别名会存储在 `backgroundColor` 属性中。
|
||
|
||
背景颜色预设来源于 `editor-color-palette` [主题支持](/docs/how-to-guides/themes/theme-support.md#block-color-palettes)。
|
||
|
||
区块可以通过指定带有默认值的自身属性来应用默认的预设背景颜色。例如：
|
||
|
||
```js
|
||
attributes: {
|
||
backgroundColor: {
|
||
type: 'string',
|
||
default: 'some-preset-background-slug',
|
||
}
|
||
}
|
||
```
|
||
|
||
- `style`：一个 `object` 类型的属性，未分配默认值。
|
||
|
||
当选择自定义背景颜色时（即使用自定义颜色选择器），自定义颜色值会存储在 `style.color.background` 属性中。
|
||
|
||
区块可以通过指定带有默认值的自身属性来应用默认的自定义背景颜色。例如：
|
||
|
||
```js
|
||
attributes: {
|
||
style: {
|
||
type: 'object',
|
||
default: {
|
||
color: {
|
||
background: '#aabbcc',
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### color.button
|
||
|
||
_**注意：** 自 WordPress 6.5 起可用。_
|
||
|
||
此属性添加区块控件，允许用户在区块中设置按钮颜色（文本、背景）。按钮颜色默认处于禁用状态。
|
||
|
||
要启用按钮颜色支持，请将 `color.button` 设置为 `true`。
|
||
|
||
```js
|
||
supports: {
|
||
color: {
|
||
button: true
|
||
}
|
||
}
|
||
```
|
||
|
||
按钮颜色预设来源于 `editor-color-palette` [主题支持](/docs/how-to-guides/themes/theme-support.md#block-color-palettes)。
|
||
|
||
当区块声明支持 `color.button` 时，属性定义会扩展以包含 `style` 属性：
|
||
|
||
- `style`：一个 `object` 类型的属性，未分配默认值。
|
||
|
||
当选择按钮颜色时，颜色值会存储在 `style.elements.button.color.text` 和 `style.elements.button.color.background` 属性中。
|
||
|
||
区块可以通过指定带有默认值的自身属性来应用默认的按钮颜色。例如：
|
||
|
||
```js
|
||
attributes: {
|
||
style: {
|
||
type: 'object',
|
||
default: {
|
||
elements: {
|
||
button: {
|
||
color: {
|
||
text: 'var:preset|color|contrast',
|
||
background: '#000000',
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 版式设置
|
||
|
||
- 类型：`对象`
|
||
- 默认值：`null`
|
||
- 子属性：
|
||
- `fontSize`：类型为 `布尔值`，默认值 `false`
|
||
- `lineHeight`：类型为 `布尔值`，默认值 `false`
|
||
- `textAlign`：类型为 `布尔值` 或 `数组`，默认值 `false`
|
||
|
||
此对象的存在表示区块支持某些与版式相关的属性。当支持时，区块编辑器将显示版式设置界面，允许用户控制这些属性的值。
|
||
|
||
```js
|
||
supports: {
|
||
typography: {
|
||
// 启用字体大小的支持和界面控制。
|
||
fontSize: true,
|
||
// 启用行高的支持和界面控制。
|
||
lineHeight: true,
|
||
// 启用文本对齐的支持和界面控制。
|
||
textAlign: true,
|
||
},
|
||
}
|
||
```
|
||
|
||
### typography.fontSize
|
||
|
||
- 类型：`布尔值`
|
||
- 默认值：`false`
|
||
|
||
此值表示区块支持 CSS 样式属性 `font-size`。当支持时，区块编辑器将显示一个界面控件，供用户设置其值。
|
||
|
||
该控件中显示的值是由主题通过 `editor-font-sizes` [主题支持](/docs/how-to-guides/themes/theme-support.md#block-font-sizes)声明的，如果未提供任何值，则使用默认值。
|
||
|
||
```js
|
||
supports: {
|
||
typography: {
|
||
// 启用字体大小的支持和界面控制。
|
||
fontSize: true,
|
||
},
|
||
}
|
||
```
|
||
|
||
当区块声明支持 `fontSize` 时，属性定义将扩展为包含两个新属性：`fontSize` 和 `style`：
|
||
|
||
- `fontSize`：一个 `字符串` 类型的属性，未分配默认值。它存储用户选择的任何预设值。区块可以通过指定自己的 `fontSize` 属性并设置默认值来应用默认字体大小。例如：
|
||
|
||
```js
|
||
attributes: {
|
||
fontSize: {
|
||
type: 'string',
|
||
default: 'some-value',
|
||
}
|
||
}
|
||
```
|
||
|
||
- `style`：一个 `对象` 类型的属性，未分配默认值。它存储用户设置的自定义值，并与其他区块支持（如颜色）共享。区块可以通过指定自己的 `style` 属性并设置默认值来应用默认样式。例如：
|
||
|
||
```js
|
||
attributes: {
|
||
style: {
|
||
type: 'object',
|
||
default: {
|
||
typography: {
|
||
fontSize: 'value'
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### typography.lineHeight
|
||
|
||
- 类型：`布尔值`
|
||
- 默认值：`false`
|
||
|
||
此值表示区块支持 CSS 样式属性 `line-height`。当支持时，区块编辑器将显示一个界面控件，供用户设置其值（前提是[主题声明支持](/docs/how-to-guides/themes/theme-support.md#supporting-custom-line-heights)）。
|
||
|
||
```js
|
||
supports: {
|
||
typography: {
|
||
// 启用行高的支持和界面控制。
|
||
lineHeight: true,
|
||
},
|
||
}
|
||
```
|
||
|
||
当区块声明支持 `lineHeight` 时，属性定义将扩展为包含一个新的 `style` 属性，类型为 `对象`，未分配默认值。它存储用户设置的自定义值。区块可以通过指定自己的 `style` 属性并设置默认值来应用默认样式。例如：
|
||
|
||
```js
|
||
attributes: {
|
||
style: {
|
||
type: 'object',
|
||
default: {
|
||
typography: {
|
||
lineHeight: 'value'
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### typography.textAlign
|
||
|
||
_**注意：**自 WordPress 6.6 起。_
|
||
|
||
- 类型：`布尔值` 或 `数组`
|
||
- 默认值：`false`
|
||
|
||
此属性添加区块工具栏控件，允许更改区块的文本对齐方式。
|
||
|
||
```js
|
||
supports: {
|
||
typography: {
|
||
// 声明支持区块的文本对齐。
|
||
// 这将支持所有选项：
|
||
// 左对齐、居中对齐、右对齐。
|
||
textAlign: true
|
||
}
|
||
}
|
||
```
|
||
|
||
```js
|
||
supports: {
|
||
typography: {
|
||
// 声明支持特定的文本对齐选项。
|
||
textAlign: [ 'left', 'right' ]
|
||
}
|
||
}
|
||
```
|
||
|
||
当区块声明支持 `textAlign` 时，属性定义将扩展为包含一个新的 `style` 属性，类型为 `对象`，未分配默认值。它存储用户设置的自定义值。区块可以通过指定自己的 `style` 属性并设置默认值来应用默认样式。例如：
|
||
|
||
```js
|
||
attributes: {
|
||
style: {
|
||
type: 'object',
|
||
default: {
|
||
typography: {
|
||
textAlign: 'value'
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### color.text
|
||
|
||
该属性用于添加区块控件，允许用户在区块中设置文本颜色。
|
||
|
||
当声明支持颜色功能时，此属性会默认启用（同时启用背景色），因此仅需设置颜色属性即可启用文本颜色功能。
|
||
|
||
```js
|
||
supports: {
|
||
color: true // 同时启用背景色和文本颜色，但不启用链接颜色
|
||
}
|
||
```
|
||
|
||
若需在保持其他颜色支持功能的情况下禁用文本颜色支持，可将 `color.text` 设为 `false`。
|
||
|
||
```js
|
||
supports: {
|
||
color: {
|
||
// 禁用文本颜色支持
|
||
text: false
|
||
}
|
||
}
|
||
```
|
||
|
||
文本颜色预设值来源于 `editor-color-palette` [主题支持功能](/docs/how-to-guides/themes/theme-support.md#block-color-palettes)。
|
||
|
||
当区块声明支持 `color.text` 时，属性定义将扩展包含两个新属性：`textColor` 和 `style`：
|
||
|
||
- `textColor`：未设默认值的字符串类型属性。
|
||
|
||
当用户从预设文本颜色列表中选择时，预设别名将存储在 `textColor` 属性中。
|
||
|
||
区块可通过指定带默认值的自定义属性来应用预设文本颜色。例如：
|
||
|
||
```js
|
||
attributes: {
|
||
textColor: {
|
||
type: 'string',
|
||
default: '某个预设文本颜色别名',
|
||
}
|
||
}
|
||
```
|
||
|
||
- `style`：未设默认值的对象类型属性。
|
||
|
||
当选择自定义文本颜色时（即使用自定义颜色选择器），自定义颜色值将存储在 `style.color.text` 属性中。
|
||
|
||
区块可通过指定带默认值的自定义属性来应用默认自定义文本颜色。例如：
|
||
|
||
```js
|
||
attributes: {
|
||
style: {
|
||
type: 'object',
|
||
default: {
|
||
color: {
|
||
text: '#aabbcc',
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## customClassName
|
||
|
||
- 类型：`boolean`
|
||
- 默认值：`true`
|
||
|
||
该属性用于添加自定义 className 字段以定义区块包装器类名。
|
||
|
||
```js
|
||
supports: {
|
||
// 移除对自定义 className 的支持
|
||
customClassName: false
|
||
}
|
||
```
|
||
|
||
## dimensions
|
||
|
||
_**注意：** 自 WordPress 6.2 起可用。_
|
||
|
||
- 类型：`Object`
|
||
- 默认值：null
|
||
- 子属性：
|
||
- `minHeight`：类型 `boolean`，默认值 `false`
|
||
|
||
该值表示区块支持部分与尺寸相关的 CSS 样式属性。当启用时，若[主题声明支持](/docs/how-to-guides/themes/global-settings-and-styles.md#opt-in-into-ui-controls)，区块编辑器将显示用户界面控件供用户设置数值。
|
||
|
||
```js
|
||
supports: {
|
||
dimensions: {
|
||
aspectRatio: true // 启用宽高比控件
|
||
minHeight: true // 启用最小高度控件
|
||
}
|
||
}
|
||
```
|
||
|
||
当区块声明支持特定尺寸属性时，其属性定义将扩展包含 `style` 属性：
|
||
|
||
- `style`：未设默认值的对象类型属性。该属性在声明支持 `aspectRatio` 或 `minHeight` 时添加，用于存储用户设置的自定义值。例如：
|
||
|
||
```js
|
||
attributes: {
|
||
style: {
|
||
dimensions: {
|
||
aspectRatio: "16/9",
|
||
minHeight: "50vh"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## filter
|
||
|
||
- 类型：`Object`
|
||
- 默认值：null
|
||
- 子属性：
|
||
- `duotone`：类型 `boolean`，默认值 `false`
|
||
|
||
该值表示区块支持部分与滤镜相关的属性。当启用时，区块编辑器将显示用户界面控件供用户设置数值。
|
||
|
||
### filter.duotone
|
||
|
||
该属性用于添加用户界面控件，允许用户对区块或区块局部应用双色调滤镜。
|
||
|
||
```js
|
||
supports: {
|
||
filter: {
|
||
// 启用双色调支持
|
||
duotone: true
|
||
}
|
||
},
|
||
selectors: {
|
||
filter: {
|
||
// 对图片区块内的 img 元素应用滤镜
|
||
duotone: '.wp-block-image img'
|
||
}
|
||
}
|
||
```
|
||
|
||
通过设置 `selectors.filter.duotone` 选择器，可将滤镜应用于区块内部的元素。
|
||
|
||
双色调预设值来源于 [theme.json](/docs/how-to-guides/themes/global-settings-and-styles.md) 中的 `color.duotone`。
|
||
|
||
当区块声明支持 `filter.duotone` 时，属性定义将扩展包含 `style` 属性：
|
||
|
||
- `style`：未设默认值的对象类型属性。
|
||
|
||
区块可通过指定带默认值的自定义属性来应用默认双色调。例如：
|
||
|
||
```js
|
||
attributes: {
|
||
style: {
|
||
type: 'object',
|
||
default: {
|
||
color: {
|
||
duotone: [
|
||
'#FFF',
|
||
'#000'
|
||
]
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### color.enableContrastChecker
|
||
|
||
_**注意：** 自 WordPress 6.5 起可用。_
|
||
|
||
决定对比度检查器小部件是否在区块编辑器界面中显示。
|
||
|
||
仅当区块声明支持颜色时，对比度检查器才会显示。它会测试颜色组合的可读性，并在存在潜在问题时发出警告。该属性默认启用。设置为 `false` 可显式禁用：
|
||
|
||
```js
|
||
supports: {
|
||
color: {
|
||
enableContrastChecker: false
|
||
}
|
||
}
|
||
```
|
||
|
||
### color.__experimentalDuotone
|
||
|
||
_**注意：** 自 WordPress 6.3 起已弃用。_
|
||
|
||
该属性已被 [`filter.duotone`](#filterduotone) 替代。
|
||
|
||
### color.gradients
|
||
|
||
此属性添加用户界面控件，允许用户为区块应用渐变背景。
|
||
|
||
```js
|
||
supports: {
|
||
color: {
|
||
gradients: true,
|
||
// 如果不想将默认值与渐变一起使用，则必须禁用它们。
|
||
background: false,
|
||
text: false
|
||
}
|
||
}
|
||
```
|
||
|
||
渐变预设来源于 `editor-gradient-presets` [主题支持](/docs/how-to-guides/themes/theme-support.md#block-gradient-presets)。
|
||
|
||
当区块声明支持 `color.gradient` 时，属性定义会扩展为包含两个新属性：`gradient` 和 `style`：
|
||
|
||
- `gradient`：一个 `string` 类型的属性，未分配默认值。
|
||
|
||
当用户从预设渐变列表中选择时，预设别名会存储在 `gradient` 属性中。
|
||
|
||
区块可以通过指定带有默认值的自身属性来应用默认预设渐变。例如：
|
||
|
||
```js
|
||
attributes: {
|
||
gradient: {
|
||
type: 'string',
|
||
default: 'some-preset-gradient-slug',
|
||
}
|
||
}
|
||
```
|
||
|
||
- `style`：一个 `object` 类型的属性，未分配默认值。
|
||
|
||
当选择自定义渐变（即使用自定义渐变选择器）时，自定义渐变值会存储在 `style.color.gradient` 属性中。
|
||
|
||
区块可以通过指定带有默认值的自身属性来应用默认自定义渐变。例如：
|
||
|
||
```js
|
||
attributes: {
|
||
style: {
|
||
type: 'object',
|
||
default: {
|
||
color: {
|
||
gradient: 'linear-gradient(135deg,rgb(170,187,204) 0%,rgb(17,34,51) 100%)',
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### color.heading
|
||
|
||
_**注意：** 自 WordPress 6.5 起可用。_
|
||
|
||
此属性添加区块控件，允许用户在区块中设置标题颜色。标题颜色默认禁用。
|
||
|
||
要启用标题颜色支持，请将 `color.heading` 设置为 `true`。
|
||
|
||
```js
|
||
supports: {
|
||
color: {
|
||
// 启用标题颜色支持。
|
||
heading: true
|
||
}
|
||
}
|
||
```
|
||
|
||
标题颜色预设来源于 `editor-color-palette` [主题支持](/docs/how-to-guides/themes/theme-support.md#block-color-palettes)。
|
||
|
||
当区块声明支持 `color.heading` 时，属性定义会扩展为包含 `style` 属性：
|
||
|
||
- `style`：一个 `object` 类型的属性，未分配默认值。
|
||
|
||
当选择标题颜色时，颜色值会存储在 `style.elements.heading.color.text` 和 `style.elements.heading.color.background` 属性中。
|
||
|
||
区块可以通过指定带有默认值的自身属性来应用默认标题颜色。例如：
|
||
|
||
```js
|
||
attributes: {
|
||
style: {
|
||
type: 'object',
|
||
default: {
|
||
elements: {
|
||
heading: {
|
||
color: {
|
||
text: 'var:preset|color|contrast',
|
||
background: '#000000',
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### color.link
|
||
|
||
此属性添加区块控件，允许用户在区块中设置链接颜色。链接颜色默认禁用。
|
||
|
||
要启用链接颜色支持，请将 `color.link` 设置为 `true`。
|
||
|
||
```js
|
||
supports: {
|
||
color: {
|
||
link: true
|
||
}
|
||
}
|
||
```
|
||
|
||
链接颜色预设来源于 `editor-color-palette` [主题支持](/docs/how-to-guides/themes/theme-support.md#block-color-palettes)。
|
||
|
||
当区块声明支持 `color.link` 时，属性定义会扩展为包含 `style` 属性：
|
||
|
||
- `style`：一个 `object` 类型的属性，未分配默认值。
|
||
|
||
当选择链接颜色时，颜色值会存储在 `style.elements.link.color.text` 和 `style.elements.link.:hover.color.text` 属性中。
|
||
|
||
区块可以通过指定带有默认值的自身属性来应用默认链接颜色。例如：
|
||
|
||
```js
|
||
attributes: {
|
||
style: {
|
||
type: 'object',
|
||
default: {
|
||
elements: {
|
||
link: {
|
||
color: {
|
||
text: 'var:preset|color|contrast',
|
||
},
|
||
":hover": {
|
||
color: {
|
||
text: "#000000"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### layout.allowCustomContentAndWideSize
|
||
|
||
- 类型：`boolean`
|
||
- 默认值：`true`
|
||
|
||
仅适用于 `constrained` 布局类型，用于控制区块侧边栏中自定义内容与宽尺寸控件的显示。
|
||
|
||
## lock
|
||
|
||
- 类型：`boolean`
|
||
- 默认值：`true`
|
||
|
||
区块可能需要禁用锁定状态的切换功能。默认情况下，用户可通过区块“选项”下拉菜单锁定/解锁区块。若要禁用此行为，可将 `lock` 设为 `false`。
|
||
|
||
```js
|
||
supports: {
|
||
// 移除对锁定UI的支持
|
||
lock: false
|
||
}
|
||
```
|
||
|
||
## multiple
|
||
|
||
- 类型：`boolean`
|
||
- 默认值：`true`
|
||
|
||
非多重区块在每个文章中只能插入一次。例如，内置的“更多”区块若已存在于正在编辑的文章中，则无法再次插入。非多重区块的图标会自动变灰（不可点击）以防止多次插入。
|
||
|
||
```js
|
||
supports: {
|
||
// 每篇文章仅使用该区块一次
|
||
multiple: false
|
||
}
|
||
```
|
||
|
||
## position
|
||
|
||
_**注意：** 自 WordPress 6.2 起可用。_
|
||
|
||
- 类型：`Object`
|
||
- 默认值：null
|
||
- 子属性：
|
||
- `sticky`：类型为 `boolean`，默认值 `false`
|
||
|
||
此值表示区块支持部分与定位相关的 CSS 样式属性。若声明支持，且[主题声明支持](/docs/how-to-guides/themes/global-settings-and-styles.md#opt-in-into-ui-controls)，区块编辑器将显示 UI 控件供用户设置这些值。
|
||
|
||
注意：粘性定位控件目前仅适用于文档根层级的区块。将区块设为 `sticky` 位置后，当用户滚动页面时，该区块会粘附至其直接父级。
|
||
|
||
```js
|
||
supports: {
|
||
position: {
|
||
sticky: true // 启用选择粘性定位
|
||
}
|
||
}
|
||
```
|
||
|
||
当区块声明支持特定定位属性时，其属性定义会扩展以包含 `style` 属性。
|
||
|
||
- `style`：类型为 `object` 的属性，无默认值。当声明支持 `sticky` 时添加。它存储用户设置的自定义值。例如：
|
||
|
||
```js
|
||
attributes: {
|
||
style: {
|
||
position: {
|
||
type: "sticky",
|
||
top: "0px"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## renaming
|
||
|
||
_**注意：** 自 WordPress 6.5 起可用。_
|
||
|
||
- 类型：`boolean`
|
||
- 默认值：`true`
|
||
|
||
默认情况下，用户可通过区块“选项”下拉菜单或“高级”面板重命名区块。若要禁用此行为，可将 `renaming` 设为 false。
|
||
|
||
```js
|
||
supports: {
|
||
// 禁止在编辑器中重命名该区块
|
||
renaming: false,
|
||
}
|
||
```
|
||
|
||
## reusable
|
||
|
||
- 类型：`boolean`
|
||
- 默认值：`true`
|
||
|
||
区块可能需要禁用转换为可重用区块的功能。默认情况下，所有区块均可转换为可重用区块。若将 `reusable` 支持设为 false，则不会显示将区块转换为可重用区块的选项。
|
||
|
||
```js
|
||
supports: {
|
||
// 禁止将该区块转换为可重用区块
|
||
reusable: false,
|
||
}
|
||
```
|
||
|
||
## shadow
|
||
|
||
_**注意：** 自 WordPress 6.5 起可用。_
|
||
|
||
- 类型：`boolean`
|
||
- 默认值：`false`
|
||
|
||
此属性添加区块控件，允许用户为区块设置盒子阴影。默认情况下阴影功能是禁用的。
|
||
|
||
```js
|
||
supports: {
|
||
shadow: true // 启用盒子阴影选择器
|
||
}
|
||
```
|
||
|
||
阴影预设来源于 `theme.json` 中定义的阴影预设。
|
||
|
||
当区块声明支持 `shadow` 时，其属性定义会扩展以包含 `style` 属性：
|
||
|
||
- `style`：类型为 `object` 的属性，无默认值。
|
||
|
||
当选择阴影时，颜色值会存储在 `style.shadow` 中。
|
||
|
||
区块可通过指定带有默认值的自身属性来应用默认阴影。例如：
|
||
|
||
```js
|
||
attributes: {
|
||
style: {
|
||
type: 'object',
|
||
default: {
|
||
shadow: "var:preset|shadow|deep"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## spacing
|
||
|
||
- 类型：`Object`
|
||
- 默认值：null
|
||
- 子属性：
|
||
- `margin`：类型为 `boolean` 或 `array`，默认值 `false`
|
||
- `padding`：类型为 `boolean` 或 `array`，默认值 `false`
|
||
- `blockGap`：类型为 `boolean` 或 `array`，默认值 `false`
|
||
|
||
此值表示区块支持部分与间距相关的 CSS 样式属性。若声明支持，且[主题声明支持](/docs/how-to-guides/themes/theme-support.md#cover-block-padding)，区块编辑器将显示 UI 控件供用户设置这些值。
|
||
|
||
```js
|
||
supports: {
|
||
spacing: {
|
||
margin: true, // 启用边距 UI 控件
|
||
padding: true, // 启用内边距 UI 控件
|
||
blockGap: true, // 对同样使用 `layout` 的区块启用区块间距 UI 控件
|
||
}
|
||
}
|
||
```
|
||
|
||
当区块声明支持特定间距属性时，其属性定义会扩展以包含 `style` 属性。
|
||
|
||
- `style`：类型为 `object` 的属性，无默认值。当声明支持 `margin` 或 `padding` 时添加。它存储用户设置的自定义值。例如：
|
||
|
||
```js
|
||
attributes: {
|
||
style: {
|
||
margin: 'value',
|
||
padding: {
|
||
top: 'value',
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
间距属性可定义可配置的允许边——'top'、'right'、'bottom'、'left'。当定义了此类任意边时，仅显示这些边的 UI 控件。
|
||
|
||
轴向边使用 `vertical` 和 `horizontal` 术语定义，并为每个轴向对显示单个 UI 控件（例如，`vertical` 同时控制顶部和底部边）。间距属性可以支持任意单个边 **或** 轴向边，但不能混合使用两者。
|
||
|
||
注意：`blockGap` 接受 `vertical` 和 `horizontal` 轴向边，用于调整间距的列和行值。`blockGap` 不支持任意边。
|
||
|
||
```js
|
||
supports: {
|
||
spacing: {
|
||
margin: [ 'top', 'bottom' ], // 为任意边启用边距
|
||
padding: true, // 为所有边启用内边距
|
||
blockGap: [ 'horizontal', 'vertical' ], // 启用轴向（列/行）区块间距控件
|
||
}
|
||
}
|
||
``` |