Firefly博客模板文档

外观

侧边栏配置

约 2805 字大约 9 分钟

2025-10-11

概述

sidebarConfig.ts 文件用于配置网站侧边栏的布局、组件显示、排序、动画和响应式行为。

文件位置

src/config/sidebarConfig.ts

配置结构

interface SidebarLayoutConfig {
  enable: boolean;                           // 是否启用侧边栏功能
  position: "left" | "both";                 // 侧边栏位置：left=左侧，both=双侧
  leftComponents: WidgetComponentConfig[];   // 左侧边栏组件配置列表
  rightComponents: WidgetComponentConfig[];  // 右侧边栏组件配置列表
  defaultAnimation: AnimationConfig;         // 默认动画配置
  responsive: ResponsiveConfig;              // 响应式布局配置
}

interface WidgetComponentConfig {
  type: string;                      // 组件类型
  enable: boolean;                   // 是否启用该组件
  order: number;                     // 显示顺序
  position: "top" | "sticky";        // 组件位置
  class: string;                     // CSS类名
  style: string;                     // CSS内联样式
  animationDelay: number;            // 动画延迟时间
  showOnPostPage?: boolean;          // 是否在文章详情页显示（仅右侧边栏组件有效）
  responsive?: ResponsiveOptions;    // 响应式配置
  configId?: string;                 // 配置ID（用于广告等组件）
  customProps?: Record<string, any>; // 自定义属性
}

基础配置

export const sidebarLayoutConfig: SidebarLayoutConfig = {
  // 是否启用侧边栏功能
  enable: true,

  // 侧边栏位置：left=左侧，both=双侧
  // 注意：开启双侧后网格（双列）模式将无法使用，且右侧组件会在宽度低于1024px时隐藏
  position: "both",

  // 左侧边栏组件配置列表
  leftComponents: [
    // 组件配置...
  ],

  // 右侧边栏组件配置列表
  rightComponents: [
    // 组件配置...
  ],

  // 默认动画配置
  defaultAnimation: {
    enable: true,
    baseDelay: 0,
    increment: 50,
  },

  // 响应式布局配置
  responsive: {
    // 不同设备的布局模式
    // hidden:不显示侧边栏   drawer:抽屉模式(移动端不显示)   sidebar:显示侧边栏
    // 使用 Tailwind 标准断点：mobile(<768px), tablet(768px-1023px), desktop(>=1024px)
    layout: {
      mobile: "sidebar",    // 移动端：<768px
      tablet: "sidebar",    // 平板端：768px-1023px
      desktop: "sidebar",   // 桌面端：>=1024px
    },
  },
};

支持的组件类型

1. 用户资料组件 (profile)

{
  type: "profile",
  enable: true,
  order: 1,
  position: "top",
  class: "onload-animation",
  animationDelay: 0,
}

功能：

  • 显示用户头像、姓名、简介
  • 显示社交链接
  • 显示网站统计数据

2. 公告组件 (announcement)

{
  type: "announcement",
  enable: true,
  order: 2,
  position: "top",
  class: "onload-animation",
  animationDelay: 50,
}

功能：

  • 显示重要公告信息
  • 支持关闭功能
  • 支持链接跳转

3. 分类组件 (categories)

{
  type: "categories",
  enable: true,
  order: 3,
  position: "sticky",
  class: "onload-animation",
  animationDelay: 150,
  responsive: {
    collapseThreshold: 5,  // 超过5个分类时自动折叠
  },
}

功能：

  • 显示文章分类列表
  • 自动折叠功能
  • 显示分类文章数量

4. 标签组件 (tags)

{
  type: "tags",
  enable: true,
  order: 5,
  position: "sticky",
  class: "onload-animation",
  animationDelay: 250,
  responsive: {
    collapseThreshold: 20,  // 超过20个标签时自动折叠
  },
}

功能：

  • 显示文章标签云
  • 自动折叠功能
  • 显示标签使用频率

5. 侧边栏目录组件 (sidebarToc)

{
  type: "sidebarToc",
  enable: true,
  order: 3,
  position: "sticky",
  class: "onload-animation",
  animationDelay: 250,
  showOnPostPage: true,  // 只在文章详情页显示
}

功能：

  • 在文章详情页显示目录导航
  • 自动高亮当前浏览位置的标题
  • 支持点击跳转到对应标题
  • 支持多级标题层级显示

