HarmonyOS设备能力查询开发小知识

在分布式场景下，不同设备的能力千差万别——手机有摄像头、手表有心率传感器、电视有大屏幕、音箱有扬声器……如何准确查询和匹配设备能力，是实现智能设备协同的关键。这篇文章带你深入理解HarmonyOS设备能力查询的核心机制。

一、背景与动机：为什么需要设备能力查询？

1.1 设备能力的多样性

在IoT时代，设备能力呈现高度多样化：

输入能力：键盘、鼠标、触摸屏、语音、手势、手写笔、游戏手柄……不同的输入方式适合不同的场景。

输出能力：显示屏、扬声器、振动马达、LED指示灯、投影仪……输出方式决定了信息呈现的形式。

传感器能力：摄像头、麦克风、GPS、加速度计、陀螺仪、心率传感器、血氧传感器、温度传感器……传感器是感知物理世界的窗口。

计算能力：CPU性能、GPU性能、NPU性能、内存大小、存储容量……计算能力决定了设备能承担什么任务。

1.2 能力查询的价值

准确查询设备能力，是实现智能协同的前提：

能力查询的核心价值：

二、核心原理：设备能力模型

2.1 能力分类体系

HarmonyOS建立了完整的设备能力分类体系。

2.1.1 能力大类

// 设备能力大类
enum CapabilityCategory {
  INPUT = 'input',           // 输入能力
  OUTPUT = 'output',         // 输出能力
  SENSOR = 'sensor',         // 传感器能力
  COMPUTE = 'compute',       // 计算能力
  STORAGE = 'storage',       // 存储能力
  NETWORK = 'network',       // 网络能力
  POWER = 'power',           // 电源能力
  DISPLAY = 'display'        // 显示能力
}

2.1.2 能力细类

// 输入能力细类
enum InputCapability {
  // 基础输入
  INPUT_KEYBOARD = 'input.keyboard',           // 物理键盘
  INPUT_VIRTUAL_KEYBOARD = 'input.vkeyboard',  // 虚拟键盘
  INPUT_MOUSE = 'input.mouse',                 // 鼠标
  INPUT_TOUCH = 'input.touch',                 // 触摸屏
  INPUT_STYLUS = 'input.stylus',               // 手写笔
  
  // 语音输入
  INPUT_VOICE = 'input.voice',                 // 语音输入
  INPUT_VOICE_WAKEUP = 'input.voice.wakeup',   // 语音唤醒
  
  // 手势输入
  INPUT_GESTURE = 'input.gesture',             // 手势识别
  INPUT_MOTION = 'input.motion',               // 动作识别
  
  // 游戏输入
  INPUT_GAMEPAD = 'input.gamepad',             // 游戏手柄
  INPUT_JOYSTICK = 'input.joystick'            // 操纵杆
}

// 输出能力细类
enum OutputCapability {
  // 显示输出
  OUTPUT_DISPLAY = 'output.display',           // 显示屏
  OUTPUT_PROJECTOR = 'output.projector',       // 投影仪
  OUTPUT_HDMI = 'output.hdmi',                 // HDMI输出
  
  // 音频输出
  OUTPUT_SPEAKER = 'output.speaker',           // 扬声器
  OUTPUT_HEADPHONE = 'output.headphone',       // 耳机
  OUTPUT_BLUETOOTH_AUDIO = 'output.bt.audio',  // 蓝牙音频
  
  // 触觉输出
  OUTPUT_VIBRATE = 'output.vibrate',           // 振动马达
  OUTPUT_HAPTIC = 'output.haptic'              // 触觉反馈
}

// 传感器能力细类
enum SensorCapability {
  // 图像传感器
  SENSOR_CAMERA_FRONT = 'sensor.camera.front',     // 前置摄像头
  SENSOR_CAMERA_BACK = 'sensor.camera.back',       // 后置摄像头
  SENSOR_CAMERA_DEPTH = 'sensor.camera.depth',     // 深度摄像头
  SENSOR_CAMERA_THERMAL = 'sensor.camera.thermal', // 热成像摄像头
  
  // 音频传感器
  SENSOR_MICROPHONE = 'sensor.microphone',         // 麦克风
  SENSOR_MICROPHONE_ARRAY = 'sensor.mic.array',    // 麦克风阵列
  
  // 运动传感器
  SENSOR_ACCELEROMETER = 'sensor.accelerometer',   // 加速度计
  SENSOR_GYROSCOPE = 'sensor.gyroscope',           // 陀螺仪
  SENSOR_MAGNETOMETER = 'sensor.magnetometer',     // 磁力计
  SENSOR_PEDOMETER = 'sensor.pedometer',           // 计步器
  
