Firefly 布局系统详解

1.1 单侧边栏模式#

1.1.1 左侧边栏 (position: “left”)#

1.1.2 右侧边栏 (position: “right”)#

1
export const sidebarLayoutConfig: SidebarLayoutConfig = {
2
  enable: true,
3
  position: "left", // 左侧边栏
4
  showBothSidebarsOnPostPage: true, // 是否在文章详情页显示双侧边栏
5
};

1.2 双侧边栏模式 (position: “both”)#

布局结构#

1
export const sidebarLayoutConfig: SidebarLayoutConfig = {
2
  enable: true,
3
  position: "both", // 双侧边栏

2.1 列表模式 (defaultMode: “list”)#

列表布局结构#

1
export const siteConfig: SiteConfig = {
2
  postListLayout: {
3
    defaultMode: "list", // 列表模式
4
    allowSwitch: true,   // 允许用户切换
5
  },
6
};

2.2 网格模式 (defaultMode: “grid”)#

自适应网格#

网格模式通过 columnWidth 配置卡片的最小宽度（单位 px），浏览器会根据容器可用宽度自动计算能容纳多少列。

1
export const siteConfig: SiteConfig = {
2
  postListLayout: {
3
    defaultMode: "grid",
4
    allowSwitch: true,
5
    grid: {
6
      masonry: true,      // 开启瀑布流
7
      columnWidth: 320,   // 卡片最小宽度(px)，浏览器自动计算列数
8
    },
9
  },
10
};

2.3 瀑布流布局 (Masonry)#

Firefly 的网格模式内置了智能瀑布流布局支持，解决了网格布局中因图文混合文章导致的卡片高度不一致导致的空白问题。

• 智能排版：自动将卡片放置到最短的列，最大化利用垂直空间。
• 消除空白：通过绝对定位精确计算每个卡片的位置，让卡片紧贴上方卡片，消除垂直方向的空白间隙。
• 自适应列数：瀑布流同样根据 columnWidth 和容器宽度动态计算列数，无需固定配置。
• 配置灵活：您可以在 siteConfig.ts 中通过 postListLayout.grid.masonry 选项自由开启或关闭此功能。

3.1 布局选择建议#

4.1 智能降级规则#

为了保证最佳阅读体验，系统会在屏幕变窄时自动调整布局：

1. 网格列数自动减少：网格模式的列数由 columnWidth 和容器宽度自动决定，屏幕越窄列数越少。
2. 网格模式 -> 列表模式：当屏幕宽度小于 1200px（平板和手机）时，网格模式会自动切换为单列列表模式，以保证卡片内容的可读性。
3. 双侧边栏 -> 单侧边栏：当屏幕宽度小于 1280px 时，会根据tabletSidebar配置显示单侧边栏，隐藏其中一个侧边栏，文章目录导航会切换成浮动目录导航。

Q1: 为什么在手机上看不到网格效果？#

A: 为了保证阅读体验，Firefly 在屏幕宽度小于 1200px 时会自动强制切换为列表模式。手机屏幕太窄，不适合展示多列网格。

Q2: 布局切换按钮在哪里？#

A: 布局切换按钮位于导航栏右侧。它仅在屏幕宽度 ≥ 1200px 时显示，因为在小屏幕上系统强制使用列表模式，无需切换。

Q3: 如何调整网格列数？#

A: 通过 columnWidth 配置卡片最小宽度即可。值越小，同等宽度下列数越多；值越大，列数越少。浏览器会自动根据可用宽度计算最佳列数。