ag-live-player

v0.6.0

Published

a month ago

Vue2 仿抖音直播 H5 播放插件

0High
0Medium
0Low

allengxs

vue2 live hls player danmaku

ag-live-player

Vue2 仿抖音直播 H5 播放插件，支持 HLS(m3u8) 直播、点播、弹幕、点赞等能力，适合嵌入业务页面作为独立的直播播放器组件使用。

安装

npm install ag-live-player
# 或
yarn add ag-live-player

快速上手

在 Vue2 项目入口（例如 main.js）中全局注册：

import Vue from 'vue';
import AgLivePlayer from 'ag-live-player';
import 'ag-live-player/dist/style.css';

Vue.use(AgLivePlayer);

注册后即可在任意组件中直接使用标签 <ag-live-player>。

最简直播示例

<template>
  <ag-live-player
    mode="live"
    :src="liveSrc"
    @state-change="onState"
  />
</template>

<script>
export default {
  data() {
    return {
      liveSrc: 'https://example.com/live/playlist.m3u8',
    };
  },
  methods: {
    onState(s) {
      console.log('直播状态变化:', s);
    },
  },
};
</script>

点播示例

<template>
  <ag-live-player
    ref="vod"
    mode="vod"
    :src="vodSrc"
    :poster="vodPoster"
    :controls="true"
    :controls-list="['play', 'volume', 'seek', 'fullscreen']"
    @state-change="onVodState"
  />
</template>

<script>
export default {
  data() {
    return {
      vodSrc: 'https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8',
      vodPoster: 'https://example.com/poster.jpg',
    };
  },
  methods: {
    onVodState(s) {
      console.log('点播状态:', s);
    },
  },
};
</script>

组件标签

全局注册后会提供以下组件：

<ag-live-player>：主播放器组件（对应内部 LivePlayer）

ag-live-player 属性（props）

基础

width: number | string
播放器宽度。默认 100%。
- 数字会被当成像素值，例如 430 → 430px
- 字符串可以是任意合法 CSS 值，例如 "100%"、"430px"
height: number | string
播放器高度。默认 240（px）。
mode: 'live' | 'vod'
播放模式。
- "live"：直播模式
- "vod"：点播模式
  默认 "vod"。
liveStatus: 'not-started' | 'living' | 'ended'
仅在 mode="live" 时生效，用于区分直播状态，控制显示逻辑：
- "not-started"：直播未开始
- "living"：直播进行中（默认）
- "ended"：直播已结束
  默认 "living"。
src: string
播放地址。支持：
- HLS：.m3u8（优先使用 hls.js，Safari 等也支持原生 HLS）
- 其他浏览器原生支持的格式（例如 .mp4）
poster: string
视频封面地址。默认空字符串。

播放控制

volume: number
默认音量，范围 0 ~ 1，默认 1。
muted: boolean
初始是否静音。默认 false。
progress: number
初始播放进度（秒）。仅在点播模式下有效。默认 0。
controls: boolean
是否显示点播控制栏。默认 true。
- 对于 mode="live"，内部本身不会显示进度条/播放按钮，controls 主要影响点播。
controlsList: Array | Object
控制栏显示项配置。
1. 数组写法（推荐）：
```
:controls-list="['play', 'volume', 'seek', 'fullscreen']"
```
  可选值：
  - "play"：播放/暂停按钮
  - "volume"：音量
  - "seek" / "progress"：进度条
  - "fullscreen"：全屏
2. 对象写法：
```
:controls-list="{
  play: true,
  volume: true,
  seek: true,
  fullscreen: false,
}"
```
  任意项设置为 false 即可隐藏。
autoplay: boolean | undefined
是否自动播放。
- 显式传 true 或 false 时按传入为准
- 不传时：直播模式默认尝试自动播放，点播默认不自动播放
seekable: boolean
是否允许用户拖动进度。默认 true。仅点播有效。
playbackRate: number
播放速度。默认 1.0。
loop: boolean
是否循环播放。仅点播有效。默认 false。
startTime: number
初始播放时间（秒）。仅点播有效。
- 若同时设置了 progress 和 startTime，优先使用 progress。

顶部栏 `topBar`

topBar 是一个对象，用于控制默认顶部栏展示内容。如果你自己通过 slot="top" 完全自定义顶部，则 topBar 不会生效。

默认结构（参见源码）：

topBar: {
  // 是否显示默认顶部栏
  show: false,
  // 展示参数
  option: {
    // 显示关注按钮
    showFollow: true,
    // 显示在线人数
    showAudience: true,
  },
  // 用户信息
  info: {
    avatar: '',
    name: '默认用户',
    isFollow: false,
  },
  // 在线人数
  audience: {
    count: 0,
  },
}

