@zjp179280/web-call-components

@zjp179280/web-call-components

基于 MQTT 信令 + WebRTC 的一对一语音 / 视频通话组件，封装为原生 Web Component，Vue2 / Vue3 / 原生 HTML 均可直接使用。

• 语音通话：<wc-audio-call>
• 视频通话：<wc-video-call>

信令逻辑完整移植自原项目 mqtStore.js 的一对一通话路径（type 0/1/5/6/7/8/9/10/11/1012/1014/1015），去除了 Pinia / Element Plus / 全局 store 依赖，所有外部配置通过 config 属性注入。

一、安装

npm install @zjp179280/web-call-components

本地开发时可通过 file:../web-call-components 直接链接源码包（见同级 web-call-components-demo）。

二、最快上手（Vue3）

<template>
  <button @click="start">发起语音通话</button>

  <wc-audio-call
    v-if="show"
    ref="callEl"
    peer-name="设备A"
    @call-status-change="onCall"
    @mqtt-status-change="onMqtt"
    @error="onError"
    @close="show = false"
  ></wc-audio-call>
</template>

<script setup>
import { ref, nextTick } from 'vue'
import '@zjp179280/web-call-components'   // 样式已内联进各元素 Shadow DOM，无需再引入 css

const show = ref(false)
const callEl = ref(null)

async function start() {
  show.value = true
  await nextTick()
  // 对象配置必须以 DOM property 方式注入（不能写在模板属性里）
  callEl.value.config = {
    mqtt: {
      url: 'ws://your-mqtt-broker:8083/mqtt',
      clientId: 'Web~10001',
      username: '10001',
      password: '你的token'
    },
    rtc: { iceServers: [{ urls: 'stun:stun.l.google.com:19302' }] },
    user: { id: '10001', name: '管理员' },
    targetId: '设备号'
  }
}

// 注意：自定义元素 DOM 事件的载荷统一放在 event.detail[0]（Vue 把 emit 参数放进 detail 数组）
function onCall(e) { console.log('通话状态', e.detail[0]) }
function onMqtt(e) { console.log('MQTT', e.detail[0]) }
function onError(e) { console.error(e.detail[0]) }
</script>

视频通话同理，把标签换成 <wc-video-call> 即可。

Vue3 + Vite 工程必做：在 vite.config.js 告诉编译器 wc- 开头的标签是原生自定义元素（否则对象 props / 事件会被当成 Vue 组件处理而异常）：

// vite.config.js
import vue from '@vitejs/plugin-vue'
export default {
  plugins: [
    vue({ template: { compilerOptions: { isCustomElement: (t) => t.startsWith('wc-') } } })
  ]
}

Vue3 + vue.config（CLI / webpack）则用 compilerOptions.isCustomElement 链式配置。

二·五、推荐：先连接 MQTT，确认成功后再拨号（两步法）

组件支持注入一个已连接好的 CallEngine，把“连 MQTT”和“拨号”拆开，便于先校验连接：

import { CallEngine } from '@zjp179280/web-call-components'

let engine = null

// 第一步：连接 MQTT
async function connectMqtt(config) {
  engine = new CallEngine(config)
  engine.on('mqttStatus', (s) => console.log('MQTT', s.status, s.message))
  await engine.connect()   // 会等待真正连上并订阅 p2p 主题；失败会抛错
}

// 第二步：拨号（复用上面的连接，组件不会重复连 MQTT）
async function startVoice(config) {
  const el = document.createElement('wc-audio-call')
  el.engine = engine        // 注入已连接引擎（关键）
  el.config = config        // 仍需传 config，用于 targetId / user 等
  document.body.appendChild(el)
}

• 传入 engine 后，组件不再自建 MQTT 连接，通话结束也不会断开这条连接，可连续拨打。
• 不传 engine 时，组件会在挂载后用 config 自行连接（一步法，向后兼容）。
• 完整可运行示例见同级工程 web-call-components-demo（页面上就是「① 连接 MQTT → ② 发起通话」两个按钮）。

