Gutenberg 区块编辑器文档

title: "区块支持" post_status: publish comment_status: open taxonomy: category: - gutenberg-docs post_tag: - Block Api - Reference Guides - Repos

区块支持

区块支持是一个 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 起可用。

此属性添加了 UI 控件，使用户能够为块容器选择允许的子块。要使用此功能，请将 attributes.allowedBlocks 作为 allowedBlocks 属性传递到 useInnerBlocksProps 的选项对象中。

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

锚点功能允许您直接链接到页面上的特定区块。此属性会添加一个用于定义区块 ID 的字段和一个用于复制直接链接的按钮。

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

autoRegister

启用仅 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>Server content</div>',
            $wrapper_attributes
        );
    },
    'supports' => array(
        'autoRegister' => true,
    ),
) );

align

This property adds block controls, which enable changes to a block's alignment.

supports: {
    // Declare support for block's alignment.
    // This adds support for all the options:
    // left, center, right, wide, and full.
    align: true
}

supports: {
    // Declare support for specific alignment options.
    align: [ 'left', 'right', 'full' ]
}

When the block declares support for align, the attributes definition is extended to include an align attribute with a string type. By default, no alignment is assigned. The block can apply a default alignment by specifying its own align attribute with a default. For example:

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

alignWide

This property allows to enable wide alignment for your theme. To disable this behavior for a single block, set this flag to false.

supports: {
    // Remove the support for wide alignment.
    alignWide: false
}

ariaLabel

ARIA-labels let you define an accessible label for elements. This property allows enabling the definition of an aria-label for the block, without exposing a UI field.

supports: {
    // Add support for an aria label.
    ariaLabel: true
}

background

Note: Since WordPress 6.5.

This value signals that a block supports some of the CSS style properties related to background. When it does, the block editor will show UI controls for the user to set their values if the theme declares support.

backgroundImage adds UI controls which allow the user to select a background image. backgroundSize adds the FocalPointPicker to pick the position of the background image and allow the user to select the background size (cover, contain, fixed).

supports: {
    background: {
        backgroundImage: true // Enable background image control.
        backgroundSize: true // Enable background image + size control.
    }
}

When a block declares support for a specific background property, its attributes definition is extended to include the style attribute.

When a background image is selected, the image data is stored in the style.background.backgroundImage.

When a background images is selected and its position or size are changed, the background-position is stored in the style.background.backgroundPosition and its background-size in style.background.backgroundSize attribute.

The block can apply a default background image, position and size by specifying its own attribute with a default. For example:

attributes: {
    style: {
        background: {
            backgroundImage: {
                "url":"IMAGE_URL"
            }
            backgroundPosition:"50% 50%",
            backgroundSize: "cover"
        }
    }
}

className

By default, the class .wp-block-your-block-name is added to the root element of your saved markup. This helps by providing a consistent mechanism for styling blocks that themes and plugins can rely on. If, for whatever reason, a class is not desired on the markup, this functionality can be disabled.

supports: {
    // Remove the support for the generated className.
    className: false
}

color

This value signals that a block supports some of the properties related to color. When this value is present, the block editor will show UI controls for the user to set their values.

Note that the background and text keys have a default value of true, so if the color property is present they will also be considered enabled:

supports: {
    color: {
        // This also enables text and background UI controls.
        gradients: true // Enables the gradients UI control.
    }
}

It's possible to disable them individually:

supports: {
    color: { // Text UI control is enabled.
        background: false, // Disables the background UI control.
        gradients: true // Enables the gradients UI control.
    }
}

color.background

This property adds UI controls which allow the user to apply a solid background color to a block.

When color support is declared, this property is enabled by default (along with text), so simply setting color will enable background color.

supports: {
    color: true // Enables background and text color support.
}

To disable background support while keeping other color supports enabled, set to false.

supports: {
    color: {
        // Disables background support. Text color support is still enabled.
        background: false
    }
}

When the block declares support for color.background, the attributes definition is extended to include two new attributes: backgroundColor and style:

color.button

