LyricPlayerBase

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

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

Extends

• EventTarget

Extended by

• DomLyricPlayer
• DomSlimLyricPlayer

Implements

• HasElement
• Disposable

Constructors

Constructor

new LyricPlayerBase(element?): LyricPlayerBase;

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

Parameters

Parameter	Type
element?	HTMLElement

Returns

LyricPlayerBase

Overrides

EventTarget.constructor

Properties

Property	Modifier	Type	Default value	Description	Defined in
alignAnchor	protected	"center" | "bottom" | "top"	"center"	-	packages/core/src/lyric-player/base.ts:56
alignPosition	protected	number	0.35	-	packages/core/src/lyric-player/base.ts:57
allowScroll	protected	boolean	true	-	packages/core/src/lyric-player/base.ts:60
bottomLine	protected	BottomLineEl	undefined	-	packages/core/src/lyric-player/base.ts:45
bufferedLines	protected	Set<number>	undefined	-	packages/core/src/lyric-player/base.ts:38
currentLyricLineObjects	protected	LyricLineBase[]	[]	-	packages/core/src/lyric-player/base.ts:53
currentLyricLines	protected	LyricLine[]	[]	-	packages/core/src/lyric-player/base.ts:33
currentTime	protected	number	0	-	packages/core/src/lyric-player/base.ts:28
disableSpring	protected	boolean	false	-	packages/core/src/lyric-player/base.ts:42
element	protected	HTMLElement	undefined	-	packages/core/src/lyric-player/base.ts:25
enableBlur	protected	boolean	true	-	packages/core/src/lyric-player/base.ts:46
enableScale	protected	boolean	true	-	packages/core/src/lyric-player/base.ts:47
hasDuetLine	protected	boolean	false	-	packages/core/src/lyric-player/base.ts:40
hidePassedLines	protected	boolean	false	-	packages/core/src/lyric-player/base.ts:51
hotLines	protected	Set<number>	undefined	-	packages/core/src/lyric-player/base.ts:37
initialLayoutFinished	protected	boolean	false	-	packages/core/src/lyric-player/base.ts:64
interludeDots	protected	InterludeDots	undefined	-	packages/core/src/lyric-player/base.ts:44
interludeDotsSize	protected	[number, number]	undefined	-	packages/core/src/lyric-player/base.ts:43
isNonDynamic	protected	boolean	false	-	packages/core/src/lyric-player/base.ts:39
isPageVisible	protected	boolean	true	-	packages/core/src/lyric-player/base.ts:61
isPlaying	protected	boolean	true	-	packages/core/src/lyric-player/base.ts:1107
isScrolled	protected	boolean	false	-	packages/core/src/lyric-player/base.ts:106
isSeeking	protected	boolean	false	-	packages/core/src/lyric-player/base.ts:54
isUserScrolling	protected	boolean	false	标记用户是否正在进行滚动交互	packages/core/src/lyric-player/base.ts:69
lastCurrentTime	protected	number	0	-	packages/core/src/lyric-player/base.ts:55
lastInterludeState	protected	boolean	false	-	packages/core/src/lyric-player/base.ts:160
lyricLineElementMap	public	WeakMap<Element, LyricLineBase>	undefined	Internal	packages/core/src/lyric-player/base.ts:32
lyricLinesIndexes	protected	WeakMap<LyricLineBase, number>	undefined	-	packages/core/src/lyric-player/base.ts:36
lyricLinesSize	public	WeakMap<LyricLineBase, [number, number]>	undefined	Internal	packages/core/src/lyric-player/base.ts:30
maskObsceneWordChar	protected	string	"*"	-	packages/core/src/lyric-player/base.ts:50
maskObsceneWords	protected	MaskObsceneWordsMode	MaskObsceneWordsMode.Disabled	-	packages/core/src/lyric-player/base.ts:48
optimizeOptions	protected	OptimizeLyricOptions	{}	-	packages/core/src/lyric-player/base.ts:62
overscanPx	protected	number	300	视图额外预渲染（overscan）距离，单位：像素。 用于决定在视口之外多少距离内也认为是“可见”，以便提前创建/保留行元素。	packages/core/src/lyric-player/base.ts:76
posXSpringParams	protected	Partial<SpringParams>	undefined	-	packages/core/src/lyric-player/base.ts:78
posYSpringParams	protected	Partial<SpringParams>	undefined	-	packages/core/src/lyric-player/base.ts:83
processedLines	protected	LyricLine[]	[]	-	packages/core/src/lyric-player/base.ts:35
resizeObserver	public	ResizeObserver	undefined	Internal	packages/core/src/lyric-player/base.ts:108
scaleForBGSpringParams	protected	Partial<SpringParams>	undefined	-	packages/core/src/lyric-player/base.ts:93
scaleSpringParams	protected	Partial<SpringParams>	undefined	-	packages/core/src/lyric-player/base.ts:88
scrollBoundary	protected	[number, number]	undefined	-	packages/core/src/lyric-player/base.ts:52
scrollOffset	protected	number	0	-	packages/core/src/lyric-player/base.ts:58
scrollToIndex	protected	number	0	-	packages/core/src/lyric-player/base.ts:41
size	readonly	[number, number]	undefined	-	packages/core/src/lyric-player/base.ts:59
targetAlignIndex	protected	number	0	-	packages/core/src/lyric-player/base.ts:159
wheelTimeout	protected	Timeout | undefined	undefined	-	packages/core/src/lyric-player/base.ts:70
wordFadeWidth	protected	number	0.5	-	packages/core/src/lyric-player/base.ts:158