三、在 Vue2 中使用

Vue2 需要告诉编译器这些标签是原生自定义元素：

// main.js
import Vue from 'vue'
import App from './App.vue'
import '@zjp179280/web-call-components'   // 样式已内联进各元素 Shadow DOM，无需再引入 css

Vue.config.ignoredElements = [/^wc-/]

new Vue({ render: h => h(App) }).$mount('#app')

<template>
  <wc-audio-call
    v-if="show"
    ref="call"
    peer-name="设备A"
    @call-status-change.native="onCall"
    @mqtt-status-change.native="onMqtt"
    @close.native="show = false"
  ></wc-audio-call>
</template>

<script>
export default {
  data: () => ({ show: false }),
  methods: {
    start() {
      this.show = true
      this.$nextTick(() => {
        this.$refs.call.config = { /* 同上方 config */ }
      })
    }
  }
}
</script>

Vue2 监听原生自定义事件需要加 .native。

四、在原生 HTML 中使用

<script type="module">
  import '@zjp179280/web-call-components'   // 样式已内联，无需引 css

  const call = document.createElement('wc-audio-call')
  call.peerName = '设备A'
  call.config = {
    mqtt: { url: 'ws://your-mqtt-broker:8083/mqtt', clientId: 'Web~1', username: '1', password: 'token' },
    rtc: { iceServers: [{ urls: 'stun:stun.l.google.com:19302' }] },
    user: { id: '1', name: '管理员' },
    targetId: '设备号'
  }
  call.addEventListener('call-status-change', (e) => console.log(e.detail[0]))
  call.addEventListener('close', () => call.remove())
  document.body.appendChild(call)
</script>

五、完整 config 配置项

六、事件

组件派发以下 DOM 事件（CustomEvent）。Vue 自定义元素约定：emit 的参数被放进 event.detail 数组，业务载荷取 event.detail[0]（close 无载荷）：

el.addEventListener('call-status-change', (e) => {
  const s = e.detail[0]          // ← 载荷在数组首项
  console.log(s.message, s.errorMessage)
})

直接使用 CallEngine 实例（不走 DOM 事件）时，engine.on('callStatus', s => ...) 回调里的 s 就是载荷本身，无需 [0]。

七、暴露的方法

通过 ref 调用：

callEl.value.hangup()   // 通话中挂断
callEl.value.cancel()   // 拨打中取消
callEl.value.close()    // 关闭面板

八、内置校验（重要）

组件在发起前会依次做以下校验，并通过 mqtt-status-change / call-status-change / error 反馈：

1. MQTT 地址校验：缺少 mqtt.url 或不是 ws/wss 开头 → 直接报错，不发起呼叫。
2. MQTT 连接校验：连接成功 / 重连中 / 断开 / 失败都会实时回传状态徽标。
3. HTTP 配置校验：若未配置 http.baseURL，控制台给出警告（不阻断，因为通话走 MQTT）。
4. 媒体设备校验：摄像头/麦克风权限被拒绝、设备不存在、被占用时，回传中文错误提示。
5. targetId 校验：缺少对端设备 ID 时提示。
6. 30 秒无应答：自动转为 no_answer 并取消呼叫。
7. 资源释放：关闭/卸载时停止轨道、关闭 PeerConnection、断开音频元素。

九、样式自定义（CSS 变量 + ::part + 头像）

组件运行在 Shadow DOM 内：宿主页面的普通 CSS 选择器进不去（因此不会被全局样式污染，也不会泄漏样式），但有两条标准通道可以深度定制。所有样式已随 JS 内联进各自定义元素，无需、也不要再引入任何 css 文件。

9.1 方式一：覆盖 CSS 变量（推荐）

CSS 自定义属性会穿透 Shadow 边界。在你的页面里对元素本身（或 :root）赋值即可，随改随生效：

