sldz-easyplayer
v1.0.4
Published
基于 EasyPlayerPro SDK 封装的 Vue 3 视频播放器组件,支持直播流播放、云台控制、语音对讲、多清晰度切换等功能
Downloads
22
Maintainers
Readme
sldz-easyplayer
基于 EasyPlayerPro SDK 封装的 Vue 3 视频播放器组件,支持直播流播放、云台控制、语音对讲、多清晰度切换等功能。
前置依赖
- EasyPlayerPro SDK:必须引入,确保
window.EasyPlayerPro全局变量可用(见下方 SDK 引入说明) - Vue 3:
>=3.2.0 - @imengyu/vue3-context-menu(可选):用于右键菜单功能
- recorder-core(可选):用于语音对讲功能
安装
npm install sldz-easyplayer安装后终端会提示 SDK 文件路径。如未看到提示,SDK 文件位于:
node_modules/sldz-easyplayer/static/SDK 引入(重要)
EasyPlayerPro SDK 包含 WASM 等大文件,不能通过 import 引入,必须通过 <script> 标签加载。有两种方式:
方式一:手动引入(推荐)
步骤1:将 SDK 文件复制到你的 public/ 目录
# 在项目根目录执行
cp -r node_modules/sldz-easyplayer/static/* public/easy-player/
# Windows PowerShell:
Copy-Item -Recurse -Force node_modules/sldz-easyplayer/static/* public/easy-player/步骤2:在 index.html 的 <head> 中添加
<script src="./easy-player/EasyPlayer-pro.js"></script>这样 SDK 会在页面加载时自动初始化 window.EasyPlayerPro,组件内部会自动检测并使用。
方式二:动态加载
不需要修改 index.html,在代码中调用 loadSDK() 动态注入:
// main.js 或 App.vue
import { loadSDK } from "sldz-easyplayer";
// 先复制 SDK 到 public/easy-player/,然后:
await loadSDK(); // 默认加载 ./easy-player/EasyPlayer-pro.js
// 或自定义路径:
await loadSDK("/your-path/EasyPlayer-pro.js");方式三:自定义 SDK 源
如果你将 SDK 部署在 CDN 或其他路径:
<!-- index.html -->
<script src="https://your-cdn.com/EasyPlayer-pro.js"></script>组件内部会自动检测 window.EasyPlayerPro,无需额外操作。
SDK 加载工具函数
import { loadSDK, isSDKReady, waitForSDK } from "sldz-easyplayer";
// 动态加载 SDK
await loadSDK("./easy-player/EasyPlayer-pro.js");
// 检查 SDK 是否已就绪
if (isSDKReady()) { /* ... */ }
// 等待 SDK 就绪(适用于 <script> 标签异步加载场景)
await waitForSDK(10000); // 最多等 10 秒基本使用
1. 全局注册(推荐)
import { createApp } from "vue";
import App from "./App.vue";
import { install as SldzEasyPlayer } from "sldz-easyplayer";
import "sldz-easyplayer/dist/style.css";
const app = createApp(App);
app.use(SldzEasyPlayer, {
// 全局配置视频流获取方法(必需)
getVideoUrl: async (data) => {
// data: { deviceCode, channelCode, quality, ... }
// 返回: { url: "http://xxx/live/stream.flv" }
const res = await yourApi.getPlayUrl(data);
return { url: res.data.url };
},
// 全局云台控制回调(可选)
onPtzControl: (command, data) => {
yourApi.ptzControl({ ...data, ptzDirection: command });
},
// 全局语音对讲API(可选,启用语音对讲功能时必需)
voiceIntercomApi: {
start: async (data) => {
const res = await yourApi.startVoiceIntercom(data);
return { data: res.data }; // { taskId, ip, port, testDomain }
},
stop: async (data) => {
await yourApi.stopVoiceIntercom(data);
},
wsUrlBuilder: (data) => {
return `wss://${data.testDomain || data.ip + ":" + data.port}`;
},
},
// 全局消息提示服务(可选,默认使用 console)
messageService: {
error: (msg) => console.error(msg),
success: (msg) => console.log(msg),
},
// 全局模态框服务(可选,用于语音对讲冲突确认)
modalService: {
confirm: ({ title, content, onOk, onCancel }) => {
if (confirm(title + "\n" + content)) onOk();
else onCancel();
},
},
});
app.mount("#app");2. 组件内直接使用
<template>
<EasyPlayer :data="deviceData" :customer-get-video-url="getVideoUrl" @close="onClose" @play="onPlay" />
</template>
<script setup>
import { EasyPlayer } from "sldz-easyplayer";
import "sldz-easyplayer/dist/style.css";
const deviceData = {
deviceCode: "D001",
channelCode: "C001",
channelStatus: "Y", // Y=在线, N=离线
channelName: "前门摄像头",
ptzFlag: 1, // 1=支持云台控制
voiceFlag: 1, // 1=支持语音对讲
};
const getVideoUrl = async (data) => {
const res = await fetch("/api/video/getPlayUrl", {
method: "POST",
body: JSON.stringify(data),
});
const result = await res.json();
return { url: result.data.url };
};
const onClose = () => console.log("播放器关闭");
const onPlay = () => console.log("开始播放");
</script>Props
| Prop | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| data | Object | 是 | - | 设备参数,包含 deviceCode, channelCode, channelStatus 等 |
| customerGetVideoUrl | Function | 否 | null | 自定义获取视频流地址,需返回 Promise<{url}> |
| excludeFeatures | Array | 否 | [] | 需要隐藏的功能按钮 |
| visibleHeader | Boolean | 否 | true | 是否显示头部标题栏 |
| warning | Boolean | 否 | false | 是否显示预警按钮 |
| closeHeader | Boolean | 否 | true | 是否显示关闭按钮 |
| visibleContextMenu | Boolean | 否 | false | 是否启用右键菜单 |
| loadingConfig | Object | 否 | {} | 加载状态自定义配置 |
| onPtzControl | Function | 否 | null | 云台控制回调 (command, data) => void |
| voiceIntercomApi | Object | 否 | null | 语音对讲API配置 |
| messageService | Object | 否 | null | 消息提示服务 { error, success, warning, info } |
| modalService | Object | 否 | null | 模态框服务 { confirm } |
data 对象结构
{
deviceCode: "", // 设备编码
channelCode: "", // 通道编码
channelStatus: "", // "Y"=在线, "N"=离线
channelName: "", // 通道名称(显示在头部)
deviceName: "", // 设备名称
ptzFlag: 0, // 1=支持云台控制
voiceFlag: 0, // 1=支持语音对讲
}excludeFeatures 可选值
audio, record, quality, screenshot, mediaInfo, fullscreen, continuousScreenshot, playPause, stopPlay, ptzControl, voiceIntercom
voiceIntercomApi 对象结构
{
start: async (data) => { return { data: { taskId, ip, port, testDomain } } },
stop: async (data) => { },
wsUrlBuilder: (data) => "wss://xxx:port" // 可选,不配则用 data.ip:port 或 data.testDomain
}Events
| 事件 | 参数 | 说明 |
|------|------|------|
| close | - | 播放器关闭时触发 |
| play | - | 视频开始播放时触发 |
| clickHandle | { ...data } | 单击播放器时触发 |
| warn | { file } | 点击预警按钮时触发,file 为截图 File 对象 |
Slots
| 插槽 | 作用域参数 | 说明 |
|------|-----------|------|
| loading | { loadingState } | 自定义加载状态展示 |
Expose 方法
| 方法 | 参数 | 说明 |
|------|------|------|
| getPlayUrl() | - | 重新获取流地址并播放 |
| handleSetMute(flag) | flag: boolean | 设置静音 |
| state | - | 播放器状态(reactive) |
| buttonStates | - | 按钮状态(reactive) |
| easyPlayer | - | 底层播放器实例 |
工具函数
import { resizeBlobToJpeg, loadSDK, isSDKReady, waitForSDK } from "sldz-easyplayer";
// 截图缩放
const result = await resizeBlobToJpeg(blob, {
maxWidth: 2560,
maxHeight: 1440,
quality: 0.92,
});
// result: { blob, dataUrl, format, quality, timestamp, width, height, size }
// SDK 加载
await loadSDK(); // 动态加载 SDK
isSDKReady(); // 检查是否就绪
await waitForSDK(10000); // 等待就绪(超时10秒)配置优先级
组件级别的 Props 优先级高于 Plugin 全局配置:
customerGetVideoUrl (Prop) > getVideoUrl (Plugin) > 报错
在原项目 sldz-wuliangye-web 中迁移
原项目已有 <script src="./easy-player/EasyPlayer-pro.js"></script>,SDK 已就绪,无需额外操作。只需:
// main.js
import { install as SldzEasyPlayer } from "sldz-easyplayer";
import "sldz-easyplayer/dist/style.css";
import { postAction } from "@/api/index";
import { decryptBase64 } from "@/utils/encrypt";
app.use(SldzEasyPlayer, {
getVideoUrl: async (data) => {
const result = await postAction("/api/video/getPlayUrl", {
deviceCode: data.deviceCode,
channelCode: data.channelCode,
quality: data.quality,
videoType: 1,
});
return { url: decryptBase64(result?.data?.url) };
},
onPtzControl: (command, data) => {
postAction("/api/ptzControl", {
channelCode: data.channelCode,
deviceCode: data.deviceCode,
ptzDirection: command,
ptzSpeed: 2,
});
},
voiceIntercomApi: {
start: (data) => postAction("/audio/operations/startVoiceIntercom", data),
stop: (data) => postAction("/audio/operations/endTask", data),
},
messageService: {
error: (msg) => message.error(msg),
success: (msg) => message.success(msg),
},
modalService: {
confirm: Modal.confirm,
},
});发布到 npm
cd E:\DX\sldz-easyplayer
npm run build
npm login
npm publishLicense
MIT
AI生成
