查看操作映射

读取设备按键或触控操作与已分配设备功能之间的映射关系。

前置条件

• 设备已连接并就绪
• 设备支持 DevicePhysicalOperationsAPI

API 参考

框架

AIBuds.xcframework

导入

Swift

Swift

import AIBuds

Objective-C

Objective-C

#import <AIBuds/AIBuds-Swift.h>
#import <AIBuds/AIBuds.h>

协议

该映射作为 DevicePhysicalOperationsAPI 的属性提供。

Swift

Swift

/// The protocol for device physical operations API.
protocol DevicePhysicalOperationsAPI: DeviceAPI {
    /// Physical operations with functions mapping
    /// - Returns: A dictionary mapping physical operation identifiers to function identifiers.
    ///
    /// The dictionary is structured as follows:
    /// - Keys: Physical operation identifiers. Defined in ``DeviceOperation``.
    /// - Values: Function identifiers. Defined in ``DeviceFunction``.
    var physicalOperationsMapping: [NSNumber: NSNumber]? { get }
}

Objective-C

Objective-C

/// The protocol for device physical operations API.
@protocol AIBudsDevicePhysicalOperationsAPI <AIBudsDeviceAPI>
/// Physical operations with functions mapping
/// - Returns: A dictionary mapping physical operation identifiers to function identifiers.
///
/// The dictionary is structured as follows:
/// - Keys: Physical operation identifiers. Defined in ``DeviceOperation``.
/// - Values: Function identifiers. Defined in ``DeviceFunction``.
@property(nonatomic, readonly, copy)
    NSDictionary<NSNumber *, NSNumber *> *_Nullable physicalOperationsMapping;
@end

属性

属性	类型	说明
physicalOperationsMapping	[NSNumber: NSNumber]?	将每个 DeviceOperation 原始值映射到一个 DeviceFunction 原始值。

返回值

这是一个只读可选属性，不是异步查询方法。

使用示例

Swift

Swift

import AIBuds

guard let device = device as? DevicePhysicalOperationsAPI else {
    print("Device does not support physical-operation mapping")
    return
}

guard let mapping = device.physicalOperationsMapping else {
    print("Mapping is unavailable")
    return
}

for (operationValue, functionValue) in mapping {
    let operation = DeviceOperation(rawValue: operationValue.intValue)
    let function = DeviceFunction(rawValue: functionValue.intValue)
    print("\(String(describing: operation)) → \(String(describing: function))")
}

Objective-C

Objective-C

#import <AIBuds/AIBuds-Swift.h>
#import <AIBuds/AIBuds.h>

id<AIBudsDevicePhysicalOperationsAPI> device = (id<AIBudsDevicePhysicalOperationsAPI>)self.device;

if (![device conformsToProtocol:@protocol(AIBudsDevicePhysicalOperationsAPI)]) {
    NSLog(@"Device does not support physical-operation mapping");
    return;
}

[device.physicalOperationsMapping
    enumerateKeysAndObjectsUsingBlock:^(NSNumber *operation, NSNumber *function, BOOL *stop) {
        NSLog(@"Operation %@ → function %@", operation, function);
    }];

错误处理

该属性没有完成回调。需要分别处理设备不支持协议、映射为 nil，以及原始值无法初始化为已知枚举项的情况。

最佳实践

1. 将数值视为枚举原始值：使用 DeviceOperation 和 DeviceFunction 转换键和值。
2. 不要推断缺失项：映射中缺少某个操作，不能据此认为设备支持它。
3. 分配成功后刷新界面：如果设备会更新映射，分配成功后应重新读取该属性。

注意事项

• SDK Demo 直接读取该属性，并按操作原始值排序后显示
• 该属性不使用 Result 回调，也不存在 KeyMapping 模型