LyricPlayerBase

Defined in: packages/core/src/lyric-player/base/index.ts:79

歌词播放器的基类，已经包含了有关歌词操作和排版的功能， 子类需要为其实现对应的显示展示操作

Extends

• EventTarget

Extended by

• DomLyricPlayer

Implements

• HasElement
• Disposable

Constructors

Constructor

new LyricPlayerBase(element?): LyricPlayerBase;

Defined in: packages/core/src/lyric-player/base/index.ts:272

Parameters

Parameter	Type
element?	HTMLElement

Returns

LyricPlayerBase

Overrides

EventTarget.constructor

Properties

Property	Modifier	Type	Default value	Description	Defined in
alwaysPostpositionBackground	protected	boolean	false	是否强制让背景人声行始终后置（即始终在主歌词下方显示，不前置背景人声）	packages/core/src/lyric-player/base/index.ts:173
bottomLine	protected	BottomLine	undefined	-	packages/core/src/lyric-player/base/index.ts:140
currentLyricGroups	public	LyricLineGroupBase<LyricLineBase>[]	[]	-	packages/core/src/lyric-player/base/index.ts:154
dataManager	protected	LyricDataManager	undefined	-	packages/core/src/lyric-player/base/index.ts:99
disableSpring	protected	boolean	false	-	packages/core/src/lyric-player/base/index.ts:97
element	protected	HTMLElement	undefined	-	packages/core/src/lyric-player/base/index.ts:83
enableAutoSeekDetection	protected	boolean	true	-	packages/core/src/lyric-player/base/index.ts:89
enableBlur	protected	boolean	true	-	packages/core/src/lyric-player/base/index.ts:141
enableScale	protected	boolean	true	-	packages/core/src/lyric-player/base/index.ts:142
hidePassedLines	protected	boolean	false	-	packages/core/src/lyric-player/base/index.ts:143
interludeDots	protected	InterludeDots	undefined	-	packages/core/src/lyric-player/base/index.ts:139
isPageVisible	protected	boolean	true	-	packages/core/src/lyric-player/base/index.ts:157
isPlaying	protected	boolean	false	-	packages/core/src/lyric-player/base/index.ts:86
layoutCalculator	protected	LayoutCalculator	undefined	-	packages/core/src/lyric-player/base/index.ts:151
layoutConfig	protected	LayoutConfig	undefined	-	packages/core/src/lyric-player/base/index.ts:113
layoutState	protected	PlayerLayoutState	undefined	-	packages/core/src/lyric-player/base/index.ts:110
lyricGroupElementMap	public	WeakMap<Element, LyricLineGroupBase<LyricLineBase>>	undefined	Internal	packages/core/src/lyric-player/base/index.ts:95
lyricGroupSize	public	WeakMap<LyricLineGroupBase<LyricLineBase>, [number, number]>	undefined	-	packages/core/src/lyric-player/base/index.ts:155
lyricLinesIndexes	protected	WeakMap<LyricLineBase, number>	undefined	-	packages/core/src/lyric-player/base/index.ts:96
posXSpringParams	protected	Partial<SpringParams>	undefined	-	packages/core/src/lyric-player/base/index.ts:175
posYSpringParams	protected	Partial<SpringParams>	undefined	-	packages/core/src/lyric-player/base/index.ts:180
resizeObserver	public	ResizeObserver	undefined	Internal	packages/core/src/lyric-player/base/index.ts:204
scaleForBGSpringParams	protected	Partial<SpringParams>	undefined	-	packages/core/src/lyric-player/base/index.ts:190
scaleSpringParams	protected	Partial<SpringParams>	undefined	-	packages/core/src/lyric-player/base/index.ts:185
scrollEngine	protected	ScrollInteractionEngine	undefined	-	packages/core/src/lyric-player/base/index.ts:145
scrollState	protected	PlayerScrollState	undefined	-	packages/core/src/lyric-player/base/index.ts:146
seekDetector	protected	SeekDetector	undefined	-	packages/core/src/lyric-player/base/index.ts:88
size	readonly	[number, number]	undefined	-	packages/core/src/lyric-player/base/index.ts:156
timelineController	protected	TimelineController	undefined	-	packages/core/src/lyric-player/base/index.ts:87
wordFadeWidth	protected	number	0.5	-	packages/core/src/lyric-player/base/index.ts:270

