2025-10-22 01:40:18 +08:00

34 KiB

Raw Blame History

拆分功能

当设置为 true 时，按下 Enter 键会将当前区块分割为两个独立区块。请注意，此功能仅适用于简单文本区块（例如包含单个 RichText 字段的段落和标题）。在 edit 函数中的 RichText 组件_必须_包含与文本属性键相匹配的 identifier 属性，这样才能正确更新选区定位，并确保系统能准确识别拆分位置。

支持功能

区块支持功能是一套 API，允许区块声明对特定功能的支持。

启用这些功能中的任意一项，都会在区块上注册额外属性，并提供操作这些属性的用户界面。

为了让属性应用到区块上，生成的属性会被添加到区块的包装元素中。这些属性会被添加到通过 useBlockProps 钩子函数返回的对象中。

BlockEdit 函数：

function BlockEdit() {
	const blockProps = useBlockProps();

	return <div { ...blockProps }>Hello World!</div>;
}

save 函数：

function BlockEdit() {
	const blockProps = useBlockProps.save();

	return <div { ...blockProps }>Hello World!</div>;
}

对于通过 PHP 中的 render_callback 渲染的动态区块，可以使用 get_block_wrapper_attributes() 函数。该函数返回一个包含所有生成属性的字符串，需要输出到区块包装元素的开始标签中。

render_callback 函数：

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 属性传递。

supports: {
	allowedBlocks: true
}

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 的字段和一个复制直接链接的按钮。重要提示：目前尚不适用于动态区块。

// 声明支持锚点链接。
supports: {
	anchor: true
}

auto_register

类型：boolean
默认值：false

启用仅限 PHP 的区块自动出现在区块编辑器中，无需进行 JavaScript 注册。当设置为 true 时，在服务器上通过 render_callback 注册的区块将自动在编辑器中注册并使用 ServerSideRender。这些区块默认使用区块 API 版本 3，如果使用旧版本，则会自动升级。

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

此属性添加区块控件，支持更改区块的对齐方式。

supports: {
	// 声明支持区块对齐。
	// 这将支持所有选项：
	// 左对齐、居中对齐、右对齐、宽对齐和全宽对齐。
	align: true
}

supports: {
	// 声明支持特定的对齐选项。
	align: [ 'left', 'right', 'full' ]
}

当区块声明支持 align 时，属性定义会扩展为包含一个 string 类型的 align 属性。默认情况下，不分配任何对齐方式。区块可以通过指定自己的 align 属性并设置默认值来应用默认对齐方式。例如：

attributes: {
    align: {
        type: 'string',
        default: 'right'
    }
}

alignWide（宽对齐）

类型：boolean（布尔值）
默认值：true

此属性可为您的主题启用宽对齐功能。若需对单个区块禁用此功能，请将该标志设为 false。

supports: {
	// 移除宽对齐功能支持
	alignWide: false
}

ariaLabel（无障碍标签）

类型：boolean（布尔值）
默认值：false

ARIA标签可用于为元素定义无障碍访问标签。此属性支持为区块定义aria-label，且无需暴露用户界面字段。

supports: {
	// 启用无障碍标签支持
	ariaLabel: true
}

background（背景）

_注意：自WordPress 6.5版本起支持。*

类型：Object（对象）
默认值：null
子属性说明
- backgroundImage：类型为 boolean，默认值 false
- backgroundSize：类型为 boolean，默认值 false

此值表示区块支持部分与背景相关的CSS样式属性。当启用时，若主题声明支持，区块编辑器将显示用户界面控件供用户设置数值。

backgroundImage 添加用户界面控件，允许用户选择背景图像。 backgroundSize 添加焦点选择器用于选择背景图像位置，并允许用户选择背景尺寸（覆盖、包含、固定）。

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 值在CSS中使用
  - backgroundSize：类型为 string 的属性，定义CSS background-size 值

区块可通过指定带默认值的自身属性来应用默认背景图像、位置和尺寸。例如：

attributes: {
    style: {
        background: {
            backgroundImage: {
				"url":"图像URL"
			},
			backgroundPosition:"50% 50%",
            backgroundSize: "cover"
        }
    }
}

className（类名）

类型：boolean（布尔值）
默认值：true

默认情况下，类名 .wp-block-your-block-name 会添加到已保存标记的根元素中。这有助于为主题和插件所依赖的区块样式提供一致的机制。若因故不需要在标记中添加类名，可禁用此功能。

supports: {
	// 移除生成类名的支持
	className: false
}

