家庭信息管理

更新时间：2025-12-16 07:15:48下载pdf

用户登录成功后需要通过 TSmartHomeManager 去查询整个家庭列表的信息，然后初始化其中的一个家庭 TSmartHome，查询家庭详情信息，就可以对家庭中的设备进行操作控制。

功能说明

类名	说明
TSmartHomeManager	查询家庭列表、添加家庭、当前家庭管理、家庭邀请等
TSmartHome	单个家庭信息管理，获取家庭下所有设备、群组，家庭详情查询等
ITSmartHomeChangeListener	家庭列表变化回调监听器
ITSmartHomeStatusListener	单个家庭信息变化回调监听器

单个家庭信息管理相关的所有功能对应 TSmartHome 类，需要使用正确的 homeId 进行初始化。错误的 homeId 会导致初始化失败。主要功能：单个家庭信息管理，获取家庭下所有设备、群组，房间管理等。

获取家庭下所有设备、群组前需先初始化 TSmartHome 对象，并查询家庭的详情 getHomeDetail(callback)，然后 TSmartHome 实例对象中才有完整的数据。

创建家庭

接口说明

public async addHome(params: TSmartCreateHomeDataParams): Promise<TSmartAtopResponse<TSmartHomeBean>>

参数说明

TSmartCreateHomeDataParams 结构

参数	说明
name	家庭的名称
geoName	家庭的地理位置名称（城市名称）
latitude	家庭地址纬度
longitude	家庭地址经度
rooms	家庭下房间的名称列表

返回值说明

返回 Promise<TSmartAtopResponse<TSmartHomeBean>>，包含创建的家庭信息。

示例代码

import { TSmartHomeManager } from '@thingsmart/homelib';
import { TSmartCreateHomeDataParams } from '@thingsmart/homelib';

const homeManager = TSmartHomeManager.getInstance();

const params: TSmartCreateHomeDataParams = {
  name: '我的家',
  geoName: '北京市',
  latitude: 39.9042,
  longitude: 116.4074,
  rooms: ['客厅', '卧室', '厨房']
};

try {
  const response = await homeManager.addHome(params);
  if (response.success) {
    const homeBean = response.result;
    console.log('创建家庭成功，家庭ID:', homeBean.homeId);
  } else {
    console.error('创建家庭失败:', response.errorMsg);
  }
} catch (error) {
  console.error('创建家庭异常:', error);
}

查询家庭列表

本接口返回的数据只是家庭的简单信息。如果要查询具体家庭的详情，您需要去 TSmartHome 初始化一个 home，调用接口 getHomeDetail(callback)。

接口说明

public async getHomeList(): Promise<TSmartAtopResponse<Array<TSmartHomeBean>>>

返回值说明

返回 Promise<TSmartAtopResponse<Array<TSmartHomeBean>>>，包含家庭列表数据。

示例代码

const homeManager = TSmartHomeManager.getInstance();

try {
  const response = await homeManager.getHomeList();
  if (response.success) {
    const homeList = response.result;
    homeList.forEach((home) => {
      console.log('家庭ID:', home.homeId, '家庭名称:', home.homeName);
    });
  } else {
    console.error('查询家庭列表失败:', response.errorMsg);
  }
} catch (error) {
  console.error('查询家庭列表异常:', error);
}

修改家庭信息

接口说明

public async updateHome(updateHomeInfoParams: TSmartUpdateHomeDataParams): Promise<TSmartAtopResponse<boolean>>

参数说明

参数	说明
updateHomeInfoParams	更新家庭信息的参数对象

TSmartUpdateHomeDataParams 结构

参数	说明
name	家庭名称
geoName	家庭地理位置名称
latitude	家庭地址纬度
longitude	家庭地址经度

示例代码

import { TSmartHome } from '@thingsmart/homelib';
import { TSmartUpdateHomeDataParams } from '@thingsmart/homelib';

const homeId = 123456;
const smartHome = TSmartHome.getInstance(homeId);

