设备控制 UI 业务包

设备控制 UI 业务包是涂鸦智能设备控制面板的核心容器。在涂鸦智能 iOS 智慧居住 App SDK 的基础上，业务包提供了设备控制面板的加载和控制的接口封装，加速应用开发过程。

功能说明

UI 业务包主要包括以下功能：

• 面板加载：加载多种设备类型，支持 Wi-Fi、Zigbee、蓝牙 Mesh、蓝牙等接入协议的设备
• 设备控制：支持单设备和群组的控制，不支持群组管理
• 设备定时：支持为设备添加定时任务

接入组件

请在工程的 Podfile 文件中添加设备控制 UI 业务包组件，并执行 pod update 命令：

source "https://github.com/TuyaInc/TuyaPublicSpecs.git"
source 'https://cdn.cocoapods.org/'

target 'your_target_name' do
  # TuyaSmartResidence SDK
  pod "TuyaSmartResidenceKit"
  # 添加设备控制 UI 业务包
  pod 'TuyaSmartResidencePanelBizBundle'
  # 若需要扫地机功能，请依赖扫地机相关插件
  # pod 'TuyaRNApi/Sweeper'
end

注意事项

设备控制 UI 业务包包含了开源框架 RN（React Native），版本为 0.59.10。

• 若您的 iOS 工程未集成 ReactNative，请按本文步骤集成设备控制 UI 业务包。

• 若您的 iOS 工程已集成 ReactNative，需按下面步骤操作，以确定是否可集成设备控制 UI 业务包：

  • 若已集成 ReactNative，且版本 > 0.59.10，因版本兼容性问题，则无法集成设备控制 UI 业务包。
  • 若已集成 ReactNative，且 0.59.10 ≥ 版本 > 0.51，因 ReactNative 库冲突，不保证能够正常接入涂鸦面板。按下面两种方式进行操作：
    1. 移除您 iOS 工程中的 ReactNative，使用设备控制 UI 业务包依赖的 ReactNative 0.59.10。
    2. 将您 iOS 工程中集成的 ReactNative 进行更名，从而避免与业务包集成的 ReactNative 冲突。

  若均无法集成成功，则您无法接入集成设备控制 UI 业务包。

权限要求

设备控制 UI 业务包中封装了一系列 RN 接口供面板调用，其中会涉及到部分苹果隐私权限的声明。

• 如果接入的设备面板有使用相册相关的（例如：云相册），则需要在工程的 info.plist 中添加如下权限声明：

  NSPhotoLibraryAddUsageDescription
  

• 如果接入的设备面板有使用照相机相关的（例如：云相册），则需要在工程的 info.plist 中添加如下权限声明：

  NSCameraUsageDescription
  

• 如果接入的设备面板有使用位置信息相关的，则需要在工程的 info.plist 中添加如下权限声明：

  NSLocationWhenInUseUsageDescription
  

• 如果接入的设备面板有使用到麦克风（例如：音乐灯面板），则需要在工程的 info.plist 中添加如下权限声明：

  NSMicrophoneUsageDescription
  

• 如果接入的设备面板是蓝牙相关的，则需要在工程的 info.plist 中添加如下权限声明：

  NSBluetoothAlwaysUsageDescription
  NSBluetoothPeripheralUsageDescription
  

服务协议

提供服务

设备控制 UI 业务包实现 TuyaSmartResidencePanelProtocol 协议以提供服务。在 TYModuleServices 组件中，查看 TuyaSmartResidencePanelProtocol.h 的协议文件主要功能有：

#import <TuyaSmartBizCore/TuyaSmartBizCore.h>
#import <TYModuleServices/TuyaSmartResidencePanelProtocol.h>

// 清除面板缓存
- (void)cleanPanelCache;

/**
 * 获取设备面板控制器
 *
 * @param deviceModel 设备模型
 * @param initialProps  自定义初始化参数，会以 'extraInfo' 为 key 设置进 RN 应用的 initialProps 中
 * @param contextProps  自定义面板上下文，会以 'extraInfo' 为 key 设置进 Panel Context 中
 * @param completionHandler 回调返回视图控制器
 */
