MUSE 5: API Documents

MUSE Player APIs (Chinese Simplified)

这篇 Wiki 列出了 MUSE Player 的一些主要的 API，并且对他们的作用和调用方式做了一些简略的解释。概括的说它包含这些内容：

• API 分类
• 调用方式
• 内部变量
• Life-cycle APIs
• Getter APIs
• Action APIs
• Extending APIs
• High-level APIs

API 分类

MUSE Player 采用 React 构建，由于从外部直接抽象地操作 React 组件较不便，所以我们封装了一些 API 在 MuseDOM 对象中，这些 API 都可以通过 window.MUSE 访问。根据功能的不同，我们将 MUSE Player 的 API 分为五类；

Life-cycle APIs

Life-cycle APIs (生命周期 API) 是用于渲染和移除 MUSE Player 实例的接口，例如 MUSE.render() 和 MUSE.destroy() 就属于生命周期 API. 生命周期 API 主要涉及对 DOM 的操作。

Getter APIs

Getter APIs 是用于读取播放器实例的一些数据的，例如你想获取播放器当前的播放状态，播放进度，播放列表等等，那么你可以使用对应的 Getter API. Getter APIs 不具有写入功能，调用它们是绝对安全的，且不会对播放器的状态做出任何的改变，是一类只读的接口。

Action APIs

Action APIs 对应着相应的 Player action。调用这些 API 相当于调用 Redux 当中的 dispatch（或者调用 Mobx model 的相关 Action） 对播放器的行为做出改变。例如你想要改变播放器的当前播放状态，动态的修改播放列表，就需要使用对应的 Action API. 这些 API 一般会改变播放器的状态，但绝大多数的 Action APIs 的行为都是可预测的，因此调用它们在大部分情况下是安全的。

请注意并不是每一个定义在 actions/PlayerActions.js 的 PlayerAction 都有与之对应的 Action API 来调用（例如由于浏览器的限制， toggleFullscreen() 是没有暴露出的接口）。

Extending APIs

Extending APIs (扩展 API) 用于在接口允许的范围内为播放器添加一些其他的功能，您可以把它理解为 MUSE 的插件机制。MUSE 提供了自定义样式 (Customed Layout) 和中间件 (Middleware) 的一系列接口，都可以通过 Extending APIs 来利用。

High-level APIs

High-level APIs (高级 API) 是直接操作 React 实例或 Redux/Mobx store 的接口，具有对整个播放器实例的最高操作权，因此相对来说他们是比较危险的。调用这些 API 可能导致播放器的行为出现不可预测的变化，所以若非确实有借助上述 API 无法满足的需求，才选择使用高级 API.

调用方式

使用 window.MUSE 全局对象调用。除 MUSE.render() 和部分 Extending APIs 外，所有的 API 调用时都需要传入播放器的 ID.

如何获取播放器的 ID？如果你使用 MUSE.render() 方法创建了一个播放器，那么将会返回类似下面的这样一个对象：

{
  component: ReactComponent,
  ref: <div data-reactroot class="muse-player" id="muse-player-1496283842000"></div>,
  id: 'muse-player-1496283842000'
}

其中的 id 字段就是播放器的 ID. 另外，如果你能获取到播放器的 DOM 节点实例，那么 ID 就是这个 DOM 的 id 属性。当然，前提是你没有修改过这个 id 属性，所以我们推荐用第一种方式获取播放器的 ID 来确保 ID 与实例的对应。

对于具体的 API，需要的参数可能有所不同，请参考下文的 API 列表了解具体需要的参数。这里以调用 togglePlay() API 为例，这个 API 需要的参数只有播放器的 ID：

// 创建播放器
const player = MUSE.render(/* ... */);
// 调用 API
MUSE.togglePlay(player.id);

就是这么简单。

内部变量

你可能会发现 window.MUSE 对象中有一些以下划线开头的变量，这些是 MUSE Player 的内部变量。在任何情况下请不要直接地修改它们，否则可能会使得播放器的行为变得不可预测而产生各种莫名奇妙的问题。他们的用途将会在下面解释：

变量名称	作用
_instances	储存 MUSE Player 在当前页面的所有实例。
_layouts	记录当前注册到 MUSE Player 的布局名称。
_middlewares	记录当前注册到 MUSE Player 的中间件处理器。
actions	对应 PlayerActions，描述播放器的所有行为（MUSE <= 5.2.7）。

Life-cycle APIs

• MUSE.render()
• MUSE.destroy()

MUSE.render(playList, node, options)

创建播放器实例的方法。

Params

Name	Type	isRequired	Description
playList	Array	√	播放列表，可以为空，播放列表的格式请参照 Getting Start 中描述的格式.
node	HTMLElement		指定播放器渲染后挂载到的 DOM 节点。如果不立刻渲染到页面，可以传入 undefined.
options	Object		播放器的可选项。

Return

Object:

{
  component: ReactComponent,
  ref: <div data-reactroot class="muse-player" id="muse-player-1496283842000"></div>,
  id: 'muse-player-1496283842000'
}

MUSE.destroy(id)

从当前页面删除一个播放器实例。

Params

Name	Type	isRequired	Description
id	String	√	要删除的播放器的 ID。

Getter APIs

