Quartz 高阶布局组件完全指南Flex、MobileOnly、DesktopOnly 与 ConditionalRender 的配置与源码解析【免费下载链接】quartz a fast, batteries-included static-site generator that transforms Markdown content into fully functional websites项目地址: https://gitcode.com/GitHub_Trending/qua/quartzQuartz 提供了一组高阶布局组件Higher-Order Layout Components用于解决站点布局组合与响应式设计问题Flex负责把多个组件编排成弹性布局MobileOnly/DesktopOnly控制组件的设备可见性ConditionalRender则根据页面属性决定是否渲染。本文以 docs/layout-components.md 为骨架结合 Quartz 仓库中的源码实现系统讲解这四类组件的 YAML 配置方式、TS 覆写方式以及它们背后的工作机理帮助你在quartz.config.yaml与quartz.ts中精准控制页面每个区域的最终呈现。概述从配置到渲染的两条路径在 Quartz 中页面布局由各个插件Plugin提供的组件Component拼装而成。常见的布局需求——把搜索框和深色模式按钮排成一排、让目录只在桌面端出现、在首页隐藏面包屑——都可以通过高阶布局组件解决。绝大多数场景可以在quartz.config.yaml中通过插件条目的layout字段直接声明需要自定义逻辑例如自定义渲染条件时则在quartz.ts中用 TS 覆写方式调用Component.Flex()、Component.MobileOnly()、Component.DesktopOnly()、Component.ConditionalRender()这些包装器。这两条路径最终都会归一到同一批组件之上Flex、MobileOnly、DesktopOnly、ConditionalRender均在 quartz/components/index.ts 中被导出是官方提供的一等公民组件从源码结构看它们都是“工厂式”组件构造器接收配置对象或子组件返回一个新的QuartzComponent同时把子组件的afterDOMLoaded、beforeDOMLoaded、css等资源元数据一并透传保证子组件所需的前端脚本与样式仍然会被正确收集与注入。Flex组件用 Flexbox 编排一行或一列Flex是 Quartz 实现弹性布局的核心。它基于 CSS Flexbox详见 MDN flex 文档把一组子组件放进同一个容器中按行或列排列并允许对每个子项单独设置伸缩、对齐与排序规则。从源码看Flex的实现位于 quartz/components/Flex.tsx外层容器 div 使用flex-component类并以内联样式注入flex-direction、flex-wrap、gap每个子组件被包进一个内层 div内联样式写入flex-grow、flex-shrink、flex-basis、order、align-self、justify-self。默认值分别是direction: row、wrap: nowrap、gap: 1rem每个子项的shrink默认true、basis默认auto、order默认0、align与justify默认center。YAML 配置通过 layout.groups 定义弹性组在 YAML 中弹性布局通过“组group”实现。流程分两步在顶层layout.groups中定义一个组名并配置该 flex 容器本身的属性在插件条目的layout中通过group字段把插件指派给该组并通过groupOptions设置该子项在组内的弹性行为。plugins: - source: github:quartz-community/search enabled: true layout: position: left priority: 20 group: toolbar groupOptions: grow: true # Search will grow to fill available space - source: github:quartz-community/darkmode enabled: true layout: position: left priority: 30 group: toolbar # Darkmode keeps its natural size - source: github:quartz-community/reader-mode enabled: true layout: position: left priority: 35 group: toolbar layout: groups: toolbar: direction: row gap: 0.5rem上面的示例把搜索、深色模式、阅读模式三个组件编入toolbar组搜索框grow: true会伸展填满剩余空间另外两个保持自然尺寸组内元素按row方向排列、间距0.5rem。每个插件条目上的groupOptions字段支持以下 flex 子项属性类型定义见 quartz/plugins/loader/types.tsOptionTypeDescriptiongrowbooleanWhether the component should grow to fill available spaceshrinkbooleanWhether the component should shrink if neededbasisstringInitial main size of the component (e.g.,200px)ordernumberOrder in the flex containeralignstart|end|center|stretchCross-axis alignmentjustifystart|end|center|between|aroundMain-axis alignment顶层的layout.groups小节则配置 flex 容器本身类型定义见 quartz/plugins/loader/types.tsOptionTypeDescriptionprioritynumber组的显式优先级覆盖组内第一个成员的 priority数值越小越靠前渲染directionrow|row-reverse|column|column-reverseFlex directionwrapnowrap|wrap|wrap-reverseFlex wrap behaviorgapstringGap between flex items (e.g.,0.5rem)底层解析逻辑resolveGroups 如何把组变成组件YAML 中的组并不是由Flex组件直接读取的而是在配置加载阶段被解析成真实的组件树。核心逻辑位于 quartz/plugins/loader/config-loader.ts 的resolveGroups()收集所有带group的插件记录每个组的成员与每个成员的groupOptions组的有效优先级取“组配置中显式声明的priority”若未声明则回退为“第一个成员的priority”遍历时每个组只被输出一次processedGroups去重把成员映射为Flex的components数组再以direction: groupConfig.direction ?? row、gap: groupConfig.gap ?? 1rem调用Flex(...)得到一个新的QuartzComponent未分组的普通组件与生成的 flex 组组件随后统一按优先级排序合并进header/left/right/beforeBody/afterBody/footer等位置config-loader.ts。这意味着一个组在最终布局中表现为一个整体它占据自己在优先级序列中的位置组内成员的相对顺序则由组内 priority 与 flex 属性共同决定。另外Flex会通过concatenateResources汇总所有子组件的afterDOMLoaded、beforeDOMLoaded与css见 quartz/components/Flex.tsx因此放入组内的组件所需的交互脚本和样式不会丢失。TS Override用 Component.Flex() 获得完全编程控制当 YAML 不足以表达需求例如需要在代码中动态决定子组件时可以在quartz.ts中直接使用Component.Flex()Component.Flex({ components: [ { Component: Plugin.Search(), grow: true, // Search will grow to fill available space }, { Component: Plugin.Darkmode() }, // Darkmode keeps its natural size ], direction: row, gap: 1rem, })其配置类型与 YAML 中的字段一一对应type FlexConfig { components: { Component: QuartzComponent grow?: boolean shrink?: boolean basis?: string order?: number align?: start | end | center | stretch justify?: start | end | center | between | around }[] direction?: row | row-reverse | column | column-reverse wrap?: nowrap | wrap | wrap-reverse gap?: string }[!note] 覆写默认渲染行为Flex内的组件会被额外加上 CSS 类flex-component该类带有display: flex属性。如需覆盖这一默认行为可以在你的自定义 CSS 文件中为该组件的 CSS 类添加display属性.flex-component { display: block; // or any other display type }MobileOnly/DesktopOnly组件按设备控制可见性这两个组件用于控制某个插件在移动端或桌面端的可见性是构建响应式布局的常用手段——例如目录Table of Contents在手机窄屏上占据大量空间通常只希望在桌面端展示。从源码看两者的实现完全对称quartz/components/DesktopOnly.tsx 与 quartz/components/MobileOnly.tsx分别把子组件包进一个带desktop-only或mobile-only类的 div同时透传子组件的displayName、afterDOMLoaded、beforeDOMLoaded与css。可见性最终由 quartz/styles/base.scss 中针对这两个类的媒体查询规则实现移动端隐藏desktop-only、桌面端隐藏mobile-only。YAML 配置使用 display 属性在 YAML 中只需在插件条目的layout上声明displayplugins: - source: github:quartz-community/table-of-contents enabled: true layout: position: right priority: 20 display: desktop-only # Only visible on desktop可用的display取值类型定义见 quartz/plugins/loader/types.tsValueDescriptionallVisible on all screen sizes (default)mobile-onlyOnly visible on mobile devicesdesktop-onlyOnly visible on desktop devicesTS Override使用组件包装器TS 覆写方式下使用Component.MobileOnly()或Component.DesktopOnly()包装任意组件Component.MobileOnly(Component.Spacer())Component.DesktopOnly(Plugin.TableOfContents())ConditionalRender组件按页面属性条件渲染ConditionalRender根据页面属性如是否为首页、是否含标签、是否有反向链接决定是否渲染某个插件。它适合构建动态布局例如在根首页隐藏面包屑、在没有任何标签的页面上隐藏标签列表。从源码看quartz/components/ConditionalRender.tsx实现非常直接ConditionalRender调用配置中提供的condition(props)谓词函数返回true时渲染子组件否则渲染null同时把子组件的资源元数据透传出去。condition接收完整的QuartzComponentProps因此可以访问fileData含 slug、frontmatter、toc、backlinks 等页面数据与displayClass等渲染上下文。YAML 配置使用内置条件预设在 YAML 中通过插件条目layout上的condition属性引用条件名。Quartz 内置了以下预设实现见 quartz/plugins/loader/conditions.tsplugins: - source: github:quartz-community/breadcrumbs enabled: true layout: position: beforeBody priority: 5 condition: not-index # Hide breadcrumbs on the root index pageConditionDescription源码判定逻辑not-indexOnly render when the page is not the rootindex.mdprops.fileData.slug ! indexhas-tagsOnly render when the page has tags in its frontmatterfrontmatter 的tags是非空数组has-backlinksOnly render when the page has backlinksfileData.backlinks是非空数组has-tocOnly render when the page has a table of contentsfileData.toc是非空数组TS Override自定义渲染条件内置预设之外的场景可以在quartz.ts中传入自定义谓词函数Component.ConditionalRender({ component: Plugin.Search(), condition: (props) props.displayClass ! fullpage, })type ConditionalRenderConfig { component: QuartzComponent condition: (props: QuartzComponentProps) boolean }例如上面的示例会在displayClass为fullpage全页模式如独立搜索页时隐藏搜索组件避免重复。[!tip] 注册自定义条件供 YAML 使用 你还可以在插件的初始化代码中调用registerCondition()注册自定义条件之后就能在quartz.config.yaml中通过condition字段直接引用。注册表与内置条件共享同一个命名空间quartz/plugins/loader/conditions.ts 中customConditions与builtinConditions均通过getCondition()查询因此自定义名称不要与内置条件重名。具体插件编写方式见 making plugins。实战组合建议几个典型的组合用法帮助你理解这些高阶组件如何协同工作工具栏布局把搜索、深色模式、阅读模式、间距组件放入同一个toolbar组用grow: true让搜索框占据剩余宽度形成典型的顶部工具条响应式侧栏对table-of-contents设置display: desktop-only同时把移动端使用的组件设置为mobile-only实现桌面/移动端的差异化布局首页净化面包屑、标签列表等对首页意义不大的组件统一设置condition: not-index让首页更聚焦按内容驱动标签列表使用condition: has-tags反向链接区域使用condition: has-backlinks只在页面确实存在对应内容时才渲染避免出现空区块。小结Quartz 的高阶布局组件把“布局”从插件内部抽离成了可声明的配置层Flex含 YAML 中的 group 机制负责空间编排MobileOnly/DesktopOnly负责设备适配ConditionalRender负责条件渲染。理解它们的 YAML 字段与 TS 覆写方式再结合 quartz/components 下的源码与 quartz/plugins/loader/config-loader.ts 的解析流程你就能精确掌控 Quartz 页面在任意屏幕尺寸、任意页面类型下的最终形态。【免费下载链接】quartz a fast, batteries-included static-site generator that transforms Markdown content into fully functional websites项目地址: https://gitcode.com/GitHub_Trending/qua/quartz创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