Accessors

baseFontSize

Get Signature

get abstract baseFontSize(): number;

Defined in: packages/core/src/lyric-player/base/index.ts:84

Returns

number

---

defaultLineHeight

Get Signature

get defaultLineHeight(): number;

Defined in: packages/core/src/lyric-player/base/index.ts:160

默认/回退单行歌词估算高度基准 (containerHeight / 5)

Returns

number

---

hasDuetLine

Get Signature

get protected hasDuetLine(): boolean;

Defined in: packages/core/src/lyric-player/base/index.ts:106

Returns

boolean

---

isNonDynamic

Get Signature

get protected isNonDynamic(): boolean;

Defined in: packages/core/src/lyric-player/base/index.ts:103

Returns

boolean

---

processedLines

Get Signature

get protected processedLines(): readonly LyricLine[];

Defined in: packages/core/src/lyric-player/base/index.ts:100

Returns

readonly LyricLine[]

Methods

addEventListener()

addEventListener(
   type,
   callback,
   options?): void;

Defined in: node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.dom.d.ts:14380

The addEventListener() method of the EventTarget interface sets up a function that will be called whenever the specified event is delivered to the target.

MDN Reference

Parameters

Parameter	Type
type	string
callback	EventListenerOrEventListenerObject | null
options?	boolean | AddEventListenerOptions

Returns

void

Inherited from

EventTarget.addEventListener

---

buildLyricGroups()

abstract protected buildLyricGroups(): void;

Defined in: packages/core/src/lyric-player/base/index.ts:714

由子类实现的歌词组构建逻辑

Returns

void

---

calcLayout()

calcLayout(reason): void;

Defined in: packages/core/src/lyric-player/base/index.ts:842

Internal

重新计算歌词行的几何排版坐标与视觉状态

此方法不会触发 DOM 强制重排

计算完成后，在每一帧调用 update() / commitChanges() 即可让歌词平滑移动至目标位置

仅供内部和绑定包使用

Parameters

Parameter	Type	Description
reason	LayoutReason	触发排版布局更新的原因场景

Returns

void

---

createBottomLine()

abstract protected createBottomLine(): BottomLine;

Defined in: packages/core/src/lyric-player/base/index.ts:734

由子类实现的底栏组件创建逻辑

在基类构造函数中调用，子类需要返回对应渲染实现的实例

Returns

BottomLine

Remarks

工厂执行时子类字段尚未初始化，实现内不得读取子类实例状态， 所需资源应由返回的组件自行创建或延迟获取

---

createInterludeDots()

abstract protected createInterludeDots(): InterludeDots;

Defined in: packages/core/src/lyric-player/base/index.ts:724

由子类实现的间奏点组件创建逻辑

在基类构造函数中调用，子类需要返回对应渲染实现的实例

Returns

InterludeDots

Remarks

工厂执行时子类字段尚未初始化，实现内不得读取子类实例状态， 所需资源应由返回的组件自行创建或延迟获取

---

dispatchEvent()

dispatchEvent(event): boolean;

Defined in: node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.dom.d.ts:14386

The dispatchEvent() method of the EventTarget sends an Event to the object, (synchronously) invoking the affected event listeners in the appropriate order. The normal event processing rules (including the capturing and optional bubbling phase) also apply to events dispatched manually with dispatchEvent().

MDN Reference

Parameters

Parameter	Type
event	Event

Returns

boolean

Inherited from

EventTarget.dispatchEvent

---

dispose()

dispose(): void;

Defined in: packages/core/src/lyric-player/base/index.ts:1200

销毁实现了该接口的对象实例，释放占用的资源

一般情况下，调用本函数后就不可以再调用对象的任何函数了

Returns

void

Implementation of

Disposable.dispose

---

getAlwaysPostpositionBackground()

getAlwaysPostpositionBackground(): boolean;

Defined in: packages/core/src/lyric-player/base/index.ts:1193

获取当前是否设置了让背景人声行始终后置显示

Returns

boolean

---

getBottomLineElement()

getBottomLineElement(): HTMLElement;

Defined in: packages/core/src/lyric-player/base/index.ts:1138

