如何为区块添加仅内容编辑支持

查看官方原文 ↗ 发布于 2024年11月5日

WordPress 6.7 引入了许多令人兴奋的功能，但一个值得注意的细微增强是仅内容编辑功能的稳定化，现在可供扩展者和区块开发者使用。

虽然仅内容编辑最初在 WordPress 6.1 中引入，但此前在自定义区块中支持此模式需要在 block.json 中使用一个实验性属性。再加上缺乏应用仅内容模式的编辑器界面，它一直是区块编辑器中较为被忽视和未充分利用的功能之一。但这种情况可能很快就会改变。

所以，如果这是你第一次听说仅内容编辑，别担心——你并不孤单。

在本文中，我将解释什么是仅内容编辑，为什么在您的区块中支持它很重要，以及如何通过一个实际示例来实现它。

什么是仅内容编辑？

仅内容编辑于两年前添加到 WordPress 中，作为一种额外的锁定机制，旨在减少为那些本可以使用区块模式构建的布局创建自定义区块的需求。

使用自定义区块的主要优势是，您可以完全控制用户可以编辑的内容，例如限制他们只能编辑文本、图像和其他内容元素。这简化了用户的编辑体验，同时保持了一致的布局并强制执行了设计标准。

仅内容编辑为所有区块原生提供了类似的功能。

您可以通过向容器区块（如 Group、Column 和 Cover）添加 templateLock: contentOnly 来启用它。一旦激活，用户只能编辑嵌套内容的特定元素。没有可编辑内容的区块将从列表视图中隐藏且无法被选中。此外，所有区块的设置侧边栏将被禁用。

为了演示其工作原理，请考虑以下区块布局，它包含一个包含标题、段落和社交图标区块的 Group 区块。已应用区块样式和设置，此示例使用了 WordPress 6.7 中即将推出的 Twenty Twenty-Five 主题。

在 WordPress 的默认编辑模式下，用户可以更改此设计的任何内容。以下是供参考的区块标记。

<!-- wp:group {"style":{"spacing":{"padding":{"top":"var:preset|spacing|50","bottom":"var:preset|spacing|50","left":"var:preset|spacing|50","right":"var:preset|spacing|50"},"margin":{"top":"var:preset|spacing|70","bottom":"var:preset|spacing|70"}}},"backgroundColor":"accent-5","layout":{"type":"constrained"}} -->
<div class="wp-block-group has-accent-5-background-color has-background" style="margin-top:var(--wp--preset--spacing--70);margin-bottom:var(--wp--preset--spacing--70);padding-top:var(--wp--preset--spacing--50);padding-right:var(--wp--preset--spacing--50);padding-bottom:var(--wp--preset--spacing--50);padding-left:var(--wp--preset--spacing--50)">
    <!-- wp:heading -->
    <h2 class="wp-block-heading">Speaker Name</h2>
    <!-- /wp:heading -->
    
    <!-- wp:paragraph -->
    <p>Speaker Description—Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus luctus urna sed urna ultricies ac tempor dui sagittis.</p>
    <!-- /wp:paragraph -->
    
    <!-- wp:social-links {"iconColor":"accent-5","iconColorValue":"#FBFAF3","iconBackgroundColor":"contrast","iconBackgroundColorValue":"#111111","showLabels":true,"size":"has-normal-icon-size","style":{"spacing":{"margin":{"top":"var:preset|spacing|50"}}}} -->
    <ul class="wp-block-social-links has-normal-icon-size has-visible-labels has-icon-color has-icon-background-color" style="margin-top:var(--wp--preset--spacing--50)">
        <!-- wp:social-link {"url":"#","service":"wordpress"} /-->
        <!-- wp:social-link {"url":"#","service":"chain"} /-->
        <!-- wp:social-link {"url":"#","service":"mail"} /-->
    </ul>
    <!-- /wp:social-links -->
</div>
<!-- /wp:group -->

现在，让我们将 "templateLock": "contentOnly" 属性应用到 Group 区块的区块标记中。您只需要修改属性对象。区块标记的其余部分应保持不变。

<!-- wp:group {"templateLock": "contentOnly","style":{"spacing":{"padding":{"top":"var:preset|spacing|50","bottom":"var:preset|spacing|50","left":"var:preset|spacing|50","right":"var:preset|spacing|50"}}},"backgroundColor":"accent-5","layout":{"type":"constrained"}} -->

要跟着操作，请打开一个运行 WordPress 6.7 的 WordPress Playground 实例。这里有一个方便的链接。

导航到一个新页面。
打开代码编辑器，复制并粘贴上面的原始区块标记。
将 "templateLock": "contentOnly" 属性添加到 Group 区块。
切换回可视化编辑器。