html

类型：boolean
默认值：true

默认情况下，区块的标记可以单独编辑。要禁用此行为，请将 html 设置为 false。

supports: {
	// 移除对 HTML 模式的支持。
	html: false
}

inserter

类型：boolean
默认值：true

默认情况下，所有区块都会出现在插入器、区块转换菜单、样式手册等界面中。若要将某个区块从用户界面的所有部分隐藏，使其只能通过编程方式插入，请将 inserter 设置为 false。

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 属性，它们也会被视为启用状态：

supports: {
	color: {
		// 同时启用文本和背景 UI 控件
		gradients: true // 启用渐变 UI 控件
	}
}

也可以单独禁用它们：

supports: {
    color: { // 文本 UI 控件处于启用状态
        background: false, // 禁用背景 UI 控件
        gradients: true // 启用渐变 UI 控件
    }
}

color.background

此属性添加用户界面控件，允许用户为区块设置纯背景颜色。

当声明颜色支持时，此属性默认启用（与文本颜色同时启用），因此仅设置 color 就会启用背景颜色支持。

supports: {
    color: true // 启用背景和文本颜色支持
}

若要在保持其他颜色支持启用的同时禁用背景支持，请设置为 false。

supports: {
    color: {
        // 禁用背景支持，文本颜色支持仍处于启用状态
        background: false
    }
}

当区块声明支持 color.background 时，属性定义会扩展以包含两个新属性：backgroundColor 和 style：

backgroundColor：一个 string 类型的属性，未分配默认值。

当用户从预设背景颜色列表中选择时，预设别名会存储在 backgroundColor 属性中。

背景颜色预设来源于 editor-color-palette 主题支持。

区块可以通过指定带有默认值的自身属性来应用默认的预设背景颜色。例如：
```
attributes: {
    backgroundColor: {
        type: 'string',
        default: 'some-preset-background-slug',
    }
}
```
style：一个 object 类型的属性，未分配默认值。

当选择自定义背景颜色时（即使用自定义颜色选择器），自定义颜色值会存储在 style.color.background 属性中。

区块可以通过指定带有默认值的自身属性来应用默认的自定义背景颜色。例如：
```
attributes: {
    style: {
        type: 'object',
        default: {
            color: {
                background: '#aabbcc',
            }
        }
    }
}
```

color.button

注意： 自 WordPress 6.5 起可用。

此属性添加区块控件，允许用户在区块中设置按钮颜色（文本、背景）。按钮颜色默认处于禁用状态。

要启用按钮颜色支持，请将 color.button 设置为 true。

supports: {
	color: {
		button: true
	}
}

按钮颜色预设来源于 editor-color-palette 主题支持。

当区块声明支持 color.button 时，属性定义会扩展以包含 style 属性：

style：一个 object 类型的属性，未分配默认值。

当选择按钮颜色时，颜色值会存储在 style.elements.button.color.text 和 style.elements.button.color.background 属性中。

区块可以通过指定带有默认值的自身属性来应用默认的按钮颜色。例如：

attributes: {
    style: {
        type: 'object',
        default: {
            elements: {
                button: {
                    color: {
                        text: 'var:preset|color|contrast',
					    background: '#000000',
                    }
                }
            }
        }
    }
}

版式设置

类型：对象
默认值：null
子属性：
- fontSize：类型为 布尔值，默认值 false
- lineHeight：类型为 布尔值，默认值 false
- textAlign：类型为 布尔值 或 数组，默认值 false

此对象的存在表示区块支持某些与版式相关的属性。当支持时，区块编辑器将显示版式设置界面，允许用户控制这些属性的值。

supports: {
    typography: {
        // 启用字体大小的支持和界面控制。
        fontSize: true,
        // 启用行高的支持和界面控制。
        lineHeight: true,
        // 启用文本对齐的支持和界面控制。
        textAlign: true,
    },
}

typography.fontSize

类型：布尔值
默认值：false

此值表示区块支持 CSS 样式属性 font-size。当支持时，区块编辑器将显示一个界面控件，供用户设置其值。

该控件中显示的值是由主题通过 editor-font-sizes 主题支持声明的，如果未提供任何值，则使用默认值。

supports: {
    typography: {
        // 启用字体大小的支持和界面控制。
        fontSize: true,
    },
}

当区块声明支持 fontSize 时，属性定义将扩展为包含两个新属性：fontSize 和 style：