  // 位置传感器
  SENSOR_GPS = 'sensor.gps',                       // GPS
  SENSOR_WIFI_RTT = 'sensor.wifi.rtt',             // Wi-Fi RTT
  
  // 生物传感器
  SENSOR_HEARTRATE = 'sensor.heartrate',           // 心率传感器
  SENSOR_SPO2 = 'sensor.spo2',                     // 血氧传感器
  SENSOR_FINGERPRINT = 'sensor.fingerprint',       // 指纹传感器
  SENSOR_FACE = 'sensor.face',                     // 人脸识别
  SENSOR_IRIS = 'sensor.iris',                     // 虹膜识别
  
  // 环境传感器
  SENSOR_TEMPERATURE = 'sensor.temperature',       // 温度传感器
  SENSOR_HUMIDITY = 'sensor.humidity',             // 湿度传感器
  SENSOR_PRESSURE = 'sensor.pressure',             // 气压传感器
  SENSOR_LIGHT = 'sensor.light'                    // 光线传感器
}

// 计算能力细类
enum ComputeCapability {
  // CPU能力
  COMPUTE_CPU_CORES = 'compute.cpu.cores',         // CPU核心数
  COMPUTE_CPU_FREQ = 'compute.cpu.freq',           // CPU频率
  COMPUTE_CPU_ARCH = 'compute.cpu.arch',           // CPU架构
  
  // GPU能力
  COMPUTE_GPU = 'compute.gpu',                     // GPU
  COMPUTE_GPU_VULKAN = 'compute.gpu.vulkan',       // Vulkan支持
  COMPUTE_GPU_OPENGL = 'compute.gpu.opengl',       // OpenGL支持
  
  // NPU能力
  COMPUTE_NPU = 'compute.npu',                     // NPU（神经网络处理器）
  COMPUTE_NPU_TOPS = 'compute.npu.tops',           // NPU算力（TOPS）
  
  // 内存能力
  COMPUTE_MEMORY = 'compute.memory',               // 内存大小
  COMPUTE_MEMORY_BANDWIDTH = 'compute.memory.bw'   // 内存带宽
}

2.2 能力属性模型

每个能力不仅有"有无"的概念，还有丰富的属性信息。

// 能力属性定义
interface CapabilityProperty {
  capabilityId: string;          // 能力ID
  
  // 基础属性
  available: boolean;            // 是否可用
  enabled: boolean;              // 是否启用
  exclusive: boolean;            // 是否独占（同一时间只能被一个应用使用）
  
  // 性能属性
  performance: PerformanceInfo;  // 性能信息
  
  // 配置属性
  config: ConfigInfo;            // 配置信息
  
  // 状态属性
  state: CapabilityState;        // 能力状态
  lastUsedTime: number;          // 最后使用时间
}

// 性能信息
interface PerformanceInfo {
  // 通用性能指标
  latency: number;               // 延迟（ms）
  throughput: number;            // 吞吐量
  powerConsumption: number;      // 功耗（mW）
  
  // 能力特定指标
  metrics: Map<string, number>;  // 自定义指标
}

// 配置信息
interface ConfigInfo {
  // 可配置项
  configurable: boolean;         // 是否可配置
  options: ConfigOption[];       // 配置选项
  
  // 当前配置
  currentConfig: Map<string, any>;
}

// 能力状态
enum CapabilityState {
  UNAVAILABLE = 0,    // 不可用
  AVAILABLE = 1,      // 可用
  BUSY = 2,           // 繁忙
  ERROR = 3           // 错误
}

2.3 摄像头能力详解

以摄像头能力为例，展示能力属性的丰富性：

// 摄像头能力属性
interface CameraCapabilityProperty extends CapabilityProperty {
  // 基础信息
  cameraId: string;              // 摄像头ID
  cameraPosition: CameraPosition;  // 摄像头位置
  cameraType: CameraType;        // 摄像头类型
  
  // 分辨率信息
  supportedResolutions: Resolution[];  // 支持的分辨率列表
  maxResolution: Resolution;           // 最大分辨率
  defaultResolution: Resolution;       // 默认分辨率
  
  // 帧率信息
  supportedFrameRates: number[];       // 支持的帧率列表
  maxFrameRate: number;                // 最大帧率
  
  // 功能特性
  features: CameraFeature[];           // 支持的功能列表
  
