🎵 悬浮播放器功能简介

悬浮音乐播放器是 Demius 主题 v2.8.2 版本新增的独立功能，是一个桌面端的独立小组件，位于页面左下角。它与侧栏音乐组件完全分离，拥有独立的配置和数据源，支持拖拽移动、缩小、关闭等丰富的交互功能。

主要特性

  • 🎯 配置独立：使用独立的 [params.floatMusicPlayer] 配置项，与侧栏音乐组件分离
  • 📊 数据源独立：从 data/music-planet.yaml 读取数据，与侧栏音乐组件数据源分离
  • 🎵 灵活选择：支持4种方式选择要播放的音乐（索引、标题匹配、精确匹配、直接指定）
  • 🖱️ 拖拽移动：支持拖动到全屏任意位置，位置自动保存
  • 📦 缩小功能：可以缩小播放器，缩小后内容不可交互但可拖拽移动
  • ❌ 关闭功能：可以关闭播放器，关闭时自动停止音乐播放
  • 💾 状态保存：位置和缩小状态自动保存到localStorage，刷新后恢复
  • 📱 响应式设计：窄屏（≤768px）自动隐藏
  • 🌓 暗色模式：自动适配主题
  • 🔄 PJAX兼容：支持无刷新切换

🚀 快速开始

1. 启用悬浮播放器

在 hugo.toml 中启用悬浮播放器：

# ===== 悬浮音乐播放器配置（独立配置，与侧栏音乐组件分离） =====
[params.floatMusicPlayer]
  enabled = true  # 启用悬浮音乐播放器

2. 配置数据源

悬浮播放器从 data/music-planet.yaml 读取数据。确保该文件存在并包含音乐数据。

3. 选择要播放的音乐

支持4种方式选择要播放的音乐（详见下方配置说明）。

4. 查看效果

启动 Hugo 服务器，访问网站查看左下角的悬浮播放器。

📝 配置详解

基础配置

# ===== 悬浮音乐播放器配置（独立配置，与侧栏音乐组件分离） =====
[params.floatMusicPlayer]
  # 是否启用悬浮音乐播放器（桌面独立小组件，位于左下角）
  enabled = true
  
  # 数据源配置：从 data/music-planet.yaml 中选择数据
  # （见下方数据选择方式）
  
  # 播放器选项（可选，优先级高于data/music-planet.yaml中的配置）
  # autoplay = false           # 是否自动播放
  # loop = "all"              # 循环模式：all、one、none
  # order = "list"            # 播放顺序：list、random
  # volume = 0.7              # 音量：0-1
  # listFolded = true         # 列表是否折叠
  # listMaxHeight = "340px"   # 列表最大高度
  # mini = false              # 迷你模式
  # fixed = false             # 固定模式

数据选择方式

方式1：通过section索引选择

选择指定索引的section（从0开始，支持多个索引）：

[params.floatMusicPlayer]
  enabled = true
  sectionIndexes = [0, 1]  # 选择第1和第2个section的所有音乐

方式2：通过section标题部分匹配选择

选择标题包含指定关键词的sections：

[params.floatMusicPlayer]
  enabled = true
  sectionTitles = ["网易云音乐", "QQ音乐"]  # 选择标题包含这些关键词的sections

方式3：通过section标题精确匹配选择（推荐）

选择标题完全匹配的section：

[params.floatMusicPlayer]
  enabled = true
  sectionTitle = "🎧 网易云音乐 · 歌单"  # 选择标题完全匹配的section（优先级最高）

方式4：直接指定音乐项

直接指定要播放的音乐项（如果设置了此项，将忽略上面的section选择方式）：

[params.floatMusicPlayer]
  enabled = true
  
  # 直接指定时会从所有sections中查找匹配的items
  [[params.floatMusicPlayer.items]]
    server = "netease"
    type = "playlist"
    id = "4977885420"
  
  [[params.floatMusicPlayer.items]]
    server = "netease"
    type = "song"
    id = "27583305"

数据选择优先级：

  1. 方式4：直接指定items（优先级最高）
  2. 方式3：精确匹配section标题
  3. 方式2：部分匹配section标题
  4. 方式1：通过索引选择
  5. 如果都没有设置，默认使用第一个section

播放器选项配置

播放器选项可以覆盖 data/music-planet.yaml 中对应item的配置：

