# detectDevice

一个用于检测用户设备类型的轻量级 TypeScript 库。

[![GitHub](https://img.shields.io/badge/GitHub-源码-blue?logo=github)](https://github.com/al01cn/detectdevice)
[![Gitee](https://img.shields.io/badge/Gitee-源码-orange?logo=gitee)](https://gitee.com/al01/detectdevice)

## 功能

- 🎯 准确识别移动设备、平板和桌面设备
- 🖥️ 检测操作系统平台 (iOS, Android, Windows, macOS, Linux)
- 👆 检测触摸支持
- 📱 判断屏幕尺寸
- 🧠 使用现代 User-Agent Client Hints API，同时兼容传统 User-Agent 解析
- 📦 轻量级，无外部依赖
- 🌐 仅支持浏览器环境
- 📦 支持多种包管理器：npm, yarn, bun, deno

## 安装

### 使用 npm

```bash
npm install @al01/detectdevice
```

### 使用 yarn

```bash
yarn add @al01/detectdevice
```

### 使用 bun

```bash
bun add @al01/detectdevice
```

### 使用 deno

```bash
deno add jsr:@al01/detectdevice
```

### 浏览器直接引用

```html
<script src="https://unpkg.com/@al01/detectdevice/dist/index.min.js"></script>
<script>
  // 直接使用全局方法 detectDevice()
  const device = detectDevice();
  console.log(device);
</script>
```

## 使用方法

### 基础用法

```ts
import { detectDevice } from '@al01/detectdevice'

const device = detectDevice()

// 设备类型检测
if (device.isMobile) {
  console.log('这是一台手机')
} else if (device.isTablet) {
  console.log('这是一台平板')
} else if (device.isDesktop) {
  console.log('这是一台桌面设备')
}

// 平台检测
console.log(`操作系统: ${device.platform}`)

// 其他特性
console.log(`是否支持触摸: ${device.isTouch}`)
console.log(`是否为小屏设备: ${device.isSmallScreen}`)
```

### 实际应用场景

#### 响应式 UI 调整

```ts
import { detectDevice } from '@al01/detectdevice'

const device = detectDevice()

// 根据设备类型应用不同的 UI 组件
if (device.isMobile) {
  // 加载移动端优化的组件
  loadMobileComponents()
} else if (device.isTablet) {
  // 平板优化的布局
  loadTabletLayout()
} else {
  // 桌面端完整功能界面
  loadDesktopInterface()
}
```

#### 功能适配

```ts
import { detectDevice } from '@al01/detectdevice'

const device = detectDevice()

// 根据设备功能启用相应特性
if (device.isTouch) {
  // 启用触摸手势支持
  enableTouchGestures()
} else {
  // 启用鼠标悬停效果
  enableHoverEffects()
}

// 根据屏幕尺寸调整内容
if (device.isSmallScreen) {
  // 简化导航菜单
  initializeMobileNavigation()
} else {
  // 显示完整导航菜单
  initializeFullNavigation()
}
```

#### 平台特定处理

```ts
import { detectDevice } from '@al01/detectdevice'

const device = detectDevice()

// 根据不同平台进行特殊处理
switch (device.platform) {
  case 'ios':
    // iOS 特定处理
    handleIOSFeatures()
    break
  case 'android':
    // Android 特定处理
    handleAndroidFeatures()
    break
  case 'windows':
  case 'macos':
  case 'linux':
    // 桌面系统特定处理
    handleDesktopFeatures()
    break
  default:
    // 默认处理
    handleDefaultFeatures()
}
```

## API 参考

### detectDevice()

返回包含设备信息的对象：

| 属性 | 类型 | 描述 |
|------|------|------|
| type | `'mobile' \| 'tablet' \| 'desktop'` | 设备类型 |
| isMobile | `boolean` | 是否为手机 |
| isTablet | `boolean` | 是否为平板 |
| isDesktop | `boolean` | 是否为桌面设备 |
| isTouch | `boolean` | 是否支持触摸 |
| isSmallScreen | `boolean` | 是否为小屏设备 (≤ 768px) |
| platform | `'ios' \| 'android' \| 'windows' \| 'macos' \| 'linux' \| 'unknown'` | 操作系统 |

## 浏览器支持

- Chrome >= 89
- Firefox >= 90
- Safari >= 16
- Edge >= 89
- 其他支持 User-Agent 解析的浏览器

对于不支持 User-Agent Client Hints API 的浏览器，库会自动降级到传统的 User-Agent 解析方式。

## 许可证

[MIT](LICENSE)

---

该项目使用 [Bun](https://bun.sh) v1.3.2 创建。Bun 是一个快速的一体化 JavaScript 运行时。