配置说明：

  • showOnPostPage: true：只在文章详情页（URL包含 /posts/）显示
  • 建议放在右侧边栏的粘性位置，方便阅读时查看
  • 与悬浮目录（FloatingTOC）配合使用：
    • 当侧边栏目录启用且屏幕宽度 ≥ 1200px 且为列表模式时，优先显示侧边栏目录
    • 其他情况（网格模式/小屏幕/侧边栏目录未启用）显示悬浮目录

6. 站点统计组件 (stats)

{
  type: "stats",
  enable: true,
  order: 6,
  position: "top",
  class: "onload-animation",
  animationDelay: 200,
}

功能：

  • 显示站点运行天数
  • 显示文章总数、分类数、标签数
  • 显示总字数统计

7. 广告组件 (advertisement)

{
  type: "advertisement",
  enable: false,
  order: 10,
  position: "sticky",
  class: "onload-animation",
  animationDelay: 300,
  configId: "ad1",  // 对应 adConfig 中的配置ID
}

功能：

  • 显示广告内容
  • 支持图片和文字广告
  • 支持关闭功能

组件配置详解

组件类型 (type)

类型说明必需配置所在侧边栏
profile用户资料组件无通常在左侧
announcement公告组件无通常在左侧
categories分类组件无通常在左侧
tags标签组件无通常在左侧
sidebarToc侧边栏目录组件showOnPostPage: true通常在右侧
stats站点统计组件无通常在右侧
calendar日历组件无可自定义
advertisement广告组件configId可自定义

显示顺序 (order)

// 数字越小越靠前
components: [
  { type: "profile", order: 1 },      // 最前面
  { type: "announcement", order: 2 }, // 第二
  { type: "categories", order: 3 },   // 第三
  { type: "tags", order: 5 },         // 第四
  { type: "advertisement", order: 6 }, // 最后
]

组件位置 (position)

值说明使用场景
"top"固定在顶部重要组件（资料、公告）
"sticky"粘性定位，可滚动一般组件（分类、标签、广告）

动画配置

{
  class: "onload-animation",    // 动画CSS类
  animationDelay: 100,          // 延迟时间（毫秒）
}

延迟时间建议：

  • 第一个组件：0ms
  • 后续组件：递增50ms
  • 避免动画重叠

响应式配置 (responsive)

{
  responsive: {
    collapseThreshold: 5,  // 折叠阈值
  },
}

折叠阈值：

  • 分类组件：建议5-10个
  • 标签组件：建议15-25个
  • 超过阈值时自动折叠

动画系统

默认动画配置

defaultAnimation: {
  enable: true,        // 是否启用默认动画
  baseDelay: 0,        // 基础延迟时间
  increment: 50,       // 递增延迟时间
}

组件动画延迟

// 推荐配置：递增延迟
components: [
  { animationDelay: 0 },    // 0ms
  { animationDelay: 50 },   // 50ms
  { animationDelay: 100 },  // 100ms
  { animationDelay: 150 },  // 150ms
  { animationDelay: 200 },  // 200ms
]

动画类名

// 可用的动画类名
class: "onload-animation"     // 加载动画
class: "fade-in"             // 淡入动画
class: "slide-in-left"       // 从左滑入
class: "slide-in-right"      // 从右滑入
class: "bounce-in"           // 弹跳进入

响应式布局

断点配置

responsive: {
  breakpoints: {
    mobile: 768,      // 移动端：< 768px
    tablet: 1024,     // 平板端：< 1024px
    desktop: 1280,    // 桌面端：< 1280px
  },
}

布局模式

layout: {
  mobile: "sidebar",    // 移动端：显示侧边栏
  tablet: "sidebar",    // 平板端：显示侧边栏
  desktop: "sidebar",   // 桌面端：显示侧边栏
}

布局模式说明：

  • "hidden"：不显示侧边栏
  • "drawer"：抽屉模式（移动端不显示）
  • "sidebar"：显示侧边栏

响应式组件配置

{
  type: "categories",
  responsive: {
    collapseThreshold: 5,  // 超过5个时折叠
  },
}

完整配置示例

