音频生命周期托管
基于 Howler 统一处理加载、播放、暂停、切歌和资源释放。同一页面只维护一个活跃播放器，替换前等待异步销毁完成。
Skip to content
稳定生命周期托管与记忆播放
便捷HTML · Vue · React · CDN
高性能轻量按需加载
降低页面负担
降低页面负担
快速了解
- 云端与本地歌单
- 同步歌词与记忆播放
- 多主题与 AI 创作
核心特性
跨框架快速接入
提供 Web Component 标签、IIFE、ESM、npm 和 JS 实例化方式，Vue、React、静态页面都能直接使用。
高性能渲染策略
延迟渲染、懒加载、请求取消和状态节流协同工作，减少首屏压力和高频播放状态更新开销。
主题系统可扩展
内置多套主题，同时支持随机主题、自动主题、CSS 变量和自定义主题样式，适配不同品牌视觉。
歌词体验完整
支持 LRC、结构化歌词、外链歌词、底部歌词和全屏歌词，切歌时自动处理请求竞态和滚动定位。
桌面快捷控制
支持 Tab、Space、左右方向键控制播放器，并自动避开输入框、滑块和组合键，兼容 macOS 与 Windows。
播放策略灵活
顺序播放、单曲循环、随机播放、记忆播放和自动播放都可通过属性或实例 API 精确控制。
云端与本地双模式
默认支持云端 api-url，也支持本地歌单和 audioProvider，接口异常时提供重拉歌单、跳歌和连续失败保护。
在线调试与代码生成
调试页可视化配置云端接口、本地歌单、主题、音量和播放参数，并生成可直接复制的集成代码。
适用场景
产品官网
为音乐、播客、内容产品提供可视化试听入口。
博客与作品集
在不侵入页面主体的情况下加入固定音乐播放控件。
后台和工具页
用统一 API 管理歌单、播放模式、状态记忆和主题。
FAQ
常见问题
小枫音乐播放器是什么？
小枫音乐播放器（XF Music Player）是可嵌入网站的 HTML5 音乐播放器插件，基于 Lit Web Components 与 Howler 开发。1.0.7 支持歌单、歌词、主题和记忆播放，适用于官网、博客及 Web 应用。
了解播放器能力如何接入 HTML、Vue 或 React 项目？
可通过 npm 安装或 CDN 加载发布文件，再使用 Web Component 标签或 JavaScript 实例接入。Vue、React 与静态 HTML 页面均可使用；歌单对象、audioProvider 和生命周期钩子等复杂配置需通过 JavaScript 传入。
查看接入示例播放器的歌单和音频来自哪里？
播放器使用接入方提供的歌单和音频地址。云端模式通过 apiUrl 获取歌单，本地模式使用 playlist 或 audioProvider；自定义 audioProvider 优先于内置云端请求，音频是否可访问取决于实际资源地址。
查看数据源配置支持 FLAC、WAV、AIFF 元数据是否代表一定能播放？
不是。播放器可读取 FLAC、WAV、AIFF / AIFF-C 文件中可用的音频参数、标签、封面和歌词，但元数据解析与音频解码是不同能力。能否播放取决于目标浏览器及文件编码，播放器不负责转码。
查看元数据读取说明同一页面可以创建多个播放器吗？
同一页面只保留一个活跃播放器宿主，播放状态与音频管理器共享。替换实例前先等待旧实例的 destroy() 完成，再确认当前页面仍有效并创建新实例；更换 tagName 不会获得隔离的并发播放器。
查看生命周期契约为什么开启自动播放后仍需要点击播放？
autoplay 只尝试启动播放，浏览器的用户手势策略或嵌入权限仍可能阻止它；isAutoPopup 仅控制界面展开。可在在线调试页设置接口、歌单和播放参数，点击播放验证，再生成接入代码。
打开在线调试免责声明
本站仅用于小枫音乐播放器插件展示、文档说明和功能调试。示例音频、封面、歌词或第三方接口数据仅用于演示，实际接入请自行确认资源版权、接口合规性与业务使用范围。
作者: 小枫
联系方式: 1809185784@qq.com