  // 曝光信息
  exposureRange: Range;                // 曝光范围
  sensitivityRange: Range;             // 感光度范围
  
  // 对焦信息
  focusModes: FocusMode[];             // 支持的对焦模式
  
  // 闪光灯信息
  flashMode: FlashMode[];              // 支持的闪光灯模式
}

// 摄像头位置
enum CameraPosition {
  FRONT = 'front',       // 前置
  BACK = 'back',         // 后置
  EXTERNAL = 'external'  // 外接
}

// 摄像头类型
enum CameraType {
  WIDE_ANGLE = 'wide',      // 广角
  ULTRA_WIDE = 'ultra',     // 超广角
  TELEPHOTO = 'telephoto',  // 长焦
  DEPTH = 'depth',          // 深度
  THERMAL = 'thermal'       // 热成像
}

// 摄像头功能
enum CameraFeature {
  AUTO_FOCUS = 'autoFocus',           // 自动对焦
  CONTINUOUS_FOCUS = 'continuousFocus',  // 连续对焦
  FACE_DETECTION = 'faceDetection',   // 人脸检测
  IMAGE_STABILIZATION = 'imageStabilization',  // 图像防抖
  HDR = 'hdr',                        // HDR
  NIGHT_MODE = 'nightMode',           // 夜景模式
  PORTRAIT_MODE = 'portraitMode',     // 人像模式
  RAW_CAPTURE = 'rawCapture'          // RAW拍摄
}

// 分辨率定义
interface Resolution {
  width: number;
  height: number;
}

2.4 能力查询流程

sequenceDiagram
    participant App as 应用
    participant Query as 能力查询服务
    participant Cache as 能力缓存
    participant Device as 设备管理器
    
    Note over App: 1. 发起能力查询
    App->>Query: queryCapabilities(deviceId, filter)
    
    Note over Query: 2. 检查缓存
    Query->>Cache: get(deviceId)
    
    alt 缓存命中
        Cache-->>Query: 返回缓存数据
        Query-->>App: 返回能力列表
    else 缓存未命中
        Note over Query: 3. 查询设备管理器
        Query->>Device: getDeviceCapabilities(deviceId)
        Device-->>Query: 返回能力数据
        
        Note over Query: 4. 应用过滤器
        Query->>Query: applyFilter(capabilities, filter)
        
        Note over Query: 5. 更新缓存
        Query->>Cache: set(deviceId, capabilities)
        
        Query-->>App: 返回过滤后的能力列表
    end
    
    classDef primary fill:#4A90E2,stroke:#2E5C8A,stroke-width:2px,color:#fff
    classDef warning fill:#F5A623,stroke:#C17A00,stroke-width:2px,color:#fff
    classDef info fill:#7ED321,stroke:#5BA315,stroke-width:2px,color:#fff
    
    class App,Query primary
    class Cache warning
    class Device info

三、代码实战：能力查询API使用

3.1 能力查询服务

import deviceManager from '@ohos.distributedHardware.deviceManager';

/**
 * 设备能力查询服务
 * 提供统一的能力查询接口
 */
export class CapabilityQueryService {
  private deviceMgr: deviceManager.DeviceManager | null = null;
  private capabilityCache: Map<string, CachedCapability> = new Map();
  private cacheExpireTime: number = 30000;  // 缓存30秒
  
  /**
   * 初始化
   */
  async initialize(bundleName: string): Promise<void> {
    try {
      this.deviceMgr = deviceManager.createDeviceManager(bundleName);
      console.info('[CapabilityQuery] 初始化成功');
    } catch (error) {
      console.error(`[CapabilityQuery] 初始化失败: ${JSON.stringify(error)}`);
      throw error;
    }
  }
  
  /**
   * 查询设备所有能力
   */
  async queryAllCapabilities(deviceId: string): Promise<CapabilityInfo[]> {
    // 检查缓存
    const cached = this.getFromCache(deviceId);
    if (cached) {
      return cached.capabilities;
    }
    
    // 查询设备能力
    const capabilities = await this.doQueryCapabilities(deviceId);
    
    // 更新缓存
    this.updateCache(deviceId, capabilities);
    
    return capabilities;
  }
  
  /**
   * 查询指定类型的能力
   */
  async queryCapabilitiesByCategory(
    deviceId: string,
    category: CapabilityCategory
  ): Promise<CapabilityInfo[]> {
    const allCapabilities = await this.queryAllCapabilities(deviceId);
    
    // 过滤指定类别
    return allCapabilities.filter(cap => 
      cap.capabilityId.startsWith(category)
    );
  }
  
