LyricPlayerBase

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

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

Extends

EventTarget

Extended by

Implements

Constructors

Constructor

new LyricPlayerBase(element?): LyricPlayerBase;

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

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:55
`alignPosition`	`protected`	`number`	`0.35`	-	packages/core/src/lyric-player/base.ts:56
`allowScroll`	`protected`	`boolean`	`true`	-	packages/core/src/lyric-player/base.ts:59
`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:52
`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:50
`hotLines`	`protected`	`Set`<`number`>	`undefined`	-	packages/core/src/lyric-player/base.ts:37
`initialLayoutFinished`	`protected`	`boolean`	`false`	-	packages/core/src/lyric-player/base.ts:63
`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:60
`isPlaying`	`protected`	`boolean`	`true`	-	packages/core/src/lyric-player/base.ts:1008
`isScrolled`	`protected`	`boolean`	`false`	-	packages/core/src/lyric-player/base.ts:105
`isSeeking`	`protected`	`boolean`	`false`	-	packages/core/src/lyric-player/base.ts:53
`isUserScrolling`	`protected`	`boolean`	`false`	标记用户是否正在进行滚动交互	packages/core/src/lyric-player/base.ts:68
`lastCurrentTime`	`protected`	`number`	`0`	-	packages/core/src/lyric-player/base.ts:54
`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:49
`maskObsceneWords`	`protected`	`MaskObsceneWordsMode`	`MaskObsceneWordsMode.Disabled`	-	packages/core/src/lyric-player/base.ts:48
`optimizeOptions`	`protected`	`OptimizeLyricOptions`	`{}`	-	packages/core/src/lyric-player/base.ts:61
`overscanPx`	`protected`	`number`	`300`	视图额外预渲染（overscan）距离，单位：像素。用于决定在视口之外多少距离内也认为是“可见”，以便提前创建/保留行元素。	packages/core/src/lyric-player/base.ts:75
`posXSpringParams`	`protected`	`Partial`<`SpringParams`>	`undefined`	-	packages/core/src/lyric-player/base.ts:77
`posYSpringParams`	`protected`	`Partial`<`SpringParams`>	`undefined`	-	packages/core/src/lyric-player/base.ts:82
`processedLines`	`protected`	`LyricLine`[]	`[]`	-	packages/core/src/lyric-player/base.ts:35
`resizeObserver`	`public`	`ResizeObserver`	`undefined`	`Internal`	packages/core/src/lyric-player/base.ts:107
`scaleForBGSpringParams`	`protected`	`Partial`<`SpringParams`>	`undefined`	-	packages/core/src/lyric-player/base.ts:92
`scaleSpringParams`	`protected`	`Partial`<`SpringParams`>	`undefined`	-	packages/core/src/lyric-player/base.ts:87
`scrollBoundary`	`protected`	`number`[]	`undefined`	-	packages/core/src/lyric-player/base.ts:51
`scrollOffset`	`protected`	`number`	`0`	-	packages/core/src/lyric-player/base.ts:57
`scrollToIndex`	`protected`	`number`	`0`	-	packages/core/src/lyric-player/base.ts:41
`size`	`readonly`	[`number`, `number`]	`undefined`	-	packages/core/src/lyric-player/base.ts:58
`targetAlignIndex`	`protected`	`number`	`0`	-	packages/core/src/lyric-player/base.ts:158
`wheelTimeout`	`protected`	`number` \| `undefined`	`undefined`	-	packages/core/src/lyric-player/base.ts:69
`wordFadeWidth`	`protected`	`number`	`0.5`	-	packages/core/src/lyric-player/base.ts:157

Accessors

baseFontSize

Get Signature

get abstract baseFontSize(): number;

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

Returns

number

Methods

addEventListener()

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

Defined in: node_modules/.pnpm/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

calcLayout()

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

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

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

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

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

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

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

Parameters

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

Returns

Promise<void>

dispatchEvent()

dispatchEvent(event): boolean;

