# LyricView **Repository Path**: jackiehou/lyric-view ## Basic Information - **Project Name**: LyricView - **Description**: HarmonyOS下逐行歌词&逐字歌词组件 - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 4 - **Forks**: 0 - **Created**: 2025-09-03 - **Last Updated**: 2026-03-01 ## Categories & Tags **Categories**: Uncategorized **Tags**: HarmonyOS组件 ## README # LrcView ### 介绍 HarmonyOS下歌词组件 - 支持逐句歌词和逐字歌词 - 可以使用逐句歌词模拟逐字歌词动画效果 - 拖动进度条、点击歌词行可跳转到对应的歌词 - 可以设置歌词字体大小、颜色、对齐方式 - 可自定义滑动歌词的居中时间指示器 ### 效果图 | 逐句歌词 | 逐字歌词 | |--------------------------------------------------------------|--------------------------------------------------------------| | ![](https://pic1.imgdb.cn/item/68c780c5c5157e1a880375b8.gif) | ![](https://pic1.imgdb.cn/item/68c78116c5157e1a88037d87.gif) | ### 安装 ``` ohpm install @jackiehou/lyric-view ``` ### 注意 - 从1.0.9版本开始，将属性font:TextFont 替换为了fontWeight:FontWeight | number，新增了textScale : number属性；normalFontSize由maxFont和textScale决定（normalFontSize=maxFont.textSize*textScale） - 从1.0.9版本开始，将属性fadingEdgeFraction:number替换为fadingEdgeLength: LengthMetrics | undefined 边缘渐隐长度，在api> =14的的设备生效（api>=14已经覆盖了99.9%的设备了） ### 使用 ```ts import { LrcLine, LrcPosition, LrcView, parseLyrics} from '@jackiehou/lyric-view' ``` #### 基础示例，推荐使用状态管理V2 ```ts @Local lrcLines: LrcLine[] = [] @Local isPlay:boolean = true player:media.AVPlayer|undefined //返回负值歌词不和播放器同步，这里为了演示效果，因此position函数返回负值，和播放器同步的代码参考LrcPageV2 lrcPosition :LrcPosition = new LrcPosition(() =>this.player?.currentTime ?? -1) async aboutToAppear() { this.lrcLines = parseLyrics(lrcString) } build() { Column({space:10}) { LrcView({ lrcLines:this.lrcLines, isPlay:this.isPlay, lrcPosition:this.lrcPosition, normalFontColor:$r('sys.color.font_secondary'), selectFontColor:$r('sys.color.font_primary'), highlightFontColor:$r('sys.color.font_emphasize'), onLrcLineClick:(start) =>{ this.player?.seek(start) this.lrcPosition.seekTo(start) return true }, }) .width('100%') .layoutWeight(1) SymbolGlyph(this.isPlay ? $r('sys.symbol.pause_circle') :$r('sys.symbol.play_circle')) .fontSize(50) .fontColor([$r('sys.color.font_primary')]) .onClick(() =>{ this.isPlay = !this.isPlay }) } .height('100%') .width('100%') .padding(15) } ``` #### 状态管理V1可参考 https://gitee.com/jackiehou/lyric-view/blob/master/entry/src/main/ets/pages/SamplePage.ets ### 接口说明 #### LrcView | 名称 | 类型 | 是否必填 | 说明 | |-----------------------|-------------------------------------------------------------|------|--------------------------------------------------------------------------------------------------------| | lrcLines | LrcLine[] | 是 | 解析后的逐字&逐行歌词数据 | | fontWeight | FontWeight | 否 | 没有播放的歌词的字重 | | textScale | number | 否 | 缩放value，默认值0.8，textScale = normalFontSize/highlightFontSize ，isSingleLine为false有效，isSingleLine为true不缩放 | | maxFont | TextFont | 否 | 播放的歌词行的字体大小粗细 | | normalFontColor | ResourceColor | 否 | 未播放的歌词行的文字颜色 | | selectFontColor | ResourceColor | 否 | 播放的歌词行的未播放的文字颜色 | | highlightFontColor | ResourceColor | 否 | 播放的歌词行的已播放的文字颜色 | | space | number \| string | 否 | 歌词行的间距 | | itemVerticalPadding | number | 否 | 歌词item纵向的间距 ，isSingleLine为false有效 | | itemHorizontalPadding | number | 否 | 歌词item横向的间距 ，isSingleLine为false有效 | | fadingEdgeLength | LengthMetrics \| undefined | 否 | 边缘渐隐长度，在api>=14的的设备生效（api>=14已经覆盖了99.9%的设备了） | | contentStartOffset | number | 否 | 设置内容区域起始偏移量。列表滚动到起始位置时，列表内容与列表显示区域边界保留指定距离。 | | contentEndOffset | number | 否 | 设置内容区末尾偏移量。列表滚动到末尾位置时，列表内容与列表显示区域边界保留指定距离。 | | animationLyrics | boolean | 否 | 是否播放歌词动态效果，如果lyricsLine.words不为空也播放歌词动态效果 | | lrcAlignCenter | boolean | 否 | 歌词是否居中对齐显示，false：居左对齐 | | isSingleLine | boolean | 否 | 歌词item是否只显示单行 | | enableScroll | boolean | 否 | 设置是否支持滚动手势 | | isPlay | boolean | 否 | 是否在播放 | | lrcPosition | LrcPosition | 否 | 歌曲的播放进度 | | centerBuilder | (line:LineTime) => void | 否 | 滑动居中的歌词指示器Builder，不填则为默认样式， 为undefined则无指示器 ，isSingleLine为false有效 | | onLrcLineClick | (lrcLineStart: number) => boolean | 否 | 歌词行的点击事件 | | log | ((level: hilog.LogLevel, tag: string, msg: string) => void) | 否 | 打印log的 | #### parseLyrics parseLyrics(lyricsText: string,isAddFirstEmptyLine:boolean): LrcLine[] 歌词解析方法 | 名称 | 类型 | 说明 | |---------------------|---------|-------------------------------| | lyricsText | string | 歌词 | | isAddFirstEmptyLine | boolean | 默认值true，当首行歌词开始时间大于0时是否添加首行空行 | #### LrcLine | 名称 | 类型 | 说明 | |----------|----------------|-----------------| | start | number | 此行歌词开始的时间，单位毫秒 | | duration | number | 此行歌词消耗的时间 ，单位毫秒 | | words | Array | 此行歌词每个字、单词的内容 | | text | string | 此行歌词的内容 | #### LrcWord | 名称 | 类型 | 说明 | |----------|--------|------------------| | start | number | 此单词/字开始的时间，单位毫秒 | | duration | number | 此单词/字消耗的时间 ，单位毫秒 | | text | string | 此单词/字的内容 | #### TextFont | 名称 | 类型 | 说明 | |------------|----------------------|-------| | textSize | number | 字体大小 | | textWeight | FontWeight \| number | 字体粗细 | | lineHeight | number | 字体的行高 | #### LrcPosition | 方法名/字段名 | 参数/类型 | 说明 | |----------|-----------------------------------|---------------------------------| | position | () => number | 播放器的播放进度 ,LrcView组件会调用此函数获取播放进度 | | seekTo | (number,withoutPlayState) => void | 跳转至对应歌词的时间 | #### LineTime | 名称 | 类型 | 说明 | |---------|--------|--------------| | time | number | 歌词行开始时间，单位毫秒 | | timeStr | string | mm:ss 格式时间 | #### 效果图示例代码&仓库地址 https://gitee.com/jackiehou/lyric-view #### 开源协议 本项目基于 [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0.html) ，请自由的享受和参与开源。