topBar 支持的字段：

topBar.show: boolean
是否显示顶部栏。默认 false。
topBar.option.showFollow: boolean
是否显示关注按钮。默认 true。
topBar.option.showAudience: boolean
是否显示在线人数。默认 true。
注意：在直播未开始或已结束状态下（liveStatus="not-started" | "ended"），组件内部会强制隐藏人数。
topBar.info.avatar: string
topBar.info.name: string
topBar.info.isFollow: boolean
topBar.audience: { count?: number } | number
在线人数，可以传数字或对象：
```
topBar: {
  audience: 1024,
  // 或
  audience: { count: 1024 },
}
```

弹幕配置 `danmaku`

danmaku 是一个对象，用于控制直播弹幕展示：

danmaku: {
  enabled: true,
  maxVisible: 50,
  messages: [],
  notice: '',
}

danmaku.enabled: boolean
是否启用弹幕。默认 true。只在直播模式且 enabled=true 时才会显示。
danmaku.maxVisible: number
本地最大可见弹幕条数。默认 50。
danmaku.messages: Array<{ id?: string|number, user?: { name?: string, avatar?: string }, content: string }>
外部传入的弹幕列表。组件内部也会把通过 receiveMessage 收到的弹幕追加在后面。

danmaku.notice: string
直播间公告，会显示在弹幕列表上方一条高亮文字。例如：

<ag-live-player
  :danmaku="{
    enabled: true,
    maxVisible: 50,
    messages: demoDanmaku,
    notice: '欢迎来到直播间，严禁发布违法违规内容'
  }"
/>

主题和背景

theme: string
播放器主题色（用于按钮、icon 高亮等）。默认 #fadfa3。
background: string
播放器背景（CSS background 值），默认：
```
linear-gradient(90deg, #2f1d17 0%, #1e2326 100%)
```

插槽（slots）

顶部自定义：`top`

<ag-live-player :top-bar="topBarConfig">
  <template #top>
    <!-- 完全自定义顶部栏内容 -->
  </template>
</ag-live-player>

使用 #top 时，内部默认的 TopBar 不会渲染。

底部自定义：`bottom`

<ag-live-player mode="live">
  <template #bottom>
    <!-- 自定义底部操作区域，例如输入框、点赞按钮等 -->
  </template>
</ag-live-player>

直播模式下，未提供 #bottom 时会渲染默认的底部输入框组件 BottomBar。

直播未开始：`live-not-started`

<ag-live-player
  mode="live"
  :live-status="liveStatus"
>
  <template #live-not-started>
    <div class="live-placeholder">直播即将开始，敬请期待</div>
  </template>
</ag-live-player>

当 mode="live" 且 liveStatus === 'not-started' 时：

会渲染 live-not-started 插槽内容
隐藏播放器画面、弹幕、底部输入区
顶部仍会展示标题/关注/关闭按钮，但人数隐藏

直播结束：`live-ended`

<ag-live-player
  mode="live"
  :live-status="liveStatus"
>
  <template #live-ended>
    <div class="live-placeholder">本场直播已结束，感谢观看</div>
  </template>
</ag-live-player>

当 mode="live" 且 liveStatus === 'ended' 时：

会渲染 live-ended 插槽内容
隐藏播放器画面、弹幕、底部输入区
顶部人数同样隐藏

加载状态自定义：`loading`

<ag-live-player>
  <template #loading>
    <!-- 自定义 Loading 内容 -->
    <div>加载中，请稍候...</div>
  </template>
</ag-live-player>

当组件处于加载/缓冲/错误状态且 overlayVisible 为 true 时，会在遮罩层中渲染该插槽。

事件（events）

`state-change`

播放器内部通过 this.$emit('state-change', s) 抛出状态变化事件，其中 s 可能的取值包括：

初始化相关：
- "init"：每次 src 或 mode 变化、重新初始化播放器时触发
- "ready"：可以开始播放时触发（canplay 或 HLS Manifest 解析完成）
播放过程：
- "play"：调用 play() 或用户点击播放后触发
- "pause"：暂停时触发
- "playing"：真正进入播放状态时触发
- "waiting"：缓冲中、网络抖动时触发
错误：
- "error"：不可恢复的错误（HLS fatal error 或 video error）时触发
结束：
- "ended"：点播播放完成时触发（mode="vod"）
- "live-ended"：直播播放结束时触发（mode="live"）

示例：

<ag-live-player mode="live" @state-change="onLiveState" />

methods: {
  onLiveState(s) {
    if (s === 'live-ended') {
      this.liveStatus = 'ended';
    }
  },
}

`send-message`

直播模式下，用户在默认底部输入框发送弹幕时触发：

<ag-live-player mode="live" @send-message="onSend" />