  /**
   * 查询指定能力是否存在
   */
  async hasCapability(
    deviceId: string,
    capabilityId: string
  ): Promise<boolean> {
    const capabilities = await this.queryAllCapabilities(deviceId);
    
    return capabilities.some(cap => 
      cap.capabilityId === capabilityId && cap.available
    );
  }
  
  /**
   * 查询能力属性
   */
  async getCapabilityProperty(
    deviceId: string,
    capabilityId: string
  ): Promise<CapabilityProperty | null> {
    if (!this.deviceMgr) {
      return null;
    }
    
    try {
      const property = await this.deviceMgr.getCapabilityProperty(
        deviceId,
        capabilityId
      );
      
      return property;
    } catch (error) {
      console.error(`[CapabilityQuery] 查询能力属性失败: ${JSON.stringify(error)}`);
      return null;
    }
  }
  
  /**
   * 查询摄像头能力详情
   */
  async queryCameraCapabilities(deviceId: string): Promise<CameraCapability[]> {
    const capabilities = await this.queryCapabilitiesByCategory(
      deviceId,
      CapabilityCategory.SENSOR
    );
    
    // 过滤摄像头能力
    const cameraCapabilities: CameraCapability[] = [];
    
    for (const cap of capabilities) {
      if (cap.capabilityId.startsWith('sensor.camera')) {
        // 获取详细属性
        const property = await this.getCapabilityProperty(
          deviceId,
          cap.capabilityId
        ) as CameraCapabilityProperty;
        
        cameraCapabilities.push({
          capabilityId: cap.capabilityId,
          cameraId: property?.cameraId || '',
          cameraPosition: property?.cameraPosition || CameraPosition.BACK,
          cameraType: property?.cameraType || CameraType.WIDE_ANGLE,
          maxResolution: property?.maxResolution || { width: 1920, height: 1080 },
          maxFrameRate: property?.maxFrameRate || 30,
          features: property?.features || [],
          available: cap.available
        });
      }
    }
    
    return cameraCapabilities;
  }
  
  /**
   * 匹配能力需求
   */
  async matchCapabilityRequirements(
    deviceId: string,
    requirements: CapabilityRequirement[]
  ): Promise<MatchResult> {
    const capabilities = await this.queryAllCapabilities(deviceId);
    
    const matched: string[] = [];
    const missing: string[] = [];
    
    for (const req of requirements) {
      const found = capabilities.find(cap => 
        cap.capabilityId === req.capabilityId && 
        cap.available &&
        this.checkConstraints(cap, req.constraints)
      );
      
      if (found) {
        matched.push(req.capabilityId);
      } else {
        missing.push(req.capabilityId);
      }
    }
    
    return {
      deviceId: deviceId,
      matched: matched,
      missing: missing,
      score: matched.length / requirements.length,
      fullyMatched: missing.length === 0
    };
  }
  
  /**
   * 检查能力约束
   */
  private checkConstraints(
    capability: CapabilityInfo,
    constraints: CapabilityConstraint[]
  ): boolean {
    for (const constraint of constraints) {
      const value = capability.properties?.get(constraint.key);
      
      switch (constraint.operator) {
        case 'eq':
          if (value !== constraint.value) return false;
          break;
        case 'gte':
          if (value < constraint.value) return false;
          break;
        case 'lte':
          if (value > constraint.value) return false;
          break;
        case 'in':
          if (!constraint.value.includes(value)) return false;
          break;
      }
    }
    
    return true;
  }
  
  /**
   * 查找满足能力需求的设备
   */
  async findDevicesWithCapabilities(
    requirements: CapabilityRequirement[],
    deviceIds?: string[]
  ): Promise<MatchResult[]> {
    // 获取设备列表
    const devices = deviceIds || await this.getOnlineDevices();
    
    // 并行匹配所有设备
    const matchPromises = devices.map(deviceId =>
      this.matchCapabilityRequirements(deviceId, requirements)
    );
    
    const results = await Promise.all(matchPromises);
    
    // 按匹配度排序
    results.sort((a, b) => b.score - a.score);
    
    return results;
  }
  