fontSize：一个 字符串 类型的属性，未分配默认值。它存储用户选择的任何预设值。区块可以通过指定自己的 fontSize 属性并设置默认值来应用默认字体大小。例如：

attributes: {
    fontSize: {
        type: 'string',
        default: 'some-value',
    }
}

style：一个 对象 类型的属性，未分配默认值。它存储用户设置的自定义值，并与其他区块支持（如颜色）共享。区块可以通过指定自己的 style 属性并设置默认值来应用默认样式。例如：

attributes: {
    style: {
        type: 'object',
        default: {
            typography: {
                fontSize: 'value'
            }
        }
    }
}

typography.lineHeight

类型：布尔值
默认值：false

此值表示区块支持 CSS 样式属性 line-height。当支持时，区块编辑器将显示一个界面控件，供用户设置其值（前提是主题声明支持）。

supports: {
    typography: {
        // 启用行高的支持和界面控制。
        lineHeight: true,
    },
}

当区块声明支持 lineHeight 时，属性定义将扩展为包含一个新的 style 属性，类型为 对象，未分配默认值。它存储用户设置的自定义值。区块可以通过指定自己的 style 属性并设置默认值来应用默认样式。例如：

attributes: {
    style: {
        type: 'object',
        default: {
            typography: {
                lineHeight: 'value'
            }
        }
    }
}

typography.textAlign

**注意：**自 WordPress 6.6 起。

类型：布尔值 或 数组
默认值：false

此属性添加区块工具栏控件，允许更改区块的文本对齐方式。

supports: {
    typography: {
        // 声明支持区块的文本对齐。
        // 这将支持所有选项：
        // 左对齐、居中对齐、右对齐。
        textAlign: true
    }
}

supports: {
    typography: {
        // 声明支持特定的文本对齐选项。
        textAlign: [ 'left', 'right' ]
    }
}

当区块声明支持 textAlign 时，属性定义将扩展为包含一个新的 style 属性，类型为 对象，未分配默认值。它存储用户设置的自定义值。区块可以通过指定自己的 style 属性并设置默认值来应用默认样式。例如：

attributes: {
    style: {
        type: 'object',
        default: {
            typography: {
                textAlign: 'value'
            }
        }
    }
}

color.text

该属性用于添加区块控件，允许用户在区块中设置文本颜色。

当声明支持颜色功能时，此属性会默认启用（同时启用背景色），因此仅需设置颜色属性即可启用文本颜色功能。

supports: {
	color: true // 同时启用背景色和文本颜色，但不启用链接颜色
}

若需在保持其他颜色支持功能的情况下禁用文本颜色支持，可将 color.text 设为 false。

supports: {
	color: {
		// 禁用文本颜色支持
		text: false
	}
}

文本颜色预设值来源于 editor-color-palette 主题支持功能。

当区块声明支持 color.text 时，属性定义将扩展包含两个新属性：textColor 和 style：

textColor：未设默认值的字符串类型属性。

当用户从预设文本颜色列表中选择时，预设别名将存储在 textColor 属性中。

区块可通过指定带默认值的自定义属性来应用预设文本颜色。例如：
```
attributes: {
    textColor: {
        type: 'string',
        default: '某个预设文本颜色别名',
    }
}
```
style：未设默认值的对象类型属性。

当选择自定义文本颜色时（即使用自定义颜色选择器），自定义颜色值将存储在 style.color.text 属性中。

区块可通过指定带默认值的自定义属性来应用默认自定义文本颜色。例如：
```
attributes: {
    style: {
        type: 'object',
        default: {
            color: {
                text: '#aabbcc',
            }
        }
    }
}
```

customClassName

类型：boolean
默认值：true

该属性用于添加自定义 className 字段以定义区块包装器类名。

supports: {
	// 移除对自定义 className 的支持
	customClassName: false
}

dimensions

注意： 自 WordPress 6.2 起可用。

类型：Object
默认值：null
子属性：
- minHeight：类型 boolean，默认值 false

该值表示区块支持部分与尺寸相关的 CSS 样式属性。当启用时，若主题声明支持，区块编辑器将显示用户界面控件供用户设置数值。

supports: {
	dimensions: {
		aspectRatio: true // 启用宽高比控件
		minHeight: true // 启用最小高度控件
	}
}

当区块声明支持特定尺寸属性时，其属性定义将扩展包含 style 属性：

style：未设默认值的对象类型属性。该属性在声明支持 aspectRatio 或 minHeight 时添加，用于存储用户设置的自定义值。例如：

