块讲解：款式、图案、详情栏

查看官方原文 ↗ 发布于 2023年12月1日

当 WordPress 6.3 捆绑了 Details 块时，我非常兴奋。真的！我是一名主题作者，所以每当有新的块进入核心时，我总是很兴奋。因为这意味着我可以摆弄它——看看它能做什么、如何工作，最重要的是，找出使用它的新方法。

而且我已经期待这个功能好几年了。

Details 块结合了两个 HTML 元素：<details> 和 <summary>。它是一种原生的 HTML 方式来显示和隐藏内容：summary 部分是一个标题，它隐藏 details 内容，直到用户点击它来触发 details 的显示。

现在，默认情况下，它看起来并不那么令人印象深刻：

WordPress 文章编辑器，显示了一个关闭和一个打开的 Details 块，其中包含占位符。

但这意味着 WordPress 在样式上为你留下了各种空间，让你每次在主题中使用它时都可以添加自己的修饰，使其真正成为你自己的。

你可以用它做很多事情：

剧透警告
代码显示
音频转录稿
可切换的常见问题解答列表

在本教程中，我将引导你了解我一直在尝试的一些事情。可以将其视为让该块在视觉上适应你的主题，并使其与其他主题功能良好配合的入门指南。我们将涉及从自定义 CSS 到模式再到块样式的所有内容。

Details 块的基础 HTML

在开始摆弄这个块之前，请确保你理解 HTML 结构的作用，无论是在前端还是在编辑器中，它看起来都像这样：

<details class="wp-block-details is-layout-flow wp-block-details-is-layout-flow" open="">
	<summary>Custom summary text</summary>
	<!-- Almost any other block or markup can appear here. -->
</details>

请注意，<details> 元素是一个包装器，用于包裹 <summary> 元素和其他块。从这里很难知道你的用户可能会在里面放什么，但他们可以添加任何他们认为需要的东西。因此，如果你能很好地掌握标记，你将拥有一个坚实的设计方法，可以很好地为他们服务。

还要知道，无法使用 theme.json 中的默认设计工具专门针对内部的 <summary> 元素。你需要编写一些自定义 CSS。

自定义 Details 块

从这一点开始，我将与你分享我的一些自定义内容。但你会希望在这个块上加入你自己的风格，使其成为你自己的。

添加基础样式

我不建议让 Details 块保持默认的浏览器样式。它很无聊，网站访问者会直接滑过。所以给它多一点生气，像这样：

WordPress 文章编辑器，显示了一个关闭和一个打开的 Details 块，其中包含占位符。摘要部分有浅灰色背景，整个块有更浅的灰色。

好吧。这并没有增加太多生气，但这是一个开始。

要构建这种外观，请在 theme.json 文件中定位 styles.blocks.core/details：

{
	"$schema": "https://schemas.wp.org/trunk/theme.json",
	"version": 2,
	"styles": {
		"blocks": {
			"core/details": {
				"border": {
					"radius": "6px"
				},
				"color": {
					"text": "#0284c7",
					"background": "#f1f5f9"
				},
				"shadow": "0 1px 2px 0 rgb(0 0 0 / 0.05)"
			}
		}
	}
}

该块支持 theme.json 中典型的样式属性范围，但这也是你可能发现 theme.json 相当受限的时候之一。它将不支持：

直接针对 <summary> 元素。
自定义 transition CSS 属性。
根据其 open 属性对 <details> 元素进行上下文样式设置。
针对嵌套块。

对于这些事情以及更多，你需要编写自己的 CSS，至少如果你想要做比 WordPress 开箱即用支持的更高级的事情。

你可以将自定义 CSS 放在三个地方，按推荐顺序排列：

一个块样式表
theme.json 中的 css 属性
你主题的主样式表（例如 style.css）

选择最适合你项目的方法。然后，添加这个自定义 CSS：

/* 添加打开/关闭时的自定义过渡效果。 */
.wp-block-details {
	transition: all 0.5s ease-in-out;
}

/* 为嵌套块/元素添加水平边距。 */
.wp-block-details > :where( :not( summary ) ) {
	margin-left: 2rem;
	margin-right: 2rem;
}

/* 如果打开，添加一些底部内边距，避免内容紧贴底部。 */
.wp-block-details[open] {
	padding-bottom: 2rem;
}