- (void)getPanelViewControllerWithDeviceModel:(TuyaSmartDeviceModel *)deviceModel
                                 initialProps:(nullable NSDictionary *)initialProps
                                 contextProps:(nullable NSDictionary *)contextProps
                            completionHandler:(void (^ _Nullable)(__kindof UIViewController * _Nullable panelViewController, NSError * _Nullable error))completionHandler;

/**
 * 获取群组面板控制器
 *
 * @param groupModel 群组模型
 * @param initialProps  自定义初始化参数，会以 'extraInfo' 为 key 设置进 RN 应用的 initialProps 中
 * @param contextProps  自定义面板上下文，会以 'extraInfo' 为 key 设置进 Panel Context 中
 * @param completionHandler 回调返回视图控制器
 */
- (void)getPanelViewControllerWithGroupModel:(TuyaSmartGroupModel *)groupModel
                                initialProps:(nullable NSDictionary *)initialProps
                                contextProps:(nullable NSDictionary *)contextProps
                           completionHandler:(void (^ _Nullable)(__kindof UIViewController * _Nullable panelViewController, NSError * _Nullable error))completionHandler;

// RN 版本号
- (NSString *_Nonnull)rnVersionForApp;

依赖服务

设备控制 UI 业务包主要功能为加载设备，针对不同设备会有不同的一些功能，依赖服务是为了保证这些功能正常运行。

• TuyaSmartResidenceDeviceDetailProtocol：设备面板界面右上角点击跳转事件。

  /**
  导航栏右边按钮点击事件，跳转到设备详情页
  
  @param device 设备
  @param group 群组，若有就传
  */
  - (void)gotoDeviceDetailDetailViewControllerWithDevice:(TuyaSmartDeviceModel *)device group:(TuyaSmartGroupModel *)group;
  

• TuyaSmartResidenceGroupHandleProtocol：蓝牙 Mesh 品类的设备，面板内有需要跳转到 Mesh 群组界面的事件。若需要跳转 Mesh 群组，实现如下方法：

  /**
  跳转本地 mesh 群组
  
  @param query 初始数据
  @param 是否以 navigator 的方式进行 present
  @param success
  @param failure
  */
  - (void)presentMeshLocalGroupWithQueryData:(NSDictionary *)query
                                   isNav:(BOOL)isNav;
  

使用指南

注意事项

• 调用 UI 业务包逻辑前，请确保该站点调用过以下方法：

  [self.site fetchSiteDetailWithSuccess:^(TuyaResidenceSiteModel * _Nonnull siteModel) {
  
  } failure:^(NSError *error) {
  
  }];
  

• 然后实现 TYFamilyProtocol 中的协议方法currentFamilyId。

  #import <TuyaSmartBizCore/TuyaSmartBizCore.h>
  #import <TYModuleServices/TYFamilyProtocol.h>
  
  - (void)initCurrentSite {
  	// 注册要实现的协议
  	[[TuyaSmartBizCore sharedInstance] registerService:@protocol(TYFamilyProtocol) withInstance:self];
  }
  
  // 实现对应的协议方法
  - (long long)currentFamilyId {
  	return @"site id";
  }
  

清除面板缓存

id<TuyaSmartResidencePanelProtocol> impl = [[TuyaSmartBizCore sharedInstance] serviceOfProtocol:@protocol(TuyaSmartResidencePanelProtocol)];
[impl cleanPanelCache];

打开面板

id<TuyaSmartResidencePanelProtocol> impl = [[TuyaSmartBizCore sharedInstance] serviceOfProtocol:@protocol(TuyaSmartResidencePanelProtocol)];
// 获取面板视图控制器，自行跳转
if (deviceModel) {
    [impl getPanelViewControllerWithDeviceModel:deviceModel initialProps:nil contextProps:nil completionHandler:^(__kindof UIViewController * _Nullable panelViewController, NSError * _Nullable error) {
        [self.navigationController pushViewController:panelViewController animated:YES];
    }];
} else if (groupModel) {
    [impl getPanelViewControllerWithGroupModel:groupModel initialProps:nil contextProps:nil completionHandler:^(__kindof UIViewController * _Nullable panelViewController, NSError * _Nullable error) {
        [self.navigationController pushViewController:panelViewController animated:YES];
    }];
}