[params.floatMusicPlayer]
  enabled = true
  sectionTitle = "🎧 网易云音乐 · 歌单"
  
  # 播放器选项（优先级高于data/music-planet.yaml中的配置）
  autoplay = false           # 是否自动播放
  loop = "all"              # 循环模式：all（全部循环）、one（单曲循环）、none（不循环）
  order = "list"            # 播放顺序：list（列表顺序）、random（随机播放）
  volume = 0.7              # 音量：0-1之间的数值
  listFolded = true         # 列表是否折叠
  listMaxHeight = "340px"   # 列表最大高度
  mini = false              # 迷你模式
  fixed = false             # 固定模式

🎮 交互功能演示

拖拽移动

操作方式：

  1. 鼠标悬停在播放器顶部区域（拖拽手柄）
  2. 按住鼠标左键拖动
  3. 释放鼠标左键，播放器将停留在新位置

特性：

  • ✅ 支持拖动到全屏任意位置
  • ✅ 位置自动保存到localStorage
  • ✅ 刷新页面后位置自动恢复

缩小功能

操作方式：

  1. 鼠标悬停在播放器上，显示控制按钮
  2. 点击缩小按钮（顶部右侧的减号图标）
  3. 播放器缩小到80%

特性：

  • ✅ 缩小后内容不可交互（鼠标透过）
  • ✅ 控制按钮和拖拽手柄仍可交互
  • ✅ 可以拖拽移动位置
  • ✅ 点击缩小按钮可恢复

关闭功能

操作方式：

  1. 鼠标悬停在播放器上，显示控制按钮
  2. 点击关闭按钮（顶部右侧的X图标）
  3. 播放器关闭并停止音乐播放

特性：

  • ✅ 关闭时自动停止所有音乐播放
  • ✅ 关闭状态保存到localStorage
  • ✅ 需要手动重新打开（刷新页面或重新配置）

📊 完整配置示例

示例1：播放网易云音乐歌单

# ===== 悬浮音乐播放器配置 =====
[params.floatMusicPlayer]
  enabled = true
  sectionTitle = "🎧 网易云音乐 · 歌单"  # 从data/music-planet.yaml中选择标题匹配的section
  listFolded = true                      # 列表折叠
  autoplay = false                       # 不自动播放
  volume = 0.8                          # 音量80%

示例2：播放多个平台的音乐

[params.floatMusicPlayer]
  enabled = true
  sectionTitles = ["网易云音乐", "QQ音乐"]  # 选择包含这些关键词的sections
  loop = "all"                           # 全部循环
  order = "random"                       # 随机播放

示例3：直接指定音乐项

[params.floatMusicPlayer]
  enabled = true
  
  # 直接指定要播放的音乐
  [[params.floatMusicPlayer.items]]
    server = "netease"
    type = "playlist"
    id = "4977885420"
  
  [[params.floatMusicPlayer.items]]
    server = "tencent"
    type = "playlist"
    id = "1234567890"
  
  # 播放器选项
  autoplay = true
  loop = "all"
  volume = 0.7

示例4：自定义播放器选项

[params.floatMusicPlayer]
  enabled = true
  sectionTitle = "🎧 网易云音乐 · 歌单"
  
  # 自定义播放器选项
  autoplay = false           # 不自动播放
  loop = "one"              # 单曲循环
  order = "list"            # 列表顺序
  volume = 0.6              # 音量60%
  listFolded = false        # 列表展开
  listMaxHeight = "400px"   # 列表最大高度400px
  mini = false              # 非迷你模式
  fixed = false             # 非固定模式

🔧 高级配置

与侧栏音乐组件分离

悬浮播放器与侧栏音乐组件完全独立，互不影响：

# 侧栏音乐组件配置
[params.aside.music]
  enabled = true
  title = "音乐"
  # ... 其他配置

# 悬浮音乐播放器配置（完全独立）
[params.floatMusicPlayer]
  enabled = true
  sectionTitle = "🎧 网易云音乐 · 歌单"
  # ... 其他配置

数据源配置

悬浮播放器从 data/music-planet.yaml 读取数据，确保该文件格式正确：

sections:
  - title: "🎧 网易云音乐 · 歌单"
    badge: violet
    items:
      - server: netease
        type: playlist
        id: "4977885420"
      - server: netease
        type: song
        id: "27583305"
  
  - title: "QQ音乐 · 歌单"
    badge: blue
    items:
      - server: tencent
        type: playlist
        id: "1234567890"

