设置设备语言

设置已连接设备使用的语言。目标语言由 SDK 的 DeviceLanguage 枚举表示。

前置条件

设置设备语言前，请确保：

• 设备已连接并处于稳定状态。
• 设备支持 DeviceInfoAPI 协议。
• 所选语言存在于设备的 supportedLanguages 列表中。

API 参考

框架

AIBuds.xcframework

导入

在需要使用 SDK 的文件中导入主框架：

Swift

Swift

import AIBuds

Objective-C

Objective-C

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

协议

setDeviceLanguage 方法定义在 DeviceInfoAPI 中，该协议继承自基础设备 API 协议。

Swift

Swift

protocol DeviceInfoAPI: DeviceAPI {
    /// Current language setting of the device.
    var languageSetting: DeviceLanguage { get }

    /// List of languages supported by the device, each element is an
    /// `NSNumber` wrapping the raw value of `DeviceLanguage`.
    var supportedLanguages: [NSNumber] { get }

    /// Sets the device language.
    /// - Parameters:
    ///   - language: The target language to set.
    ///   - completion: A closure that is called when the operation completes.
    ///     - success: `true` if the operation was successful; otherwise `false`.
    ///     - error: An `NSError` object that describes the error that occurred, or `nil` if the operation was successful.
    func setDeviceLanguage(
        _ language: DeviceLanguage,
        completion: AIBudsCompletionHandler?
    )
}

Objective-C

Objective-C

@protocol AIBudsDeviceInfoAPI <AIBudsDeviceAPI>
/// Current language setting of the device.
@property(nonatomic, readonly) enum AIBudsDeviceLanguage languageSetting;

/// List of languages supported by the device, each element is an
/// `NSNumber` wrapping the raw value of `DeviceLanguage`.
@property(nonatomic, readonly, copy) NSArray<NSNumber *> *_Nonnull supportedLanguages;

/// Sets the device language.
/// - Parameters:
///   - language: The target language to set.
///   - completion: A closure that is called when the operation completes.
///     - success: `true` if the operation was successful; otherwise `false`.
///     - error: An `NSError` object that describes the error that occurred, or `nil` if the
///     operation was successful.
- (void)setDeviceLanguage:(enum AIBudsDeviceLanguage)language
               completion:(AIBudsCompletionHandler _Nullable)completion;
@end

实例方法

将设备语言设置为受支持的 DeviceLanguage 值。

Swift

Swift

/// Sets the device language.
/// - Parameters:
///   - language: The target language to set.
///   - completion: A closure that is called when the operation completes.
///     - success: `true` if the operation was successful; otherwise `false`.
///     - error: An `NSError` object that describes the error that occurred, or `nil` if the operation was successful.
func setDeviceLanguage(
    _ language: DeviceLanguage,
    completion: AIBudsCompletionHandler?
)

Objective-C

Objective-C

/// Sets the device language.
/// - Parameters:
///   - language: The target language to set.
///   - completion: A closure that is called when the operation completes.
///     - success: `true` if the operation was successful; otherwise `false`.
///     - error: An `NSError` object that describes the error that occurred, or `nil` if the
///     operation was successful.
- (void)setDeviceLanguage:(enum AIBudsDeviceLanguage)language
               completion:(AIBudsCompletionHandler _Nullable)completion;

参数

参数	类型	描述
language	DeviceLanguage / AIBudsDeviceLanguage	要设置的目标语言。
completion	AIBudsCompletionHandler?	操作结束时调用的可选完成回调。

回调参数：

名称	类型	描述
success	Bool / BOOL	操作成功时为 true，否则为 false。
error	NSError?	操作失败时的错误详情；成功时为 nil。

返回值

该方法不直接返回值，结果通过完成回调提供。

使用示例

Swift

Swift

import AIBuds

final class DeviceManager {
    weak var device: DeviceConvertible?

    func setDeviceLanguage(_ language: DeviceLanguage) {
        guard let device = device as? DeviceInfoAPI else {
            print("Device does not support language settings")
            return
        }

        let isSupported = device.supportedLanguages.contains {
            $0.intValue == language.rawValue
        }
        guard isSupported else {
            print("The selected language is not supported by this device")
            return
        }

        device.setDeviceLanguage(language) { success, error in
            if !success {
                print("Failed to set language: \(error?.localizedDescription ?? "Unknown error")")
                return
            }

            print("Device language set successfully")
        }
    }
}

Objective-C

Objective-C

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

@interface DeviceManager ()
@property(weak, nonatomic) id<AIBudsDeviceConvertible> device;
@end

@implementation DeviceManager

- (void)setDeviceLanguage:(AIBudsDeviceLanguage)language {
    id<AIBudsDeviceInfoAPI> device = (id<AIBudsDeviceInfoAPI>)self.device;
    if (![device conformsToProtocol:@protocol(AIBudsDeviceInfoAPI)]) {
        NSLog(@"Device does not support language settings");
        return;
    }

    if (![device.supportedLanguages containsObject:@(language)]) {
        NSLog(@"The selected language is not supported by this device");
        return;
    }

    [device setDeviceLanguage:language
                   completion:^(BOOL success, NSError *_Nullable error) {
                       if (!success) {
                           NSLog(@"Failed to set language: %@",
                                 error.localizedDescription ?: @"Unknown error");
                           return;
                       }

                       NSLog(@"Device language set successfully");
                   }];
}

@end

错误处理

1. 将新语言视为已应用前，先检查 success。
2. 操作失败时，通过 error 获取失败详情。
3. 发送命令前拒绝不受支持的值。
4. 除非目标设备文档明确说明，否则不要假设特定错误码。

最佳实践

1. 使用 SDK 枚举：传入 DeviceLanguage 值，而不是 ISO 语言代码字符串。
2. 检查支持的语言：调用方法前，将枚举原始值与 supportedLanguages 对照。
3. 检查协议支持：确认设备支持 DeviceInfoAPI。
4. 在主队列更新 UI：将完成回调触发的 UIKit 更新派发到主队列。

注意事项

• supportedLanguages 包含 NSNumber，用于封装 DeviceLanguage 原始值。
• languageSetting 提供设备当前语言设置。
• 支持的语言可能因设备型号和固件而异。
• SDK Demo 将语言设置为 AIBudsDeviceLanguageEnglish；生产应用应从设备声明的支持值中选择。