[NMP v2] NeteaseMiniPlayer v2 使用文档

主题

配置参考 ​

NeteaseMiniPlayer 通过 HTML data-* 属性提供灵活的配置选项。本页面详细介绍每个配置属性的功能、默认值和使用示例。

🎵 基础配置 ​

data-playlist-id ​

功能描述：指定要播放的网易云音乐歌单ID

默认值：无

类型：string

使用示例：

html
<div class="netease-mini-player" data-playlist-id="14273792576"></div>

获取方法：

  1. 打开网易云音乐网页版
  2. 进入目标歌单页面
  3. 从URL中获取ID：https://music.163.com/#/playlist?id=14273792576

特别说明：

  • 与 data-song-id 互斥，优先级更高
  • 支持公开歌单和个人收藏歌单
  • 建议使用热门歌单以确保歌曲可用性

data-song-id ​

功能描述：指定要播放的单首歌曲ID

默认值：无

类型：string

使用示例：

html
<div class="netease-mini-player" data-song-id="1347230324"></div>

获取方法：

  1. 打开网易云音乐网页版
  2. 进入目标歌曲页面
  3. 从URL中获取ID：https://music.163.com/#/song?id=1347230324

特别说明：

  • 适用于只需要播放单首歌曲的场景
  • 如果同时设置了 data-playlist-id，此属性将被忽略

🎨 显示配置 ​

data-embed ​

功能描述：启用嵌入模式，播放器将以内联方式显示

默认值：false

类型：boolean

使用示例：

html
<!-- 嵌入模式 -->
<div class="netease-mini-player" 
     data-playlist-id="14273792576"
     data-embed="true"></div>

<!-- 浮动模式（默认） -->
<div class="netease-mini-player" 
     data-playlist-id="14273792576"></div>

特别说明：

  • 嵌入模式适合文章内容中的音乐播放器
  • 浮动模式适合全站背景音乐
  • 嵌入模式下不支持拖拽功能

data-position ​

功能描述：设置浮动播放器的位置（仅在非嵌入模式下生效）

默认值：static

类型：string

可选值：

  • static：静态定位
  • top-left：左上角
  • top-right：右上角
  • bottom-left：左下角
  • bottom-right：右下角

使用示例：

html
<!-- 右下角浮动 -->
<div class="netease-mini-player" 
     data-playlist-id="14273792576"
     data-position="bottom-right"></div>

<!-- 左上角浮动 -->
<div class="netease-mini-player" 
     data-playlist-id="14273792576"
     data-position="top-left"></div>

特别说明：

  • 浮动定位会自动添加 position: fixed 样式
  • 在移动设备上会自动调整位置以避免遮挡内容
  • 无效值会自动回退到 static

data-size ​

功能描述：设置播放器的尺寸大小

默认值：compact

类型：string

可选值：

  • compact：紧凑模式（推荐）
  • normal：标准模式
  • large：大尺寸模式

使用示例：

html
<!-- 紧凑模式 -->
<div class="netease-mini-player" 
     data-playlist-id="14273792576"
     data-size="compact"></div>

<!-- 大尺寸模式 -->
<div class="netease-mini-player" 
     data-playlist-id="14273792576"
     data-size="large"></div>

特别说明：

  • 紧凑模式适合大多数使用场景
  • 大尺寸模式适合专门的音乐页面
  • 尺寸会影响专辑封面、按钮和文字大小

🎼 播放配置 ​

data-autoplay ​

功能描述：页面加载完成后自动开始播放

默认值：false

类型：boolean

使用示例：

html
<!-- 自动播放 -->
<div class="netease-mini-player" 
     data-playlist-id="14273792576"
     data-autoplay="true"></div>

特别说明：

  • 受浏览器自动播放策略限制，可能需要用户交互后才能生效
  • Chrome、Safari 等浏览器默认禁止自动播放音频
  • 建议在用户明确期望音乐播放的页面使用

data-loop ​

功能描述：设置播放循环模式

默认值：list

类型：string

可选值：

  • list：列表循环
  • single：单曲循环
  • random：随机播放

使用示例：

html
<!-- 单曲循环 -->
<div class="netease-mini-player" 
     data-playlist-id="14273792576"
     data-loop="single"></div>

<!-- 随机播放 -->
<div class="netease-mini-player" 
     data-playlist-id="14273792576"
     data-loop="random"></div>

