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下拉会渲染出三列，从左到右依次为：

注意最后一列没有section，因此以无标题列的形式出现在其书写位置上。

mega menu 内的链接接受与普通 header 链接 完全相同的属性：title、to、icon、newTab、style；group 本身则保留自己的title、icon、align。

本仓库自己的 scalar.config.json 就是一个真实用例：头部Resources下拉的 children 里，Compare / Migration / Blog / Changelog 四个链接统一标注"section": "Resources"，About / 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字段规格与约束

约束要点：

• 必须是非空字符串。空字符串会直接导致校验失败；如果想让某个链接不进入任何带标题的列，正确做法是省略该键，而不是传空串；
• 直接位于头部横条（header band）或 tab 栏顶层、而不是 group 内部的链接上，section会被忽略；
• 它是“每个链接上的注解”，因此重命名一列意味着要修改该连续段里所有链接的值——这也是 Dashboard 编辑体验存在的原因（见下文）。

编辑器辅助：如果你的配置声明了"$schema": "https://cdn.scalar.com/schema/scalar-config-next.json"，编辑器会在下拉 children 上为section提供自动补全。

必须掌握的布局规则

以下六条规则决定了最终渲染结果，每一条都来自连续段（consecutive run）这一单一机制：

1. 顺序即书写顺序。列从左到右按“首个链接在children中出现的位置”排序；列内链接自上而下同样按书写顺序堆叠。
2. 保持同列链接相邻。分组按连续段判断，而非按名称归并。两段相同标题但被其他 section 隔开的链接，会渲染成两个同名的独立列。
3. 无标题列是合法的。没有section的链接就是自己的无标题列。常见模式是在末尾放一两根“兜底”无标题列（如上文 header 示例）。
4. 一个带 section 的链接就足以触发切换。只要任意一个 child 声明了 section，整个下拉就切换到分栏模式；未标注的链接会变成对应位置的无标题列。所以要在动手前就决定这个下拉是“列表”还是“mega menu”。
5. 纯下拉不受影响。所有 children 都没有section的 group 依旧渲染为单列列表；同一条横条上可以自由混用纯下拉和 mega menu。
6. 只有链接能成列。已废弃的spacerchild 在下拉中不渲染任何东西，也不会把一列切断。

外观与响应式行为

• 面板的打开方式与其他下拉一致：悬停和点击都能触发；
• 列标题渲染为链接上方的小号弱化标签（small, muted labels），链接图标在列内正常显示；
• 各列等分面板宽度。宽屏上最多 4 列并排，超过 4 列时自动换行到下一行；
• 视口收窄时网格自行减少列数，直到手机上呈现单列堆叠；面板永远不会把页面撑得比屏幕更宽；
• 视口小于 1000px时，header 链接移入移动端菜单抽屉（mobile menu drawer）：header mega menu 在那里变成一个可折叠文件夹（collapsible folder），每列按原顺序显示为带标题的 section；
• Tab 栏在手机上保持可见；tab mega menu 则以单列形式打开，标题与链接按书写顺序纵向堆叠。

这套行为与“数据是单一扁平列表”的设计直接对应：桌面三列、移动抽屉分节、tab 单列，全部是同一份children列表在不同视口下的投影。

在 Dashboard 中可视化编辑

如果不想直接改配置文件，可以在 Dashboard 的文档编辑器里搭建 mega menu：打开 header 设置，选择Header或Tabs，点击目标下拉打开它。

1. 点击Add column：会在一个暂定标题（如Column 1）下新增一个链接并展开，供你设置标题与目标地址；
2. 用列上方的Column heading输入框重命名该列——重命名会改写该列内所有链接的 heading（正好解决了上面“重命名要改所有链接”的痛点）；
3. 用Move up / Move down调整链接顺序。当一个链接被移出所在列的边界时，它会进入相邻列，并自动继承那一列的标题；
4. Add link新增的链接没有标题，会作为无标题列出现在末尾；把它向上移入某列即可归入该标题。

反向操作同样成立：清空所有列标题会把下拉还原为普通列表；删除某列的最后一个链接时该列随之消失——因为列只有在有链接声明它时才存在。编辑面板旁的预览区会实时展示列的最终形态，所见即读者所见。

用 CLI 校验与本地预览

scalar project check-config接受section字段，并在标题为空时报出点名该字段的错误：

scalar project check-config scalar.config.json

scalar 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