  /**
   * 选择最优设备
   */
  async selectBestDevice(
    requirements: CapabilityRequirement[],
    strategy: SelectionStrategy = 'BEST_MATCH'
  ): Promise<string | null> {
    const results = await this.findDevicesWithCapabilities(requirements);
    
    if (results.length === 0) {
      return null;
    }
    
    switch (strategy) {
      case 'BEST_MATCH':
        // 返回匹配度最高的设备
        return results[0].deviceId;
      
      case 'FIRST_AVAILABLE':
        // 返回第一个完全匹配的设备
        const fullyMatched = results.find(r => r.fullyMatched);
        return fullyMatched?.deviceId || null;
      
      case 'LOWEST_POWER':
        // 返回功耗最低的设备（需要额外查询）
        // 简化实现，返回第一个
        return results[0].deviceId;
      
      default:
        return results[0].deviceId;
    }
  }
  
  /**
   * 执行能力查询
   */
  private async doQueryCapabilities(deviceId: string): Promise<CapabilityInfo[]> {
    if (!this.deviceMgr) {
      return [];
    }
    
    try {
      const capabilities = await this.deviceMgr.getDeviceCapabilities(deviceId);
      return capabilities;
    } catch (error) {
      console.error(`[CapabilityQuery] 查询失败: ${JSON.stringify(error)}`);
      return [];
    }
  }
  
  /**
   * 从缓存获取
   */
  private getFromCache(deviceId: string): CachedCapability | null {
    const cached = this.capabilityCache.get(deviceId);
    
    if (!cached) {
      return null;
    }
    
    // 检查是否过期
    if (Date.now() - cached.timestamp > this.cacheExpireTime) {
      this.capabilityCache.delete(deviceId);
      return null;
    }
    
    return cached;
  }
  
  /**
   * 更新缓存
   */
  private updateCache(deviceId: string, capabilities: CapabilityInfo[]): void {
    this.capabilityCache.set(deviceId, {
      capabilities: capabilities,
      timestamp: Date.now()
    });
  }
  
  /**
   * 获取在线设备列表
   */
  private async getOnlineDevices(): Promise<string[]> {
    if (!this.deviceMgr) {
      return [];
    }
    
    const devices = await this.deviceMgr.getTrustedDeviceList(true);
    return devices.map(d => d.deviceId);
  }
  
  /**
   * 清除缓存
   */
  clearCache(): void {
    this.capabilityCache.clear();
  }
  
  /**
   * 释放资源
   */
  release(): void {
    this.deviceMgr = null;
    this.capabilityCache.clear();
  }
}

// 缓存的能力信息
interface CachedCapability {
  capabilities: CapabilityInfo[];
  timestamp: number;
}

// 能力信息
interface CapabilityInfo {
  capabilityId: string;
  available: boolean;
  properties?: Map<string, any>;
}

// 能力需求
interface CapabilityRequirement {
  capabilityId: string;
  constraints?: CapabilityConstraint[];
  required?: boolean;  // 是否必需
}

// 能力约束
interface CapabilityConstraint {
  key: string;
  operator: 'eq' | 'gte' | 'lte' | 'in';
  value: any;
}

// 匹配结果
interface MatchResult {
  deviceId: string;
  matched: string[];
  missing: string[];
  score: number;
  fullyMatched: boolean;
}

// 选择策略
type SelectionStrategy = 'BEST_MATCH' | 'FIRST_AVAILABLE' | 'LOWEST_POWER';

// 摄像头能力
interface CameraCapability {
  capabilityId: string;
  cameraId: string;
  cameraPosition: CameraPosition;
  cameraType: CameraType;
  maxResolution: Resolution;
  maxFrameRate: number;
  features: CameraFeature[];
  available: boolean;
}

3.2 设备能力面板组件

/**
 * 设备能力展示面板
 * 可视化展示设备能力信息
 */
@Component
export struct DeviceCapabilityPanel {
  @Prop deviceId: string = '';
  @State capabilities: CapabilityInfo[] = [];
  @State selectedCategory: CapabilityCategory = CapabilityCategory.SENSOR;
  
  private queryService: CapabilityQueryService | null = null;
  
  aboutToAppear(): void {
    this.loadCapabilities();
  }
  
  private async loadCapabilities(): Promise<void> {
    if (!this.deviceId) {
      return;
    }
    
    // 初始化查询服务
    this.queryService = new CapabilityQueryService();
    await this.queryService.initialize('com.example.app');
    
    // 加载能力列表
    this.capabilities = await this.queryService.queryAllCapabilities(this.deviceId);
  }
  