/* `summary` 元素的基础样式。 */
.wp-block-details summary {
	transition: all 0.5s ease-in-out;
	box-sizing: border-box;
	padding: 2rem;
	font-weight: 500;
}

/* 根据状态更改 `summary` 元素的背景。 */
.wp-block-details[open] summary,
.wp-block-details summary:hover,
.wp-block-details summary:focus {
	background: #e2e8f0;
}

如你所见，几乎所有的 CSS 都是针对内部的 <summary> 元素和其他元素。上面代码中的每个 CSS 规则集都有注释来解释发生了什么，因为别人光看是不知道的。而且三个月后，你可能也不记得了。

当然，你的 Details 块的实际设计会与我的不同。这只是为你提供了一个工作基础，并表明你可能需要结合使用 theme.json 和 CSS 来获得你想要的显示和功能。

添加自定义标记

因为标记在技术上位于嵌套的 <summary> 元素内部，所以你将使用 CSS（确切地说是 CSS 伪元素）来设置其样式。你可以通过两种方式做到这一点。

针对 ::marker 伪元素

<summary> 元素支持 ::marker CSS 伪元素，因此你可以使用它将其内容更改为任何有效的字符串。

让我们尝试在 Details 块关闭时添加一个 + 号，在打开时添加一个 - 号，如下所示：

WordPress 文章编辑器，显示了一个关闭和一个打开的灰色 Details 块。关闭状态有一个 "+" 标记，打开状态有一个 "-" 标记。

要自定义标记，请将此 CSS 添加到你放置其他块 CSS 的地方：

.wp-block-details summary::marker {
	content: "+ ";
}

.wp-block-details[open] summary::marker {
	content: "- "
}

注意代码中的 [open] CSS 属性选择器。针对它来设置 Details 块打开时的样式。

针对 ::before 或 ::after 伪元素

或者，你可以针对 ::before 或 ::after CSS 伪元素。

如果我们将自定义的 +/- 标记移到 <summary> 元素之后，如下所示，会发生什么？

WordPress 文章编辑器，显示了一个关闭和一个打开的灰色 Details 块。关闭状态有一个 "+" 标记，打开状态有一个 "-" 标记。标记位于摘要的末尾。

现在添加这个自定义 CSS，使用 ::after 伪元素添加标记：

.wp-block-details summary::marker {
	content: none;
}

.wp-block-details summary::after {
	content: " +";
	float: right;
	text-align: right;
}

.wp-block-details[open] summary::after {
	content: " -"
}

请注意，代码专门禁用了 ::marker 伪元素的内容，这样你就不会得到两个标记。

使用 Details 块构建常见问题解答模式

到现在为止，我希望你已经对可以用 Details 块做的好事有了想法。它非常适合几种不同的模式。

让我们尝试构建一个简单的常见问题解答模式，像这样：

WordPress 文章编辑器，显示了一组四个 Details 块堆叠在一起。这些块被设置为看起来像一个带有问题和答案的常见问题解答列表。

事实上，Twenty Twenty-Four 主题附带了一个这样的模式（查看实时演示）。

让我们从模式中提取的 Details 块开始。特别要注意默认嵌套段落块的 placeholder 属性：

<!-- wp:details -->
<details class="wp-block-details">
	<summary><?php esc_html_e( 'Question 1?', 'themeslug' ); ?></summary>
	<!-- wp:paragraph {"placeholder":"<?php esc_attr_e( 'Add an answer to the question.', 'themeslug' ); ?>"} -->
	<p></p>
	<!-- /wp:paragraph -->
</details>
<!-- /wp:details -->

你可以将此值更改为你想要的任何内容——例如，如果你想为用户提供一个特定于你正在构建的模式的占位符。在这种情况下，该块将提示用户“添加问题的答案。”很整洁，对吧？

按照块模式文档的说明，在你主题的 /patterns 文件夹中添加一个名为 faqs.php 的文件。然后向其添加你的模式文件头元数据：

<?php
/**
 * Title: FAQs
 * Slug: themeslug/faqs
 * Description: Outputs a list of configurable FAQ items.
 * Categories: text
 * Keywords: faq, accordion, toggle, questions, answers
 * Viewport Width: 640
 */
?>