注意： 自 WordPress 6.5 起可用。

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

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

supports: {
    color: {
        button: true
    }
}

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

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

color.enableContrastChecker

注意： 自 WordPress 6.5 起。

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

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

supports: {
    color: {
        enableContrastChecker: false
    }
}

color.__experimentalDuotone

Note: Deprecated since WordPress 6.3.

This property has been replaced by filter.duotone.

color.gradients

This property adds UI controls which allow the user to apply a gradient background to a block.

supports: {
    color: {
        gradients: true,
        // Default values must be disabled if you don't want to use them with gradients.
        background: false,
        text: false
    }
}

Gradient presets are sourced from editor-gradient-presets theme support.

When the block declares support for color.gradient, the attributes definition is extended to include two new attributes: gradient and style:

color.heading

Note: Since WordPress 6.5.

This property adds block controls which allow the user to set heading colors in a block. Heading colors are disabled by default.

To enable heading color support, set color.heading to true.

supports: {
    color: {
        // Enable heading color support.
        heading: true
    }
}

Heading color presets are sourced from the editor-color-palette theme support.

When the block declares support for color.heading, the attributes definition is extended to include the style attribute:

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

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

supports: {
    color: {
        link: true
    }
}

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

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

color.text

This property adds block controls which allow the user to set text color in a block.

When color support is declared, this property is enabled by default (along with background), so simply setting color will enable text color.

supports: {
    color: true // Enables background and text, but not link.
}

To disable text color support while keeping other color supports enabled, set color.text to false.

supports: {
    color: {
        // Disable text color support.
        text: false
    }
}

Text color presets are sourced from the editor-color-palette theme support.

When the block declares support for color.text, the attributes definition is extended to include two new attributes: textColor and style:

contentRole

注意： 自 WordPress 6.9 起。

将区块本身标记为内容。它主要适用于那些未声明 content 属性，或其内容仅通过内部区块表达的区块。启用后，仅内容编辑模式仍可编辑这些区块，并允许添加或移除内部区块。

supports: {
    contentRole: true
}

customClassName

This property adds a field to define a custom className for the block's wrapper.

supports: {
    // Remove the support for the custom className.
    customClassName: false
}

dimensions

Note: Since WordPress 6.2.

This value signals that a block supports some of the CSS style properties related to dimensions. When it does, the block editor will show UI controls for the user to set their values if the theme declares support.

supports: {
    dimensions: {
        aspectRatio: true // Enable aspect ratio control.
        height: true // Enable height control.
        minHeight: true // Enable min height control.
        width: true // Enable width control.
    }
}

When a block declares support for a specific dimensions property, its attributes definition is extended to include the style attribute.

attributes: {
    style: {
        dimensions: {
            aspectRatio: "16/9",
            height: "40vh",
            minHeight: "50vh",
            width: "400px",
        }
    }
}

filter

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

filter.duotone

This property adds UI controls which allow the user to apply a duotone filter to a block or part of a block.

supports: {
    filter: {
        // Enable duotone support
        duotone: true
    }
},
selectors: {
    filter: {
        // Apply the filter to img elements inside the image block
        duotone: '.wp-block-image img'
    }
}

The filter can be applied to an element inside the block by setting the selectors.filter.duotone selector.

Duotone presets are sourced from color.duotone in theme.json.

When the block declares support for filter.duotone, the attributes definition is extended to include the attribute style:

html

By default, a block's markup can be edited individually. To disable this behavior, set html to false.

supports: {
    // Remove support for an HTML mode.
    html: false
}

inserter

By default, all blocks will appear in the inserter, block transforms menu, Style Book, etc. To hide a block from all parts of the user interface so that it can only be inserted programmatically, set inserter to false.

supports: {
    // Hide this block from the inserter.
    inserter: false
}

交互性

指示区块是否使用交互性 API 功能。

clientNavigation 子属性指示区块是否兼容交互性 API 的客户端导航。 仅当区块是非交互式的，或者使用交互性 API 实现交互时，才将其设置为 true。如果区块是交互式的，但使用原生 JS、jQuery 或其他非交互性 API 的 JS 框架/库，则将其设置为 false。