  build() {
    Column() {
      // 设备信息头部
      Row() {
        Text('设备能力')
          .fontSize(20)
          .fontWeight(FontWeight.Bold)
        
        Blank()
        
        Text(this.deviceId.substring(0, 8))
          .fontSize(14)
          .fontColor('#666666')
      }
      .width('100%')
      .padding(16)
      
      Divider()
      
      // 类别选择
      Row() {
        ForEach(this.getCategories(), (category: CategoryItem) => {
          Button(category.name)
            .fontSize(12)
            .height(32)
            .backgroundColor(
              this.selectedCategory === category.value ? '#4A90E2' : '#E0E0E0'
            )
            .fontColor(
              this.selectedCategory === category.value ? '#FFFFFF' : '#333333'
            )
            .onClick(() => {
              this.selectedCategory = category.value;
            })
            .margin({ right: 8 })
        }, (category: CategoryItem) => category.value)
      }
      .width('100%')
      .padding({ left: 16, right: 16, top: 12, bottom: 12 })
      
      Divider()
      
      // 能力列表
      List() {
        ForEach(this.getFilteredCapabilities(), (cap: CapabilityInfo) => {
          ListItem() {
            this.CapabilityItem(cap)
          }
        }, (cap: CapabilityInfo) => cap.capabilityId)
      }
      .width('100%')
      .layoutWeight(1)
      .padding(16)
    }
    .width('100%')
    .height('100%')
    .backgroundColor('#F5F5F5')
  }
  
  @Builder
  CapabilityItem(cap: CapabilityInfo) {
    Row() {
      // 能力图标
      Circle()
        .width(40)
        .height(40)
        .fill(cap.available ? '#4A90E2' : '#CCCCCC')
      
      // 能力信息
      Column() {
        Text(this.getCapabilityName(cap.capabilityId))
          .fontSize(16)
          .fontWeight(FontWeight.Medium)
        
        Text(cap.capabilityId)
          .fontSize(12)
          .fontColor('#999999')
          .margin({ top: 4 })
      }
      .alignItems(HorizontalAlign.Start)
      .margin({ left: 12 })
      .layoutWeight(1)
      
      // 状态标识
      Text(cap.available ? '可用' : '不可用')
        .fontSize(12)
        .fontColor(cap.available ? '#7ED321' : '#D0021B')
    }
    .width('100%')
    .padding(12)
    .backgroundColor(Color.White)
    .borderRadius(8)
    .margin({ bottom: 8 })
  }
  
  /**
   * 获取类别列表
   */
  private getCategories(): CategoryItem[] {
    return [
      { name: '传感器', value: CapabilityCategory.SENSOR },
      { name: '输入', value: CapabilityCategory.INPUT },
      { name: '输出', value: CapabilityCategory.OUTPUT },
      { name: '计算', value: CapabilityCategory.COMPUTE },
      { name: '存储', value: CapabilityCategory.STORAGE },
      { name: '网络', value: CapabilityCategory.NETWORK }
    ];
  }
  
  /**
   * 获取过滤后的能力
   */
  private getFilteredCapabilities(): CapabilityInfo[] {
    return this.capabilities.filter(cap => 
      cap.capabilityId.startsWith(this.selectedCategory)
    );
  }
  
  /**
   * 获取能力名称
   */
  private getCapabilityName(capabilityId: string): string {
    const nameMap: Record<string, string> = {
      'sensor.camera.front': '前置摄像头',
      'sensor.camera.back': '后置摄像头',
      'sensor.microphone': '麦克风',
      'sensor.gps': 'GPS定位',
      'sensor.heartrate': '心率传感器',
      'sensor.accelerometer': '加速度计',
      'input.touch': '触摸屏',
      'input.keyboard': '键盘',
      'output.display': '显示屏',
      'output.speaker': '扬声器',
      'output.vibrate': '振动马达'
    };
    
    return nameMap[capabilityId] || capabilityId;
  }
  
  aboutToDisappear(): void {
    this.queryService?.release();
  }
}

// 类别项
interface CategoryItem {
  name: string;
  value: CapabilityCategory;
}

3.3 能力匹配工具

/**
 * 能力匹配工具类
 * 提供场景化的能力匹配能力
 */
export class CapabilityMatcher {
  private queryService: CapabilityQueryService;
  
  constructor(queryService: CapabilityQueryService) {
    this.queryService = queryService;
  }
  
  /**
   * 匹配视频通话场景
   */
  async matchVideoCall(): Promise<MatchResult[]> {
    const requirements: CapabilityRequirement[] = [
      {
        capabilityId: 'sensor.camera.front',
        required: true
      },
      {
        capabilityId: 'sensor.microphone',
        required: true
      },
      {
        capabilityId: 'output.display',
        required: true
      },
      {
        capabilityId: 'output.speaker',
        required: false
      }
    ];
    
    return await this.queryService.findDevicesWithCapabilities(requirements);
  }
  