太杂，懒得写，暂时没有，不过很快会补上。

Action APIs

• play()
• pause()
• stop()
• togglePlay()
• toggleLoop()
• toggleDrawer()
• togglePanel()
• setCurrentMusic()
• setLyricOffset()
• addMusicToList()
• removeMusicFromList()
• changePlayerLayout()

API Name	Param	Description
play(id)	id: String	改变播放器当前播放状态为正在播放。
pause(id)	id: String	改变播放器当前播放状态为暂停。
stop(id)	id: String	改变播放器当前播放状态为停止播放。
togglePlay(id)	id: String	改变播放器的播放状态使之与当前状态相反。
toggleLoop(id)	id: String	单曲循环开关。
toggleDrawer(id)	id: String	抽屉(Drawer) 开关。
togglePanel(id, panel)	id, panel: String	改变 Drawer 的 panel。
setCurrentMusic(id, index)	id: String, index: Number	改变当前播放的音乐条目。
setLyricOffset(id, offset)	id: String, offset: Number	调整歌词的 offset，其中的 offset 为变化量。
addMusicToList(id, item)	id: String, item: Object*	添加音乐到播放列表。
removeMusicFromList(id, index)	id: String, index: Number	从播放列表移除音乐。
changePlayerLayout(id, layout)	id, layout: String	改变播放器的布局样式。

*: item 参数的格式如下所示：

item = {
  title: undefined,
  artist: undefined,
  cover: undefined,
  src: undefined,
  lyric: undefined,
  translation: undefined
}

Extending APIs

对本页面上所有的播放器实例挂载一个操作。说得通俗一些，就是把一个你自定义的函数挂载到 MUSE 的事件钩子上，当这个事件触发的时候，这个自定义函数就会被调用。例如，你需要在渲染 MUSE 之后做一件事情（或许是一个小提示，又或者是自动开始播放，等等），那么你就可以把你想做的事情对应的方法挂载到 afterRender 事件钩子上。

• registerMiddleware(hook, func)
• registerLayout(name, constructor)

Hooks

Hooks	Description
afterRender	播放器渲染后
onMusicChange	歌曲切换后
onTogglePlay	更改歌曲播放状态后
onToggleMenu	点击右键菜单后
onToggleFullscreen	切换全屏模式后
onToggleDrawer	切换抽屉状态后
onPlayerResize	播放器尺寸改变后

默认提供了以上事件挂载点。如果你有其他的需要，欢迎提 issues 告诉我，我们会尽量满足你的需求。

registerMiddleware(hook, func)

将一个事件挂载到指定的钩子上。请注意，这个事件是对全局生效的，也就是说如果你的一个页面中有多个播放器，那么这个事件会对所有的播放器生效。

Params

Name	Type	isRequired	Description
hook	String	√	事件钩子的名称.
func	Function	√	事件发生所触发的方法.

其中 func 可能在调用时会传入一些参数（一般是 func 执行对象的实例信息等），具体到每个钩子有所不同。

Example

例如，我想要让每个播放器实例在渲染之后 log 一段信息：

const func = (instance) => {
    console.log('MUSE Player (id: ' + instance.id + ') rendered successfully.');
};
MUSE.registerMiddleware('afterRender', func);

就是这样。

registerLayout(name, constructor)

在全局范围内声明一个可用的自定义布局样式（通俗地讲，你可以把它理解为主题）。仅用于声明布局，构造函数会被立即执行，但是现有的播放器布局不会改变，除非手动调用MUSE.changePlayerLayout() 方法。

Params

Name	Type	isRequired	Description
name	String	√	自定义布局的名称.
constructor	Function	√	布局被声明时的构造函数.

PS. 如果你的自定义布局不需要构造函数，你可以传入一个空函数：() => false

High-level APIs

• dispatchAction() // MUSE <= 5.2.7
• getInstance()
• getReducerState() // MUSE <= 5.2.7
• getState() // MUSE >= 5.3.0
• changeState() // MUSE >= 5.3.0

dispatchAction(id, action)

对指定的播放器实例 dispatch 一个指定的 action. 可用于 Redux 版本的 MUSE（5.2.7 以前的版本）。

Params

Name	Type	isRequired	Description
id	String	√	播放器实例 ID.
action	Object	√	将要 dispatch 的 Action，这些 Actions 的 generators 都在 MUSE.action 中可以访问到。

getInstance(id)

通过 ID 获取播放器的 React Component 实例。

Params

Name	Type	isRequired	Description
id	String	√	播放器实例 ID.

Return

ReactComponent

getReducerState(id, key)

通过指定 key 获取当前 Redux store 的状态。可用于 Redux 版本的 MUSE（5.2.7 以前的版本）。

Params

Name	Type	isRequired	Description
id	String	√	播放器实例 ID.
key	String	√	要获取的状态的 key.

Return

Mixed.

getState(id, key)

与上文的 getReducerState() 类似，由于 Mobx 没有 Reducer 的概念，所以去掉了 Reducer.

changeState(id, key, value)

对指定的播放器实例修改状态。

Params

Name	Type	isRequired	Description
id	String	√	播放器实例 ID.
key	String	√	要修改的状态的 key.
value	Mixed	√	要修改的状态的目标值.

Return

Mixed.