CN.md

February 7, 2021 · View on GitHub

react-jinke-music-player

:musical_note: 也许是颜值最高,最好用的一个响应式 React HTML5 音频播放器组件 : )

安装

使用 yarn:

yarn add react-jinke-music-player

或者 npm

npm install react-jinke-music-player --save

预览

迷你模式

白天主题

light theme

黑夜主题

dark theme

移动端

mobile

例子

在线访问 : https://lijinke666.github.io/react-music-player/

实际应用 : 李金珂的小屋

本地访问 : http://localhost:8081/

例子示例代码

使用

import React from 'react'
import ReactDOM from 'react-dom'
import ReactJkMusicPlayer from 'react-jinke-music-player'
import 'react-jinke-music-player/assets/index.css'

ReactDOM.render(
  <ReactJkMusicPlayer {...options} />,
  document.getElementById('root'),
)

API

中文版本文档可能不完整, 请以英文版为准, 维护两个版本太累了

| 属性 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | --- | --- | --- | | className | string | - | 附加的 className | | audioLists | object[] | - | 播放列表 : {name: "YOUR_AUDIO_NAME",singer: "YOUR_AUDIO_SINGER_NAME",cover: "YOUR_AUDIO_COVER",musicSrc: "YOUR_AUDIO_SRC"} | | theme | string | dark | 播放器主题可选 'light'(白天) 和 'dark'(黑夜) 两种 | | defaultPosition | object | {top:0,left:0} | 当播放器是迷你模式时的初始位比如 {top:0,left:0} or {top:'20%',left:"20%"} | | playModeText | object | {order: "order",orderLoop: "orderLoop",singleLoop: "singleLoop",shufflePlay:"shufflePlay"}| 播放模式对应的文字 | | playModeShowTime |number|600| 切换播放模式时提示语的显示时间,单位毫秒 | | bounds |object,string|body| 拖拽边界可以是一个具体的字符串,比如body,也可以是具体的值 left,top,right,bottom| | preload |boolean,string|false| 是否在页面加载后立即加载音频。可选值auto | metadata | none true | false如果preload=true默认会设置 preload="auto" | | remember |boolean|false| 是否记住当前播放状态,比如音量,播放状态,下次访问时继续播放 | | glassBg |boolean|false| 是否显示毛玻璃背景效果 | | remove |boolean|true| 音乐是否可以被删除 | | defaultPlayIndex |number|0| 默认从第几首歌开始播放, 当值超过或低于可播放数默认为最大播放数和最小播放数 | | openText |string | ReactNode|open| 迷你模式时播放器的打开文案 | | closeText |string | ReactNode|close| 迷你模式时播放器的关闭文案 | | panelTitle |string | ReactNode|PlayList| 播放列表显示的标题 | | emptyText |string | ReactNode|no music| 播放列表为空时显示的文字 | | checkedText |string | ReactNode|-| 播放器主题开关选中的文字 | | unCheckedText |string | ReactNode|-| 播放器主题开关未选中的文字 | | defaultPlayMode |string|order| 默认的播放模式可选order,orderLoop,singleLoop,shufflePlay| | mode |string|mini| 播放器的默认模式可选mini,full| | once |boolean|false| 在默认情况下 'audioPlay' 函数会在你每次暂停后再次播放触发 , 如果你只想让 'audioPlay' 在音乐初始化播放的时候触发一次,你可以设置为true| | autoPlay |boolean|true| 是否在加载完成后随即播放音频 | | toggleMode |boolean|true| 是否可以从迷你模式切换到完整模式 , 或者完整模式切换到迷你模式 | | drag |boolean|true| 当播放器是迷你模式时是否可以对其进行拖拽 | | seeked |boolean|true| 是否能拖动或点击进度条调整播放进度 | | showMiniModeCover |boolean|true| 在迷你模式时, 是否显示封面图 | | showMiniProcessBar |boolean|false| 在迷你模式时, 是否显示圆形进度条 | | showProgressLoadBar |boolean|true| 显示音频加载进度条 | | showPlay |boolean|true| 是否显示播放按钮 | | showReload |boolean|true| 是否显示重放按钮 | | showDownload |boolean|true| 是否显示下载按钮 | | showPlayMode |boolean|true| 是否显示切换播放模式按钮 | | showThemeSwitch |boolean|true| 是否显示主题切换开关 | | extendsContent |array | ReactNode | string | boolean|-| 如果默认的功能按钮不满足你你可以自定义扩展比如<> </>| | controllerTitle |string | ReactNode|| 播放器模拟模式封面显示的文字 | | defaultVolume |number|1| 播放器初始音量, 范围0-1| | loadAudioErrorPlayNext |number|true| 当前音频加载加载失败时是否尝试播放下一首 | | onAudioDownload |function(audioInfo)|-| 音频下载的钩子函数 | | onAudioPlay |function(audioInfo)|-| 音频播放的钩子函数 | | onAudioPause |function(audioInfo)|-| 音频暂停的钩子函数 | | onAudioSeeked |function(audioInfo)|-| 进度条被点击或者拖动改变播放进度的钩子函数 | | onAudioVolumeChange |function(volume)|-| 音量改变的钩子函数范围0.0-1.0| | onAudioEnded |function(currentPlayId,audioLists,audioInfo)|-| 当前音频播放结束的钩子函数 | | onAudioAbort |function(currentPlayId,audioLists,audioInfo)|-| 当前音频播放中断的钩子函数 | | onAudioProgress |function(audioInfo)|-| 音频正在播放中的钩子函数 | | onAudioError |function(errMsg,currentPlayId,audioLists,audioInfo)|-| 音频播放失败的钩子函数 | | onAudioReload |function(audioInfo)|-| 音频重新播放的钩子函数 | | onAudioListsChange |function(currentPlayId,audioLists,audioInfo)|-| 播放列表发生改变时的钩子函数 | | onAudioPlayTrackChange |function(currentPlayId,audioLists,audioInfo)|-| 当前播放的音乐发生改变时的钩子函数 | | onAudioPlayModeChange |function(playMode)|-| 播放模式发生改变时的钩子函数 | | onAudioListsPanelChange |function(panelVisible)|-| 播放列表打开或关闭的钩子函数 | | onThemeChange |function(theme)|-| 主题切换后的钩子函数 | | onModeChange |function(mode)|-| 模式切换发生改变时的钩子函数 | | onAudioListsSortEnd |function(fromIndex,toIndex)|-| 列表歌曲拖拽后钩子函数 | | onAudioLyricChange |function(lineNum, currentLyric)|-| 当前播放的歌词改变回调 | | getContainer |() => HTMLElement\|Selectors|document.body| 播放器挂载的节点默认在 body | | getAudioInstance |(instance: HTMLAudioElement) => void|-| 获取原始的 audio 实例, 可以用它所有的 api 做你想做的事情 | | autoHiddenCover |boolean|false| 当前歌曲没有封面图时是否不渲染对应的 dom 节点 | | onBeforeAudioDownload |(audioInfo: ReactJkMusicPlayerAudioInfo) => Promise|-| 转换下载歌曲的文件名,路径等 | | clearPriorAudioLists |boolean|false| 更新歌曲列表时, 是否清除之前的列表 | | autoPlayInitLoadPlayList |boolean|false| 歌曲列表更新后, 是否自动播放 | | spaceBar |boolean|false| 是否可以通过空格键控制音乐的播放与暂停 | | showDestroy |boolean|false| 是否显示销毁按钮 | | onBeforeDestroy |function(currentPlayId,audioLists,audioInfo)|-| 销毁之前处理函数 | | onDestroyed |function(currentPlayId,audioLists,audioInfo)|-| 销毁之后的回调 | | customDownloader |function(downloadInfo: TransformedDownloadAudioInfo)|-| 自定义下载器 | | audioTitle |string | (audioInfo: ReactJkMusicPlayerAudioInfo) => string|{name} - {signer}` | 自定义音乐显示名称, 默认歌曲名-歌手 |

自定义操作按钮

如果播放器自带的功能不能满足你的需求, 可以自己实现操作按钮 UI, 会同步播放器对应的状态, 并触发钩子函数, 支持功能:

播放
暂停
重新播放
改变当前播放位置
改变播放倍速
改变音量
销毁播放器

class App extends React.Component {
  constructor() {
    this.audioInstance = null
  }
  render() {
    return (
      <>
        <ReactJkMusicPlayer
          getAudioInstance={(instance) => (this.audioInstance = instance)}
        />
        <button onClick={() => this.audioInstance.play()}>播放</button>
        <button onClick={() => this.audioInstance.pause()}>暂停</button>
        <button onClick={() => this.audioInstance.load()}>重新播放</button>
        <button onClick={() => (this.audioInstance.currentTime = 40)}>
          改变当前播放位置
        </button>
        <button onClick={() => (this.audioInstance.playbackRate = 2)}>
          改变播放倍速
        </button>
        <button onClick={() => (this.audioInstance.volume = 0.2)}>
          改变音量
        </button>
        <button onClick={() => this.audioInstance.destroy()}>销毁播放器</button>
      </>
    )
  }
}

毛玻璃效果

<ReactJkMusicPlayer glassBg />

glass-1

glass-2

自定义下载器

eg. https://www.npmjs.com/package/file-saver

const customDownloader = (downloadInfo) => {
  const link = document.createElement('a')
  link.href = downloadInfo.src // a.mp3
  link.download = downloadInfo.filename || 'test'
  document.body.appendChild(link)
  link.click()
}
;<ReactJkMusicPlayer
  audioLists={[{ src: 'a.mp3' }]}
  customDownloader={customDownloader}
/>

// 配合 onBeforeAudioDownload 使用
const onBeforeAudioDownload = () => {
  return Promise.resolve({
    src: '1.mp3',
  })
}

const customDownloader = (downloadInfo) => {
  console.log(downloadInfo.src) // 1.mp3
}
;<ReactJkMusicPlayer customDownloader={customDownloader} />

关闭/销毁播放器

const onBeforeDestroy = (currentPlayId, audioLists, audioInfo) => {
  return new Promise((resolve, reject) => {
    // 返回一个 Promise, 这里可以做一些自定义的校验
    if (window.confirm('是否关闭?')) {
      // 调用 resolve, 播放器正常关闭/销毁
      resolve()
    } else {
      // 调用 reject, 本次操作无效.
      reject()
    }
  })
}

const onDestroyed = (currentPlayId, audioLists, audioInfo) => {
  console.log('onDestroyed:', currentPlayId, audioLists, audioInfo)
}

ReactDOM.render(
  <ReactJkMusicPlayer
    showDestroy
    onBeforeDestroy={onBeforeDestroy}
    onDestroyed={onDestroyed}
  />,
)

开发

git clone https://github.com/lijinke666/react-music-player.git
yarn | npm install
yarn start | npm start
访问 `http://localhost:8081/`

单元测试

npm run test

音乐列表数据结构

Like This

interface ReactJkMusicPlayerAudioList {
  name: string | React.ReactNode,
  singer?: string | React.ReactNode,
  cover: string,
  musicSrc: string | () => Promise<string>,
  lyric?: string
  [key: string]: any
}>

返回的音乐信息