attributes: {
    style: {
        dimensions: {
            aspectRatio: "16/9",
            minHeight: "50vh"
        }
    }
}

filter

类型：Object
默认值：null
子属性：
- duotone：类型 boolean，默认值 false

该值表示区块支持部分与滤镜相关的属性。当启用时，区块编辑器将显示用户界面控件供用户设置数值。

filter.duotone

该属性用于添加用户界面控件，允许用户对区块或区块局部应用双色调滤镜。

supports: {
    filter: {
        // 启用双色调支持
        duotone: true
    }
},
selectors: {
    filter: {
        // 对图片区块内的 img 元素应用滤镜
        duotone: '.wp-block-image img'
    }
}

通过设置 selectors.filter.duotone 选择器，可将滤镜应用于区块内部的元素。

双色调预设值来源于 theme.json 中的 color.duotone。

当区块声明支持 filter.duotone 时，属性定义将扩展包含 style 属性：

style：未设默认值的对象类型属性。

区块可通过指定带默认值的自定义属性来应用默认双色调。例如：

attributes: {
    style: {
        type: 'object',
        default: {
            color: {
                duotone: [
                    '#FFF',
                    '#000'
                ]
            }
        }
    }
}

color.enableContrastChecker

注意： 自 WordPress 6.5 起可用。

决定对比度检查器小部件是否在区块编辑器界面中显示。

仅当区块声明支持颜色时，对比度检查器才会显示。它会测试颜色组合的可读性，并在存在潜在问题时发出警告。该属性默认启用。设置为 false 可显式禁用：

supports: {
	color: {
		enableContrastChecker: false
	}
}

color.__experimentalDuotone

注意： 自 WordPress 6.3 起已弃用。

该属性已被 filter.duotone 替代。

color.gradients

此属性添加用户界面控件，允许用户为区块应用渐变背景。

supports: {
    color: {
        gradients: true,
        // 如果不想将默认值与渐变一起使用，则必须禁用它们。
        background: false,
        text: false
    }
}

渐变预设来源于 editor-gradient-presets 主题支持。

当区块声明支持 color.gradient 时，属性定义会扩展为包含两个新属性：gradient 和 style：

gradient：一个 string 类型的属性，未分配默认值。

当用户从预设渐变列表中选择时，预设别名会存储在 gradient 属性中。

区块可以通过指定带有默认值的自身属性来应用默认预设渐变。例如：
```
attributes: {
    gradient: {
        type: 'string',
        default: 'some-preset-gradient-slug',
    }
}
```

style：一个 object 类型的属性，未分配默认值。

当选择自定义渐变（即使用自定义渐变选择器）时，自定义渐变值会存储在 style.color.gradient 属性中。

区块可以通过指定带有默认值的自身属性来应用默认自定义渐变。例如：

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。

supports: {
	color: {
		// 启用标题颜色支持。
		heading: true
	}
}

标题颜色预设来源于 editor-color-palette 主题支持。

当区块声明支持 color.heading 时，属性定义会扩展为包含 style 属性：

style：一个 object 类型的属性，未分配默认值。

当选择标题颜色时，颜色值会存储在 style.elements.heading.color.text 和 style.elements.heading.color.background 属性中。

区块可以通过指定带有默认值的自身属性来应用默认标题颜色。例如：

attributes: {
    style: {
        type: 'object',
        default: {
            elements: {
                heading: {
                    color: {
                        text: 'var:preset|color|contrast',
					    background: '#000000',
                    }
                }
            }
        }
    }
}

color.link

此属性添加区块控件，允许用户在区块中设置链接颜色。链接颜色默认禁用。

要启用链接颜色支持，请将 color.link 设置为 true。

supports: {
	color: {
		link: true
	}
}

链接颜色预设来源于 editor-color-palette 主题支持。

当区块声明支持 color.link 时，属性定义会扩展为包含 style 属性：

style：一个 object 类型的属性，未分配默认值。

当选择链接颜色时，颜色值会存储在 style.elements.link.color.text 和 style.elements.link.:hover.color.text 属性中。

区块可以通过指定带有默认值的自身属性来应用默认链接颜色。例如：

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。

supports: {
	// 移除对锁定UI的支持
	lock: false
}

multiple

类型：boolean
默认值：true

非多重区块在每个文章中只能插入一次。例如，内置的“更多”区块若已存在于正在编辑的文章中，则无法再次插入。非多重区块的图标会自动变灰（不可点击）以防止多次插入。

supports: {
	// 每篇文章仅使用该区块一次
	multiple: false
}