interactive 子属性指示区块是否使用交互性 API 指令。

如果将 supports.interactivity 设置为 true，则等同于同时将 supports.interactivity.clientNavigation 和 supports.interactivity.interactive 也设置为 true。

布局

此值仅适用于作为内部块容器的块。如果设置为 true，布局类型将为 flow。对于其他布局类型，必须在 default 对象内显式设置 type。

请注意，为使布局正常工作，应用布局的块应具有一个类名作为其选择器。该类名将与布局类型字符串连接以形成布局选择器。

layout.default

允许设置 type 属性来定义该区块默认的布局类型，以及该布局类型固有属性的默认值。例如，对于 flex 布局，可以为 flexWrap 设置默认值。

layout.allowSwitching

暴露一个切换器控件，允许在所有现有布局类型之间切换。

layout.allowEditing

决定区块侧边栏中布局控件的显示。如果设为 false，布局控件将被隐藏。

layout.allowInheriting

仅适用于 flow 布局类型，决定是否显示“内部块使用内容宽度”切换开关。

layout.allowSizingOnChildren

仅适用于 flex 布局类型，决定是否在弹性块的所有子块上显示尺寸控制选项（适应/填充/固定）。

layout.allowVerticalAlignment

仅适用于 flex 布局类型，决定块工具栏中垂直对齐控件的显示。

layout.allowJustification

对于 flex 布局类型，决定块工具栏和块侧边栏中对齐控件的显示。对于 constrained 布局类型，决定块侧边栏中对齐控件的显示。

layout.allowOrientation

仅适用于 flex 布局类型，决定块工具栏中方向控制按钮的显示。

layout.allowWrap

仅适用于 flex 布局类型，决定块侧边栏中“允许多行换行”切换开关的显示。当设置为 false 时，换行行为由 layout.default 中的 flexWrap 值控制。

layout.allowCustomContentAndWideSize

仅适用于 constrained 布局类型，用于决定区块侧边栏中自定义内容和宽尺寸控件的显示。

listView

注意： 自 WordPress 7.0 起。

在区块检查器中为该区块的内部区块启用列表视图面板。

启用此支持后，检查器会显示一个列表视图树，允许用户从侧边栏检查和管区块的内部区块，而不仅仅是使用全局文档列表视图。

supports: {
    listView: true
}

listView 支持仅影响编辑器界面，不会向区块添加任何属性。

lock

A block may want to disable the ability to toggle the lock state. It can be locked/unlocked by a user from the block "Options" dropdown by default. To disable this behavior, set lock to false.

supports: {
    // Remove support for locking UI.
    lock: false
}

multiple

A non-multiple block can be inserted into each post, one time only. For example, the built-in 'More' block cannot be inserted again if it already exists in the post being edited. A non-multiple block's icon is automatically dimmed (unclickable) to prevent multiple instances.

supports: {
    // Use the block just once per post
    multiple: false
}

position

Note: Since WordPress 6.2.

This value signals that a block supports some of the CSS style properties related to position. When it does, the block editor will show UI controls for the user to set their values if the theme declares support.

Note that sticky position controls are currently only available for blocks set at the root level of the document. Setting a block to the sticky position will stick the block to its most immediate parent when the user scrolls the page.

supports: {
    position: {
        sticky: true // Enable selecting sticky position.
    }
}

When the block declares support for a specific position property, its attributes definition is extended to include the style attribute.

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

renaming

Note: Since WordPress 6.5.

By default, a block can be renamed by a user from the block 'Options' dropdown or the 'Advanced' panel. To disable this behavior, set renaming to false.

supports: {
    // Don't allow the block to be renamed in the editor.
    renaming: false,
}

reusable

A block may want to disable the ability of being converted into a reusable block. By default all blocks can be converted to a reusable block. If supports reusable is set to false, the option to convert the block into a reusable block will not appear.

supports: {
    // Don't allow the block to be converted into a reusable block.
    reusable: false,
}

