Fumadocs 16.2 | Fumadocs 中文网

我们很高兴地宣布发布 Fumadocs 16.2，该版本为 Fumadocs 用户界面引入了更优的布局系统。

🌐 We are pleased to announce the release of Fumadocs 16.2, introducing a better layout system for Fumadocs UI.

新布局系统

🌐 The New Layout System

在文档框架中处理布局可能会带来重大挑战。

🌐 Handling layouts in documentation frameworks can present significant challenges.

作为解决方案，Fumadocs UI 实现了一个网格系统，该系统可组合、灵活、一致且可预测。有关更多详细信息，请参阅链接的文档。

🌐 As a solution, Fumadocs UI implemented a Grid System that is composable, flexible, cohesive and predictable. See the linked docs for more details.

简而言之，布局由一个网格容器和使用 position: sticky 的布局组件组成：

🌐 In short, the layout consists of a grid container, and layout components using position: sticky:

#nd-docs-layout {
  grid-template:
    'sidebar header toc'
    'sidebar toc-popover toc'
    'sidebar main toc' 1fr / minmax(var(--fd-sidebar-col), 1fr) minmax(0, var(--fd-page-col))
    minmax(min-content, 1fr);

  --fd-docs-row-1: var(--fd-banner-height, 0px);
  --fd-docs-row-2: calc(var(--fd-docs-row-1) + var(--fd-header-height));
  --fd-docs-row-3: calc(var(--fd-docs-row-2) + var(--fd-toc-popover-height));
}

容器定义了每一行的偏移量，布局组件可以根据它们的网格区域来利用这些偏移量：

🌐 The container defines the offsets of each row, layout components can leverage them according to their grid area:

.layout-component {
  position: sticky;
  top: var(--fd-docs-row-1);
  height: calc(var(--fd-docs-height) - var(--fd-docs-row-1));
}

布局组件还负责通过 CSS 变量声明它们的高度，从而使容器能够计算正确的行偏移量。

🌐 Layout components are also responsible to declare their heights via CSS variables, allowing container to calculate the right row offsets.

#nd-docs-layout:has(.layout-component) {
  --fd-header-height: 56px;
}

对于用户自定义，我们推荐使用 Fumadocs CLI 的 customize 命令，或者挂接相关的网格区域，例如：

🌐 For user-land customizations, we recommend the Fumadocs CLI customize command, or hooking the relevant grid areas like:

.custom-component {
  /* depends on the layout, usually we have toc, toc-popover, sidebar, header, main */
  grid-area: main;
}

为什么要改变？

🌐 Why the Change?

以前，Fumadocs 的 UI 依赖于 position: fixed 和数学计算（受 Vitepress 启发）。旧的方法通常缺乏可组合性，对初学者来说也很难管理。

🌐 Previously, Fumadocs UI relied on position: fixed and mathematical computations (inspired by Vitepress). The older method often lacked composability and difficult for beginners to manage.

新系统修复了大部分缺陷，使可视化更加容易，同时降低了以往解决方案的复杂性。

🌐 The new system fixed most of the flaws, allowing easier visualizations, while reducing the complexity of previous solutions.

重大更改

🌐 Breaking Changes

尽管 Fumadocs 16.2 在多个方面保持了兼容性，尤其是：

🌐 While Fumadocs 16.2 preserves compatibility in several areas, notably:

--fd-layout-width CSS 变量继续按预期工作。
所有 ID 和数据属性保持不变。

然而，转向新的网格系统可能会影响现有的自定义设置，特别是那些依赖于之前固定位置逻辑的设置。我们建议仔细审查你的实现并进行全面测试。

🌐 However, the shift to the new grid system may impact existing customizations, particularly those dependent on the prior fixed-position logic. We recommend reviewing your implementation carefully and testing thoroughly.

小改动

🌐 Minor Changes

不再暴露内部组件

🌐 No Longer Exposing Internal Components

布局组件如 Root 切换、语言切换和主题切换不再直接暴露。这个决定使 Fumadocs UI 能够对这些元素进行迭代，而不会对 API 之外的使用引入意外的破坏性变更。

🌐 Layout components such as Root Toggle, Language Toggle, and Theme Toggle are no longer directly exposed. This decision enables Fumadocs UI to iterate these elements without introducing unexpected breaking changes to usage outside of API surfaces.

迁移步骤： 使用你自己的实现覆盖相关的布局组件，或使用 Fumadocs CLI 命令（add 或 customize）将它们本地安装。

按类型导入页面布局

🌐 Importing Page Layouts by Type

注意本布局现在与默认布局隔离，包括它们的页面组件。

🌐 The notebook layout is now isolated from default layout, including their page components.

确保根据文档的布局导入适当的页面布局：

🌐 Make sure to import the appropriate page layout based on your docs layout:

// For docs layout
import { DocsPage } from 'fumadocs-ui/layouts/docs/page';
// For notebook layout
import { DocsPage } from 'fumadocs-ui/layouts/notebook/page';

迁移步骤： 相应地更新你的导入。虽然默认的 fumadocs-ui/page 会重定向到正确的布局，但我们强烈建议明确导入以提高清晰度并确保未来兼容性。

移除未使用的样式

🌐 Removal of Unused Styles

与弃用的 container 工具和 --spacing-fd-container 变量相关的样式已被删除，因为它们不再使用。

🌐 Styles related to the abandoned container utility, and --spacing-fd-container variable, have been dropped as they are no longer utilized.

迁移步骤： 从你的代码库中移除对这些样式的引用。

侧边栏上下文的重新定位

🌐 Relocation of Sidebar Context

fumadocs-ui/contexts/sidebar 模块已被移除。请通过以下方式访问上下文：

🌐 The fumadocs-ui/contexts/sidebar module has been removed. Access the context via:

import { useSidebar } from 'fumadocs-ui/components/sidebar/base';

迁移步骤： 更新导入路径，确保上下文仅在 <DocsLayout /> 内访问。

结论

🌐 Conclusion

Fumadocs 16.2 旨在为开发者提供更大的灵活性。欢迎在 GitHub 讨论区分享你对新设计的看法！

🌐 Fumadocs 16.2 aims to offer greater flexibility for developers. Welcome to share your thoughts about the new design on GitHub Discussion!