叮铃铃~🔔：一个前端铃声/提示音组件
更新
目前组件已经更新到2.0版本，因此此文档也进行相应更改😊。2.0版本主要新增了以下特性：
-
兼容了更多的框架环境，包括Vue2、Vue3、React、纯JS。使用方式也提供了两种不同的风格：组件风格、对象函数调用的风格，更加灵活
-
取消了Vue插件形式注册组件。这个方式不是太有必要，而且还需要考虑在Vue2、Vue3里的兼容问题，收益不大
-
增加了用简谱来自定义铃声的功能
-
默认音效改用Web Audio API实现，可兼容任意框架环境
-
增加了循环/非循环的模式选择，可用于更多的情境（现在不光是铃声，也可用于音效）
若使用1.0版本，可参考文档：https://juejin.cn/post/7157530254947385375
如果你觉得本组件给你带来了帮助，欢迎来给个Star~ 😊 也欢迎提供宝贵意见。github地址：https://github.com/xun19/easy-ring
介绍
这是一个使用简单、通用、酷炫的前端铃声🔔组件～
可用于铃声、消息提示音、交互音效等诸多场景。
背景
之前的一个功能需求，需要在页面接收消息，一旦有了新消息之后，需要用铃声进行提醒。
因为没有找到类似的比较便捷的组件，所以就自己写了一个。然后想着能不能尝试下做成一个公共的组件，发布出去让其他开发者也用用？于是就试着写了一个项目，发布成了npm包。
目前这个组件已经发布到了npm上，欢迎大家试用。如果有好的建议，或者找到了更好的类似组件，欢迎指出和分享~
特点
-
支持多种开发环境。可在Vue、React、纯js（ES6+）中使用
-
支持多种调用风格。有Vue组件、React组件、以及js函数调用三种风格
-
可自定义音频源
-
支持使用简谱来自定义乐曲音效
-
内置默认音效
-
循环播放/单播放
参数
| 参数名 | 类型 | 必须 | 默认值 | 说明 |
| ------ | ------- | ------- | ------------------ | ------------------------------------------------------------ |
| open | Boolean | √ | false | 开启组件。将其设为true是使用本组件的前提 |
| ring | Boolean | √ |false | 是否开始播放音效。当设置为false时，则为关闭音效 |
| src | String | × | '' | 铃声音频文件的地址，可以是网络资源或者项目内资源。项目内资源需传入绝对路径。如果不清楚如何获取绝对路径，可参见下文《关于音效.自定义音频源》一节，这其实非常简单 |
| loop | Boolean | × | true | 是否循环播放 |
| defaultMusic | String | × |'EZIOS_FAMILY' | 默认铃声曲目。目前可选值：'LITTLE_STAR' | 'TWO_TIGERS' | 'EZIOS_FAMILY' | 'CASTLE_IN_THE_SKY' |
| musicText | String | × | '' | 以简谱来自定义音效。详见下文《关于音效.自定义简谱音效》一节 |
| log | Boolean | × |true | 是否打印日志 |
| ended | Function | × |function() {} | 音频（一次）播放结束事件回调 |
| setRing | Function | √ (React) | - | 对于React组件为必传。传入的值为使用useState Hook后，ring所对应的状态更新函数。具体可参考《使用.React组件形式》里的例子 |
安装
npm i easy-ring
使用
使用easy-ring只需要简单的三个操作，
-
① 开启组件。
-
② 播放音效。可以让组件开始响起。
-
③ 暂停音效。可以让组件安静下来。
不同风格的使用方式基本都遵循这三个操作，只是在使用细节上有一些差异。
1）Vue组件形式
当作一般的Vue组件引入、使用即可。主要通过open、ring参数进行控制。
- ① 开启组件：将open参数设置为true。
PS：这一步需要放到一个交互（比如：按钮点击）里进行触发，这是为了规避目前浏览器的限制。详细可参见下文 《关于open参数以及浏览器限制的解释》一章
-
② 播放音效：将ring参数设置为true
-
③ 暂停音效：将ring参数设置为false
根据自己的需求和想要的效果，自行决定何时播放、暂停音效，只需在对应的逻辑代码下控制ring参数值的更新即可
这里分别提供了Vue2、Vue3的例子进行参考：
Vue2的写法
<template>
<easy-ring
:open="open"
:ring.sync="ring" // 注意：这里需要使用双向绑定
:src="yourAudio"
/>
</template>
<script>
import { EasyRingVueComponent as EasyRing } from 'easy-ring'
import yourAudio from '@/assets/yourAudio.wav'
import msg from 'msg'
export default {
components: {
EasyRing
}
data() {
return {
open: false,
ring: false
}
},
methods: {
openComponent() {
if (confirm('我们需要您同意开启声音')) {
this.open = true // ① 开启组件
}
}
},
mounted() {
this.openComponent()
msg.listening()
msg.onReceived(() => {
this.ring = true // ② 播放音效
})
msg.onRead(() => {
this.ring = false // ③ 暂停音效
})
}
}
</script>
Vue3的写法
<template>
<easy-ring
:open="open"
v-model:ring="ring" // 注意：这里需要使用双向绑定
:src="yourAudio"
/>
</template>
<script setup>
import { ref } from 'vue'
import { EasyRingVueComponent as EasyRing } from 'easy-ring'
import yourAudio from '@/assets/yourAudio.wav'
import msg from 'msg'
const open = ref(false)
const ring = ref(false)
const openComponent = () => {
if (confirm('我们需要您同意开启声音')) {
open.value = true // ① 开启组件
}
}
openComponent()
msg.listening()
msg.onReceived(() => {
ring.value = true // ② 播放音效
})
msg.onRead(() => {
ring.value = false // ③ 暂停音效
})
</script>
DEMO项目地址：https://github.com/xun19/easy-ring/tree/master/easy-ring-demo-vue2、https://github.com/xun19/easy-ring/tree/master/easy-ring-demo-vue3
2）React组件形式
当作一般的React组件引入、使用即可。主要通过open、ring参数进行控制。
- ① 开启组件：将open参数设置为true。
PS：这一步需要放到一个交互（比如：按钮点击）里进行触发，这是为了规避目前浏览器的限制。详细可参见下文 《关于open参数以及浏览器限制的解释》一章
-
② 播放音效：将ring参数设置为true
-
③ 暂停音效：将ring参数设置为false
根据自己的需求和想要的效果，自行决定何时播放、暂停音效，只需在对应的逻辑代码下控制ring参数值的更新即可
PS: 另外，不要忘记传入一个setRing参数，它实际就是ring参数所对应的状态更新函数，easy-ring将用它来做一些状态自动更新的操作。这将让easy-ring使用起来更傻瓜、更自动化。
这里提供了一个可供参考的例子：
import { useState, useEffect } from 'react'
import { EasyRingReactComponent as EasyRing } from 'easy-ring'
import msg from 'msg'
export default Demo = () => {
const [open, setOpen] = useState(false)
const [ring, setRing] = useState(false)
const getMsg = () => {
msg.listening()
msg.onReceived(() => {
setRing(true) // ② 播放音效
})
msg.onRead(() => {
setRing(false) // ③ 暂停音效
})
}
const openComponent = () => {
if (confirm('我们需要您同意开启声音')) {
setOpen(true) // ① 开启组件
}
}
useEffect(() => {
this.openComponent()
this.getMsg()
}, [])
return (
<div>
<EasyRing
open={this.state.open}
ring={this.state.ring}
setRing={setRing} // 注意：请记得传入这个参数
></EasyRing>
</div>
)
}
DEMO项目地址：https://github.com/xun19/easy-ring/tree/master/easy-ring-demo-react
3）js函数调用的形式
easy-ring提供了一个CommonEasyRing类，该类的实例有三个方法：open( )、ring( )、stop( )、close( )，分别用于开启组件、播放音效、暂停音效、关闭组件。
- ① 开启组件：open( )
PS：这一步需要放到一个交互（比如：按钮点击）里进行触发，这是为了规避目前浏览器的限制。详细可参见下文 《关于open参数以及浏览器限制的解释》一章
-
② 播放音效：ring( )
-
③ 暂停音效：stop( )
-
④ 关闭组件：close( )
下面是一个可供参考的例子：
const myEasyring = new CommonEasyRing()
button.addEventListener('click', () => {
if (confirm('我们需要您同意开启声音 ｜ We need your consent to turn on sound')) {
myEasyring.open() // ① 开启组件
}
})
msg.listening()
msg.onReceived(() => {
myEasyring.ring() // ② 播放音效
})
msg.onRead(() => {
myEasyring.stop() // ③ 暂停音效
})
msg.onUnmount(() => {
myEasyring.close() // ④ 关闭组件
})
关于音效
本组件有三种音效的使用方式：自定义音频源、自定义简谱音效、内置默认音效。可根据需求选择自己喜欢的方式。
这三种音效的播放优先级为: 自定义音频源 > 自定义简谱音效 > 内置默认音效
1）自定义音频源
将你的音频文件地址传给组件的src参数，即可使用自定义音频源。可以是网络资源或者项目内资源。
项目内资源采用的是绝对路径，因为使用相对路径容易在本地构建或者打包过程中出现问题，且作为第三方组件的easy-ring无法从你项目里的相对路径找到音频文件。
获取绝对路径其实非常简单，在Vue或者React环境（可能也包括其他构建环境）中使用下列方式：
import yourAudio from '@/assets/yourAudio.wav'
此时yourAudio变量就是你音频文件的绝对路径，将这个变量传给src参数即可。
2）自定义简谱音效
将一串简谱的字符串传给musicText参数，即可使用自定义简谱音效。
例如下面例子展示了怎么使用《小星星》的音效：
/* in Vue */
<EasyRing
:open="open"
:ring="ring"
musicText="1 1 5 5 6 6 5 - 4 4 3 3 2 2 1 - 5 5 4 4 3 3 2 - 5 5 4 4 3 3 2 - 1 1 5 5 6 6 5 - 4 4 3 3 2 2 1 - - - -"
/>
/* in React */
<EasyRing
open={this.state.open}
ring={this.state.ring}
musicText="1 1 5 5 6 6 5 - 4 4 3 3 2 2 1 - 5 5 4 4 3 3 2 - 5 5 4 4 3 3 2 - 1 1 5 5 6 6 5 - 4 4 3 3 2 2 1 - - - -"
/>
/* in JS */
const myEasyring = new CommonEasyRing({
musicText: '1 1 5 5 6 6 5 - 4 4 3 3 2 2 1 - 5 5 4 4 3 3 2 - 5 5 4 4 3 3 2 - 1 1 5 5 6 6 5 - 4 4 3 3 2 2 1 - - - -'
})
musicText参数的值需要是一串字符串，里面主要由数字、"-"组成，并以一个空格进行间隔区分。
| 字符 | 对应| 说明 |
| ------ | ------- | ------ |
| .1 ~ .7 | 低音 | 注意前面的符号是"." |
| 1 ~ 7 | 中音 | |
| 1. ~ 7. | 高音 | 注意前面的符号是"." |
| - | 一个停顿单位 | 停顿单位连续得越多，代表停顿时间越长。比如： "- - -"代表停顿三个单位 |
下面是目前本组件内置的几首简谱乐曲，可用于参考：
| 曲名 | musicText值 |
| ------ | ------- |
| 小星星（LITTLE_STAR） | '1 1 5 5 6 6 5 - 4 4 3 3 2 2 1 - 5 5 4 4 3 3 2 - 5 5 4 4 3 3 2 - 1 1 5 5 6 6 5 - 4 4 3 3 2 2 1 - - - -' |
| 两只老虎（TWO_TIGERS） | '1 2 3 1 - 1 2 3 1 - 3 4 5 - 3 4 5 - - 5 6 5 4 3 - 1 - 5 6 5 4 3 - 1 - 2 - .5 - 1 - - 2 - .5 - 1 - - - -' |
| 艾吉奥之家（EZIOS_FAMILY） | '.6 - 1 - 2 - 3 - .6 - 1 - 2 - 1 - .6 - 1 - 2 - 3 - .6 - 1 - 2 - 1 - .6 - 1 - 2 - 3 - 6 - 7 - 1. - 2. - 3. - - - - - -' |
| 天空之城（CASTLE_IN_THE_SKY） | '.6 .7 1 - - .7 1 - 3 - .7 - - - - .3 .3 .6 - - .5 .6 - 1 - .5 - - - - .3 .3 .4 - - .3 .4 - 1 - .3 - - - - 1 1 1 .7 - - .4 .4 - .7 - .7 - - - - -' |
这实际上使用了Web Audio API的前端技术。这块要感谢张鑫旭大佬（https://www.zhangxinxu.com/wordpress/2017/06/html5-web-audio-api-js-ux-voice/） 的启发 、以及前端王睿
大佬（https://www.jianshu.com/p/4f4c8bbd9775、https://www.zhanhu56.com/h5/music_box/、https://github.com/chchlsh/MusicBox） MusicBox组件的功能支持👍，他们的灵感和帮助让这个组件有了更多拓展性和乐趣。
3）内置默认音效
如果没有给src参数、musicText参数传递值的时候，组件会使用默认音效。目前的默认音效为《Ezio's Family》，这是游戏《刺客信条》的一首主题曲。
你也可以通过设置defaultMusic的值来更换默认音效曲目，目前支持的可选值为：'LITTLE_STAR'、'TWO_TIGERS'、'EZIOS_FAMILY'、'CASTLE_IN_THE_SKY'。
这实际上跟自定义简谱音效功能的实现使用了同一种技术（Web Audio API）。如果你有更好、更动听的旋律简谱，也欢迎在我的github或者博客里进行分享，后续会考虑将更多内置音效放到组件里。😊
关于open参数以及浏览器限制的解释
当前大多数浏览器不支持自动播放音频，这需要用户自己主动触发交互后才能播放。因此，本组件才会增加一个open参数，用于（提醒开发者）实现这一操作。
我们需要把“将open参数设置为true”的这一控制逻辑，放在触发用户交互行为的事件回调里，例如：按钮的click事件、switch开关的change事件等。
但是，你可以通过一些交互设计来淡化这一过程，从而提升用户体验。比如：
-
在用户点击“登录”按钮时，在click回调里设置open参数为true
-
设置一个音效开关，在change回调里设置open参数为true
-
点击导航菜单的时候，在click回调里设置open参数为true
-
在点击打开消息弹窗时，在click回调里设置open参数为true
上面的例子不太适用于刷新页面后的情况，刷新页面情景下，个人认为较好的方式可能是：
- 弹出一个询问“是否允许开启音效”的弹窗
感谢
自定义简谱音效功能的实现，要感谢张鑫旭大佬【https://www.zhangxinxu.com/wordpress/2017/06/html5-web-audio-api-js-ux-voice/ 】的启发 、以及王睿
大佬【https://www.jianshu.com/p/4f4c8bbd9775、https://www.zhanhu56.com/h5/music_box/、https://github.com/chchlsh/MusicBox 】MusicBox组件的功能支持👍，他们的灵感和帮助让这个组件有了更多拓展性和乐趣。