const params: TSmartUpdateHomeDataParams = {
  name: '新家庭名称',
  geoName: '上海市',
  latitude: 31.2304,
  longitude: 121.4737
};

try {
  const response = await smartHome.updateHome(params);
  if (response.success) {
    console.log('更新家庭信息成功');
  } else {
    console.error('更新家庭信息失败:', response.errorMsg);
  }
} catch (error) {
  console.error('更新家庭信息异常:', error);
}

删除或注销家庭

接口说明

删除家庭后，该家庭下所有设备会被重置。

public async deleteHome(): Promise<TSmartAtopResponse<boolean>>

示例代码

const homeId = 123456;
const smartHome = TSmartHome.getInstance(homeId);

try {
  const response = await smartHome.deleteHome();
  if (response.success) {
    console.log('删除家庭成功');
  } else {
    console.error('删除家庭失败:', response.errorMsg);
  }
} catch (error) {
  console.error('删除家庭异常:', error);
}

查询家庭的详细信息

只有调用了此接口，TSmartHome 实例对象中才有完整的家庭数据，包括房间列表、设备列表、群组列表等。

接口说明

public getHomeDetail(callback: (homeBean?: TSmartHomeBean) => void): void

参数说明

参数	说明
callback	回调函数，参数为家庭详情对象

示例代码

const homeId = 123456;
const smartHome = TSmartHome.getInstance(homeId);

smartHome.getHomeDetail((homeBean?: TSmartHomeBean) => {
  if (homeBean) {
    console.log('家庭ID:', homeBean.homeId);
    console.log('家庭名称:', homeBean.homeName);
    console.log('房间列表:', homeBean.rooms);
    
    // 获取设备列表
    homeBean.getDeviceList().then((deviceList) => {
      console.log('设备数量:', deviceList.length);
    });
  } else {
    console.error('查询家庭详情失败');
  }
});

异步方式查询家庭详情

const homeId = 123456;
const smartHome = TSmartHome.getInstance(homeId);

try {
  const homeBean = await smartHome.getHomeDetailAsync();
  if (homeBean) {
    console.log('家庭详情:', homeBean);
  }
} catch (error) {
  console.error('查询家庭详情异常:', error);
}

对家庭中设备和群组排序

接口说明

public async sortDeviceAndGroup(params: DeviceAndGroupInHomeParams): Promise<TSmartAtopResponse<boolean>>

参数说明

参数	说明
params	排序参数对象

DeviceAndGroupInHomeParams 结构

参数	说明
list	设备和群组排序列表

list 数组元素结构

字段	说明
bizId	设备 ID（devId）或群组 ID（groupId）
bizType	业务类型，设备为 `TSmartHomeResBizType.DEVICE`，群组为 `TSmartHomeResBizType.GROUP`

示例代码

import { TSmartHome, DeviceAndGroupInHomeParams, TSmartHomeResBizType } from '@thingsmart/homelib';

const homeId = 123456;
const smartHome = TSmartHome.getInstance(homeId);

const params: DeviceAndGroupInHomeParams = {
  list: [
    { bizId: 'device_id_1', bizType: TSmartHomeResBizType.DEVICE },
    { bizId: 'group_id_1', bizType: TSmartHomeResBizType.GROUP },
    { bizId: 'device_id_2', bizType: TSmartHomeResBizType.DEVICE }
  ]
};

try {
  const response = await smartHome.sortDeviceAndGroup(params);
  if (response.success) {
    console.log('设备和群组排序成功');
  }
} catch (error) {
  console.error('排序异常:', error);
}

家庭列表变化的回调

实现 ITSmartHomeChangeListener 监听器后，可以在家庭列表更变的回调中进行处理。

注册家庭列表变化监听器

接口说明

public registerHomeChangeListener(homeChangeListener: ITSmartHomeChangeListener): void

ITSmartHomeChangeListener 接口定义

