Scalar Docs 配置实战：用 `section` 字段打造 Header / Tabs 大菜单（Mega Menus）

Scalar Docs 配置实战用section字段打造 Header / Tabs 大菜单Mega Menus【免费下载链接】scalarScalar is an open-source API platform: Modern REST API Client Beautiful API References ✨ 1st-Class OpenAPI/Swagger Support项目地址: https://gitcode.com/GitHub_Trending/sc/scalar本文围绕 Scalar 文档配置文件中navigation的 Mega Menu大菜单能力展开讲清“一个section字段如何把普通下拉菜单变成分栏面板”的渲染机制完整给出navigation.header与navigation.tabs两套可复制的配置示例、section字段的全部取值规则、响应式行为与断点、Dashboard 可视化编辑步骤以及scalar project check-config/scalar project preview两条 CLI 命令的校验与预览方式。读完后你可以直接在 scalar.config.json 中落地一个带标题列的多栏下拉菜单并保证桌面、移动端与折叠菜单三种形态共用同一份数据。什么是 Mega Menu以及它的定位Mega Menu 是出现在文档站 Header 头部 或 Tab 栏 中的下拉面板与普通下拉的“单列链接列表”不同它把链接按标题分栏titled columns平铺展示。官方文档给出的使用判据很明确当下拉菜单里的链接超过 6 个左右、读者需要第二层分组才能找到目标时就应该升级为 mega menu。关键认知是没有任何布局开关需要打开。一个下拉菜单在它内部的任意一个链接声明了section的那一刻就自动变成了 mega menu。这是一个纯渲染层的特性——数据层面始终是一个扁平、有序的链接列表。工作原理section是对链接的注解不是嵌套层级所有下拉菜单在数据上都是一个扁平的有序列表。Mega menu 只是这个列表的一种渲染方式而非多一层嵌套给某个链接写上section它就“归属于”这个标题命名的列连续的、section相同的链接构成一列列标题就是该值列的数量 这样的连续段run的数量不存在任何需要单独配置的“列数”没有写section的链接自成一根无标题列位置由书写顺序决定。正因为列只是“按顺序读取列表”得到的结果同一份列表同时驱动折叠后的移动端菜单因此你永远不需要维护第二份结构去保持同步。Header 大菜单完整配置示例做法是在 scalar.config.json 的navigation.header中给一个 group 的 children 添加section// scalar.config.json { $schema: https://registry.scalar.com/scalar/schemas/config, scalar: 2.0.0, navigation: { header: [ { type: link, title: Home, to: / }, { type: group, title: Resources, children: [ { type: link, title: API Reference, to: /reference, icon: phosphor/regular/code, section: Documentation }, { type: link, title: Guides, to: /guides, icon: phosphor/regular/compass, section: Documentation }, { type: link, title: About, to: https://scalar.com, newTab: true, section: Company }, { type: link, title: Status, to: https://status.scalar.com, newTab: true, section: Company }, { type: link, title: Everything else, to: /more } ] } ], routes: { // ... } } }上面这个Resources下拉会渲染出三列从左到右依次为DocumentationCompany(无标题)API ReferenceAboutEverything elseGuidesStatus注意最后一列没有section因此以无标题列的形式出现在其书写位置上。mega menu 内的链接接受与普通 header 链接 完全相同的属性title、to、icon、newTab、stylegroup 本身则保留自己的title、icon、align。本仓库自己的 scalar.config.json 就是一个真实用例头部Resources下拉的 children 里Compare / Migration / Blog / Changelog 四个链接统一标注section: ResourcesAbout / Careers / Support / Security 标注section: Company且每个链接都配了phosphor/regular/...图标——正是文档所描述的“带图标、分两列”的标准形态可以直接对照阅读。Tabs 大菜单Tab 栏也支持下拉Tab 栏同样接受下拉分组。Tab group 的结构是{ type: group, title, icon, children }每个 child 是一个可带section的 tab 链接// scalar.config.json { $schema: https://registry.scalar.com/scalar/schemas/config, scalar: 2.0.0, navigation: { tabs: [ { title: Home, to: / }, { type: group, title: Platform, children: [ { title: API Reference, to: /reference, section: Build }, { title: Guides, to: /guides, section: Build }, { title: Scalar Website, to: https://scalar.com, section: Operate } ] } ], routes: { // ... } } }与 header 链接不同tab 链接没有type键。它们接受title、to、icon、newTab和section也就是“顶层 tab 的属性 列标题”。section字段规格与约束属性类型必填说明sectionstring否链接所处于的列标题。仅作用于navigation.header或navigation.tabs中group的 children。约束要点必须是非空字符串。空字符串会直接导致校验失败如果想让某个链接不进入任何带标题的列正确做法是省略该键而不是传空串直接位于头部横条header band或 tab 栏顶层、而不是 group 内部的链接上section会被忽略它是“每个链接上的注解”因此重命名一列意味着要修改该连续段里所有链接的值——这也是 Dashboard 编辑体验存在的原因见下文。编辑器辅助如果你的配置声明了$schema: https://cdn.scalar.com/schema/scalar-config-next.json编辑器会在下拉 children 上为section提供自动补全。必须掌握的布局规则以下六条规则决定了最终渲染结果每一条都来自连续段consecutive run这一单一机制顺序即书写顺序。列从左到右按“首个链接在children中出现的位置”排序列内链接自上而下同样按书写顺序堆叠。保持同列链接相邻。分组按连续段判断而非按名称归并。两段相同标题但被其他 section 隔开的链接会渲染成两个同名的独立列。无标题列是合法的。没有section的链接就是自己的无标题列。常见模式是在末尾放一两根“兜底”无标题列如上文 header 示例。一个带 section 的链接就足以触发切换。只要任意一个 child 声明了 section整个下拉就切换到分栏模式未标注的链接会变成对应位置的无标题列。所以要在动手前就决定这个下拉是“列表”还是“mega menu”。纯下拉不受影响。所有 children 都没有section的 group 依旧渲染为单列列表同一条横条上可以自由混用纯下拉和 mega menu。只有链接能成列。已废弃的spacerchild 在下拉中不渲染任何东西也不会把一列切断。外观与响应式行为面板的打开方式与其他下拉一致悬停和点击都能触发列标题渲染为链接上方的小号弱化标签small, muted labels链接图标在列内正常显示各列等分面板宽度。宽屏上最多 4 列并排超过 4 列时自动换行到下一行视口收窄时网格自行减少列数直到手机上呈现单列堆叠面板永远不会把页面撑得比屏幕更宽视口小于 1000px时header 链接移入移动端菜单抽屉mobile menu drawerheader mega menu 在那里变成一个可折叠文件夹collapsible folder每列按原顺序显示为带标题的 sectionTab 栏在手机上保持可见tab mega menu 则以单列形式打开标题与链接按书写顺序纵向堆叠。这套行为与“数据是单一扁平列表”的设计直接对应桌面三列、移动抽屉分节、tab 单列全部是同一份children列表在不同视口下的投影。在 Dashboard 中可视化编辑如果不想直接改配置文件可以在 Dashboard 的文档编辑器里搭建 mega menu打开 header 设置选择Header或Tabs点击目标下拉打开它。点击Add column会在一个暂定标题如Column 1下新增一个链接并展开供你设置标题与目标地址用列上方的Column heading输入框重命名该列——重命名会改写该列内所有链接的 heading正好解决了上面“重命名要改所有链接”的痛点用Move up / Move down调整链接顺序。当一个链接被移出所在列的边界时它会进入相邻列并自动继承那一列的标题Add link新增的链接没有标题会作为无标题列出现在末尾把它向上移入某列即可归入该标题。反向操作同样成立清空所有列标题会把下拉还原为普通列表删除某列的最后一个链接时该列随之消失——因为列只有在有链接声明它时才存在。编辑面板旁的预览区会实时展示列的最终形态所见即读者所见。用 CLI 校验与本地预览scalar project check-config接受section字段并在标题为空时报出点名该字段的错误scalar project check-config scalar.config.jsonscalar project preview可以在本地把 mega menu 渲染出来无需部署scalar project preview兼容性与版本前提该特性是纯增量purely additive的任何没有section的配置解析与渲染行为和之前完全一致添加section也不会改变任何链接在折叠菜单中的位置。版本边界下拉 mega menu 随2.2.0 之后的 CLI 版本发布。在更旧的 CLI 上section字段会被忽略下拉按单列列表渲染——也就是说即使使用section的配置在旧版本上依然能正常构建只是看不到分栏效果。本仓库根部的 scalar.config.json 中scalar: 2.0.0声明了配置 schema 版本且其 header 已实际使用section说明该特性在当前仓库使用的 CLI 链路上是可用状态。实践建议列标题控制在一两个词它们是小号标签样式作用是定位而非解释2–4 列、每列 3–6 个链接是最易读的区间超出后把下拉拆成两个把读者最常访问的列放在最左边——它是视障读者屏幕阅读器和视觉读者最先遇到的一列无标题列只承担单一、明确的目的例如末尾一两个兜底链接。小结Scalar 的 mega menu 用一个最小的section注解字段把“扁平链接列表 → 标题分栏”的转换完全交给了渲染层列是连续段的投影、顺序即书写顺序、无标题列合法且无害同一份数据同时驱动桌面分栏、1000px 以下抽屉折叠与 tab 单列三种形态。配合scalar project check-config的字段级校验、scalar project preview的本地渲染以及 Dashboard 里“Add column / Column heading / Move up / Move down”的可视化操作从配置文件到可视化编辑两条路径都能以同一份数据落地且对不使用section的旧配置保持完全向后兼容。【免费下载链接】scalarScalar is an open-source API platform: Modern REST API Client Beautiful API References ✨ 1st-Class OpenAPI/Swagger Support项目地址: https://gitcode.com/GitHub_Trending/sc/scalar创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考