/* 单个组件定制 */
wc-audio-call {
  --wc-panel-bg: #0b1f33;        /* 面板底色（默认深蓝 rgb(0,29,55)） */
  --wc-primary: #13c2c2;         /* 主色：确定按钮、拨打波点、头像渐变起点 */
  --wc-accent: #ffd000;          /* 底部 L 形切角颜色 */
  --wc-corner-size: 22px;        /* 切角大小，设 0 可隐藏切角 */
  --wc-avatar-size: 84px;        /* 头像大小 */
}

/* 全局统一改两个组件 */
:root {
  --wc-hangup: #e53935;
  --wc-panel-radius: 12px;
}

可用变量（均在内部 :host 上给了默认值）：

9.2 方式二：::part() 精准改结构元素

组件已把关键结构通过 part 暴露，可用 ::part() 直接改某个部位（背景、模糊、边框等）：

/* 视频底部控制条加毛玻璃 */
wc-video-call::part(control-bar) { backdrop-filter: blur(8px); background: linear-gradient(to top, rgba(0,0,0,.8), transparent); }
/* 自定义“确定”按钮 */
wc-audio-call::part(btn-confirm) { background: #00b359; border-radius: 8px; }
/* 头像外圈 */
wc-audio-call::part(avatar) { border: 2px solid #fff; box-shadow: 0 0 12px rgba(255,255,255,.6); }

暴露的 part：

• 公共：panel header title-plate title title-line close mqtt avatar peer-name peer-code status-text btn（以及具体按钮 btn-mute btn-speaker btn-hangup btn-cancel btn-confirm btn-camera）。
• 语音：另有 body peer top-controls stage wave duration。
• 视频：另有 stage banner（重连横幅）remote-video overlay pulse（脉冲环）local-pip local-video control-bar call-info。

提示：part="btn btn-mute" 这样的元素同时拥有两个 part 名——::part(btn) 命中所有按钮，::part(btn-mute) 只命中麦克风钮。

9.3 头像

三种方式（优先级从高到低）：

1. 属性传图片地址（推荐）：<wc-audio-call avatar-url="https://xxx/a.png">，或 JS el.avatarUrl = url。
2. CSS 变量铺图：wc-audio-call { --wc-avatar-image: url(https://xxx/a.png); }。
3. 都不配时，显示 peer-name 的第一个字，底为 --wc-avatar-bg 渐变。

9.4 视频本地小窗

通话中右上角（默认定位，可拖到舞台任意位置）的本地预览窗，尺寸用 --wc-pip-width / --wc-pip-height 调整，边框 / 镜像可通过 ::part(local-pip)、::part(local-video) 覆盖；关闭摄像头时本地窗会自动变暗。

十、目录结构

web-call-components/
├── src/
│   ├── core/CallEngine.js          # MQTT+WebRTC 信令引擎（移植自 mqtStore）
│   ├── components/
│   │   ├── AudioCall.ce.vue        # <wc-audio-call>
│   │   └── VideoCall.ce.vue        # <wc-video-call>
│   ├── styles/theme.css            # 集中管理的设计变量与公共样式
│   └── index.js                    # 注册自定义元素
└── dist/                           # 构建产物

十一、发布到 npm

⚠️ 不要把账号密码写进任何文件。请在 npmjs.com 生成 Automation Token。

# 1. 登录（推荐用 token）
npm login

# 2. 构建
npm run build

# 3. 发布（首次发布需要 --access public）
npm publish --access public

发布后，业务项目即可 npm install @zjp179280/web-call-components 使用。

十二、本地测试项目111

同级目录 web-call-components-demo 是一个 Vue3 测试工程：

cd web-call-components-demo
npm install
npm run dev    # 默认 http://localhost:5199

打开页面后填写 MQTT 地址、clientId、对端设备号，点击「发起语音/视频通话」即可联调。