interface ITSmartHomeChangeListener {
  /**
   * 新增一个家庭的回调
   */
  onHomeAdded?(homeBean: TSmartHomeBean): void;
  
  /**
   * 删除一个家庭的回调
   */
  onHomeRemoved?(homeId: number): void;
  
  /**
   * 家庭信息更新的回调
   */
  onHomeInfoChanged?(homeBean: TSmartHomeBean): void;
  
  /**
   * 切换当前家庭的回调
   */
  onCurrentHomeChanged?(homeId: number, homeName: string): void;
  
  /**
   * MQTT 服务连接成功的回调
   */
  onServerConnected?(): void;
}

示例代码

import { TSmartHomeManager, ITSmartHomeChangeListener, TSmartHomeBean } from '@thingsmart/homelib';

class MyHomeListener implements ITSmartHomeChangeListener {
  onHomeAdded(homeBean: TSmartHomeBean): void {
    console.log('新增家庭:', homeBean.homeName);
  }
  
  onHomeRemoved(homeId: number): void {
    console.log('删除家庭:', homeId);
  }
  
  onHomeInfoChanged(homeBean: TSmartHomeBean): void {
    console.log('家庭信息更新:', homeBean.homeName);
  }
  
  onCurrentHomeChanged(homeId: number, homeName: string): void {
    console.log('切换家庭:', homeName);
  }
  
  onServerConnected(): void {
    console.log('MQTT 连接成功，建议重新查询家庭详情');
    // 重新查询当前家庭详情，确保数据最新
  }
}

// 注册监听器
const homeManager = TSmartHomeManager.getInstance();
const listener = new MyHomeListener();
homeManager.registerHomeChangeListener(listener);

取消注册家庭列表变化监听器

接口说明

public unRegisterHomeChangeListener(homeChangeListener: ITSmartHomeChangeListener): void

示例代码

const homeManager = TSmartHomeManager.getInstance();
homeManager.unRegisterHomeChangeListener(listener);

取消所有家庭列表变化监听器

接口说明

public unRegisterAllHomeChangeListener(): void

示例代码

const homeManager = TSmartHomeManager.getInstance();
homeManager.unRegisterAllHomeChangeListener();

家庭信息变化的回调

实现 ITSmartHomeStatusListener 监听器后，可以在单个家庭信息更变的回调中进行处理。

注册家庭信息变化监听器

接口说明

public registerHomeStatusListener(listener: ITSmartHomeStatusListener): void

ITSmartHomeStatusListener 接口定义

interface ITSmartHomeStatusListener {
  /**
   * 家庭信息更新回调
   */
  onHomeInfoChanged?(homeBean: TSmartHomeBean): void;
  
  /**
   * 共享设备列表变化回调
   */
  onSharedDeviceList?(homeId: number): void;
  
  /**
   * 共享群组列表变化回调
   */
  onSharedGroupList?(homeId: number): void;
  
  /**
   * 添加房间回调
   */
  onRoomAdded?(roomBean: TSmartRoomBean): void;
  
  /**
   * 删除房间回调
   */
  onRoomRemoved?(roomId: number): void;
  
  /**
   * 房间信息更新回调
   */
  onRoomInfoChanged?(roomBean: TSmartRoomBean): void;
  
  /**
   * 添加设备回调
   */
  onDeviceAdded?(deviceBean: TSmartDeviceModel): void;
  
  /**
   * 删除设备回调
   */
  onDeviceRemoved?(devId: string): void;
  
  /**
   * 设备信息更新回调
   */
  onDeviceInfoChanged?(deviceBean: TSmartDeviceModel): void;
  
  /**
   * 设备 DP 数据更新回调
   */
  onDeviceDpUpdate?(deviceBean: TSmartDeviceModel, dps: Record<string, Object>): void;
  
  /**
   * 添加群组回调
   */
  onGroupAdded?(groupBean: TSmartGroupModel): void;
  
  /**
   * 删除群组回调
   */
  onGroupRemoved?(groupId: string): void;
  
