Electron Vue3 UIKit

Vue3 客户只需要安装本包和 vue。

正式 consumer 安装

Vue3 Electron 客户正式接入时，只需要：

• @xkit-yx/electron-callkit-vue3-uikit
• vue
• 自己的 Electron 宿主工程

registry 安装示意：

npm install @xkit-yx/electron-callkit-vue3-uikit vue

tarball 安装示意：

npm install ./xkit-yx-electron-callkit-vue3-uikit-<version>.tgz vue

不需要额外安装：

• @xkit-yx/electron-callkit-sdk
• @xkit-yx/callkit-vue3-core
• @xkit-yx/callkit-runtime-electron
• React UIKit

这些依赖已由正式包闭包带上。

formal tarball 不包含 native companion bundle，也不包含 nim.dll / libnim*.dylib / h_available.* / node-nim.node。packaged app 需要单独准备 CallKit native companion，并由宿主或 demo 自装 node-nim 提供 NIM V2 runtime。

建议客户在 Electron main process 最早位置调用 SDK 的自动装配 helper，减少手写环境变量：

const { app } = require('electron');
const {
  applyElectronCallKitRuntimeEnv,
} = require('@xkit-yx/electron-callkit-vue3-uikit/runtime-env');

applyElectronCallKitRuntimeEnv({
  app,
  strict: true,
});

它会按标准 Electron 路径自动发现 resources/native、node_modules/node-nim/build/Release 和 bundled node-addon，并注入 NECALL_DESKTOP_BRIDGE_PATH、NECALL_NODE_ADDON_PATH、NECALL_NIM_RUNTIME_PATH 及平台动态库搜索路径；不会把 NIM runtime 复制进 CallKit native 目录。

构建与验证平台

• 对外构建入口：cd Electron && npm run build:electron-vue3-uikit
• 正式发布产物命令：cd Electron && npm run package:electron-vue3-uikit
• 构建产物：Electron/out/release-artifacts/xkit-yx-electron-callkit-vue3-uikit-<version>.tgz
• 接入验证平台：Electron/example-vue3
• 审核重点：wrapper 只消费 @xkit-yx/callkit-vue3-core 与 @xkit-yx/callkit-runtime-electron，不再直连 monorepo 内部路径

当前 example 平台差异审核基线，统一以 specs/002-electron-callkit/contracts/electron-web-example-platform-baseline.md 为准。对 Vue3 UIKit 对应的 Electron example，固定口径是：

• 默认验证 external；managed public surface 保留，但 V2-only runtime 下托管 NIM 不作为当前 release baseline

• 与 Web Vue3 example 对齐时，只要求 shared 交集能力一致，不要求表层行为完全一致

• Web 保留群呼验证路径；Electron 群呼入口必须保持禁用态并明确标注“暂不支持”

• 本包内部依赖 @xkit-yx/electron-callkit-sdk

• 不需要额外安装 React UIKit

• 当前实现优先覆盖 1v1 UIKit 与 shared runtime/core 复用面

• 已发布 index.d.ts 类型入口

Web 对齐入口

Electron Vue3 UIKit 的 1v1 P0 对齐口径如下：

| Web Vue3 UIKit | Electron Vue3 UIKit | 说明 | |---|---|---| | CallViewProvider | CallViewProvider | 同名入口；Electron 通过 runtime/sdk 驱动 | | createCallkitRuntime() | createCallkitRuntime() | 同名；Web 创建 web runtime，Electron 创建 desktop runtime | | useCall() | useCall() | 同名；Electron 返回 provider 当前 runtime | | useCallState() | useCallState() | 同名；返回当前 1v1 视图状态 | | useCallkitRuntime() | useCallkitRuntime() | 同名；显式拿到 runtime | | uiConfig.switchCallTypeBtn | uiConfig.switchCallTypeBtn 或 switchCallTypeConfig | Electron 同时接受 Web 风格 alias 和 desktop 原生命名 | | position | position | 为 Web 兼容保留，但 desktop renderer 不消费该浮层定位参数 |

当前不提供 Web 同名 facade 的部分：

• Group UIKit / groupCall() / groupJoin()：Electron 本期仍不支持群呼
• 包级全局 call() / getCallInstance() / getGlobalCallRegistry() / useGroupCall()：这是 Web singleton + 群呼路径，Electron 不默认提供；请改用 runtime.call()、runtime.neCall 或模板内注入的 runtime
• neCallConfig 自动 setup：Web provider 会在挂载期自动 setup(neCallConfig)；Electron 需要宿主先完成 main/preload 装配，再由 runtime.setup() / runtime.login() 显式驱动，这是桌面 lifecycle 差异，不属于可透明复用的默认路径

正式包边界与宿主装配边界

本包的 formal package contract 只覆盖 renderer 侧：

• CallViewProvider
• createCallkitRuntime
• useCall
• useCallState

main/preload 宿主装配不属于本包的依赖树。当前 Electron/host-helper 仍是 workspace 内私有 helper，不作为单独发布包。

Electron packaged example 使用 npm consumer staging 安装本包 .tgz，因此 resources/app/node_modules/@xkit-yx/electron-callkit-vue3-uikit、嵌套 SDK 与 bundled node-addon 应来自 tarball 安装产物，而不是 workspace symlink 或 repo packages 副本。

因此，对外接入口径应固定为：