获取一个特殊的底栏元素，默认是空白的，可以往内部添加任意元素

这个元素始终在歌词的底部，可以用于显示歌曲创作者等信息

但是请勿删除该元素，只能在内部存放元素

Returns

HTMLElement

一个元素，可以往内部添加任意元素

---

getCurrentTime()

getCurrentTime(): number;

Defined in: packages/core/src/lyric-player/base/index.ts:1168

获取当前歌词的播放位置

一般和最后调用 setCurrentTime 给予的参数一样

Returns

number

当前播放位置

---

getElement()

getElement(): HTMLElement;

Defined in: packages/core/src/lyric-player/base/index.ts:1197

获取这个类所对应的 HTML 元素实例

Returns

HTMLElement

Implementation of

HasElement.getElement

---

getEnableAutoSeekDetection()

getEnableAutoSeekDetection(): boolean;

Defined in: packages/core/src/lyric-player/base/index.ts:427

获取当前是否启用了跳转状态的自动推导

Returns

boolean

是否启用自动推导

---

getEnableScale()

getEnableScale(): boolean;

Defined in: packages/core/src/lyric-player/base/index.ts:363

获取当前是否启用了歌词行缩放效果

Returns

boolean

是否启用歌词行缩放效果

---

getEnableSpring()

getEnableSpring(): boolean;

Defined in: packages/core/src/lyric-player/base/index.ts:593

获取当前是否启用了物理弹簧

Returns

boolean

是否启用物理弹簧

---

getIsPlaying()

getIsPlaying(): boolean;

Defined in: packages/core/src/lyric-player/base/index.ts:617

获取当前是否在播放

Returns

boolean

当前是否在播放

---

getLineHeight()

getLineHeight(index): number;

Defined in: packages/core/src/lyric-player/base/index.ts:168

获取指定索引歌词行的高度

Parameters

Parameter	Type
index	number

Returns

number

Remarks

可能为测量值或估算值

---

getLyricLines()

getLyricLines(): readonly LyricLine[];

Defined in: packages/core/src/lyric-player/base/index.ts:1159

获取当前播放的、未经过优化和掩码处理的歌词数组

一般和最后调用 setLyricLines 给予的参数一样

Returns

readonly LyricLine[]

当前歌词数组

---

getOverscanPx()

getOverscanPx(): number;

Defined in: packages/core/src/lyric-player/base/index.ts:570

获取当前 overscan 像素距离

Returns

number

---

getWordFadeWidth()

getWordFadeWidth(): number;

Defined in: packages/core/src/lyric-player/base/index.ts:371

获取当前文字动画的渐变宽度，单位以歌词行的主文字字体大小的倍数为单位

Returns

number

当前文字动画的渐变宽度，单位以歌词行的主文字字体大小的倍数为单位

---

onResize()

protected onResize(): void;

Defined in: packages/core/src/lyric-player/base/index.ts:1127

Returns

void

---

pause()

pause(): void;

Defined in: packages/core/src/lyric-player/base/index.ts:1097

暂停部分效果演出，目前会暂停播放间奏点的动画，且将背景歌词显示出来

Returns

void

---

rebuildLyricLines()

rebuildLyricLines(): void;

Defined in: packages/core/src/lyric-player/base/index.ts:537

Returns

void

---

rebuildLyricView()

rebuildLyricView(initialTime?): void;

Defined in: packages/core/src/lyric-player/base/index.ts:744

重新构建歌词行和时间状态

一般用于在调用 setLyricProcessConfig 更新配置后手动刷新视图， 或在外部样式/DOM 结构发生改变后重置歌词视图

Parameters

Parameter	Type	Description
initialTime	number	重建后对齐的初始时间（毫秒），默认使用当前播放进度

Returns

void

---

removeEventListener()

removeEventListener(
   type,
   callback,
   options?): void;

Defined in: node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.dom.d.ts:14392

The removeEventListener() method of the EventTarget interface removes an event listener previously registered with EventTarget.addEventListener() from the target. The event listener to be removed is identified using a combination of the event type, the event listener function itself, and various optional options that may affect the matching process; see Matching event listeners for removal.

MDN Reference

Parameters

