Gutenberg No Results 块core/query-no-results完全解析查询无结果时的降级渲染方案【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg本篇技术指南聚焦 WordPress Gutenberg 仓库中core/query-no-resultsNo Results块的完整实现。它位于 packages/block-library/src/query-no-results 目录是core/queryQuery 循环块的内嵌子块专门负责在查询没有任何结果时渲染降级内容。读完本文你将掌握该块的元数据配置、Supports 能力边界、编辑器端实现、服务端渲染条件逻辑以及如何基于仓库源码确认其行为细节从而在自己的主题与模板中正确使用这一空状态块。块定位Query 循环中的空状态组件No Results 块的核心职责在 README.md 中定义得很清楚Contains the block elements used to render content when no query results are found.它本质上是一个容器块用来装载当查询没有返回任何结果时要展示的内容例如提示文案暂无文章、引导按钮等。它在块注册层面的基本身份信息如下名称Namecore/query-no-results分类Categorytheme主题类核心块API 版本3apiVersion: 3见 block.json块类型Hybrid混合型——静态save输出 服务端渲染增强所谓 Hybrid 块是指该块既保存静态标记静态部分由前端save.jsx生成又允许服务端在渲染时对标记进行增强或条件性输出动态部分由index.php的render_callback完成。这正是本块的精髓所在静态标记是否真正输出最终由服务端根据查询结果动态决定。与 Query 块的关系No Results 块通过ancestor元数据约束了自身的嵌套位置见 block.jsonancestor: [ core/query ]这意味着该块只能作为core/query块的后代存在可跨层级嵌套但不允许直接出现在 Query 循环之外。在 packages/block-library/src/query/variations.js 中也可以看到该块作为 Query 块变体的内建组合成员进一步印证了No Results 是 Query 循环配套块的定位。block.json 元数据attributes、supports 与 contextAttributes无自定义属性README 明确指出 This block has no custom attributes.这在实际注册中得到了验证——block.json 中确实没有attributes字段。它不像 Image、Heading 等块那样需要保存自身内容因为真正的内容是它内部的子块通常是段落块由InnerBlocks承载。这也解释了为什么它的职责纯粹是容器 条件渲染。Supports暴露给编辑器的样式能力Supports 定义了编辑器侧对该块开放哪些样式控制项。README 中列出的能力与 block.json 完全一致逐项说明如下Supports 能力取值实际影响anchortrue允许设置 HTML 锚点id属性用于页内定位与导航aligntrue允许设置块级对齐宽、全宽等reusablefalse禁用可复用块转换容器块默认如此htmlfalse禁用以 HTML 模式编辑防止破坏动态渲染逻辑color.gradientstrue支持渐变背景color.linktrue支持链接颜色spacing.padding/spacing.margintrue支持内边距与外边距默认控件不显示__experimentalDefaultControls.margin/padding均为false需展开高级面板typography.fontSize/lineHeighttrue支持字号与行高fontSize默认出现在控件中interactivity.clientNavigationtrue支持客户端导航交互式前端导航场景值得注意的是block.json 中还额外注册了__experimentalBorderradius、color、width、style能力支持边框圆角、颜色、宽度与样式控制。README 是自动生成的 API 摘要会只列出稳定 API从源码可以确认该块实际的边框能力比文档摘要更丰富。这些能力共同保证了 No Results 容器在空状态下依然可以做出与整站风格一致的视觉呈现如居中提示、卡片式边框等。Context读取 Query 循环的运行时信息Context上下文机制允许父块向子块传递数据。该块通过usesContext声明了两个依赖见 block.jsonusesContext: [ queryId, query ]queryId当前 Query 块的实例 ID用于区分页面上多个互不干扰的查询循环在分页参数query-{queryId}-page的构造中起关键作用。query当前 Query 块的完整查询配置postType、inherit、分页参数等。服务端渲染函数正是利用这两个 context 值来重建查询并判断结果数量的详见下文。编辑器端实现一个纯内嵌块容器前端侧由三个文件协同工作注册入口与内置模板index.jsindex.js 完成块注册并定义了插入该块时的默认模板const TEMPLATE [ [ core/paragraph, { placeholder: __( Add text or blocks that will display when a query returns no results. ), }, ], ];也就是说当用户在编辑器中添加 No Results 块时会自动预置一个带占位提示的段落块提示内容为 Add text or blocks that will display when a query returns no results.。占位符只出现在编辑器中不会随save输出。同文件还提供了块预览exampleexample: { innerBlocks: [ { name: core/paragraph, attributes: { content: __( No posts were found. ), }, }, ], },预览示例使用一个典型文案 No posts were found. 展示块在无结果场景下的典型外观同时块图标使用wordpress/icons中的loop循环图标语义上呼应查询循环。编辑视图edit.jsxedit.jsx 的实现非常简洁——它就是一个InnerBlocks容器import { useBlockProps, useInnerBlocksProps } from wordpress/block-editor; export default function QueryNoResultsEdit() { const blockProps useBlockProps(); const innerBlocksProps useInnerBlocksProps( blockProps ); return div { ...innerBlocksProps } /; }编辑器内始终渲染该容器的内部区块用户可以在其中自由添加任意块作为空状态内容。保存视图save.jsxsave.jsx 只负责输出内部块内容import { InnerBlocks } from wordpress/block-editor; export default function save() { return InnerBlocks.Content /; }保存的标记就是内部块的序列化内容本身不含额外包装逻辑——包装与条件输出全部交由服务端处理。服务端渲染核心条件输出的完整逻辑真正让 No Results 块只在无结果时出现的机制在 index.php 的render_block_core_query_no_results回调中其核心逻辑分四步第一步空内容短路。如果该块内部没有任何实际内容trim( $content )为空直接返回空字符串避免输出无意义的空包装。第二步确定查询来源。依据 context 中的query.inherit决定使用哪种查询$use_global_query ( isset( $block-context[query][inherit] ) $block-context[query][inherit] ); if ( $use_global_query ) { global $wp_query; $query $wp_query; } else { $query_args build_query_vars_from_query_block( $block, $page ); $query new WP_Query( $query_args ); }当 Query 块配置了继承主查询inherit: true即博客首页/归档场景时直接复用全局$wp_query否则基于 Query 块的配置通过build_query_vars_from_query_block()重建WP_Query。第三步结果判断。关键条件if ( $query-post_count 0 ) { return ; }只要查询结果文章数大于 0渲染回调就返回空字符串——整个块在最终输出中被抹掉这正是只有无结果时才显示的实现本质。第四步包装输出。结果为空时用get_block_wrapper_attributes()生成包装属性包括来自color.link支持的has-link-color类当用户设置了链接颜色时附加并输出return sprintf( div %1$s%2$s/div, $wrapper_attributes, $content );分页参数的处理也值得一提$page_key isset( $block-context[queryId] ) ? query- . $block-context[queryId] . -page : query-page; $page empty( $_GET[ $page_key ] ) ? 1 : (int) $_GET[ $page_key ];queryIdcontext 在这里被用来构造唯一的 URL 分页参数名如query-2-page避免页面存在多个 Query 循环时分页互相干扰若块不在带queryId的上下文中则回退到默认的query-page。该块自 WordPress 6.0.0 起随核心提供since 6.0.0注册入口为function register_block_core_query_no_results() { register_block_type_from_metadata( __DIR__ . /query-no-results, array( render_callback render_block_core_query_no_results ) ); } add_action( init, register_block_core_query_no_results );块标记静态保存的序列化结构README 给出了该块的典型序列化标记即在前端页面中保存/输出的结构!-- wp:query-no-results -- !-- wp:paragraph {placeholder:Add a text or blocks that will display when the query returns no results.} -- p/p !-- /wp:paragraph -- !-- /wp:query-no-results --要点解读placeholder属性不会被序列化到最终保存内容之外——上例中的段落块属性里带有placeholder这在编辑器注释中被保留但实际段落内容为空p/p占位文本仅作编辑提示该注释结构与save.jsx的InnerBlocks.Content输出对应最终由服务端index.php决定整段是否出现在渲染结果中一旦查询有结果上例整段!-- wp:query-no-results --...!-- /wp:query-no-results --都不会输出到页面上。样式与排版约束style.scss 是唯一的样式文件内容刻意保持极简// Lowest specificity so parent layout can still enforce width. :where(.wp-block-query-no-results) { // This block has customizable padding, border-box makes that more predictable. box-sizing: border-box; }两个设计意图值得注意使用:where()将特异性降到最低确保父级 Query 循环的布局宽度、对齐始终能约束该块由于该块支持自定义padding显式声明box-sizing: border-box使内边距计算更可预测避免撑破父级容器。样式句柄为wp-block-query-no-results见 block.json 的style字段在需要额外定制空状态外观时可基于该句柄排队补充样式。典型应用场景与使用建议基于以上源码分析可以总结出该块的典型使用方式搭建文章列表模板在core/query循环内将 No Results 块置于循环内部通常紧跟在 Query Loop 的内容子块之后当分类、标签或搜索结果为空时自动显示没有找到文章提示多查询页面页面存在多个 Query 块时queryId上下文自动隔离分页参数No Results 判断互不串扰继承主查询的归档页Query 块开启inherit后No Results 直接基于全局$wp_query判断无需额外配置即可工作于博客首页、分类归档等场景空状态引导在 No Results 容器内不限于段落文本可自由嵌套按钮如返回首页、搜索表单等任意块形成完整的降级体验。源码地图块 API 文档 —— 自动生成的完整 API 摘要块元数据 —— attributes、supports、context、style 句柄声明注册与默认模板 —— 内建段落模板、预览示例、图标编辑视图 —— InnerBlocks 容器实现保存视图 —— 静态标记输出服务端渲染 —— 空内容短路、查询重建、post_count条件判断、分页参数构造块样式 ——:where()低特异性 box-sizing修正【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考