Defined in: node_modules/.pnpm/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

dispose()

dispose(): void;

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

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

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

Returns

void

Implementation of

Disposable.dispose

getBottomLineElement()

getBottomLineElement(): HTMLElement;

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

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

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

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

Returns

HTMLElement

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

getCurrentInterlude()

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

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

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

这个只允许内部调用

Returns

[number, number, number, boolean] | undefined

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

getCurrentTime()

getCurrentTime(): number;

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

获取当前歌词的播放位置

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

Returns

number

当前播放位置

getElement()

getElement(): HTMLElement;

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

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

Returns

HTMLElement

Implementation of

HasElement.getElement

getEnableScale()

getEnableScale(): boolean;

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

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

Returns

boolean

是否启用歌词行缩放效果

getEnableSpring()

getEnableSpring(): boolean;

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

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

Returns

boolean

是否启用物理弹簧

getIsPlaying()

getIsPlaying(): boolean;

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

获取当前是否在播放

Returns

boolean

当前是否在播放

getLyricLines()

getLyricLines(): LyricLine[];

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

获取当前歌词数组

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

Returns

LyricLine[]

当前歌词数组

getOverscanPx()

getOverscanPx(): number;

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

获取当前 overscan 像素距离

Returns

number

getWordFadeWidth()

getWordFadeWidth(): number;

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

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

Returns

number

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

onResize()

protected onResize(): void;

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

Returns

void

pause()

pause(): void;

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

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

Returns

void

processObsceneWord()

processObsceneWord(word): string;

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

Internal

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

Parameters

Parameter	Type	Description
`word`	`LyricWord`	单词对象

Returns

string

rebuildLyricLines()

rebuildLyricLines(): void;

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

Returns

void

removeEventListener()

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

Defined in: node_modules/.pnpm/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

resetScroll()

resetScroll(): void;

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

重置用户滚动状态

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

Returns

void

resume()

resume(): void;

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

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

Returns

void

setAlignAnchor()

setAlignAnchor(alignAnchor): void;

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

设置目标歌词行的对齐方式，默认为 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:490

设置默认的歌词行对齐位置，相对于整个歌词播放组件的大小位置，默认为 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:639

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

调用完成后，可以每帧调用 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:398

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

Parameters

Parameter	Type	Description
`enable`	`boolean`	是否启用

Returns

void

setEnableScale()

setEnableScale(enable?): void;

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

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

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

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

Parameters

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

Returns

void

setEnableSpring()

setEnableSpring(enable?): void;

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

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

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

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

Parameters

Parameter	Type	Default value
`enable`	`boolean`	`true`

Returns

void

setHidePassedLines()

setHidePassedLines(hide): void;

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

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

Parameters

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

Returns

void

setIsSeeking()

setIsSeeking(isSeeking): void;

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

Parameters

Parameter	Type
`isSeeking`	`boolean`

Returns

void

setLinePosXSpringParams()

setLinePosXSpringParams(_params?): void;

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

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

Parameters

Parameter	Type
`_params`	`Partial`<`SpringParams`>

Returns

void

Deprecated

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

setLinePosYSpringParams()

setLinePosYSpringParams(params?): void;

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

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

Parameters

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

Returns

void

setLineScaleSpringParams()

setLineScaleSpringParams(params?): void;

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

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

Parameters

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

Returns

void

setLyricLines()

setLyricLines(lines, initialTime?): void;

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

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

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:420

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

Parameters

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

Returns

void

setMaskObsceneWords()

setMaskObsceneWords(mode): void;

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

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

Parameters

Parameter	Type	Description
`mode`	`MaskObsceneWordsMode`	掩码模式

Returns

void

See

MaskObsceneWordsMode

setOptimizeOptions()

setOptimizeOptions(options): void;

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

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

注意，如果在 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:498

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

Parameters

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

Returns

void

setWordFadeWidth()

setWordFadeWidth(value?): void;

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

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

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

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

Parameters

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

Returns

void