• 客户不需要复制 example 的 demo 页面逻辑
• 但客户需要按 Electron/example-vue3 的 main.js / preload.js 模板完成同等宿主装配职责
• 若交付的是源码包，可直接复用 Electron/host-helper/src/*
• 若交付的是纯 .tgz 接入说明，则应把 example 的 main/preload 当作宿主模板

Runtime lifecycle

createCallkitRuntime() 当前直接消费 sdk 的 public lifecycle contract：

• setup(config)
• login(config)
• logout()
• destroy()
• getDiagnostics()

runtime.state.diagnostics 会和 runtime.getDiagnostics() 保持同步，承载：

• mode
• readyState
• reason
• currentAccountId
• configuredAccountId
• setupCompleted

Desktop-only 增强能力

以下能力保留为 desktop-only，不进入 Web 兼容默认路径：

• diagnostics / bridge diagnostics / capability：用于判断 native bridge readiness、capability bit 和 ABI 状态
• native renderer：createVideoRenderer()、setLocalView()、setRemoteView() 绑定的是 renderer/window handle，不是 DOM element
• device enumeration / selection：摄像头、录音、播放设备枚举与切换能力
• managed lifecycle：setup() / login() / logout() 对应 Electron native runtime 的托管与非托管模式

业务如果要跨 Web/Electron 复用，默认只依赖 CallViewProvider、runtime 基础控制面和 CallState 交集；desktop-only 能力需要显式平台判断或 capability 判断。

Confirm 能力限制

• shared core 的 pendingSwitchCallType 确认 UI 已保留，Electron Vue3 CallViewProvider 会继续渲染“权限请求 / 同意 / 拒绝”流程
• JS sdk / runtime 会保留并透传 onCallTypeChange.state = 1 / 2 / 3，并消费 native/NIM 兜底信号刷新 UI
• enableSwitchVideoConfirm / enableSwitchAudioConfirm 只影响收到对端切换请求后的本端确认流程，不拦截本端主动发起的 switchCallType({ state: 1 })
• CALL_TYPE_CHANGE_STATE capability 只表示 bridge payload 可携带 state，不能单独当作目标 release 真机双端签收证据
• 接入方如果要对外宣称 state=1/3 与 Web 默认等价，需要同时满足 capability gate、formal artifact 验证和真机链路签收

Phase D 最小集成

Electron Vue3 的最小接入链路现在拆成三层：

1. main 进程通过 Electron/host-helper/src/runtime-env 调 applyRuntimeEnv({ app, env })，如需要防休眠再调 registerWakeLockHandler(...)
2. preload 通过 Electron/host-helper/src/preload 调 installPreloadBridge({ windowTarget: window, env: process.env, framework: 'vue3', ipcRenderer })
3. renderer 里创建 runtime，再把业务树挂到 CallViewProvider

默认主叫呼叫音和被叫来电铃声已随 UIKit 包发布到 src/assets/audios/；宿主如需自定义，可在 preload host 上提供 incomingRingUrl / outgoingRingUrl 或对应 asset path。

最小 renderer 结构示意：

const { h } = require('vue');
const {
  CallViewProvider,
  createCallkitRuntime,
} = require('@xkit-yx/electron-callkit-vue3-uikit');

const runtime = createCallkitRuntime();

module.exports = {
  setup() {
    return () => h(CallViewProvider, { runtime }, () => h('div', 'your app'));
  },
};

说明：

• Electron/host-helper 只负责 packaged env、wake lock 与 window.electronCallkitHost
• demo 登录页、首页、调试面板属于 example host 层，不属于 electron-vue3-uikit 的 formal contract
• 客户正式接入不需要复制 example 的 demo 页面逻辑，但需要按 example 模板完成等价的 main/preload 宿主装配

Integration modes

Managed

适用于 CallKit 托管 IM 登录：

await runtime.setup({
  appKey: 'your-app-key',
  accountId: 'your-account-id',
});

await runtime.login({
  accountId: 'your-account-id',
  accountToken: 'your-token',
});

External

适用于宿主先完成 native NIM 登录，再让 CallKit 复用已有 runtime：

await runtime.setup({
  appKey: 'your-app-key',
  accountId: 'your-account-id',
});

此时应通过 runtime.getDiagnostics() 或 runtime.state.diagnostics 判断当前是：

• external + ready
• external + not_ready

若仍处于 external-not-ready，依赖 IM ready 的 API 会直接失败，runtime 会把最新 diagnostics.reason 同步回 state，便于 UI 或宿主侧做引导和排障。

Public surface

• CallViewProvider
• createCallkitRuntime()
• useCall() / useCallState() / useCallkitRuntime()
• typed 1v1 contract: CallState、CallDeviceInfo、CallDeviceState、CallMediaState、CallDiagnostics、CallViewProviderProps、CallViewProviderRef、UseCallResult、UseCallStateResult、SwitchCallTypeConfig、Position
• shared core additive exports：CallOverlay、IncomingOverlay、OutgoingOverlay、InCallOverlay、VideoCanvasView、ensureCallViewStyles()、CALL_VIEW_STYLE_TEXT

统一口径以 specs/002-electron-callkit/contracts/electron-web-unified-public-contract.md 为准。

当前明确不提供：

• Group UIKit
• 包级全局 call() / getCallInstance() / getGlobalCallRegistry() facade
• Web 的 singleton registry / 群呼系导出

上面这些缺口继续按“群呼未支持”或“桌面 lifecycle / renderer 限制”管理，不在本期 1v1 Electron UIKit 完成条件内。