@composy/device-vue

@composy/device-vue

@composy/device-vue 是 @composy/device-core 的 Vue 3 适配层，提供：

• 原生 Vue Plugin 接入
• @composy/engine-core plugin 接入
• composables、directives、TSX 组件
• 统一的 DeviceRuntime，避免插件、指令和组合式函数各自重复创建 detector

本包不实现设备检测算法，所有检测、模块生命周期、缓存和性能策略都来自 @composy/device-core。Vue 层只负责依赖注入、响应式状态、生命周期释放、组件和指令桥接。

安装

pnpm add @composy/device-vue @composy/device-core vue

原生 Vue Plugin

import { createDevicePlugin } from '@composy/device-vue'
import { createApp } from 'vue'
import App from './App.vue'

const app = createApp(App)

app.use(
  createDevicePlugin({
    enableResize: true,
    enableOrientation: true,
    modules: ['network', 'battery'],
    globalComponents: true,
    globalDirectives: true,
  })
)

app.mount('#app')

createDeviceVuePlugin 和 createNativeDevicePlugin 是同一条原生 Vue Plugin 安装链的别名入口。

如果需要使用核心包的优化版检测器，可以通过第二个重载直接注入；Vue runtime 依赖 DeviceDetectorRuntimePort，不会把实现锁定为具体的 DeviceDetector 类：

import { OptimizedDeviceDetector } from '@composy/device-core'
import { createDevicePlugin } from '@composy/device-vue'

const detector = new OptimizedDeviceDetector({
  enableResize: true,
  enableOrientation: true,
})

app.use(createDevicePlugin(detector))

外部 detector 默认由调用方负责销毁；如果需要把销毁责任转移给 runtime，使用 createDeviceRuntime(options, detector, 'owned')。

Engine Plugin

import { createDeviceEnginePlugin } from '@composy/device-vue'

export const devicePlugin = createDeviceEnginePlugin({
  modules: ['network', 'battery'],
  debug: true,
})

engine plugin 会优先复用已经安装到 Vue App 上的 DeviceRuntime。如果 App 尚未创建，则先在 engine 侧持有 runtime，等 app:created 后再挂载到 Vue。

Composables

import { useBattery, useDevice, useNetwork } from '@composy/device-vue'

const device = useDevice()
const battery = useBattery()
const network = useNetwork()

device.refresh()
await battery.loadModule()
await network.loadModule()

当应用已经通过 plugin 安装 runtime 时，这些 composables 会复用同一个 detector 和模块引用计数；未安装 plugin 时，才会创建本地 runtime。

原生 Vue Plugin 创建的 runtime 由插件拥有并在 App unmount 时销毁；通过 installDeviceRuntime(app, runtime) 注入的外部 runtime 默认为 borrowed，不会被 Vue App 擅自销毁。通过 createDeviceRuntime(options, detector) 注入的外部 detector 也默认为 borrowed，runtime 销毁时不会反向销毁调用方持有的 detector；需要转移责任时显式传入 'owned'。

目录结构

src/
  components/
  composables/
  context/
  directives/
  plugin/
  plugins/
  index.ts

• context/：注入 key 与 runtime 访问入口
• directives/：指令层 runtime 解析与各类设备指令
• plugin/：原生 Vue Plugin 与 runtime 安装逻辑
• plugins/：engine plugin 包装层
• composables/：基于 runtime 的组合式能力
• composables/helpers.ts：Vue 适配层内部的类型守卫与浏览器能力窄类型

架构约定

• 组合式函数通过 createComposableRuntimeManager() 获取共享 DeviceRuntime。
• 需要模块能力时优先使用 const lease = await runtime.acquireModule<T>(name)，在卸载时调用幂等的 lease.release()。
• runtime.ensureModule() / runtime.releaseModule() 仅作为兼容旧代码的桥接 API，并支持加载中的释放。
• 新能力优先在 @composy/device-core 实现；Vue 包只新增 composable、directive 或组件包装。
• 事件订阅使用 core 模块公开的 on/off 协议，并在组件卸载时释放。

主要导出

• createDevicePlugin
• createDeviceVuePlugin
• createNativeDevicePlugin
• createDeviceEnginePlugin
• devicePlugin
• useDevice
• useBattery
• useNetwork
• useGeolocation
• useOrientation
• useBreakpoints
• useClipboard
• useMediaCapabilities
• useOrientationLock
• useVibration
• useWakeLock
• usePerformance
• useVisibility
• usePreferredColorScheme
• usePreferredLanguage
• useDeviceDetector
• useDeviceRuntime

指令与组件

createDevicePlugin({ globalComponents: true, globalDirectives: true }) 时会全局注册;也可按需导入:

开发验证

pnpm --dir packages/vue run type-check
pnpm --dir packages/vue run lint:check
pnpm --dir packages/vue run build

构建产物与 core 保持一致，包含 es/、esm/、lib/ 和 dist/。

Vue 包使用 ldesign-builder 的内置 rolldown，并将 vue 与 @composy/device-core 保持为 external，避免把框架或 core 重复打进适配层。构建结束后会自动归一化声明文件、生成真实压缩 UMD、补齐 lib/package.json 并校验所有公开入口。

ESLint 与 TypeScript 权威配置位于 .ldesign/eslint.config.js、.ldesign/tsconfig.json 和 .ldesign/tsconfig.typecheck.json；包根配置路径保留为兼容转发入口。

pnpm --dir packages/vue run outputs:check

License

MIT

相关链接

• @composy/device-core —— 框架无关的核心实现层
• LDesign Device 总览 —— 家族结构、根编排命令与文档/Playground 入口

Browser lifecycle sharing

useVisibility reuses Core's BrowserLifecycle lease. Multiple Vue components therefore share one native visibilitychange listener, and unmounting one component does not affect the remaining subscribers.