@composy/device-core

@composy/device-core 是 LDesign 设备能力包的主实现层，保持框架无关，负责设备检测、模块生命周期、事件分发、缓存和性能治理。Vue 等框架适配包只做薄封装，核心逻辑统一复用本包。

安装

pnpm add @composy/device-core

核心能力

• 设备类型检测：基于屏幕尺寸、视口宽度和 UserAgent 的多级判断。
• 屏幕方向监听：横屏、竖屏、视口变化事件统一输出。
• 浏览器与系统解析：返回浏览器、操作系统、像素比、触摸能力等信息。
• 内置模块系统：网络、电池、地理位置、媒体设备、媒体能力、剪贴板、振动、Wake Lock、方向锁定、性能与特性检测。
• 统一模块注册表：createDeviceModule()、createInitializedDeviceModule() 和 listDeviceModuleNames() 是后续扩展模块的中心入口。
• 性能治理：缓存、内存压力清理、性能预算和优化事件系统均在 core 内实现。

快速使用

import {
  DeviceDetector,
  createInitializedDeviceModule,
  listDeviceModuleNames,
  type NetworkModule,
} from '@composy/device-core'

const detector = new DeviceDetector({
  enableResize: true,
  enableOrientation: true,
  modules: ['network', 'battery'],
  breakpoints: {
    mobile: 768,
    tablet: 1024,
  },
})

const info = detector.getDeviceInfo()

detector.on('deviceChange', deviceInfo => {
  console.log(deviceInfo.type, deviceInfo.detection.method)
})

const network = await detector.loadModule<NetworkModule>('network')
console.log(network.isOnline(), network.getData())

console.log(listDeviceModuleNames())

await createInitializedDeviceModule('clipboard')
await detector.destroy()

架构约定

src/
  core/                 # Detector、事件系统、模块加载器、模块注册表
  engine/               # engine 插件协议和 createDeviceEnginePlugin
  modules/              # 设备能力模块实现
  types/                # 公共类型与浏览器能力声明
  utils/                # 缓存、性能、解析与安全访问工具
  index.ts              # 统一公共出口

实现原则：

• 纯 TypeScript 能力必须先放在 core。
• 框架适配包不得复制检测逻辑，只能通过 DeviceDetector、模块类或模块注册表复用 core。
• 新增内置模块时，先补 src/modules/*，再补 src/core/module-registry.ts，最后补 README 与类型导出。
• 浏览器实验 API 必须用窄类型封装，不使用 any 或非空断言绕过类型检查。

主要 API

• DeviceDetector：标准设备检测器。
• OptimizedDeviceDetector：更激进的缓存、批量事件和低频检测版本。
• EventEmitter / OptimizedEventEmitter：类型化事件系统。
• ModuleLoader / OptimizedModuleLoader：模块加载、重试、卸载和统计。
• createDeviceModule()：创建未初始化模块实例。
• createInitializedDeviceModule()：创建并初始化模块实例。
• normalizeDeviceModuleName()：归一化模块名，兼容历史别名。
• listDeviceModuleNames()：返回所有内置模块名。

内置模块

| 模块名 | 类名 | 说明 | |--------|------|------| | network | NetworkModule | 网络连接状态与类型 | | battery | BatteryModule | 电池电量与充电状态 | | geolocation | GeolocationModule | 地理位置与距离计算 | | media | MediaModule | 摄像头、麦克风、扬声器检测 | | mediaCapabilities | MediaCapabilitiesModule | 音视频编解码与 HDR 能力 | | clipboard | ClipboardModule | 剪贴板读写与权限 | | vibration | VibrationModule | 设备振动与预设模式 | | wakeLock | WakeLockModule | 屏幕唤醒锁 | | orientationLock | OrientationLockModule | 屏幕方向锁定 | | performance | PerformanceModule | 设备性能评分与分级 | | feature | FeatureDetectionModule | 浏览器/CSS/API 特性检测 |

构建产物

构建使用 @composy/builder，包产物保持四套目录：

• es/：ESM 入口与类型声明。
• esm/：兼容 ESM 目录镜像。
• lib/：CommonJS 入口与类型声明。
• dist/：浏览器 UMD 与压缩产物。

开发命令

pnpm run type-check    # 类型检查
pnpm run lint:check    # Lint 检查
pnpm run build         # 构建
pnpm run test:run      # 运行测试

代码质量

• 源码全部使用中文逐行注释。
• 严格禁止 any 类型，浏览器实验 API 使用窄类型封装。
• 所有浏览器 API 访问均有 SSR/Node 环境安全守卫。

License

MIT