position

注意： 自 WordPress 6.2 起可用。

类型：Object
默认值：null
子属性：
- sticky：类型为 boolean，默认值 false

此值表示区块支持部分与定位相关的 CSS 样式属性。若声明支持，且主题声明支持，区块编辑器将显示 UI 控件供用户设置这些值。

注意：粘性定位控件目前仅适用于文档根层级的区块。将区块设为 sticky 位置后，当用户滚动页面时，该区块会粘附至其直接父级。

supports: {
	position: {
		sticky: true // 启用选择粘性定位
	}
}

当区块声明支持特定定位属性时，其属性定义会扩展以包含 style 属性。

style：类型为 object 的属性，无默认值。当声明支持 sticky 时添加。它存储用户设置的自定义值。例如：

attributes: {
    style: {
        position: {
            type: "sticky",
            top: "0px"
        }
    }
}

renaming

注意： 自 WordPress 6.5 起可用。

类型：boolean
默认值：true

默认情况下，用户可通过区块“选项”下拉菜单或“高级”面板重命名区块。若要禁用此行为，可将 renaming 设为 false。

supports: {
	// 禁止在编辑器中重命名该区块
	renaming: false,
}

reusable

类型：boolean
默认值：true

区块可能需要禁用转换为可重用区块的功能。默认情况下，所有区块均可转换为可重用区块。若将 reusable 支持设为 false，则不会显示将区块转换为可重用区块的选项。

supports: {
	// 禁止将该区块转换为可重用区块
	reusable: false,
}

shadow

注意： 自 WordPress 6.5 起可用。

类型：boolean
默认值：false

此属性添加区块控件，允许用户为区块设置盒子阴影。默认情况下阴影功能是禁用的。

supports: {
	shadow: true // 启用盒子阴影选择器
}

阴影预设来源于 theme.json 中定义的阴影预设。

当区块声明支持 shadow 时，其属性定义会扩展以包含 style 属性：

style：类型为 object 的属性，无默认值。

当选择阴影时，颜色值会存储在 style.shadow 中。

区块可通过指定带有默认值的自身属性来应用默认阴影。例如：
```
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 样式属性。若声明支持，且主题声明支持，区块编辑器将显示 UI 控件供用户设置这些值。

supports: {
    spacing: {
        margin: true,  // 启用边距 UI 控件
        padding: true, // 启用内边距 UI 控件
        blockGap: true,  // 对同样使用 `layout` 的区块启用区块间距 UI 控件
    }
}

当区块声明支持特定间距属性时，其属性定义会扩展以包含 style 属性。

style：类型为 object 的属性，无默认值。当声明支持 margin 或 padding 时添加。它存储用户设置的自定义值。例如：

attributes: {
    style: {
        margin: 'value',
        padding: {
            top: 'value',
        }
    }
}

间距属性可定义可配置的允许边——'top'、'right'、'bottom'、'left'。当定义了此类任意边时，仅显示这些边的 UI 控件。

轴向边使用 vertical 和 horizontal 术语定义，并为每个轴向对显示单个 UI 控件（例如，vertical 同时控制顶部和底部边）。间距属性可以支持任意单个边或轴向边，但不能混合使用两者。

注意：blockGap 接受 vertical 和 horizontal 轴向边，用于调整间距的列和行值。blockGap 不支持任意边。

supports: {
    spacing: {
        margin: [ 'top', 'bottom' ],             // 为任意边启用边距
        padding: true,                           // 为所有边启用内边距
        blockGap: [ 'horizontal', 'vertical' ],  // 启用轴向（列/行）区块间距控件
    }
}

34 KiB Raw Blame History Unescape Escape

拆分功能

支持功能

allowedBlocks

anchor

auto_register

align

alignWide（宽对齐）

ariaLabel（无障碍标签）

background（背景）

className（类名）

html

inserter

interactivity

layout

layout.default

layout.allowSwitching

layout.allowEditing

layout.allowInheriting

layout.allowSizingOnChildren

layout.allowVerticalAlignment

layout.allowJustification

layout.allowOrientation

color（颜色）

color.background

color.button

版式设置

typography.fontSize

typography.lineHeight

typography.textAlign

color.text

customClassName

dimensions

filter

filter.duotone

color.enableContrastChecker

color.__experimentalDuotone

color.gradients

color.heading

color.link

layout.allowCustomContentAndWideSize

lock

multiple

position

renaming

reusable

shadow

spacing

34 KiB

Raw Blame History