methods: {
  onSend(content) {
    console.log('用户发送弹幕:', content);
    // 这里可以把弹幕发到服务器，再广播给其他用户
  },
}

`like`

直播模式下，用户点击点赞时触发：

<ag-live-player mode="live" @like="onLike" />

payload 内容由内部点赞组件决定，通常包含一些客户端侧的信息（如时间戳、位置等），可按需上报。

顶部栏相关事件

当使用默认 TopBar 时，组件会向外抛出以下事件：

click-user：点击顶部用户区域时触发，参数为 topBar.info 或兼容字段
click-follow：点击关注按钮时触发，参数包含 action: 'follow' | 'unfollow'
click-close：点击关闭按钮时触发

示例：

<ag-live-player
  mode="live"
  :top-bar="headerInfo"
  @click-user="onClickUser"
  @click-follow="onClickFollow"
  @click-close="onClickClose"
/>

methods: {
  onClickUser(info) {
    console.log('点击用户信息:', info);
  },
  onClickFollow(payload) {
    console.log('点击关注按钮:', payload.action);
  },
  onClickClose() {
    console.log('点击关闭');
  },
}

公开方法（通过 ref 调用）

给组件设置 ref 后，可以在父组件中调用以下方法：

<ag-live-player ref="player" mode="vod" :src="vodSrc" />

methods: {
  play() {
    this.$refs.player && this.$refs.player.play();
  },
}

`play(): void`

开始播放。如果浏览器的自动播放策略限制了播放，内部会捕获异常并静默处理，不会抛出错误。

`pause(): void`

暂停播放。

`getCurrentTime(): number`

获取当前播放时间（秒）。如果尚未就绪，返回 0。

`setCurrentTime(t: number): void`

设置当前播放时间（秒）。仅在点播模式下生效；直播模式下会直接返回。

`setVolume(v: number): void`

设置音量，范围 0 ~ 1。

`mute(): void`

静音。

`unmute(): void`

取消静音。

`toggleMute(): void`

切换静音状态。

`togglePlay(): void`

切换播放/暂停。注意：直播模式下，组件默认不通过点击画面切换播放，需手动调用。

`toggleFullscreen(): void`

切换全屏状态。优先使用容器元素全屏，部分移动浏览器可能退化为 video 元素全屏。

`receiveMessage(msg: string | { id?, user?, content }): void`

向当前直播间插入一条弹幕。常用于：

自己发送消息后，立刻在本地显示
收到服务端下发的弹幕消息时渲染

示例：

methods: {
  onSend(content) {
    const p = this.$refs.live;
    if (!p || typeof p.receiveMessage !== 'function') return;
    p.receiveMessage({
      id: Date.now() + '_' + Math.random(),
      user: { name: '我', avatar: 'https://example.com/avatar.png' },
      content,
    });
  },
}

msg 说明：

如果是字符串，会被当作 content 处理
如果是对象：
- id 可选，不传则自动生成
- user 可选，形如 { name?: string, avatar?: string }
- content 必填

开发和构建

本仓库使用 Vite 打包 Vue2 组件库。

本地开发示例页面：

npm install
npm run dev

打包发布版本：

npm run build

构建产物输出在 dist/ 目录：

dist/agplayer.esm.js：ES Module 版本
dist/agplayer.umd.js：UMD 版本
dist/style.css：样式文件

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

ag-live-player

安装

快速上手

最简直播示例

点播示例

组件标签

ag-live-player 属性（props）

基础

播放控制

顶部栏 topBar

弹幕配置 danmaku

主题和背景

插槽（slots）

顶部自定义：top

底部自定义：bottom

直播未开始：live-not-started

直播结束：live-ended

加载状态自定义：loading

事件（events）

state-change

send-message

like

顶部栏相关事件

公开方法（通过 ref 调用）

play(): void

pause(): void

getCurrentTime(): number

setCurrentTime(t: number): void

setVolume(v: number): void

mute(): void

unmute(): void

toggleMute(): void

togglePlay(): void

toggleFullscreen(): void

receiveMessage(msg: string | { id?, user?, content }): void

开发和构建

顶部栏 `topBar`

弹幕配置 `danmaku`

顶部自定义：`top`

底部自定义：`bottom`

直播未开始：`live-not-started`

直播结束：`live-ended`

加载状态自定义：`loading`

`state-change`

`send-message`

`like`

`play(): void`

`pause(): void`

`getCurrentTime(): number`

`setCurrentTime(t: number): void`

`setVolume(v: number): void`

`mute(): void`

`unmute(): void`

`toggleMute(): void`

`togglePlay(): void`

`toggleFullscreen(): void`

`receiveMessage(msg: string | { id?, user?, content }): void`