Skip to content

Commit 31d5c3a

Browse files
codeacme17codeacme17
committed
docs: add cn-readme.md 
1 parent 902d8de commit 31d5c3a

File tree

1 file changed

+192
-0
lines changed

1 file changed

+192
-0
lines changed

‎docs/cn-readme.md

+192
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
1+
<br />
2+
<p align="center">
3+
<img width="200" alt="logo" src="https://raw.githubusercontent.com/codeacme17/repo-assets/ebe95dad5e4904d000cf8a7d3642a0739cb708c7/waveform/logo.svg"/>
4+
</p>
5+
6+
<h3 align="center">
7+
<samp>
8+
1llest-waveform-vue
9+
</samp>
10+
</h3>
11+
12+
<p align="center">
13+
<samp>
14+
一款轻量可控的 Vue3 音频播放插件
15+
</samp>
16+
</p>
17+
18+
## 描述
19+
20+
该组件是使用原生的 [Web Audio API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API) 编写的，在生产环境中除了依赖于 Vue 3 之外没有使用任何其他依赖。当然，这意味着：如果您的目标浏览器不支持 Web Audio API 的功能，那么我的插件也将无法应用。您可以前往 [浏览器兼容性](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API#audiocontext_2) 页面查看 AudioContext 一行，以检查它是否与目标浏览器兼容。
21+
22+
**样本** - [Live Demo](https://codeacme17.github.io/1llest-waveform-vue/)
23+
24+
## 开始
25+
26+
### 下载
27+
28+
```bash
29+
npm install 1llest-waveform-vue
30+
```
31+
32+
### 使用
33+
34+
全局组件使用
35+
36+
```javascript
37+
// main.ts
38+
import { createApp } from 'vue'
39+
import App from './App.vue'
40+
41+
import IllestWaveform from '1llest-waveform-vue'
42+
import '1llest-waveform-vue/lib/style.css'
43+
44+
const app = createApp(App)
45+
46+
app.use(IllestWaveform)
47+
app.mount('#app')
48+
```
49+
50+
本地组件使用
51+
52+
```js
53+
// example.vue
54+
import { IllestWaveform } from '1llest-waveform-vue'
55+
import '1llest-waveform-vue/lib/style.css'
56+
```
57+
58+
### 组件使用方式
59+
60+
```vue
61+
<template>
62+
<IllestWaveform
63+
ref="waveformRef"
64+
v-bind="waveOptions"
65+
@on-init="initHandler"
66+
@on-fetched="fetchedHandler"
67+
@on-ready="readyHandler"
68+
@on-play="(v: boolean) => (playing = v)"
69+
@on-pause="(v: boolean) => (playing = v)"
70+
@on-finish="finishHandler"
71+
@on-click="clickHandler"
72+
/>
73+
<div>{{ currentTime }} - {{ durationTime }}</div>
74+
</template>
75+
76+
<script setup lang="ts">
77+
import { onMounted, reactive, ref, watchEffect } from 'vue'
78+
import type { Ref } from 'vue'
79+
import { IllestWaveform } from '1llest-waveform-vue'
80+
import type { IllestWaveformProps } from '1llest-waveform-vue'
81+
import '1llest-waveform-vue/lib/style.css'
82+
83+
const waveOptions = reactive<IllestWaveformProps>({
84+
url: 'example.mp3',
85+
})
86+
87+
const waveformRef = ref<typeof IllestWaveform | null>(null)
88+
89+
onMounted(() => {
90+
getCurrentTime()
91+
})
92+
93+
const init = ref(false)
94+
const fetched = ref(false)
95+
const playing = ref(false)
96+
const finished = ref(false)
97+
const ready = ref(false)
98+
const currentTime = ref('0:00')
99+
const durationTime = ref('0:00')
100+
101+
const initHandler = (v: boolean) => {
102+
init.value = v
103+
}
104+
105+
const fetchedHandler = (v: boolean) => {
106+
fetched.value = v
107+
}
108+
109+
const readyHandler = (v: boolean) => {
110+
ready.value = v
111+
getDuration()
112+
}
113+
114+
const finishHandler = (v: boolean) => {
115+
finished.value = v
116+
}
117+
118+
const clickHandler = (el: Ref<HTMLElement>) => {
119+
console.log(el)
120+
}
121+
122+
const play = () => {
123+
waveformRef.value!.play()
124+
}
125+
126+
const replay = () => {
127+
waveformRef.value!.replay()
128+
}
129+
130+
const pause = () => {
131+
waveformRef.value!.pause()
132+
}
133+
134+
const getCurrentTime = () => {
135+
watchEffect(() => {
136+
const current = waveformRef.value!.getCurrentTime()
137+
currentTime.value = current
138+
})
139+
}
140+
141+
const getDuration = () => {
142+
const duration = waveformRef.value!.getDuration()
143+
durationTime.value = duration
144+
}
145+
</script>
146+
```
147+
148+
## 文档
149+
150+
### 组件属性
151+
152+
| 属性 | 描述 | 类型 | 默认值 |
153+
| :------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------- | :-------- |
154+
| url | 音频文件的 URL 地址 | `String` | - |
155+
| lineWidth | 组成波形的每条垂直线的宽度 | `Number` | `0.5` |
156+
| lineCap | 组成波形的每条垂直线末端的样式 | `CanvasLineCap` | `round` |
157+
| lineColor | 组成波形的每条垂直线的颜色 | `String` | `#5e5e5e` |
158+
| samplingRate | 指示您的音频采样率。值越大，波形将呈现出更多的线条，并具有更高的准确性。但不建议将此值设置得太大，因为过大的值会降低渲染效率，推荐值介于 `8000 - 44100` 之间 | `Number` | `22050` |
159+
| cursorWidth | 指示光标的宽度 | `Number` | `2` |
160+
| cursorColor | 光标的颜色 | `String` | `#fff` |
161+
| maskColor | 波形遮罩层的颜色 | `String` | `#fff` |
162+
| lazy | 是否启用延迟加载模式，如果您想将多个波形显示为列表，此属性非常有用 | `Boolean` | `true` |
163+
| skeleton | 是否在波形加载期间启用骨架屏效果 | `Boolean` | `true` |
164+
| skeletonColor | 骨架屏的颜色 | `String` | `#232323` |
165+
| interact | 是否允许用户与波形进行交互 | `Boolean` | `true` |
166+
| fade | 在播放和暂停音频时实现淡入淡出效果，这可以为用户提供更流畅的听觉体验 | `Boolean` | `true` |
167+
168+
### 事件
169+
170+
> 在使用以下事件时，您需要在前面添加 `on-` 前缀，例如 `@on-init="initHandler"`
171+
172+
| 事件 | 描述 | 参数 |
173+
| :------ | :----------------------------------------------------- | :----------------- |
174+
| init | 波形开始初始化之前的钩子事件 | `Boolean` |
175+
| fetched | 接受音频文件后的钩子事件 | `Boolean` |
176+
| ready | 在波形完成所有初始化和页面渲染后触发的钩子事件 | `Boolean` |
177+
| play | 在播放开始时触发的事件 | `Boolean` |
178+
| pause | 在播放暂停时触发的事件 | `Boolean` |
179+
| finish | 在播放完成时触发的事件（播放完成是指整个音频播放完毕） | `Boolean` |
180+
| click | 在单击波形时触发的事件 | `Ref<HTMLElement>` |
181+
182+
### 方法
183+
184+
> 您可以直接在波形组件实例上调用这些方法，例如 `waveform_ref.value.play()`
185+
186+
| 方法 | 描述 | 返回值 |
187+
| :------------- | :-------------------------------------------------------------------------------------------------- | -------- |
188+
| play | 触发波形的播放方法，使其开始播放当前音频 | - |
189+
| pause | 触发波形的暂停方法，使其暂停播放 | - |
190+
| replay | 此方法可以重新开始播放当前音频 | - |
191+
| getCurrentTime | 此方法可以获取当前播放时间。如果您想实时获取当前播放时间，可以将其包装在 `watchEffect` 钩子中 | `string` |
192+
| getDuration | 此方法可以获取当前音频的持续时间，但是**此方法必须在 `ready` 钩子事件触发后才能获得正确的持续时间** | `string` |

0 commit comments

Comments
 (0)