❓ 常见问题

Q1: 悬浮播放器不显示？

可能原因：

  1. enabled = false 或未配置
  2. 屏幕宽度 ≤ 768px（窄屏自动隐藏）
  3. data/music-planet.yaml 文件不存在或格式错误
  4. 选择的section或items不存在

解决方法：

  1. 检查 [params.floatMusicPlayer] 配置，确保 enabled = true
  2. 在桌面端浏览器查看（移动端不显示）
  3. 检查 data/music-planet.yaml 文件是否存在且格式正确
  4. 检查选择的数据源是否存在（section标题、索引、items等）

Q2: 播放器位置如何重置？

播放器位置保存在localStorage中，可以通过以下方式重置：

  1. 浏览器开发者工具：

    • 打开开发者工具（F12）
    • 进入 Application > Local Storage
    • 删除 musicFloatPlayerPosition 键
    • 刷新页面

  2. 清除浏览器缓存：

    • 清除浏览器缓存和localStorage
    • 刷新页面

Q3: 如何禁用自动播放？

在配置中设置：

[params.floatMusicPlayer]
  enabled = true
  autoplay = false  # 禁用自动播放

Q4: 如何切换播放的音乐列表？

修改配置中的 sectionTitle、sectionTitles、sectionIndexes 或 items：

[params.floatMusicPlayer]
  enabled = true
  sectionTitle = "新的歌单标题"  # 修改为新的section标题

然后重新构建站点。

Q5: 播放器关闭后如何重新打开？

播放器关闭后，需要：

  1. 刷新页面：刷新浏览器页面，播放器会重新出现
  2. 重新配置：如果播放器被永久关闭，检查配置并重新构建站点

Q6: 缩小后无法交互怎么办？

这是正常行为。缩小后：

  • 播放器内容不可交互（鼠标透过）
  • 但控制按钮和拖拽手柄仍可交互
  • 点击缩小按钮可以恢复

Q7: 支持哪些音乐平台？

支持以下音乐平台：

  • netease：网易云音乐
  • tencent：QQ音乐
  • kugou：酷狗音乐
  • xiami：虾米音乐
  • baidu：百度音乐

Q8: 如何配置MetingJS API？

如果使用自定义MetingJS API，在 hugo.toml 中配置：

[params.music]
  metingApi = "https://your-meting-api.com"  # MetingJS API地址

悬浮播放器会自动使用该API。

🎨 样式定制

悬浮播放器使用主题默认样式，自动适配明暗主题。如需自定义样式，可以通过以下方式：

  1. CSS覆盖：在自定义CSS文件中覆盖 .music-player-float 相关样式
  2. 主题修改：直接修改主题的CSS文件（不推荐，更新主题时会丢失）

📱 响应式设计

悬浮播放器在以下情况下自动隐藏：

  • 📱 窄屏设备：屏幕宽度 ≤ 768px（移动端、平板）
  • 🖥️ 桌面端：屏幕宽度 > 768px 时显示

这是为了确保移动端用户体验，避免播放器遮挡内容。

🔄 PJAX兼容

悬浮播放器完全支持PJAX（无刷新页面切换）：

  • ✅ 页面切换时播放器状态保持
  • ✅ 位置和缩小状态自动保存
  • ✅ 音乐播放状态保持（如果启用）

💡 最佳实践

  1. 选择合适的数据源：

    • 推荐使用方式3（精确匹配section标题），最清晰明确
    • 避免使用索引，因为section顺序可能变化

  2. 合理设置播放器选项：

    • 建议设置 autoplay = false，避免自动播放打扰用户
    • 合理设置音量，避免过大或过小

  3. 移动端考虑：

    • 播放器在移动端自动隐藏，这是正常行为
    • 如需移动端音乐播放，使用侧栏音乐组件

  4. 数据源管理：

    • 统一在 data/music-planet.yaml 中管理音乐数据
    • 便于维护和更新

📚 相关文档

🎉 总结

悬浮音乐播放器是 Demius 主题的一个强大且灵活的功能，通过独立的配置和数据源，您可以轻松地为网站添加一个精美的桌面音乐播放器。无论是播放网易云音乐、QQ音乐还是其他平台的音乐，都能完美支持。

希望本文档能帮助您更好地使用悬浮播放器功能。如有问题，请参考常见问题部分或查看相关文档。