Accessors

baseFontSize

Get Signature

get abstract baseFontSize(): number;

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

Returns

number

Methods

addEventListener()

Call Signature

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

Defined in: node_modules/.bun/typescript@5.9.3/node_modules/typescript/lib/lib.dom.d.ts:11569

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

Call Signature

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

Defined in: node_modules/.bun/bun-types@1.3.12/node_modules/bun-types/globals.d.ts:314

Adds a new handler for the type event. Any given listener is added only once per type and per capture option value.

If the once option is true, the listener is removed after the next time a type event is dispatched.

The capture option is not used by Node.js in any functional way other than tracking registered event listeners per the EventTarget specification. Specifically, the capture option is used as part of the key when registering a listener. Any individual listener may be added once with capture = false, and once with capture = true.

Parameters

Parameter	Type
type	string
listener	EventListener | EventListenerObject
options?	boolean | AddEventListenerOptions

Returns

void

Inherited from

EventTarget.addEventListener

---

calcLayout()

calcLayout(sync?, force?): Promise<void>;

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

重新布局定位歌词行的位置，调用完成后再逐帧调用 update 函数即可让歌词通过动画移动到目标位置。

函数有一个 force 参数，用于指定是否强制修改布局，也就是不经过动画直接调整元素位置和大小。

此函数还有一个 reflow 参数，用于指定是否需要重新计算布局

因为计算布局必定会导致浏览器重排布局，所以会大幅度影响流畅度和性能，故请只在以下情况下将其​设置为 true：

1. 歌词页面大小发生改变时（这个组件会自行处理）
2. 加载了新的歌词时（不论前后歌词是否完全一样）
3. 用户自行跳转了歌曲播放位置（不论距离远近）

Parameters

Parameter	Type	Default value	Description
sync	boolean	false	是否同步执行，通常用于初始化或 Resize 时立即布局
force	boolean	false	是否绕过弹簧效果强制更新位置

Returns

Promise<void>

---

calculateBlur()

protected calculateBlur(
   itemIndex,
   isActive,
   latestIndex): number;

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

Parameters

Parameter	Type
itemIndex	number
isActive	boolean
latestIndex	number

Returns

number

---

dispatchEvent()

Call Signature

dispatchEvent(event): boolean;

Defined in: node_modules/.bun/typescript@5.9.3/node_modules/typescript/lib/lib.dom.d.ts:11575

The dispatchEvent() method of the EventTarget sends an Event to the object, (synchronously) invoking the affected event listeners in the appropriate order.

MDN Reference

Parameters

Parameter	Type
event	Event

Returns

boolean

Inherited from

EventTarget.dispatchEvent

Call Signature

dispatchEvent(event): boolean;

Defined in: node_modules/.bun/bun-types@1.3.12/node_modules/bun-types/globals.d.ts:320

Dispatches a synthetic event event to target and returns true if either event’s cancelable attribute value is false or its preventDefault() method was not invoked, and false otherwise.

Parameters

Parameter	Type
event	Event

Returns

boolean

Inherited from

EventTarget.dispatchEvent

---

dispose()

dispose(): void;

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

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

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

Returns

void

Implementation of

Disposable.dispose

---

getBottomLineElement()

getBottomLineElement(): HTMLElement;

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

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

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

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

Returns

HTMLElement

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

---

getCurrentInterlude()

protected getCurrentInterlude(): [number, number, number, boolean] | undefined;

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

获取当前播放时间里是否处于间奏区间 如果是则会返回单位为毫秒的始末时间 否则返回 undefined

这个只允许内部调用

Returns

[number, number, number, boolean] | undefined

[开始时间,结束时间,大概处于的歌词行ID,下一句是否为对唱歌词] 或 undefined 如果不处于间奏区间

---

getCurrentTime()

getCurrentTime(): number;

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

获取当前歌词的播放位置

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

Returns

number

当前播放位置

---

getElement()

getElement(): HTMLElement;

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

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

Returns

HTMLElement

Implementation of

HasElement.getElement

---

getEnableScale()

getEnableScale(): boolean;

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

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

Returns

boolean

是否启用歌词行缩放效果

---

getEnableSpring()

getEnableSpring(): boolean;

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

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

Returns

boolean

是否启用物理弹簧

---

getIsPlaying()

getIsPlaying(): boolean;

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

获取当前是否在播放

Returns

boolean

当前是否在播放

---

getLyricLines()

getLyricLines(): LyricLine[];

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

获取当前歌词数组

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

