配置参考

主题通过 FxThemeConfig 扩展了 VitePress 默认主题配置，新增了音乐球和彩纸效果的配置项。

FxThemeConfig

FxThemeConfig 继承自 DefaultTheme.Config，新增以下字段：

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

  /**
   * 是否启用点击彩纸效果，默认 true
   */
  confetti?: boolean
}

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

音乐球配置

单曲模式

配置 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,
}

彩纸效果在用户点击页面任意位置时触发，会在点击位置释放金色星星和彩色圆形纸屑。

完整配置示例

// .vitepress/config.mts
import { defineConfigWithTheme } from 'vitepress'
import fxConfig from '@fuxishi/vitepress-theme/config'
import type { FxThemeConfig } from '@fuxishi/vitepress-theme/config'

export default defineConfigWithTheme<FxThemeConfig>({
  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,
    musicBall: {
      enable: true,
      autoplay: false,
      loop: true,
      list: [
        { name: '歌曲名', src: '/music/song.mp3' },
      ],
    },
  },
})