  /**
   * 群组信息更新回调
   */
  onGroupInfoChanged?(groupBean: TSmartGroupModel): void;
  
  /**
   * 群组 DP 数据更新回调
   */
  onGroupDpUpdate?(groupBean: TSmartGroupModel, dps: Record<string, Object>): void;
}

示例代码

import { TSmartHome, ITSmartHomeStatusListener, TSmartHomeBean } from '@thingsmart/homelib';

class MyHomeStatusListener implements ITSmartHomeStatusListener {
  onHomeInfoChanged(homeBean: TSmartHomeBean): void {
    console.log('家庭信息更新:', homeBean.homeName);
  }
  
  onRoomAdded(roomBean: TSmartRoomBean): void {
    console.log('新增房间:', roomBean.name);
  }
  
  onDeviceAdded(deviceBean: TSmartDeviceModel): void {
    console.log('新增设备:', deviceBean.name);
  }
  
  onDeviceDpUpdate(deviceBean: TSmartDeviceModel, dps: Record<string, Object>): void {
    console.log('设备数据更新:', deviceBean.devId, dps);
  }
}

// 注册监听器
const homeId = 123456;
const smartHome = TSmartHome.getInstance(homeId);
const listener = new MyHomeStatusListener();
smartHome.registerHomeStatusListener(listener);

取消注册家庭信息变化监听器

接口说明

public unRegisterHomeStatusListener(listener: ITSmartHomeStatusListener): void

示例代码

const homeId = 123456;
const smartHome = TSmartHome.getInstance(homeId);
smartHome.unRegisterHomeStatusListener(listener);

查询家庭所在地区的天气

查询天气简要信息

接口说明

该请求返回家庭所在城市的简要天气参数，如城市名称、当天的天气状况（晴、多云、雨等）、天气图片信息。

public async getHomeWeatherSketch(): Promise<TSmartAtopResponse<TSmartWeatherSketchBean>>

返回值说明

TSmartWeatherSketchBean 结构

字段	说明
condition	天气情况，例如晴、阴、雨等
iconUrl	天气图标（高亮）
inIconUrl	天气图标（普通）
temp	温度

示例代码

const homeId = 123456;
const smartHome = TSmartHome.getInstance(homeId);

try {
  const response = await smartHome.getHomeWeatherSketch();
  if (response.success) {
    const weather = response.result;
    console.log('天气:', weather.condition);
    console.log('温度:', weather.temp);
    console.log('图标:', weather.iconUrl);
  }
} catch (error) {
  console.error('查询天气失败:', error);
}

查询天气详细信息

接口说明

查询家庭天气详细参数，如温度、湿度、紫外线指数、空气质量等。

public async getHomeWeatherDetail(optionParams?: TSmartWeatherOptionParams): Promise<TSmartAtopResponse<Array<TSmartWeatherBean>>>

参数说明

参数	说明
optionParams	天气详情参数单位配置（可选）

TSmartWeatherOptionParams 结构

参数	说明
pressureUnit	气压单位
windspeedUnit	风速单位
temperatureUnit	温度单位
limit	请求的天气详情的个数

返回值说明

TSmartWeatherBean 结构

字段	说明
icon	天气参数图标
name	天气参数名称
unit	参数单位
value	参数值

示例代码

const homeId = 123456;
const smartHome = TSmartHome.getInstance(homeId);

const optionParams: TSmartWeatherOptionParams = {
  temperatureUnit: '°C',
  pressureUnit: 'hPa',
  windspeedUnit: 'm/s',
  limit: 10
};

try {
  const response = await smartHome.getHomeWeatherDetail(optionParams);
  if (response.success) {
    const weatherList = response.result;
    weatherList.forEach((weather) => {
      console.log(`${weather.name}: ${weather.value} ${weather.unit}`);
    });
  }
} catch (error) {
  console.error('查询天气详情失败:', error);
}

上一篇家庭管理

下一篇房间信息管理