引言

每个应用都运行在具体的设备上。设备的品牌、型号、系统版本、CPU 架构等硬件标识信息，对开发者而言是统计上报、设备适配和 Bug 报告的基础数据。HarmonyOS NEXT 通过 @ohos.deviceInfo 模块将这些设备元信息统一暴露为同步可读的属性，无需权限即可获取。

@ohos.deviceInfo 属于 @kit.BasicServicesKit，与 Android 的 Build.MANUFACTURER / Build.MODEL 和 iOS 的 UIDevice.current 定位类似，但 API 设计更加直观——直接通过 deviceInfo 对象上的属性获取，全部同步返回。值得注意的是，所有属性读取均无需任何权限，开发者可以在应用启动时直接获取设备完整身份信息。

本文将深入讲解 @ohos.deviceInfo 的设备类型体系、品牌识别字段、系统版本标识以及实战应用，并构建一个"设备信息档案馆"Demo，在一个页面中展示全部设备硬件和系统信息，并支持逐项复制和批量导出。

一、API 架构：同步属性读取模型

1.1 核心设计理念

@ohos.deviceInfo 的设计极其简洁：它是一个模块，导出一个 deviceInfo 常量对象，所有属性均为同步读取。没有异步 Promise、没有回调、没有生命周期管理——读取即得。

import deviceInfo from '@ohos.deviceInfo';

// 直接读取，全部同步
const model = deviceInfo.productModel;
const brand = deviceInfo.brand;
const apiLevel = deviceInfo.sdkApiVersion;

这种设计与 Android 的 android.os.Build 类相似——所有字段都是静态字符串常量或整数，读取零开销。对比 iOS 的 UIDevice 需要先获取单例再访问属性，deviceInfo 的模块级导出更加精巧。

1.2 deviceType —— 设备形态

deviceType 返回当前设备的形态枚举值，是设备适配的一级分类：

返回值	说明	典型场景
phone	智能手机	竖屏布局、触控优先
tablet	平板	横竖屏自适应、分屏布局
2in1	二合一设备	键盘/触控双输入、窗口化
pc	桌面电脑	键鼠优先、大屏窗口
tv	智能电视	遥控器交互、远距离观看
wearable	智能穿戴	小屏精简、抬手即用

// 根据设备类型切换布局策略
const dt = deviceInfo.deviceType;
if (dt === 'phone') {
  // 使用单栏布局
} else if (dt === 'tablet' || dt === '2in1') {
  // 使用双栏/多栏布局
}

1.3 品牌身份字段

四个品牌相关字段构成了设备的完整身份链：

属性	说明	示例值
manufacture	制造商	HUAWEI
brand	品牌标识	HUAWEI
marketName	市场产品系列名	Mate 60 Pro
productModel	产品型号代码	ALN-AL80

这四个字段的关系可以类比为：制造商（谁造的）→ 品牌（什么牌子）→ 市场名（消费者看到的名称）→ 型号代码（开发者用于精确识别的代码）。

在统计上报场景中的典型用法：

const deviceLabel = deviceInfo.brand + ' ' + deviceInfo.marketName;
// 结果: "HUAWEI Mate 60 Pro"

const deviceCode = deviceInfo.productModel;
// 结果: "ALN-AL80" — 用于精确机型识别和问题定位

1.4 系统版本字段

属性	说明	示例值
osFullName	操作系统完整名称	HarmonyOS NEXT 5.0
displayVersion	显示用的版本号	5.0.0
sdkApiVersion	SDK API 级别（整数）	24

osFullName 和 displayVersion 面向用户展示，sdkApiVersion 面向开发者做 API 版本判断：

if (deviceInfo.sdkApiVersion >= 24) {
  // 使用 API 24+ 的新特性
} else {
  // 降级方案
}

二、实战 Demo：设备信息档案馆

本节构建一个完整的设备信息查看工具，以身份卡片 + 系统信息面板 + 完整规格列表的方式展示所有 deviceInfo 属性，并支持逐项复制到剪贴板。

2.1 页面设计

页面分为五个功能区域：

1. 设备身份卡片：大卡展示设备类型标签（手机/平板/二合一等，带图标底色）、制造商、市场名称和型号代码，形成设备的"数字名片"