Parameter	Type
type	string
callback	EventListenerOrEventListenerObject | null
options?	boolean | EventListenerOptions

Returns

void

Inherited from

EventTarget.removeEventListener

---

resetScroll()

resetScroll(): void;

Defined in: packages/core/src/lyric-player/base/index.ts:1148

重置用户滚动状态并恢复自动对齐

一个典型的使用场景是在用户滚动完毕、但歌词未自动归位时立刻归位

Returns

void

---

resume()

resume(): void;

Defined in: packages/core/src/lyric-player/base/index.ts:1107

恢复部分效果演出，目前会恢复播放间奏点的动画

Returns

void

---

setAlignAnchor()

setAlignAnchor(alignAnchor): void;

Defined in: packages/core/src/lyric-player/base/index.ts:551

设置目标歌词行的对齐方式，默认为 center

• 设置成 top 的话将会向目标歌词行的顶部对齐
• 设置成 bottom 的话将会向目标歌词行的底部对齐
• 设置成 center 的话将会向目标歌词行的垂直中心对齐

Parameters

Parameter	Type	Description
alignAnchor	LayoutAlignAnchor	歌词行对齐方式，详情见函数说明

Returns

void

---

setAlignPosition()

setAlignPosition(alignPosition): void;

Defined in: packages/core/src/lyric-player/base/index.ts:558

设置默认的歌词行对齐位置，相对于整个歌词播放组件的大小位置，默认为 0.5

Parameters

Parameter	Type	Description
alignPosition	number	一个 [0.0-1.0] 之间的任意数字，代表组件高度由上到下的比例位置

Returns

void

---

setAlwaysPostpositionBackground()

setAlwaysPostpositionBackground(enable): void;

Defined in: packages/core/src/lyric-player/base/index.ts:1181

设置是否让背景人声行始终后置显示

默认情况下，如果背景歌词开始时间早于主歌词，会在主歌词上方展示； 如果设置为 true，则无论时间顺序如何，背景歌词都会始终在主歌词下方展示

Parameters

Parameter	Type	Description
enable	boolean	是否启用始终后置

Returns

void

---

setCurrentTime()

setCurrentTime(time, isSeek?): void;

Defined in: packages/core/src/lyric-player/base/index.ts:636

设置当前播放进度，此时将会更新内部的歌词进度信息。

内部会根据调用间隔和播放进度自动决定应如何滚动和显示歌词，所以此方法的调用频率越快越准确越好。 调用频率较低或进度细度过粗可能会导致歌词显示延迟或导致自动跳转推导错误。 调用完成后，应每帧调用 update 方法来执行歌词动画效果。此函数本身不会触发动画效果。

当 isSeek 为 true 时，将强制按跳转处理，并在下次调用 update 时触发一系列的行为变更， 具体请参考 https://amll.dev/guides/component/seeking，因此请只在真正跳转时设为 true

Parameters

Parameter	Type	Default value	Description
time	number	undefined	当前播放进度，单位为毫秒，非有限值会被静默忽略
isSeek	boolean	false	是否强制按跳转处理，默认交由内部推导

Returns

void

See

• setEnableAutoSeekDetection 自动推导跳转状态的文档
• https://amll.dev/guides/component/sequence#播放进度

---

setEnableAutoSeekDetection()

setEnableAutoSeekDetection(enable?): void;

Defined in: packages/core/src/lyric-player/base/index.ts:417

设置是否自动推导跳转状态，默认启用

启用后，即使调用 setCurrentTime 时没有传入 isSeek， 内部也会在进度前进时比较它的实际推进量与应有的推进量，超量前进即视为跳转

应有的推进量取决于当前的播放状态，因此请按 pause 与 resume 的文档正确同步播放状态：

• 播放时以物理时钟的推进量为准，容差随之按比例放宽，以容纳倍速播放与不均匀的推送节奏
• 暂停时进度本不该前进，应有的推进量是零，因此任何超出抖动幅度的前进都会被视为跳转

这意味着进度信息的粒度粗于推送间隔时，绝大多数推送都会被视为跳转， 此时应当改善进度来源的精度，或在进度未发生变化时跳过推送

较小的向前跳转可能无法被识别，但一般影响不大

