APlayer 歌词显示控制 API

ap.lrc 是什么

ap.lrc 是 APlayer 实例上专门管理歌词显示的命名空间。它只有三个方法，全部用来控制歌词区域的显隐。

三个方法

lrc.show()

强制显示歌词区域。

ap.lrc.show();

lrc.hide()

强制隐藏歌词区域。

ap.lrc.hide();

lrc.toggle()

切换歌词区域的显示 / 隐藏状态。

ap.lrc.toggle();

与歌词传递方式的关系

无论你用哪种方式传递歌词（LRC 文件 / JS 字符串 / HTML 内嵌），这三个方法都能正常工作。

但有一个前提：必须先配置了歌词。如果所有歌曲都没有配置 LRC 歌词，lrc.show() 什么都不会显示。

事件

歌词显隐切换时会触发事件：

ap.on('lrcshow', function() {
    console.log('歌词已显示');
});

ap.on('lrchide', function() {
    console.log('歌词已隐藏');
});

实际用途

自定义歌词开关按钮

// 页面上放一个切换按钮
const lrcBtn = document.getElementById('lrc-toggle');

lrcBtn.addEventListener('click', function() {
    ap.lrc.toggle();
});

// 同步按钮文字
ap.on('lrcshow', () => lrcBtn.textContent = '隐藏歌词');
ap.on('lrchide', () => lrcBtn.textContent = '显示歌词');

根据屏幕条件自动隐藏歌词

// 窗口宽度小于 600px 时自动隐藏歌词，给列表腾出空间
function responsiveLrc() {
    if (window.innerWidth < 600) {
        ap.lrc.hide();
    } else {
        ap.lrc.show();
    }
}

window.addEventListener('resize', responsiveLrc);
responsiveLrc();  // 初始调用一次

歌词滚动原理

虽然 API 层面只有显隐控制，但 APlayer 内部会自动处理歌词的实时滚动：

• 每播放一帧，检查当前播放时间
• 找到最接近当前时间戳的那一行歌词
• 将该行高亮，并自动把歌词容器滚动到该行可见

你不需要写任何代码来处理歌词滚动——APlayer 自动完成。

常见问题：歌词不显示

如果调用了 ap.lrc.show() 但歌词区域仍然空白，检查以下几点：

1. lrcType 是否正确设置：必须是 1（JS 字符串）、2（HTML 内嵌）或 3（文件方式）之一
2. audio.lrc 是否有值：每首有歌词的歌曲必须在对应的 audio 对象里配置 lrc 字段（文件方式是 URL，JS 字符串方式是 LRC 文本）
3. LRC 格式是否正确：检查 歌词格式规范
4. 控制台有没有错误：如果是文件方式，检查网络请求是否成功（404？CORS 错误？）