2. 系统信息面板：双栏四格展示系统版本、SDK API 级别、完整 OS 名称、发行版名称

3. 全部规格列表：完整列出所有 8 项设备属性，每项右侧有"复制"按钮，点击后将对应属性值复制到系统剪贴板

4. 快捷操作：刷新信息按钮 + 一键复制全部按钮（将所有属性格式化为 label: value 文本复制）

5. 操作日志：记录每次操作

2.2 核心实现

读取设备信息 —— 所有属性同步读取，try/catch 保证健壮性：

private loadDeviceInfo(): void {
  const items: SpecItem[] = [];
  try {
    items.push(this.makeItem('设备类型', deviceInfo.deviceType, 'phone', '#9333EA'));
  } catch (e) {
    items.push(this.makeItem('设备类型', '--', 'phone', '#9333EA'));
  }
  try {
    items.push(this.makeItem('制造商', deviceInfo.manufacture, 'factory', '#3B82F6'));
  } catch (e) {
    items.push(this.makeItem('制造商', '--', 'factory', '#3B82F6'));
  }
  try {
    items.push(this.makeItem('品牌', deviceInfo.brand, 'tag', '#F59E0B'));
  } catch (e) {
    items.push(this.makeItem('品牌', '--', 'tag', '#F59E0B'));
  }
  try {
    items.push(this.makeItem('市场名称', deviceInfo.marketName, 'shop', '#10B981'));
  } catch (e) {
    items.push(this.makeItem('市场名称', '--', 'shop', '#10B981'));
  }
  try {
    items.push(this.makeItem('产品型号', deviceInfo.productModel, 'cube', '#EC4899'));
  } catch (e) {
    items.push(this.makeItem('产品型号', '--', 'cube', '#EC4899'));
  }
  try {
    items.push(this.makeItem('系统版本', deviceInfo.displayVersion, 'version', '#8B5CF6'));
  } catch (e) {
    items.push(this.makeItem('系统版本', '--', 'version', '#8B5CF6'));
  }
  try {
    items.push(this.makeItem('OS 全称', deviceInfo.osFullName, 'os', '#0EA5E9'));
  } catch (e) {
    items.push(this.makeItem('OS 全称', '--', 'os', '#0EA5E9'));
  }
  try {
    items.push(this.makeItem('SDK API 版本', deviceInfo.sdkApiVersion.toString(), 'sdk', '#14B8A6'));
  } catch (e) {
    items.push(this.makeItem('SDK API 版本', '--', 'sdk', '#14B8A6'));
  }
  this.specs = items;
}

设计要点：

• 每个属性独立 try/catch，单个字段的读取失败不影响其他字段
• 使用 makeItem 辅助方法统一构建数据条目
• sdkApiVersion 是 number 类型，需 .toString() 转为字符串统一存储

单字段复制 —— 利用 @ohos.pasteboard 将指定值写入系统剪贴板：

private copyField(label: string, value: string): void {
  const pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, value);
  const sysBoard = pasteboard.getSystemPasteboard();
  sysBoard.setData(pasteData).then(() => {
    this.copiedLabel = label;
    this.addLog('已复制: ' + label + ' = ' + value, 'success');
    setTimeout(() => { this.copiedLabel = ''; }, 2000);
  }).catch((e: Error) => {
    this.addLog('复制失败: ' + e.message, 'error');
  });
}

复制成功后通过 copiedLabel 状态触发按钮文字变化（“复制” → “已复制” 绿色），2 秒后自动恢复。

一键复制全部 —— 将所有属性拼接为 key: value 格式：

let all = '';
for (let i = 0; i < this.specs.length; i++) {
  all += this.specs[i].label + ': ' + this.specs[i].value + '\n';
}
const pd = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, all);
pasteboard.getSystemPasteboard().setData(pd);

2.3 交互方式

Demo 提供三个核心交互点：

1. 逐项复制：设备规格列表中每项右侧的"复制"按钮，单击将单项属性值复制到系统剪贴板。按钮文字临时变为绿色"已复制"。

2. 一键复制全部：将所有 8 项设备信息拼成 label: value 格式的文本，一键复制到剪贴板。这对提交 Bug 报告时附上设备信息非常方便。