完成这些步骤后，您应该会看到类似这样的内容。

如果您将仅内容模式下的区块布局与默认编辑体验进行比较，您会很快注意到以下几点：

列表视图被简化，只显示容器（Group）和任何具有可编辑内容的内部区块。
设置侧边栏不再显示区块设置或样式，只显示容器 Group 区块可用的区块样式变体。
设置侧边栏中出现了一个新的“内容”面板，显示容器内的可编辑内容区块。
社交图标区块中的图标不再可编辑。（请注意这一点，以便在本文后面讨论）

为什么支持此编辑模式？

仅内容编辑是创建精选和简化用户体验的强大工具。为了使此功能有效，区块必须设计为支持它。例如，如前所述，社交图标区块目前在此模式下无法工作。

虽然未来的 WordPress 更新将解决核心区块的全面支持问题，但大多数站点至少包含一个自定义区块。对于区块开发者来说，确保与仅内容编辑的兼容性至关重要。在 WordPress 6.7 之前，在自定义区块中启用此功能需要在 block.json 中使用一个名为 __experimentalRole 的实验性属性。现在 role 属性已经稳定，添加支持通常很简单。

您可能仍然想知道为什么仅内容编辑如此重要，尤其是考虑到它直到现在仍然相对小众。答案在于 Gutenberg 中新的写作模式以及 GitHub 上设计编辑器概述议题中强调的对仅内容编辑的日益重视。

这些发展突显了仅内容编辑的未来重要性及其在 WordPress 更广泛的设计工具中创建更简单、更受控的编辑体验方面的作用。是时候让您的区块做好准备了。

如何为区块添加仅内容编辑支持

虽然我最初计划为本文创建一个示例区块插件，但让我们改为检查 WordPress 中的社交链接区块，因为截至 WordPress 6.7，它目前在仅内容模式下被禁用。您可以在 Gutenberg 插件中查看源代码。

社交链接区块是社交图标（社交链接）区块的子级，它显示一行或一列链接到社交资料或网站的图标。在许多情况下，您可能希望用户能够在仅内容模式下修改链接 URL。当区块布局作为可在不同上下文中使用的模式提供时，这尤其有用，例如前面显示的演讲者个人资料区块设计。

在本文的其余部分，我将使用 WordPress 源代码和区块标记中使用的技术名称来指代这些区块：wp:social-links 和 wp:social-link。请记住，社交链接区块在编辑器中显示为社交图标区块，而社交链接区块则由各个平台名称表示，例如 WordPress、Facebook、LinkedIn、Link、Mail 等。

那么，假设社交链接区块是您需要支持仅内容编辑的自定义区块。您该如何实现呢？

更新 block.json

第一步是更新社交链接区块的block.json文件，为每个在设置 "templateLock": "contentOnly" 时应可编辑的属性添加 "role": "content" 属性。

对于此示例，url 和 label 属性应该可用。url 属性保存社交图标的链接，而 label 属性表示当父社交链接区块中启用显示文本时图标的可选文本标签。

更新后的 block.json 文件的属性部分应如下所示：