此开关只控制上述超量前进的判定。进度倒退与停滞不受它控制，无论是否启用推导都会 被视为跳转：正常播放不会让进度停滞不前，因此重复推送同一个时间表达的是把逐字遮罩 这类自行推进的动画拉回到该时间的意图

推导只会额外识别出跳转，不会否决已显式传入的跳转标志，因此如果你已经在正确传入 跳转标志了，则一般无需关心此开关。若你的进度来源精度很差而导致超量前进被频繁误判， 可以选择关闭

Parameters

Parameter	Type	Default value	Description
enable	boolean	true	是否启用自动推导

Returns

void

---

setEnableBlur()

setEnableBlur(enable): void;

Defined in: packages/core/src/lyric-player/base/index.ts:443

设置是否启用歌词行的模糊效果

Parameters

Parameter	Type	Description
enable	boolean	是否启用

Returns

void

---

setEnableScale()

setEnableScale(enable?): void;

Defined in: packages/core/src/lyric-player/base/index.ts:355

是否启用歌词行缩放效果，默认启用

如果启用，非选中的歌词行会轻微缩小以凸显当前播放歌词行效果

此效果对性能影响微乎其微，推荐启用

Parameters

Parameter	Type	Default value	Description
enable	boolean	true	是否启用歌词行缩放效果

Returns

void

---

setEnableSpring()

setEnableSpring(enable?): void;

Defined in: packages/core/src/lyric-player/base/index.ts:580

设置是否使用物理弹簧算法实现歌词动画效果，默认启用

如果启用，则会通过弹簧算法实时处理歌词位置，但是需要性能足够强劲的电脑方可流畅运行

如果不启用，则会回退到基于 transition 的过渡效果，对低性能的机器比较友好，但是效果会比较单一

Parameters

Parameter	Type	Default value
enable	boolean	true

Returns

void

---

setHidePassedLines()

setHidePassedLines(hide): void;

Defined in: packages/core/src/lyric-player/base/index.ts:435

设置是否隐藏已经播放过的歌词行，默认不隐藏

Parameters

Parameter	Type	Description
hide	boolean	是否隐藏已经播放过的歌词行，默认不隐藏

Returns

void

---

setIsSeeking()

setIsSeeking(_isSeeking): void;

Defined in: packages/core/src/lyric-player/base/index.ts:389

设置持续性的跳转状态

Parameters

Parameter	Type
_isSeeking	boolean

Returns

void

Deprecated

此方法已无实际作用，调用它不会产生任何效果，仅为兼容保留，将在未来移除

跳转状态现在由每次进度推送逐帧推导，不再存在需要外部显式解除的持续状态

跳转会通过以下三条途径被识别，三者同时生效：

• setCurrentTime 的 isSeek 参数，由调用方明确告知某次进度变化是跳转
• 进度倒退或停滞，由内部无条件识别，不受任何开关控制
• 自动推导，由内部比对进度的实际推进量与它应有的推进量识别超量前进，默认启用， 可通过 setEnableAutoSeekDetection 关闭

---

setLinePosXSpringParams()

setLinePosXSpringParams(_params?): void;

Defined in: packages/core/src/lyric-player/base/index.ts:1055

设置所有歌词行在横坐标上的弹簧属性，包括重量、弹力和阻力。

Parameters

Parameter	Type
_params	Partial<SpringParams>

Returns

void

Deprecated

考虑到横向弹簧效果并不常见，所以这个函数将会在未来的版本中移除

---

setLinePosYSpringParams()

setLinePosYSpringParams(params?): void;

Defined in: packages/core/src/lyric-player/base/index.ts:1061

设置所有歌词行在​纵坐标上的弹簧属性，包括重量、弹力和阻力。

Parameters

Parameter	Type	Description
params	Partial<SpringParams>	需要设置的弹簧属性，提供的属性将会覆盖原来的属性，未提供的属性将会保持原样

Returns

void

---

setLineScaleSpringParams()

setLineScaleSpringParams(params?): void;

Defined in: packages/core/src/lyric-player/base/index.ts:1077

设置所有歌词行在​缩放大小上的弹簧属性，包括重量、弹力和阻力。

Parameters

Parameter	Type	Description
params	Partial<SpringParams>	需要设置的弹簧属性，提供的属性将会覆盖原来的属性，未提供的属性将会保持原样