3. 刷新信息：重新执行 loadDeviceInfo() 读取所有属性。虽然设备信息在运行时不会变化，但提供了完整的重读流程。
   
   

三、实际应用场景

3.1 Bug 报告的设备上下文

private buildDeviceContext(): string {
  return [
    '设备: ' + deviceInfo.brand + ' ' + deviceInfo.marketName,
    '型号: ' + deviceInfo.productModel,
    '系统: ' + deviceInfo.osFullName + ' (' + deviceInfo.displayVersion + ')',
    'SDK: API ' + deviceInfo.sdkApiVersion.toString(),
    '形态: ' + deviceInfo.deviceType
  ].join('\n');
}

// 将设备上下文附加到 Bug 报告邮件或 API 调用中
const bugReport = this.buildDeviceContext() + '\n\n' + errorStack;

3.2 设备适配布局选择

private chooseLayout(): LayoutMode {
  const dt = deviceInfo.deviceType;
  if (dt === 'phone') {
    return LayoutMode.SINGLE_COLUMN;
  }
  if (dt === 'tablet' || dt === '2in1') {
    return LayoutMode.DUAL_COLUMN;
  }
  if (dt === 'tv') {
    return LayoutMode.LEANBACK;
  }
  return LayoutMode.SINGLE_COLUMN;
}

3.3 数据统计上报

interface DeviceProfile {
  brand: string;
  model: string;
  os: string;
  apiLevel: number;
  type: string;
}

private getDeviceProfile(): DeviceProfile {
  return {
    brand: deviceInfo.brand,
    model: deviceInfo.productModel,
    os: deviceInfo.osFullName,
    apiLevel: deviceInfo.sdkApiVersion,
    type: deviceInfo.deviceType
  };
}

// 在应用启动时上报
analytics.report('app_launch', this.getDeviceProfile());

四、ArkTS 严格模式注意事项

4.1 属性存在性

不同 SDK 版本的 deviceInfo 对象可能具有不同数量的属性。某些文档中提到的属性（如 cpu、distributionOSName）在实际 SDK 版本中可能不存在。在 Demo 中我们为每个属性使用独立的 try/catch，确保单个属性的缺失不会影响其他字段的读取。

4.2 类型转换

sdkApiVersion 是 number 类型，而 deviceType、manufacture、brand 等均为 string。在统一展示时需要将 number 转为 string。

4.3 架构信息

deviceInfo 不包含运行时内存、CPU 频率等动态信息。如果需要获取这些指标，应使用 @ohos.hidebug 模块。如果需要设备唯一标识符，应使用 deviceInfo.udid（需 ohos.permission.ohos.permission.GET_UDID 权限）。

五、总结

@ohos.deviceInfo 是 HarmonyOS NEXT 中获取设备硬件和系统标识的最简模块。通过本文的学习，你应该已经掌握：

1. 同步读取模型：全部属性均为模块级导出常量，直接访问，无需 Promise、无需回调、无需权限
2. 设备形态体系：deviceType 返回 phone/tablet/2in1/pc/tv/wearable 六种形态，是布局适配的一级分类
3. 品牌身份四件套：manufacture（制造商）→ brand（品牌）→ marketName（消费者名称）→ productModel（开发者代码），构成完整设备身份链
4. 系统版本：osFullName 和 displayVersion 面向用户展示，sdkApiVersion（number 类型）面向 API 级别判断
5. 错误处理：每个属性独立 try/catch，防止因 SDK 版本差异导致的读取失败

@ohos.deviceInfo 的最佳使用模式可以总结为：

应用启动时全量读取，构建设备画像对象，用于统计上报、Bug 报告和布局适配。所有字段同步无权限——零成本的信息获取。

设备信息是应用运行环境的元数据。虽然 deviceInfo 的 API 极其简单，但它支撑着设备适配、数据统计和问题诊断等关键基础设施。在应用架构中为设备信息保留一个标准化的读取封装，是所有开发者都值得做的一件事。

@ohos.deviceInfo 属于 @kit.BasicServicesKit，与 Android 的 android.os.Build 和 iOS 的 UIDevice 定位一致。它的 API 体积是所有系统模块中最小的——一个模块、一个对象、几个字符串属性——但覆盖了从设备形态到系统版本的全部核心标识需求。