  /**
   * 匹配音乐播放场景
   */
  async matchMusicPlay(): Promise<MatchResult[]> {
    const requirements: CapabilityRequirement[] = [
      {
        capabilityId: 'output.speaker',
        required: true
      },
      {
        capabilityId: 'output.display',
        required: false
      }
    ];
    
    return await this.queryService.findDevicesWithCapabilities(requirements);
  }
  
  /**
   * 匹配健康监测场景
   */
  async matchHealthMonitor(): Promise<MatchResult[]> {
    const requirements: CapabilityRequirement[] = [
      {
        capabilityId: 'sensor.heartrate',
        required: true
      },
      {
        capabilityId: 'sensor.spo2',
        required: false
      },
      {
        capabilityId: 'output.display',
        required: true
      }
    ];
    
    return await this.queryService.findDevicesWithCapabilities(requirements);
  }
  
  /**
   * 匹配游戏投屏场景
   */
  async matchGameCast(): Promise<MatchResult[]> {
    const requirements: CapabilityRequirement[] = [
      {
        capabilityId: 'output.display',
        required: true,
        constraints: [
          { key: 'width', operator: 'gte', value: 1920 }
        ]
      },
      {
        capabilityId: 'output.speaker',
        required: true
      },
      {
        capabilityId: 'input.touch',
        required: false
      }
    ];
    
    return await this.queryService.findDevicesWithCapabilities(requirements);
  }
  
  /**
   * 匹配拍照场景
   */
  async matchPhotography(): Promise<MatchResult[]> {
    const requirements: CapabilityRequirement[] = [
      {
        capabilityId: 'sensor.camera.back',
        required: true,
        constraints: [
          { key: 'maxResolution.width', operator: 'gte', value: 4000 }
        ]
      },
      {
        capabilityId: 'output.display',
        required: true
      }
    ];
    
    return await this.queryService.findDevicesWithCapabilities(requirements);
  }
  
  /**
   * 匹配导航场景
   */
  async matchNavigation(): Promise<MatchResult[]> {
    const requirements: CapabilityRequirement[] = [
      {
        capabilityId: 'sensor.gps',
        required: true
      },
      {
        capabilityId: 'output.display',
        required: true
      },
      {
        capabilityId: 'output.speaker',
        required: false  // 语音导航可选
      }
    ];
    
    return await this.queryService.findDevicesWithCapabilities(requirements);
  }
  
  /**
   * 自定义场景匹配
   */
  async matchCustomScene(
    requirements: CapabilityRequirement[]
  ): Promise<MatchResult[]> {
    return await this.queryService.findDevicesWithCapabilities(requirements);
  }
}

四、踩坑与注意事项

4.1 查询相关

坑1：缓存过期未刷新

设备能力可能动态变化，缓存过期会导致查询结果不准确。

// ✅ 正确做法：监听设备能力变化并刷新缓存
deviceMgr.on('capabilityChanged', (info) => {
  console.info(`设备能力变化: ${info.deviceId}`);
  
  // 清除该设备的缓存
  queryService.clearCacheForDevice(info.deviceId);
  
  // 重新查询
  queryService.queryAllCapabilities(info.deviceId);
});

坑2：查询超时未处理

查询远程设备能力可能因网络问题超时。

// ✅ 正确做法：设置超时并提供降级方案
async queryWithTimeout(deviceId: string): Promise<CapabilityInfo[]> {
  const timeout = 5000;
  
  try {
    const result = await Promise.race([
      this.queryService.queryAllCapabilities(deviceId),
      new Promise<never>((_, reject) => {
        setTimeout(() => reject(new Error('查询超时')), timeout);
      })
    ]);
    
    return result;
  } catch (error) {
    console.error(`查询失败，使用缓存或默认值`);
    
    // 返回默认能力列表
    return this.getDefaultCapabilities();
  }
}

4.2 匹配相关

坑3：必需能力缺失未处理

必需能力缺失时应该明确告知用户。