export const sidebarLayoutConfig: SidebarLayoutConfig = {
  enable: true,
  position: "both",  // 双侧边栏模式
  
  components: [
    // 左侧边栏组件
    // 用户资料 - 固定在顶部
    {
      type: "profile",
      enable: true,
      order: 1,
      position: "top",
      sidebar: "left",
      class: "onload-animation",
      animationDelay: 0,
    },
    
    // 公告 - 固定在顶部
    {
      type: "announcement",
      enable: true,
      order: 2,
      position: "top",
      sidebar: "left",
      class: "onload-animation",
      animationDelay: 50,
    },
    
    // 分类 - 粘性定位
    {
      type: "categories",
      enable: true,
      order: 3,
      position: "sticky",
      sidebar: "left",
      class: "onload-animation",
      animationDelay: 150,
      responsive: {
        collapseThreshold: 5,
      },
    },
    
    // 标签 - 粘性定位
    {
      type: "tags",
      enable: true,
      order: 5,
      position: "sticky",
      sidebar: "left",
      class: "onload-animation",
      animationDelay: 250,
      responsive: {
        collapseThreshold: 20,
      },
    },
    
    // 右侧边栏组件
    // 站点统计 - 固定在顶部
    {
      type: "stats",
      enable: true,
      order: 1,
      position: "top",
      sidebar: "right",
      class: "onload-animation",
      animationDelay: 200,
    },
    
    // 日历组件 - 粘性定位
    {
      type: "calendar",
      enable: true,
      order: 2,
      position: "sticky",
      sidebar: "right",
      class: "onload-animation",
      animationDelay: 250,
      showOnPostPage: false,  // 不在文章页显示
    },
    
    // 侧边栏目录 - 粘性定位（只在文章详情页显示）
    {
      type: "sidebarToc",
      enable: true,
      order: 3,
      position: "sticky",
      sidebar: "right",
      class: "onload-animation",
      animationDelay: 250,
      showOnPostPage: true,  // 只在文章详情页显示
    },
    
    // 广告1 - 粘性定位（左侧）
    {
      type: "advertisement",
      enable: false,
      order: 10,
      position: "sticky",
      sidebar: "left",
      class: "onload-animation",
      animationDelay: 300,
      configId: "ad1",
    },
    
    // 广告2 - 粘性定位（右侧）
    {
      type: "advertisement",
      enable: false,
      order: 10,
      position: "sticky",
      sidebar: "right",
      class: "onload-animation",
      animationDelay: 350,
      configId: "ad2",
    },
  ],
  
  defaultAnimation: {
    enable: true,
    baseDelay: 0,
    increment: 50,
  },
  
  responsive: {
    layout: {
      mobile: "sidebar",
      tablet: "sidebar",
      desktop: "sidebar",
    },
  },
};

组件管理

启用/禁用组件

// 启用组件
{
  type: "categories",
  enable: true,  // 启用
}

// 禁用组件
{
  type: "advertisement",
  enable: false, // 禁用
}

调整组件顺序

// 调整order值来改变显示顺序
components: [
  { type: "profile", order: 1 },      // 最前面
  { type: "categories", order: 2 },   // 第二
  { type: "tags", order: 3 },         // 第三
  { type: "advertisement", order: 4 }, // 最后
]

添加新组件

// 在components数组中添加新组件
components: [
  // 现有组件...
  {
    type: "custom-component",  // 新组件类型
    enable: true,
    order: 8,                  // 新的顺序
    position: "sticky",
    class: "onload-animation",
    animationDelay: 400,
  },
]

最佳实践

1. 组件顺序规划

// 单侧边栏推荐顺序
components: [
  { type: "profile", order: 1 },        // 用户信息最重要
  { type: "announcement", order: 2 },   // 公告次重要
  { type: "categories", order: 3 },     // 导航功能
  { type: "tags", order: 4 },           // 导航功能
  { type: "advertisement", order: 5 },  // 广告最后
]

// 双侧边栏推荐配置
components: [
  // 左侧：主要导航和内容
  { type: "profile", sidebar: "left", order: 1 },
  { type: "announcement", sidebar: "left", order: 2 },
  { type: "categories", sidebar: "left", order: 3 },
  { type: "tags", sidebar: "left", order: 5 },
  
  // 右侧：辅助信息
  { type: "stats", sidebar: "right", order: 1 },
  { type: "calendar", sidebar: "right", order: 2 },
  { type: "sidebarToc", sidebar: "right", order: 3, showOnPostPage: true },
  { type: "advertisement", sidebar: "right", order: 10 },
]