特别说明：

  • 列表循环：播放完最后一首后回到第一首
  • 单曲循环：重复播放当前歌曲
  • 随机播放：随机选择下一首歌曲

🎨 主题配置 ​

data-theme ​

功能描述：设置播放器主题模式

默认值：auto

类型：string

可选值：

  • auto：自动检测
  • light：浅色主题
  • dark：深色主题

使用示例：

html
<!-- 自动主题 -->
<div class="netease-mini-player" 
     data-playlist-id="14273792576"
     data-theme="auto"></div>

<!-- 强制深色主题 -->
<div class="netease-mini-player" 
     data-playlist-id="14273792576"
     data-theme="dark"></div>

自动检测逻辑：

  1. 检测页面 CSS 变量（--bg-color, --text-color）
  2. 检测系统主题偏好（prefers-color-scheme）
  3. 分析页面背景色
  4. 默认使用浅色主题

特别说明：

  • 自动模式会实时响应系统主题变化
  • 手动设置的主题优先级最高
  • 主题切换有平滑的过渡动画

📝 功能配置 ​

data-lyric ​

功能描述：控制歌词显示功能

默认值：true

类型：boolean

使用示例：

html
<!-- 禁用歌词 -->
<div class="netease-mini-player" 
     data-playlist-id="14273792576"
     data-lyric="false"></div>

<!-- 启用歌词（默认） -->
<div class="netease-mini-player" 
     data-playlist-id="14273792576"></div>

特别说明：

  • 禁用后不会加载歌词数据，可以提升性能
  • 适用于纯背景音乐场景
  • 歌词支持中文翻译和滚动显示

📱 高级配置 ​

响应式配置 ​

播放器会自动适配不同屏幕尺寸，但你可以通过 CSS 变量进行自定义：

css
.netease-mini-player {
  --player-width: 320px;
  --player-height: 80px;
  --border-radius: 12px;
  --shadow-color: rgba(0, 0, 0, 0.1);
}

/* 移动端适配 */
@media (max-width: 768px) {
  .netease-mini-player {
    --player-width: 280px;
    --player-height: 70px;
  }
}

自定义样式 ​

通过 CSS 类名可以进一步自定义播放器外观：

css
/* 自定义播放按钮颜色 */
.netease-mini-player .play-btn {
  background: linear-gradient(45deg, #ff6b6b, #ee5a24);
}

/* 自定义进度条颜色 */
.netease-mini-player .progress-fill {
  background: #ff6b6b;
}

/* 自定义歌词样式 */
.netease-mini-player .lyric-line {
  font-family: "Microsoft YaHei", sans-serif;
  font-weight: bold;
}

🔧 配置示例 ​

博客背景音乐 ​

html
<div class="netease-mini-player"
     data-playlist-id="14273792576"
     data-embed="false"
     data-position="bottom-left"
     data-lyric="true"
     data-theme="auto">
</div>

文章内嵌播放器 ​

html
<div class="netease-mini-player"
     data-song-id="1823012873"
     data-embed="true"
     data-position="static"
     data-lyric="true"
     data-theme="auto">
</div>

⚠️ 注意事项 ​

浏览器兼容性 ​

  • 现代浏览器：Chrome 60+, Firefox 55+, Safari 11+, Edge 79+
  • 移动浏览器：iOS Safari 11+, Chrome Mobile 60+
  • 不支持：Internet Explorer

性能建议 ​

  1. 歌单大小：建议歌单包含 50 首以内的歌曲
  2. 缓存策略：播放器会自动缓存歌曲信息 5 分钟
  3. 网络要求：需要稳定的网络连接以加载音频文件

使用限制 ​

  1. API 限制：依赖第三方 API，可能存在访问限制
  2. 版权限制：部分歌曲可能因版权问题无法播放
  3. 自动播放：受浏览器策略限制，可能需要用户交互

故障排除 ​

播放器不显示：

  • 检查 CSS 和 JS 文件是否正确加载
  • 确认容器元素存在且配置正确

无法播放音乐：

  • 检查歌单/歌曲 ID 是否正确
  • 确认网络连接正常
  • 查看浏览器控制台错误信息

主题不生效：

  • 检查 data-theme 属性值是否正确
  • 确认 CSS 文件完整加载
  • 验证页面 CSS 变量设置

Copyright © 2025 NeteaseMiniPlayer

BHCN STUDIO 所有权利保留