配置参考

主题通过 FxThemeCustomConfig 提供自定义配置，消费方通过 DefaultTheme.Config & FxThemeCustomConfig 交叉类型组合完整的主题配置。

FxThemeCustomConfig

FxThemeCustomConfig 是一个独立的纯接口，新增以下字段：

interface FxThemeCustomConfig {
  /**
   * 悬浮音乐球配置
   */
  musicBall?: {
    /** 是否启用音乐球，默认 true */
    enable?: boolean
    /** 是否可见，默认 true */
    visible?: boolean
    /** 自动播放，默认 false */
    autoplay?: boolean
    /** 循环播放（仅单曲模式），默认 true */
    loop?: boolean
    /** 单首音乐地址 */
    src?: string
    /** 多首音乐列表 */
    list?: MusicItem[]
  }

  /**
   * 点击彩纸效果配置
   */
  confetti?:
    | boolean
    | {
        /** 预设形状: 'star' 金色星星 | 'colored-paper' 彩色纸片 */
        shape?: "star" | "colored-paper"
        /** 自定义 Emoji 形状，支持单个字符串或数组 */
        shapes?: string | string[]
        /** 是否添加二次散射粒子，默认 true */
        secondary?: boolean
      }

  /**
   * 自动提取 hero 图片颜色作为背景光晕和代码块光束颜色，默认 false
   */
  heroImageColor?: boolean

  /**
   * 启用平滑滚动和大纲指示条过渡动画，默认 false
   */
  smoothScroll?: boolean

  /**
   * 代码块折叠，默认 true 启用
   * 可配置折叠行数阈值
   */
  codeBlockFold?: boolean | {
    /** 超过多少行折叠，默认 10 */
    lines?: number
  }
}

interface MusicItem {
  /** 歌曲名称 */
  name: string
  /** 音频文件地址 */
  src: string
}

在配置文件中的使用方式：

import { defineConfig } from "vitepress"
import type { DefaultTheme } from "vitepress"
import type { FxThemeCustomConfig } from "@fuxishi/vitepress-theme"

type ThemeConfig = DefaultTheme.Config & FxThemeCustomConfig

export default defineConfig<ThemeConfig>({ ... })

音乐球配置

单曲模式

配置 src 字段即可启用单曲模式：

themeConfig: {
  musicBall: {
    enable: true,
    autoplay: false,
    loop: true,
    src: '/music/my-song.mp3',
  },
}

音频文件需放在 public/ 目录下，如 public/music/my-song.mp3。

列表模式

配置 list 字段启用多首歌曲列表：

themeConfig: {
  musicBall: {
    enable: true,
    autoplay: true,
    loop: true,
    list: [
      { name: '梦中的婚礼', src: '/music/wedding-dream.mp3' },
      { name: '海阔天空', src: '/music/broad-sea-sky.mp3' },
      { name: '碎银几两', src: '/music/silver-coins.mp3' },
    ],
  },
}

提示

当 list 只有一首歌曲时，自动切换为单曲模式（等价于配置 src）。

彩纸效果配置

themeConfig: {
  // 启用彩纸（默认，金色星星）
  confetti: true,

  // 禁用彩纸
  confetti: false,

  // 彩色纸片
  confetti: { shape: "colored-paper" },

  // 自定义 Emoji
  confetti: { shapes: ["🌸", "🎀"] },
}

彩纸效果在用户点击页面任意位置时触发，会在点击位置释放彩纸粒子。支持三种模式：

配置	说明
true	金色星星（默认）
{ shape: "star" }	金色星星
{ shape: "colored-paper" }	彩色纸片
{ shapes: "🌸" }	自定义单个 Emoji
{ shapes: ["🌸", "🎀"] }	自定义多个 Emoji
{ ..., secondary: false }	关闭二次散射粒子

Hero 图片取色

启用后，主题会自动从首页 hero.image 配置的图片中提取主色调，动态应用到以下区域：

• Hero 背景光晕 — 使用提取的所有色相构建 conic-gradient
• Hero 标题渐变 — 使用色相差最大的两个颜色构建 linear-gradient
• 代码块光束边框 — 通过 CSS 变量 --fx-beam-c1 / --fx-beam-c2 动态覆盖
• 音乐球 — 进度环渐变、旋转光环、播放发光等颜色同步变化

themeConfig: {
  // 启用 hero 图片取色
  heroImageColor: true,
}

提示

无需手动配置图片路径，主题会自动读取首页 frontmatter 中的 hero.image 配置。亮色和暗色模式分别从对应的图片提取颜色。颜色会缓存到 localStorage，图片更换时自动失效并重新提取。

平滑滚动

启用后，右侧大纲导航点击时页面平滑滚动到对应位置，导航指示条也会丝滑过渡：

themeConfig: {
  // 启用平滑滚动
  smoothScroll: true,
}

启用后效果：

• 点击右侧大纲导航，页面平滑滚动到对应标题
• 导航指示条（outline marker）位置切换带有丝滑过渡动画

代码块折叠

超过指定行数的代码块自动折叠，底部显示淡出遮罩和展开按钮：

themeConfig: {
  // 启用（默认，10 行折叠）
  codeBlockFold: true,

  // 禁用
  codeBlockFold: false,

  // 自定义折叠行数
  codeBlockFold: { lines: 20 },
}

配置	说明
true	启用，默认 10 行折叠
false	禁用
{ lines: 20 }	启用，自定义 20 行折叠

提示

折叠后代码底部使用毛玻璃模糊遮罩效果，不会遮挡暗色模式下的光束边框动画。

完整配置示例

// .vitepress/config.mts
import { defineConfig } from "vitepress"
import type { DefaultTheme } from "vitepress"
import fxConfig from "@fuxishi/vitepress-theme/config"
import type { FxThemeCustomConfig } from "@fuxishi/vitepress-theme"

type ThemeConfig = DefaultTheme.Config & FxThemeCustomConfig

export default defineConfig<ThemeConfig>({
  extends: fxConfig,
  lang: "zh-CN",
  title: "我的文档站",
  head: [["link", { rel: "icon", type: "image/png", href: "/favicon.png" }]],
  themeConfig: {
    logo: "/logo.png",
    nav: [{ text: "指南", link: "/guide/" }],
    sidebar: {
      "/guide/": [{ text: "快速开始", link: "/guide/getting-started" }],
    },
    footer: {
      copyright: "Copyright © 2025-present",
    },
    // 主题扩展配置
    confetti: true,
    heroImageColor: true,
    smoothScroll: true,
    codeBlockFold: true,
    musicBall: {
      enable: true,
      autoplay: false,
      loop: true,
      list: [{ name: "歌曲名", src: "/music/song.mp3" }],
    },
  },
})