Returns

void

---

setLyricLines()

setLyricLines(lines, initialTime?): void;

Defined in: packages/core/src/lyric-player/base/index.ts:604

设置当前播放歌词，要注意传入后这个数组内的信息不得修改，否则会发生错误

Parameters

Parameter	Type	Default value	Description
lines	LyricLine[]	undefined	歌词数组
initialTime	number	0	初始时间，默认为 0

Returns

void

Throws

歌词时间戳不是有限的非负数字

Throws

任一行、单词或注音的开始时间晚于结束时间

---

setLyricProcessConfig()

setLyricProcessConfig(config): void;

Defined in: packages/core/src/lyric-player/base/index.ts:458

批量更新歌词处理配置，包括优化和掩码设置

Parameters

Parameter	Type	Description
config	LyricDataConfig	需要更新的配置集合

Returns

void

Remarks

此方法不会自动重建歌词行和刷新视图， 适用于在渲染前预设配置、批量初始化，或需要手动控制 DOM 刷新时机的场景

See

LyricDataConfig

---

setMaskObsceneWordChar()

setMaskObsceneWordChar(char): void;

Defined in: packages/core/src/lyric-player/base/index.ts:519

设置不雅用语掩码使用的字符，默认为 *

Parameters

Parameter	Type	Description
char	string	单个字符，用于替换不雅用语中的字符

Returns

void

Remarks

在设置完成后会自动重建歌词行和刷新视图

---

setMaskObsceneWords()

setMaskObsceneWords(mode): void;

Defined in: packages/core/src/lyric-player/base/index.ts:510

设置歌词中不雅用语的掩码模式

Parameters

Parameter	Type	Description
mode	MaskObsceneWordsMode	掩码模式

Returns

void

Remarks

在设置完成后会自动重建歌词行和刷新视图

See

MaskObsceneWordsMode

---

setOptimizeOptions()

setOptimizeOptions(options): void;

Defined in: packages/core/src/lyric-player/base/index.ts:530

设置歌词的优化配置项，这些配置项默认全部开启

Parameters

Parameter	Type	Description
options	OptimizeLyricOptions	优化配置选项

Returns

void

Remarks

在设置完成后会自动重建歌词行和刷新视图

See

OptimizeLyricOptions

---

setOverscanPx()

setOverscanPx(px): void;

Defined in: packages/core/src/lyric-player/base/index.ts:566

设置 overscan（视图上下额外缓冲渲染区）距离，单位：像素。

Parameters

Parameter	Type	Description
px	number	像素值，默认 300

Returns

void

---

setWordFadeWidth()

setWordFadeWidth(value?): void;

Defined in: packages/core/src/lyric-player/base/index.ts:343

设置文字动画的渐变宽度，单位以歌词行的主文字字体大小的倍数为单位，默认为 0.5，即一个全角字符的一半宽度

如果要模拟 Apple Music for Android 的效果，可以设置为 1

如果要模拟 Apple Music for iPad 的效果，可以设置为 0.5

如果想要近乎禁用渐变效果，可以设置成非常接近 0 的小数（例如 0.0001 ），但是不可以为 0

Parameters

Parameter	Type	Default value	Description
value	number	0.5	需要设置的渐变宽度，单位以歌词行的主文字字体大小的倍数为单位，默认为 0.5

Returns

void

---

update()

update(delta?): void;

Defined in: packages/core/src/lyric-player/base/index.ts:1121

更新动画，这个函数应该被逐帧调用或者在以下情况下调用一次：

1. 刚刚调用完设置歌词函数的时候

Parameters

Parameter	Type	Default value	Description
delta	number	0	距离上一次被调用到现在的时长，单位为毫秒（可为浮点数）

Returns

void

---

updateLyricProcessConfig()

updateLyricProcessConfig(config): void;

Defined in: packages/core/src/lyric-player/base/index.ts:470

批量更新歌词处理配置，包括优化和掩码设置

可以调用此方法以避免多次单独设置处理配置导致的多次刷新开销

Parameters

Parameter	Type	Description
config	LyricDataConfig	需要更新的配置集合

Returns

void

Remarks

在设置完成后会自动重建歌词行和刷新视图

See

LyricDataConfig