更新

目前组件已经更新到2.0版本，因此此文档也进行相应更改😊。2.0版本主要新增了以下特性：

• 兼容了更多的框架环境，包括Vue2、Vue3、React、纯JS。使用方式也提供了两种不同的风格：组件风格、对象函数调用的风格，更加灵活
• 取消了Vue插件形式注册组件。这个方式不是太有必要，而且还需要考虑在Vue2、Vue3里的兼容问题，收益不大
• 增加了用简谱来自定义铃声的功能
• 默认音效改用Web Audio API实现，可兼容任意框架环境
• 增加了循环/非循环的模式选择，可用于更多的情境（现在不光是铃声，也可用于音效）

若使用1.0版本，可参考文档：easy-ring1.0文档

如果你觉得本组件给你带来了帮助，欢迎点个Star~ 😊 也欢迎提供宝贵意见。github地址

---

介绍

这是一个使用简单、通用、酷炫的前端铃声🔔组件～

可用于铃声、消息提示音、交互音效等诸多场景。

背景

之前的一个功能需求，需要在页面接收消息，一旦有了新消息之后，需要用铃声进行提醒。

因为没有找到类似的比较便捷的组件，所以就自己写了一个。然后想着能不能尝试下做成一个公共的组件，发布出去让其他开发者也用用？于是就试着写了一个项目，发布成了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只需要简单的三个操作，

• ① 开启组件。
• ② 播放音效。可以让组件开始响起。
• ③ 暂停音效。可以让组件安静下来。

不同风格的使用方式基本都遵循这三个操作，只是在使用细节上有一些差异。

下面是使用示例。请注意，代码中包含的“msg”不是实际存在的包，只是一个示例，假定为用户要使用的某种消息组件。它包括了监听消息方法listening、接收事件回调onReceived、用户阅读事件回调onRead

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项目源码地址

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项目源码地址

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

上面的例子不太适用于刷新页面后的情况，刷新页面情景下，个人认为较好的方式可能是：

• 弹出一个询问“是否允许开启音效”的弹窗

感谢

自定义简谱音效功能的实现，要感谢张鑫旭大佬《利用HTML5 Web Audio API给网页JS交互增加声音》的启发 、以及王睿
大佬《教你用原生JS造“钢琴”》MusicBox组件的功能支持👍，他们的灵感和帮助让这个组件有了更多拓展性和乐趣。