{
	"$schema": "https://schemas.wp.org/trunk/block.json",
	"apiVersion": 3,
	"name": "core/social-link",
	"title": "Social Icon",
	"category": "widgets",
	"parent": [ "core/social-links" ],
	"description": "Display an icon linking to a social profile or site.",
	"textdomain": "default",
	"attributes": {
		"url": {
			"type": "string",
			"role": "content"
		},
		"service": {
			"type": "string"
		},
		"label": {
			"type": "string",
			"role": "content"
		},
		"rel": {
			"type": "string"
		}
	},
	...

如果您正在为您自己的区块添加仅内容编辑，并且需要支持旧版本的 WordPress，请使用 __experimentalRole 而不是 role，直到您准备好将最低 WordPress 版本设置为 6.7。这种方法的唯一缺点是在控制台中会出现一个小的弃用警告。

通过这些更改，社交图标的 URL 编辑将自动启用。这是因为 url 属性是使用 <SocialLinkURLPopover> 组件管理的，该组件是插入区块时编辑器画布的一部分。当至少一个属性被分配了 "role": "content" 属性时，区块的画布元素将变为可编辑。

另一方面，label 属性通常使用设置侧边栏中的文本字段进行设置。侧边栏在仅内容模式下被禁用。

如果您希望通常在侧边栏中设置的区块属性在仅内容模式下可编辑，您需要在区块内创建替代的编辑体验。

一个很好的方法是借鉴现有的 WordPress 区块。例如，图像块允许用户使用区块工具栏中的替代文本下拉菜单编辑图像的 alt 文本（源代码）。

让我们对社交链接区块应用类似的方法。

添加自定义编辑体验

首先，通过在 <BlockControls> 组件内包含内容，向社交链接区块的区块工具栏添加一个按钮。为此，让我们遵循图像块中使用的方法，并实现一个 <Dropdown> 组件。

以下代码应放在区块 Edit() 函数的 return 语句中。

return (
	<>
		<BlockControls group="other">
			<Dropdown
				popoverProps={ { position: 'bottom right' } }
				renderToggle={ ( { isOpen, onToggle } ) => (
					<ToolbarButton
						onClick={ onToggle }
						aria-haspopup="true"
						aria-expanded={ isOpen }
					>
						{ __( 'Text' ) }
					</ToolbarButton>
				) }
				renderContent={ () => (
					<TextControl
						className="wp-block-social-link__toolbar_content_text"
						label={ __( 'Text' ) }
						help={ __( 'Provide a text label or use the default.' ) }
						value={ label }
						onChange={ ( value ) => setAttributes( { label: value } ) }
						placeholder={ socialLinkName }
					/>
				) }
			/>
		</BlockControls>
		<InspectorControls>
			...

<Dropdown> 组件包含两个关键属性：renderToggle 和 renderContent。

renderToggle 属性负责显示触发下拉菜单的组件。在本例中，使用了 <ToolbarButton>，因为它设计为可以无缝集成到区块工具栏中。

renderContent 属性指定了下拉菜单打开时显示的内容。在此示例中，它包含一个用于设置 label 属性的 <TextControl> 组件。此 <TextControl> 类似于区块设置侧边栏中的文本输入。

还有其他一些细节需要注意：

<BlockControls> 组件包含 group="other" 属性，这确保了文本按钮在工具栏中正确定位。
下拉菜单的位置通过 popoverProps 属性管理。
<TextControl> 组件被分配了一个自定义类用于样式设置。

添加工具栏下拉菜单的代码后，区块将如下所示。

您可能立即注意到了两个问题。首先，下拉菜单的宽度需要使用 CSS 修复。其次，文本按钮不应始终显示在工具栏中。

当区块不在仅内容模式时，用户已经可以从设置侧边栏修改 label 属性。此外，如果父社交链接区块上未启用显示文本，则无论编辑模式如何，都不应显示该按钮。

应用最后的润色

让我们从最简单的开始。下拉菜单的宽度可以通过定位添加到 <TextControl> 组件的自定义类来设置。应将以下 CSS 添加到区块的 editor.scss 文件中。

.wp-block-social-link__toolbar_content_text {
	// Corresponds to the size of the text control input in the block inspector.
	width: 250px;
}

接下来，您需要根据当前编辑模式以及是否启用显示文本来有条件地显示工具栏按钮。

社交链接区块已经从父级社交链接区块提供的上下文中接收了 showLabels 值（源代码）。编辑模式可以使用 useBlockEditingMode 函数确定。

首先从 @wordpress/block-editor 包中导入 useBlockEditingMode，并在区块的 Edit() 函数中定义以下常量：

const isContentOnlyMode = useBlockEditingMode() === 'contentOnly';

现在，将之前创建的 <BlockControls> 组件包装在一个条件语句中，该语句检查 isContentOnlyMode 和 showLabels。

return (
	<>
		{ isContentOnlyMode && showLabels && (
			<BlockControls group="other">
				...
			</BlockControls>
		) }
		<InspectorControls>
			...

工具栏中的文本按钮现在将正确显示。当社交链接区块处于 contentOnly 模式且启用显示文本时，用户将能够设置图标链接和文本标签。

您可以在拉取请求中找到此示例的完整代码，该请求在 Gutenberg 插件中为社交链接区块引入了仅内容编辑支持。此功能预计将包含在 2025 年初的 WordPress 6.8 中。

总的来说，社交链接区块所需的更改相对较小。但是，您的自定义区块所需的修改将取决于其复杂性以及您希望给予用户的编辑控制量。

结束语

如果您构建自定义区块，请考虑是否可以用锁定为仅内容编辑的区块模式替换其中一些。如果不能，请确保您的区块支持此模式。尽管仅内容编辑仍然有些小众，但预计 WordPress 将扩展其使用范围，使用您区块的站点构建者也会逐渐期待它。

这类似于添加官方的区块支持，以便您的区块样式和设置可以通过 theme.json 进行管理并在全局样式中修改。使您的自定义解决方案与核心功能保持一致，可以使它们更具适应性和鲁棒性。

云策 WordPress 开发者社区

社区新闻

如何为区块添加仅内容编辑支持

什么是仅内容编辑？

为什么支持此编辑模式？

如何为区块添加仅内容编辑支持

更新 block.json

添加自定义编辑体验

应用最后的润色

结束语