sldz-easyplayer 1.0.0

package/README.md

@@ -0,0 +1,260 @@
+---
+AIGC:
+  ContentProducer: '001191110102MAD55U9H0F10002'
+  ContentPropagator: '001191110102MAD55U9H0F10002'
+  Label: '1'
+  ProduceID: '14ca8aa2-c7b2-482c-b03c-8f13cdd19b05'
+  PropagateID: '14ca8aa2-c7b2-482c-b03c-8f13cdd19b05'
+  ReservedCode1: '055e96d0-8585-46ef-8baa-c2eb829f3e74'
+  ReservedCode2: '055e96d0-8585-46ef-8baa-c2eb829f3e74'
+---
+
+# sldz-easyplayer
+
+基于 [EasyPlayerPro](https://github.com/EasyDSS/EasyPlayerPro) SDK 封装的 Vue 3 视频播放器组件，支持直播流播放、云台控制、语音对讲、多清晰度切换等功能。
+
+## 前置依赖
+
+1. **EasyPlayerPro SDK**：需在使用前引入，确保 `window.EasyPlayerPro` 全局变量可用
+2. **Vue 3**：`>=3.2.0`
+3. **@imengyu/vue3-context-menu**（可选）：用于右键菜单功能
+4. **recorder-core**（可选）：用于语音对讲功能
+
+## 安装
+
+```bash
+npm install sldz-easyplayer
+```
+
+## 基本使用
+
+### 1. 全局注册（推荐）
+
+```js
+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) => {
+      // 根据 start 返回的数据构建 WebSocket URL
+      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. 组件内直接使用
+
+```vue
+<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 对象结构
+
+```js
+{
+  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 对象结构
+
+```js
+{
+  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` | - | 底层播放器实例 |
+
+## 工具函数
+
+```js
+import { resizeBlobToJpeg } from "sldz-easyplayer";
+
+// 将图片 Blob 缩放至指定尺寸并输出 JPEG
+const result = await resizeBlobToJpeg(blob, {
+  maxWidth: 2560,
+  maxHeight: 1440,
+  quality: 0.92,
+});
+// result: { blob, dataUrl, format, quality, timestamp, width, height, size }
+```
+
+## 配置优先级
+
+组件级别的 Props 优先级高于 Plugin 全局配置：
+
+`customerGetVideoUrl` (Prop) > `getVideoUrl` (Plugin) > 报错
+
+## 在原项目 sldz-wuliangye-web 中使用
+
+```js
+// 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
+
+```bash
+cd E:\DX\sldz-easyplayer
+npm run build
+npm login
+npm publish
+```
+
+## License
+
+MIT
+
+> AI生成