Gutenberg Details 块core/details完全指南从 block.json 属性到服务端渲染增强【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg导读Details 块是 Gutenberg 编辑器内置的折叠/展开内容容器对应原生 HTMLdetails/summary语义用于隐藏并展示附加内容FAQ、免责声明、进阶阅读等。本文以packages/block-library/src/details/README.md的自动生成 API 文档为骨架结合该块在仓库中的完整源码block.json、edit.jsx、save.jsx、index.php、测试用例逐项拆解其属性定义、支持能力Supports、编辑器交互与混合块渲染机制帮助你完全掌握该块的配置方式与二次开发要点。一、块概览一个 Hybrid 类型的文本容器根据 details/README.md 与 block.jsoncore/details块的核心元数据如下元数据项值名称Namecore/details类别Categorytext文本类API 版本3块类型Hybrid静态保存 服务端增强关键词Keywordssummary、toggle、disclosure描述Hide and show additional content.关键词summary、toggle、disclosure直接映射了该块的使用场景用户可以在块插入器中通过summarytoggledisclosure等词搜索到它。它的内部实现是对原生 HTMLdetails元素的封装天然继承了浏览器原生的折叠/展开交互与无障碍语义。从源码结构看该块目录包含 block.json、edit.jsx编辑器界面、save.jsx保存输出、index.php服务端渲染与注册、transforms.js块转换、index.js块设置聚合以及编辑器/前端样式editor.scss、style.scss是一个典型的静态保存 服务端增强混合块。二、属性Attributes详解4 个配置项的定义与数据来源README 中列出了该块的全部属性这些属性通过 block.json 中的attributes属性定义详见 block.json并受 block-attributes 的类型校验约束属性类型默认值说明showContentbooleanfalse是否默认展开对应details的open属性summaryrich-text—摘要文本数据源为rich-text选择器summary角色contentnamestring—分组名称数据源为attribute选择器.wp-block-detailsHTML 属性nameplaceholderstring—摘要占位提示文本各属性的底层实现如下showContent布尔属性默认false。在 save.jsx 中直接映射到details open{ showContent }当为true时保存的前端 HTML 会带有open属性页面加载即展开。summary富文本rich-text属性从summary元素内部提取内容role: content意味着它属于块的内容层可被全文搜索与内容校验感知。在 save.jsx 中若summary为空会回退为默认文本Details。name字符串属性从.wp-block-details根元素上读取nameHTML 属性。它的作用是让多个 Details 块通过相同的 name 值互联——如同原生details name...的行为同一组内同时只能展开一个。placeholder字符串属性不绑定任何数据源仅用于编辑器内的占位提示。在 edit.jsx 中当placeholder为空时会回退到默认文案Write summary…。三、Supports支持能力清单可用的样式与行为控制README 中列出的 Supports 配置均定义于 block.json 的supports属性决定该块在编辑器侧栏中开放哪些控制项alignwide、full——支持宽幅与全宽对齐。anchortrue——允许设置锚点 ID便于页面内跳转。colorgradients: true、link: true——支持渐变背景与链接颜色block.json 中还声明了__experimentalDefaultControls: { background: true, text: true }即默认显示背景色与文字色两个控件。htmlfalse——禁止 HTML 编辑模式用户无法切换到代码编辑视图保证输出结构的规范性。spacingmargin、padding、blockGap均为true默认控件不展开。typographyfontSize、lineHeight为truefontSize 属于默认控件block.json 进一步启用了实验性字体控制__experimentalFontFamily、__experimentalFontWeight、__experimentalFontStyle、__experimentalTextTransform、__experimentalTextDecoration、__experimentalLetterSpacing。layoutallowEditing: false——不允许用户自行修改布局类型锁定容器布局。interactivityclientNavigation: true——声明该块兼容客户端导航Client-side navigation在站点前端交互路由场景下不会破坏其折叠状态。allowedBlockstrue——允许在其中嵌套任意块。此外block.json 还包含两个未在 README 表格中出现的实验性支持项__experimentalOnEnter: true在摘要内按 Enter 可切换展开状态对应 edit.jsx 中的键盘处理与__experimentalBorder: { color, width, style }实验性边框控制。这些配置共同构成了该块外观可定制、结构受控的双重设计取向。四、Block Markup混合块如何保存与增强README 给出了该块保存到文章内容中的典型标记Block Markup!-- wp:details {summary:Details Summary} -- details classwp-block-detailssummaryDetails Summary/summary !-- wp:paragraph {placeholder:Type / to add a hidden block} -- pDetails Content/p !-- /wp:paragraph -- /details !-- /wp:details --这是一个混合块Hybrid Block编辑器保存的是静态标记服务端在渲染时可能再做增强。对照 save.jsx 可以看出保存逻辑输出根元素details挂上useBlockProps.save()生成的 class含wp-block-details与name、open当showContent为真时属性摘要由RichText.Content渲染到summary内内部内容由InnerBlocks.Content原样输出因此嵌套块如段落、图片都会完整保留。作为对照编辑器内的实时预览edit.jsx同样渲染一个真实的details元素open状态由isOpen || hasSelectedInnerBlock决定选中内部块时自动展开方便编辑onToggle事件会同步内部展开状态name属性透传。前端样式 style.scss 只做了两件事box-sizing: border-box与summary的cursor: pointer其余交互完全交给浏览器原生行为。五、编辑器体验从默认展开到分组联动编辑器界面edit.jsx围绕四个核心交互点设计摘要富文本编辑summary内嵌一个RichTextidentifier 为summary通过aria-label提示写入摘要按 Enter 展开或折叠并设置withoutInteractiveFormatting屏蔽格式化干扰。键盘行为在摘要上按 Enter不按 Shift切换展开/收起handleSummaryKeyDown配合withIgnoreIMEEvents避免 IME 组合输入误触发按空格时阻止默认行为防止输入空格时误触发原生details的切换handleSummaryKeyUp。Open by default 开关侧栏的 ToolsPanelSettings中提供ToggleControl直接读写showContent属性resetAll与onDeselect均将其重置为false。Name attribute 输入位于InspectorControls groupadvanced的高级面板中帮助文案明确说明其用途——Enables multiple Details blocks with the same name attribute to be connected, with only one open at a time.同名 Details 块互联同一时间仅一个展开。这是构建手风琴式 FAQ的关键属性。在内容组织上index.js 定义了一个默认内部模板插入 Details 块时自动附带一个占位文本为Type / to add a hidden block的段落块引导用户继续添加隐藏内容同时通过__experimentalLabel为列表视图list-view、面包屑breadcrumb与无障碍accessibility上下文提供语义化标签——例如无障碍标签会是Details. summary 文本空摘要时则为Details. Empty.。六、服务端渲染增强折叠态图片的fetchprioritylow作为混合块的服务端增强部分index.php 做了两件事通过register_block_type_from_metadata( __DIR__ . /details )在init钩子上注册core/details块通过render_block_core/details过滤器挂载block_core_details_set_img_fetchpriority_low当showContent为false默认折叠时使用WP_HTML_Tag_Processor遍历块内所有img标签并设置fetchprioritylow。其设计意图在注释中说明得很清楚折叠状态下的图片对用户不可见不应与 LCP最大内容绘制等关键渲染路径上的资源争抢加载优先级而showContent为true时直接短路返回把优先级判断交给核心逻辑如为 LCP 图片保留fetchpriorityhigh。对应的单元测试位于 phpunit/blocks/render-block-details-test.php覆盖三个典型场景折叠块内的img被设置为fetchprioritylow展开块showContent: true内的img不会被改成low展开块内已显式声明的fetchpriorityhigh会被原样保留。这三个断言精确锁定了折叠降级、展开放行、显式值优先的行为边界是理解该增强逻辑的最直接证据。七、块转换任意块组一键收纳transforms.js 为core/details定义了一条从任意块转换的规则from中允许isMultiBlock: true且匹配任意块blocks: [ * ]条件为当前选区不是单个core/details块。转换时通过createBlock创建新的 Details 块并将选中的多个块作为内部块cloneSanitizedBlock逐个克隆并清理放入其中。这意味着用户可以多选任意内容一键收纳进折叠容器反向则无法直接转换回原块需手动剪切。八、结语core/details是一个结构精炼、语义完整的混合块它用 4 个属性覆盖默认展开、摘要文本、分组联动、占位提示四种核心诉求通过原生details/summary元素获得零成本的浏览器交互与无障碍支持再以服务端渲染层fetchpriority 降级为页面性能兜底。无论是站点作者使用 Open by default 与 Name attribute 搭建手风琴 FAQ还是块开发者参考其 block.json 的 Supports 组织方式与混合块渲染模式都能从这套实现中直接获益。若需继续深入可通读 details 源码目录 下的全部实现文件并结合 render-block-details-test.php 验证其渲染行为。【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考