LyricPlayerBase

This content is not available in your language yet.

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

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

Extends

EventTarget

Extended by

DomLyricPlayer

Implements

Constructors

Constructor

new LyricPlayerBase(element?): LyricPlayerBase;

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

Parameters

Parameter	Type
`element?`	`HTMLElement`

Returns

LyricPlayerBase

Overrides

EventTarget.constructor

Properties

Property	Modifier	Type	Default value	Description	Defined in
`bottomLine`	`protected`	`BottomLineEl`	`undefined`	-	packages/core/src/lyric-player/base/index.ts:82
`currentLyricLineObjects`	`protected`	`LyricLineBase`[]	`[]`	-	packages/core/src/lyric-player/base/index.ts:96
`currentLyricLines`	`protected`	`LyricLine`[]	`[]`	-	packages/core/src/lyric-player/base/index.ts:66
`disableSpring`	`protected`	`boolean`	`false`	-	packages/core/src/lyric-player/base/index.ts:72
`element`	`protected`	`HTMLElement`	`undefined`	-	packages/core/src/lyric-player/base/index.ts:48
`enableBlur`	`protected`	`boolean`	`true`	-	packages/core/src/lyric-player/base/index.ts:83
`enableScale`	`protected`	`boolean`	`true`	-	packages/core/src/lyric-player/base/index.ts:84
`hasDuetLine`	`protected`	`boolean`	`false`	-	packages/core/src/lyric-player/base/index.ts:71
`hidePassedLines`	`protected`	`boolean`	`false`	-	packages/core/src/lyric-player/base/index.ts:88
`interludeDots`	`protected`	`InterludeDots`	`undefined`	-	packages/core/src/lyric-player/base/index.ts:81
`isNonDynamic`	`protected`	`boolean`	`false`	-	packages/core/src/lyric-player/base/index.ts:70
`isPageVisible`	`protected`	`boolean`	`true`	-	packages/core/src/lyric-player/base/index.ts:98
`layoutState`	`protected`	`PlayerLayoutState`	`undefined`	-	packages/core/src/lyric-player/base/index.ts:73
`lyricLineElementMap`	`public`	`WeakMap`<`Element`, `LyricLineBase`>	`undefined`	`Internal`	packages/core/src/lyric-player/base/index.ts:65
`lyricLinesIndexes`	`protected`	`WeakMap`<`LyricLineBase`, `number`>	`undefined`	-	packages/core/src/lyric-player/base/index.ts:69
`lyricLinesSize`	`public`	`WeakMap`<`LyricLineBase`, [`number`, `number`]>	`undefined`	`Internal`	packages/core/src/lyric-player/base/index.ts:63
`maskObsceneWordChar`	`protected`	`string`	`"*"`	-	packages/core/src/lyric-player/base/index.ts:87
`maskObsceneWords`	`protected`	`MaskObsceneWordsMode`	`MaskObsceneWordsMode.Disabled`	-	packages/core/src/lyric-player/base/index.ts:85
`optimizeOptions`	`protected`	`OptimizeLyricOptions`	`{}`	-	packages/core/src/lyric-player/base/index.ts:99
`posXSpringParams`	`protected`	`Partial`<`SpringParams`>	`undefined`	-	packages/core/src/lyric-player/base/index.ts:101
`posYSpringParams`	`protected`	`Partial`<`SpringParams`>	`undefined`	-	packages/core/src/lyric-player/base/index.ts:106
`processedLines`	`protected`	`LyricLine`[]	`[]`	-	packages/core/src/lyric-player/base/index.ts:68
`resizeObserver`	`public`	`ResizeObserver`	`undefined`	`Internal`	packages/core/src/lyric-player/base/index.ts:130
`scaleForBGSpringParams`	`protected`	`Partial`<`SpringParams`>	`undefined`	-	packages/core/src/lyric-player/base/index.ts:116
`scaleSpringParams`	`protected`	`Partial`<`SpringParams`>	`undefined`	-	packages/core/src/lyric-player/base/index.ts:111
`scrollState`	`protected`	`PlayerScrollState`	`undefined`	-	packages/core/src/lyric-player/base/index.ts:89
`size`	`readonly`	[`number`, `number`]	`undefined`	-	packages/core/src/lyric-player/base/index.ts:97
`timelineState`	`protected`	`PlayerTimelineState`	`undefined`	播放时间线状态	packages/core/src/lyric-player/base/index.ts:52
`wordFadeWidth`	`protected`	`number`	`0.5`	-	packages/core/src/lyric-player/base/index.ts:180