// ✅ 正确做法：检查必需能力并提示
async checkRequiredCapabilities(
  deviceId: string,
  requirements: CapabilityRequirement[]
): Promise<{ valid: boolean; missing: string[] }> {
  const result = await this.queryService.matchCapabilityRequirements(
    deviceId,
    requirements
  );
  
  // 检查必需能力
  const missing = requirements
    .filter(req => req.required && result.missing.includes(req.capabilityId))
    .map(req => req.capabilityId);
  
  if (missing.length > 0) {
    console.error(`必需能力缺失: ${missing.join(', ')}`);
    
    // 提示用户
    this.showMissingCapabilityDialog(missing);
  }
  
  return {
    valid: missing.length === 0,
    missing: missing
  };
}

坑4：能力约束不满足

能力存在但约束条件不满足。

// ✅ 正确做法：详细检查约束条件
async checkCapabilityConstraints(
  deviceId: string,
  capabilityId: string,
  constraints: CapabilityConstraint[]
): Promise<{ satisfied: boolean; failed: string[] }> {
  const property = await this.queryService.getCapabilityProperty(
    deviceId,
    capabilityId
  );
  
  if (!property) {
    return { satisfied: false, failed: ['能力不存在'] };
  }
  
  const failed: string[] = [];
  
  for (const constraint of constraints) {
    const value = property.metrics?.get(constraint.key);
    
    let satisfied = false;
    switch (constraint.operator) {
      case 'gte':
        satisfied = value >= constraint.value;
        break;
      case 'lte':
        satisfied = value <= constraint.value;
        break;
      case 'eq':
        satisfied = value === constraint.value;
        break;
    }
    
    if (!satisfied) {
      failed.push(`${constraint.key} 不满足约束: 期望 ${constraint.operator} ${constraint.value}, 实际 ${value}`);
    }
  }
  
  return {
    satisfied: failed.length === 0,
    failed: failed
  };
}

4.3 性能相关

坑5：频繁查询导致性能问题

// ✅ 正确做法：批量查询并缓存
async batchQueryCapabilities(deviceIds: string[]): Promise<Map<string, CapabilityInfo[]>> {
  const results = new Map<string, CapabilityInfo[]>();
  
  // 并行查询
  const promises = deviceIds.map(async deviceId => {
    const capabilities = await this.queryService.queryAllCapabilities(deviceId);
    results.set(deviceId, capabilities);
  });
  
  await Promise.all(promises);
  
  return results;
}

五、HarmonyOS 6适配指南

5.1 API变更

能力查询API增强：

// HarmonyOS 5.0
const capabilities = await deviceMgr.getDeviceCapabilities(deviceId);

// HarmonyOS 6.0
import { CapabilityQuery } from '@ohos.distributedHardware.capability';

const query = CapabilityQuery.getInstance();

// 支持更细粒度的查询
const capabilities = await query.query({
  deviceId: deviceId,
  categories: [CapabilityCategory.SENSOR, CapabilityCategory.OUTPUT],
  includeProperties: true,    // 包含详细属性
  includeMetrics: true        // 包含性能指标
});

5.2 行为变更

变更1：能力属性增强

HarmonyOS 6提供了更丰富的能力属性。

// HarmonyOS 6新增能力属性
interface EnhancedCapabilityProperty extends CapabilityProperty {
  // 新增：能力版本
  version: string;
  
  // 新增：能力提供商
  provider: string;
  
  // 新增：能力评分（AI计算）
  aiScore: number;
  
  // 新增：使用统计
  usageStats: {
    totalUsageTime: number;
    usageCount: number;
    lastUsedTime: number;
  };
}

变更2：能力预测

// HarmonyOS 6新增能力预测
const prediction = await query.predictCapabilityNeeds({
  context: 'video_call',     // 当前场景
  history: true              // 基于历史数据
});

// prediction返回可能需要的能力列表
console.info(`预测需要的能力: ${prediction.capabilities}`);

六、总结

设备能力查询是分布式协同的基础能力，通过完整的能力模型、灵活的查询接口、智能的匹配算法，让应用能够准确感知设备能力，实现智能协同。

核心要点回顾：

1. 能力分类体系：输入、输出、传感器、计算、存储、网络等大类
2. 能力属性模型：不仅查询"有无"，还能查询性能、配置、状态
3. 能力查询流程：缓存优先、按需刷新、超时处理
4. 能力匹配算法：需求匹配、约束检查、最优选择

最佳实践建议：

• 监听能力变化并及时刷新缓存
• 设置合理超时并提供降级方案
• 检查必需能力并明确提示用户
• 详细检查能力约束条件
• 批量查询优化性能
• 使用兼容层适配多版本API

设备能力查询让分布式协同从"盲目尝试"升级到"精准匹配"，是实现智能设备协同的关键。