Returns

LyricLine[]

当前歌词数组

---

getOverscanPx()

getOverscanPx(): number;

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

获取当前 overscan 像素距离

Returns

number

---

getWordFadeWidth()

getWordFadeWidth(): number;

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

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

Returns

number

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

---

onResize()

protected onResize(): void;

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

Returns

void

---

pause()

pause(): void;

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

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

Returns

void

---

processObsceneWord()

processObsceneWord(word): string;

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

Internal

根据当前配置处理不雅用语单词

Parameters

Parameter	Type	Description
word	LyricWord	单词对象

Returns

string

---

rebuildLyricLines()

rebuildLyricLines(): void;

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

Returns

void

---

removeEventListener()

Call Signature

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

Defined in: node_modules/.bun/typescript@5.9.3/node_modules/typescript/lib/lib.dom.d.ts:11581

The removeEventListener() method of the EventTarget interface removes an event listener previously registered with EventTarget.addEventListener() from the target.

MDN Reference

Parameters

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

Returns

void

Inherited from

EventTarget.removeEventListener

Call Signature

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

Defined in: node_modules/.bun/bun-types@1.3.12/node_modules/bun-types/globals.d.ts:322

Removes the event listener in target’s event listener list with the same type, callback, and options.

Parameters

Parameter	Type
type	string
listener	EventListener | EventListenerObject
options?	boolean | EventListenerOptions

Returns

void

Inherited from

EventTarget.removeEventListener

---

resetScroll()

resetScroll(): void;

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

重置用户滚动状态

请在用户完成滚动点击跳转歌词时调用本事件再调用 calcLayout 以正确滚动到目标位置

Returns

void

---

resume()

resume(): void;

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

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

Returns

void

---

setAlignAnchor()

setAlignAnchor(alignAnchor): void;

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

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

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

Parameters

Parameter	Type	Description
alignAnchor	"center" | "bottom" | "top"	歌词行对齐方式，详情见函数说明

Returns

void

---

setAlignPosition()

setAlignPosition(alignPosition): void;

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

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

Parameters

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

Returns

void

---

setCurrentTime()

setCurrentTime(time, isSeek?): void;

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

设置当前播放进度，单位为毫秒且必须是整数，此时将会更新内部的歌词进度信息 内部会根据调用间隔和播放进度自动决定如何滚动和显示歌词，所以这个的调用频率越快越准确越好

调用完成后，可以每帧调用 update 函数来执行歌词动画效果

Parameters

Parameter	Type	Default value	Description
time	number	undefined	当前播放进度，单位为毫秒
isSeek	boolean	false	-

Returns

void

---

setEnableBlur()

setEnableBlur(enable): void;

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

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

Parameters

Parameter	Type	Description
enable	boolean	是否启用

Returns

void

---

setEnableScale()

setEnableScale(enable?): void;

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

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

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

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

Parameters

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

Returns

void

---

setEnableSpring()

setEnableSpring(enable?): void;

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

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

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

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

Parameters

Parameter	Type	Default value
enable	boolean	true

Returns

void

---

setHidePassedLines()

setHidePassedLines(hide): void;

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

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

Parameters

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

Returns

void

---

setIsSeeking()

setIsSeeking(isSeeking): void;

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

Parameters

Parameter	Type
isSeeking	boolean

Returns

void

---

setLinePosXSpringParams()

setLinePosXSpringParams(_params?): void;

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

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

Parameters

Parameter	Type
_params	Partial<SpringParams>

Returns

void

Deprecated

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

---

setLinePosYSpringParams()

setLinePosYSpringParams(params?): void;

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

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

Parameters

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

Returns

void

---

setLineScaleSpringParams()

setLineScaleSpringParams(params?): void;

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

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

Parameters

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

Returns

void

---

setLyricLines()

setLyricLines(lines, initialTime?): void;

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

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

Parameters

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

Returns

void

---

setMaskObsceneWordChar()

setMaskObsceneWordChar(char): void;

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

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

Parameters

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

Returns

void

---

setMaskObsceneWords()

setMaskObsceneWords(mode): void;

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

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

Parameters

Parameter	Type	Description
mode	MaskObsceneWordsMode	掩码模式

Returns

void

See

MaskObsceneWordsMode

---

setOptimizeOptions()

setOptimizeOptions(options): void;

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

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

注意，如果在 setLyricLines 之后修改此配置，需要重新调用 setLyricLines() 才能对当前歌词生效

Parameters

Parameter	Type	Description
options	OptimizeLyricOptions	优化配置选项

Returns

void

See

OptimizeLyricOptions

---

setOverscanPx()

setOverscanPx(px): void;

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

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

Parameters

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

Returns

void

---

setWordFadeWidth()

setWordFadeWidth(value?): void;

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

设置文字动画的渐变宽度，单位以歌词行的主文字字体大小的倍数为单位，默认为 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.ts:1135

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

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

Parameters

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

Returns

void

---

updateDynamicSpringParams()

protected updateDynamicSpringParams(): void;

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

Returns

void