luqi-device-detect

统一的前端访问设备判端，供各业务系统前端共用同一套口径。

本包只回答一件事：当前访问设备是什么。 WEB（电脑）/ TABLET（平板）/ MOBILE（手机）。 至于平板该渲染桌面端还是移动端——那是业务策略，由各系统自己决定，本包不介入。

判定顺序（先判平板，再判手机，最后按指针/视口兜底）：

1. 平板 UA 特征：iPad / Tablet / PlayBook / Kindle / Silk
2. iPad 桌面模式：UA 伪装成 Macintosh 但 maxTouchPoints > 1（真 Mac 触点数为 0）
3. Android / 鸿蒙平板：UA 带 Android / HarmonyOS / OpenHarmony 但不含 Mobile / Phone 标记（手机浏览器一定会带）
4. 手机 UA 特征：Android / iPhone / iPod / Windows Phone / HarmonyOS / OpenHarmony / MicroMessenger / Mobile Safari
5. 粗指针 + 小视口：(pointer: coarse) 且视口宽度 < 900px，其中宽度 ≥ 600px 记为平板，否则手机（覆盖 DevTools 模拟与未知触屏设备）

以上都不命中 → WEB。

安装

npm i luqi-device-detect

使用

import { detectDeviceKind } from 'luqi-device-detect'

const kind = detectDeviceKind() // 'WEB' | 'TABLET' | 'MOBILE'

平板无论切"移动标识"还是"桌面标识"（iPadOS 的请求桌面网站），结果都是 TABLET， 不会随用户在浏览器里切换设备标识而漂移。

业务侧自己决定怎么用，比如企业看板的策略是"平板跟着桌面端走"：

const layout = detectDeviceKind() === 'MOBILE' ? 'mobile' : 'desktop'

想让平板独立一套，也只是换个映射：

switch (detectDeviceKind()) {
  case 'MOBILE': return renderMobile()
  case 'TABLET': return renderTablet()
  case 'WEB': return renderDesktop()
}

可配置项

都是探测口径的微调，不含业务策略：

detectDeviceKind({
  // 粗指针设备视为移动端的视口宽度上限，默认 900
  breakpoint: 820,
  // 粗指针兜底时，视口宽度 ≥ 此值算平板，默认 600
  tabletMinWidth: 640,
  // 追加手机 / 平板 UA 特征（新机型先在个别调用方试点；
  // 验证稳定后应提升进本包默认规则，让所有系统受益）
  extraMobileUA: /SomeNewOS/i,
  extraTabletUA: /SomeNewPad/i,
})

SSR / 单测

detectDeviceKind 在非浏览器环境返回 'WEB'。需要准确结果时用纯函数版，显式传入信号：

import { resolveDeviceKind } from 'luqi-device-detect'

resolveDeviceKind({
  userAgent: req.headers['user-agent'] ?? '',
  coarsePointer: false,
  viewportWidth: 0,
  maxTouchPoints: 0,
})

服务端只有 UA、拿不到触点数，无法识别 iPad 的桌面模式（UA 就是 Macintosh）。 这种场景请由前端判完再上报，别在后端复刻这条规则。

兼容：DeviceType（WEB / MOBILE 二分）

resolveDeviceType / detectDeviceType 与 DeviceType 类型仅为兼容 0.1.0 已接入的系统 和后端的二分上报字段保留，行为已冻结（平板归 MOBILE，与 0.1.0 完全一致），并已标记 @deprecated。

新代码一律用 detectDeviceKind，需要二分时在业务侧自己映射—— 这样"平板算哪一端"的决定留在各系统内部，而不是塞进探测包。

⚠️ 与后端口径对齐

部分系统的后端（如企业看板的 DashboardVisitorResolver）保留了一份 UA 兜底判定。 修改本包默认规则（尤其是 MOBILE_UA / TABLET_UA 正则）时，必须同步评估相关后端是否跟进，避免前后端判端结果漂移。

版本变更

• 0.2.0 新增平板识别：DeviceKind、resolveDeviceKind / detectDeviceKind、TABLET_UA， 以及 tabletMinWidth / extraTabletUA 两个探测选项。 DeviceType 一系转为兼容保留并标记 deprecated，判定结果与 0.1.0 完全一致， 已接入的系统直接升级即可，不升级也不受影响。 唯一例外是带显式 Tablet / PlayBook / Kindle / Silk 标记且 UA 不含 Android 的冷门平板， 此前判为 WEB，现在按平板走（在 DeviceType 下归 MOBILE）。
• 0.1.0 相比看板前端原实现新增了 OpenHarmony（鸿蒙 NEXT）与 iPad 桌面模式两条规则。

发布

npm run test    # vitest
npm publish     # prepublishOnly 会自动跑 test + build

版本策略：调整默认判定规则（正则、断点、顺序）至少升 minor 并在此文档记录变更，各系统按需升级。