根据你的需要配置它。只需确保将 themeslug 更新为与你主题的 slug 匹配。

作为练习，我建议先尝试直接从编辑器构建模式。然后，将其复制并粘贴到 faqs.php 文件中。当然，你会希望国际化你在文件中添加的任何文本。我还总是建议将模式包装在某种容器块中——Group、Row、Stack 或 Cover。

但如果你赶时间，可以随意将此示例代码复制并粘贴到你的 faqs.php 文件中：

<!-- wp:group {"layout":{"type":"constrained"}} -->
<div class="wp-block-group">
	<!-- wp:details -->
	<details class="wp-block-details">
		<summary><?php esc_html_e( 'Question 1?', 'themeslug' ); ?></summary>
		<!-- wp:paragraph {"placeholder":"<?php esc_attr_e( 'Add an answer to the question.', 'themeslug' ); ?>"} -->
		<p></p>
		<!-- /wp:paragraph -->
	</details>
	<!-- /wp:details -->

	<!-- wp:details -->
	<details class="wp-block-details">
		<summary><?php esc_html_e( 'Question 2?', 'themeslug' ); ?></summary>
		<!-- wp:paragraph {"placeholder":"<?php esc_attr_e( 'Add an answer to the question.', 'themeslug' ); ?>"} -->
		<p></p>
		<!-- /wp:paragraph -->
	</details>
	<!-- /wp:details -->

	<!-- wp:details -->
	<details class="wp-block-details">
		<summary><?php esc_html_e( 'Question 3?', 'themeslug' ); ?></summary>
		<!-- wp:paragraph {"placeholder":"<?php esc_attr_e( 'Add an answer to the question.', 'themeslug' ); ?>"} -->
		<p></p>
		<!-- /wp:paragraph -->
	</details>
	<!-- /wp:details -->

	<!-- wp:details -->
	<details class="wp-block-details">
		<summary><?php esc_html_e( 'Question 4?', 'themeslug' ); ?></summary>
		<!-- wp:paragraph {"placeholder":"<?php esc_attr_e( 'Add an answer to the question.', 'themeslug' ); ?>"} -->
		<p></p>
		<!-- /wp:paragraph -->
	</details>
	<!-- /wp:details -->
</div>
<!-- /wp:group -->

现在你已经准备好做任何必要的事情来使其成为你自己的——或者围绕 Details 块构建一些新模式，并使这些模式也成为你自己的。

自定义 Details “剧透”块样式

你可以以多种方式将 Details 块用于许多事情。它非常适合可折叠的代码片段、注释、警告等等。

让我们构建一个块样式，让你向网站访问者显示剧透警告（这对于书评网站可能很有用）：

WordPress 文章编辑器，显示了一个关闭和一个打开的 Details 块。它们被设计成橙色，以给出警告/警报。块的标记是一个 ⚠️ 符号。

为此，你将在 PHP 中注册块样式，并遵循块样式文档中的说明。这些文档告诉你使用 register_block_style() 注册自定义样式。

将此代码添加到主题的 functions.php 文件中：

add_action( 'init', 'themeslug_block_style_variations' );

function themeslug_block_style_variations() {
	register_block_style( 'core/details', array(
		'name'  => 'spoiler',
		'label' => __( 'Spoiler', 'themeslug' )
	) );
}

现在，你刚才所做的只是注册样式以使其显示在 Details 块设置侧边栏中。要设计它，你需要添加一些 CSS。

现在，将此代码添加到你的其他块 CSS 中：

.wp-block-details.is-style-spoiler {
	background: #ffffff;
	border-left: 5px solid #fcb900b8;
	box-shadow: 1px 1px 1px 0 #fcb90029;
}

.wp-block-details.is-style-spoiler summary {
	font-weight: bold;
	background: #fcb90029;
}

.wp-block-details.is-style-spoiler summary::marker {
	content: "⚠️ "
}

与本文中的大多数示例一样，你将希望添加自己的样式以匹配你的主题。

再次强调，Details 块的用途非常多，没有人能在一篇文章中涵盖它们。甚至无法想到所有可能性的一小部分！

另外，我想给你留下足够的空间，让你的想象力尽情发挥。所以请在评论中分享你的实现。

我迫不及待想看到你的发明！

云策 WordPress 开发者社区

社区新闻