Accessors

baseFontSize

Get Signature

get abstract baseFontSize(): number;

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

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/index.ts:534

重新布局定位歌词行的位置，调用完成后再逐帧调用 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/index.ts:832

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

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

Returns

void

Implementation of

Disposable.dispose

getBottomLineElement()

getBottomLineElement(): HTMLElement;

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

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

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

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

Returns

HTMLElement

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

getCurrentTime()

getCurrentTime(): number;

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

获取当前歌词的播放位置

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

Returns

number

当前播放位置

getElement()

getElement(): HTMLElement;

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

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

Returns

HTMLElement

Implementation of

HasElement.getElement

getEnableScale()

getEnableScale(): boolean;

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

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

Returns

boolean

是否启用歌词行缩放效果

getEnableSpring()

getEnableSpring(): boolean;

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

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

Returns

boolean

是否启用物理弹簧

getIsPlaying()

getIsPlaying(): boolean;

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

获取当前是否在播放

Returns

boolean

当前是否在播放

getLyricLines()

getLyricLines(): LyricLine[];

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

获取当前歌词数组

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

Returns

LyricLine[]

当前歌词数组

getOverscanPx()

getOverscanPx(): number;

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

获取当前 overscan 像素距离

Returns

number

getWordFadeWidth()

getWordFadeWidth(): number;

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

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

Returns

number

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

onResize()

protected onResize(): void;

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

Returns

void

pause()

pause(): void;

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

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

Returns

void

processObsceneWord()

processObsceneWord(word): string;

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

Internal

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

Parameters

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

Returns

string

rebuildLyricLines()

rebuildLyricLines(): void;

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

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/index.ts:806

重置用户滚动状态

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

Returns

void

resume()

resume(): void;

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

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

Returns

void

setAlignAnchor()

setAlignAnchor(alignAnchor): void;

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

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

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

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

内部会根据调用间隔和播放进度自动决定如何滚动和显示歌词，所以这个的调用频率越快越准确越好。调用完成后，应每帧调用 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/index.ts:277

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

Parameters

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

Returns

void

setEnableScale()

setEnableScale(enable?): void;

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

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

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

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

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

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

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

如果不启用，则会回退到基于 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:269

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

Parameters

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

Returns

void

setIsSeeking()

setIsSeeking(isSeeking): void;

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

Parameters

Parameter	Type
`isSeeking`	`boolean`

Returns

void

setLinePosXSpringParams()

setLinePosXSpringParams(_params?): void;

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

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

Parameters

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

Returns

void

Deprecated

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

setLinePosYSpringParams()

setLinePosYSpringParams(params?): void;

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

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

Parameters

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

Returns

void

setLineScaleSpringParams()

setLineScaleSpringParams(params?): void;

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

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

Parameters

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

Returns

void

setLyricLines()

setLyricLines(lines, initialTime?): void;

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

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

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/index.ts:299

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

Parameters

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

Returns

void

setMaskObsceneWords()

setMaskObsceneWords(mode): void;

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

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

Parameters

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

Returns

void

See

MaskObsceneWordsMode

setOptimizeOptions()

setOptimizeOptions(options): void;

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

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

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

Parameters

Parameter	Type	Description
`options`	`OptimizeLyricOptions`	优化配置选项

Returns

void

See

OptimizeLyricOptions

setOverscanPx()

setOverscanPx(px): void;

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

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

Parameters

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

Returns

void

setWordFadeWidth()

setWordFadeWidth(value?): void;

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

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

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

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

Parameters

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

Returns

void