2. 动画延迟设置

// 推荐：递增延迟，避免重叠
animationDelay: 0,    // 第一个组件
animationDelay: 50,   // 第二个组件
animationDelay: 100,  // 第三个组件
animationDelay: 150,  // 第四个组件

3. 响应式考虑

// 移动端友好的配置
responsive: {
  breakpoints: {
    mobile: 768,    // 合理的断点
  },
  layout: {
    mobile: "sidebar",  // 移动端也显示侧边栏
  },
}

4. 性能优化

// 禁用不必要的组件
{
  type: "advertisement",
  enable: false,  // 如果不需要广告，直接禁用
}

常见问题

Q: 如何禁用整个侧边栏？

A: 设置 enable: false：

export const sidebarLayoutConfig: SidebarLayoutConfig = {
  enable: false,  // 禁用整个侧边栏
  // ... 其他配置
};

Q: 如何调整侧边栏位置？

A: 修改 position 配置：

{
  position: "right",  // 改为右侧
}

// 或启用双侧边栏
{
  position: "both",  // 双侧边栏
}

Q: 如何配置双侧边栏？

A: 设置 position: "both" 并为每个组件指定 sidebar 属性：

{
  position: "both",
  components: [
    {
      type: "profile",
      sidebar: "left",  // 显示在左侧
      // ... 其他配置
    },
    {
      type: "stats",
      sidebar: "right",  // 显示在右侧
      // ... 其他配置
    },
  ],
}

注意事项：

  • 开启双侧边栏后，文章列表的网格（双列）布局将无法使用
  • 右侧组件会在宽度低于1024px时自动隐藏
  • 需要在 siteConfig.ts 中将 postListLayout.defaultMode 设置为 "list"

Q: 如何添加新的组件类型？

A: 需要先实现对应的组件，然后在配置中添加：

{
  type: "new-component",  // 新组件类型
  enable: true,
  order: 10,
  position: "sticky",
  class: "onload-animation",
  animationDelay: 500,
}

Q: 如何调整组件显示顺序？

A: 修改 order 值：

// 将分类组件移到最前面
{
  type: "categories",
  order: 1,  // 改为1，会显示在最前面
}

Q: 动画不生效怎么办？

A: 检查以下项目：

  1. defaultAnimation.enable 是否为 true
  2. 组件是否设置了正确的 class
  3. CSS动画类是否已定义

Q: 如何自定义动画延迟？

A: 修改 animationDelay 值：

{
  type: "categories",
  animationDelay: 200,  // 自定义延迟时间
}

高级配置

条件显示组件

// 根据环境显示不同组件
const getComponents = () => {
  const baseComponents = [
    { type: "profile", enable: true, order: 1 },
    { type: "categories", enable: true, order: 2 },
  ];
  
  // 开发环境显示调试组件
  if (process.env.NODE_ENV === 'development') {
    baseComponents.push({
      type: "debug-info",
      enable: true,
      order: 10,
      position: "sticky",
      class: "onload-animation",
      animationDelay: 500,
    });
  }
  
  return baseComponents;
};

动态组件配置

// 根据用户权限显示不同组件
const getUserComponents = (userRole: string) => {
  const components = [
    { type: "profile", enable: true, order: 1 },
    { type: "categories", enable: true, order: 2 },
  ];
  
  if (userRole === 'admin') {
    components.push({
      type: "admin-panel",
      enable: true,
      order: 5,
      position: "sticky",
      class: "onload-animation",
      animationDelay: 300,
    });
  }
  
  return components;
};

主题相关配置

// 根据主题显示不同组件
const getThemeComponents = (theme: string) => {
  const components = [
    { type: "profile", enable: true, order: 1 },
  ];
  
  if (theme === 'minimal') {
    // 极简主题只显示必要组件
    components.push({ type: "categories", enable: true, order: 2 });
  } else {
    // 完整主题显示所有组件
    components.push(
      { type: "announcement", enable: true, order: 2 },
      { type: "categories", enable: true, order: 3 },
      { type: "tags", enable: true, order: 4 },
      { type: "advertisement", enable: true, order: 5 }
    );
  }
  
  return components;
};

版权归属：夏叶

许可证：署名 4.0 国际 (CC-BY-4.0)