shadow

Note: Since WordPress 6.5.

This property adds block controls which allow the user to set a box shadow for a block. Shadows are disabled by default.

supports: {
    shadow: true // Enable the box-shadow picker.
}

Shadow presets are sourced from the shadow presets defined in theme.json.

When the block declares support for shadow, the attributes definition is extended to include the style attribute:

spacing

This value signals that a block supports some of the CSS style properties related to spacing. When it does, the block editor will show UI controls for the user to set their values if the theme declares support.

supports: {
    spacing: {
        margin: true,  // Enable margin UI control.
        padding: true, // Enable padding UI control.
        blockGap: true,  // Enables block spacing UI control for blocks that also use `layout`.
    }
}

When the block declares support for a specific spacing property, its attributes definition is extended to include the style attribute.

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

A spacing property may define an array of allowable sides – 'top', 'right', 'bottom', 'left' – that can be configured. When such arbitrary sides are defined, only UI controls for those sides are displayed.

Axial sides are defined with the vertical and horizontal terms, and display a single UI control for each axial pair (for example, vertical controls both the top and bottom sides). A spacing property may support arbitrary individual sides or axial sides, but not a mix of both.

Note: blockGap accepts vertical and horizontal axial sides, which adjust gap column and row values. blockGap doesn't support arbitrary sides.

supports: {
    spacing: {
        margin: [ 'top', 'bottom' ],             // Enable margin for arbitrary sides.
        padding: true,                           // Enable padding for all sides.
        blockGap: [ 'horizontal', 'vertical' ],  // Enables axial (column/row) block spacing controls
    }
}

typography

The presence of this object signals that a block supports some typography related properties. When it does, the block editor will show a typography UI allowing the user to control their values.

supports: {
    typography: {
        // Enable support and UI control for font-size.
        fontSize: true,
        // Enable support and UI control for line-height.
        lineHeight: true,
        // Enable support and UI control for text alignment.
        textAlign: true,
    },
}

typography.fontSize

This value signals that a block supports the font-size CSS style property. When it does, the block editor will show an UI control for the user to set its value.

The values shown in this control are the ones declared by the theme via the editor-font-sizes theme support, or the default ones if none are provided.

supports: {
    typography: {
        // Enable support and UI control for font-size.
        fontSize: true,
    },
}

When the block declares support for fontSize, the attributes definition is extended to include two new attributes: fontSize and style:

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

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

typography.lineHeight

This value signals that a block supports the line-height CSS style property. When it does, the block editor will show an UI control for the user to set its value if the theme declares support.

supports: {
    typography: {
        // Enable support and UI control for line-height.
        lineHeight: true,
    },
}

When the block declares support for lineHeight, the attributes definition is extended to include a new attribute style of object type with no default assigned. It stores the custom value set by the user. The block can apply a default style by specifying its own style attribute with a default. For example:

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

typography.textAlign

Note: Since WordPress 6.6.

This property adds block toolbar controls which allow to change block's text alignment.

supports: {
    typography: {
        // Declare support for block's text alignment.
        // This adds support for all the options:
        // left, center, right.
        textAlign: true
    }
}

supports: {
    typography: {
        // Declare support for specific text alignment options.
        textAlign: [ 'left', 'right' ]
    }
}

When the block declares support for textAlign, the attributes definition is extended to include a new attribute style of object type with no default assigned. It stores the custom value set by the user. The block can apply a default style by specifying its own style attribute with a default. For example:

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

拆分

当设置为 true 时，Enter 键会将区块拆分为两个区块。请注意，此功能仅适用于简单的文本区块，例如具有单个 RichText 字段的段落和标题。edit 函数中的 RichText 必须 具有与文本属性键匹配的 identifier 属性，以便正确更新选区并知道拆分位置。

可见性

注意： 自 WordPress 6.9 起。

默认情况下，用户可以从区块的“选项”下拉菜单中隐藏一个区块。要禁用此行为，请将可见性设置为 false。

supports: {
    visibility: false,
}