Tuya.com
简体中文
English
注册
登录开发者平台
简体中文
English
注册
登录开发者平台
Smart App SDK
search
根据文档目录筛选
Smart App SDK智能生活 App SDK鸿蒙开发指南智能场景

智能场景

更新时间：2025-12-16 06:09:21

智能场景分为 一键执行场景 和 自动化场景，本文分别简称为 场景 和 自动化。

  • 场景是用户添加动作，手动触发。
  • 自动化是由用户设定条件，当条件触发后自动执行设定的动作。

功能说明

涂鸦支持用户根据实际生活场景，通过设置气象或设备条件，当条件满足时，让一个或多个设备执行相应的任务。

类名 说明
TSmartScene 提供了场景的查询、执行、删除、启用/禁用等操作，使用静态方法调用。
NormalSceneBean 场景数据模型，包含场景的基本信息、条件列表、动作列表等。
SceneCondition 场景条件数据模型，表示场景的触发条件。
SceneAction 场景动作数据模型，表示场景执行的任务。

在使用智能场景相关的接口之前，您需要首先了解 场景条件 和 场景任务 这两个概念。

场景条件

场景条件对应 SceneCondition 类，涂鸦支持以下条件类型：

  • 气象条件：包括温度、湿度、天气、PM2.5、空气质量、日落日出，用户选择气象条件时，可以选择当前城市。
  • 设备条件：指用户可预先选择一个设备的功能状态，当该设备达到该状态时，会触发当前场景里的任务，但同一设备不能同时作为条件和任务，避免操作冲突。
  • 定时条件：指可以按照指定的时间去执行预定的任务。

SceneCondition 对象

参数 类型 描述
entityName String 条件名称
entityId String 条件为设备类型时，表示设备 ID
entityType Int 条件类型，例如：
  • 一键执行：99
  • 设备：1
  • 天气：3
  • 定时：6
  • Pir：7
  • 地理围栏：10
  • 家人回家：11
  • 安防：12
  • 持续时间计算：13
  • 日落日出：16
  • 能源：28
  • 结构体：30
entitySubIds String 除设备之外的其它条件标识，例如：
  • 温度：temp
  • 湿度：humidity
  • 天气：condition
  • PM 2.5：pm25
  • 空气质量：aqi
  • 日出日落：sunsetrise
  • 风速：windSpeed

场景任务

场景任务是指当该场景满足已经设定的气象或设备条件时，让一个或多个设备执行某种操作，对应 SceneAction 类。或者关闭、开启一个自动化。

SceneAction 对象

字段 类型 说明
actionId String 动作 ID
entityId String 设备 ID
entityName String 设备名称
actionExecutor String 动作类型。枚举：
  • ruleTrigger：触发场景
  • ruleEnable：启用场景
  • ruleDisable：禁用场景
  • appPushTrigger：推送消息
  • mobileVoiceSend：电话服务
  • smsSend：短信服务
  • deviceGroupDpIssue：执行群组
  • irIssue：执行红外设备
  • dpIssue：执行普通设备
  • delay：延时
  • irIssueVii：执行红外设备，执行参数为真实的红外控制码
  • toggle：执行切换开关动作
  • dpStep：执行步进动作
executorProperty Dictionary 动作执行信息
extraProperty Dictionary 动作额外信息

场景查询

查询简易场景列表

接口说明

接口会同时返回场景和自动化，您可以通过条件（conditions）字段是否为空数组来区分场景和自动化。该接口比查询完整场景列表数据更加轻量。

static getSimpleSceneAll(relationId: number): Promise<TSmartAtopResponse<NormalSceneBean[]>>

参数说明

参数 类型 说明
relationId number 家庭 ID

返回值说明

返回 Promise<TSmartAtopResponse<NormalSceneBean[]>>，其中 result 字段为场景列表数组。

示例代码

TSmartScene.getSimpleSceneAll(this.currentHomeId).then((data) => {
  if (data.result) {
    this.sceneList = data.result
    // 处理场景列表
  }
}).catch((error: Error) => {
  console.error('加载场景列表失败:', error)
})

根据联动类型查询场景列表

接口说明

根据联动类型查询列表，目前在设备首页一键执行列表使用（from 5.0.0）。

static getHomeSceneListByType(
  relationId: number, 
  sceneType: number, 
  page: number | undefined, 
  pageSize: number | undefined
): Promise<TSmartAtopResponse<FusionPageNormalScenes>>

参数说明

参数 类型 说明
relationId number 关系(家庭) ID
sceneType number 场景类型，
  • 1：一键执行
  • 2：自动化
page number 页码（可选）
pageSize number 每页数量（可选）

返回值说明

返回 Promise<TSmartAtopResponse<FusionPageNormalScenes>>，包含分页的场景列表数据。

示例代码

TSmartScene.getHomeSceneListByType(currentHomeId, 1, undefined, undefined).then((data)=> {
  if (data.result) {
    this.sceneList = data.result.datas
    // 处理场景列表
  }
}).catch((error: Error) => {
  console.error('加载场景列表失败:', error)
})

查询场景详情

接口说明

根据场景 ID 查询场景的详细信息，包括条件列表、动作列表等完整信息。

static getSceneDetailV1(
  relationId: number, 
  sceneId: string, 
  ruleGenre?: number, 
  homeModel?: boolean
): Promise<TSmartAtopResponse<NormalSceneBean>>

参数说明

参数 类型 说明
homeId number 家庭 ID
sceneId string 场景 ID
ruleGenre number 场景类型（可选）
  • 1：一键执行
  • 2：自动化
homeModel boolean 是否支持家庭房间信息（可选）
  • 如果设置为 true，会返回场景所在的房间
  • 如果设置为 false，不会返回房间相关信息

返回值说明

返回 Promise<TSmartAtopResponse<NormalSceneBean>>，其中 result 字段为场景详情对象。

NormalSceneBean 对象说明

参数 类型 描述
id String 场景 ID
name String 场景名称
enabled Bool 自动化是否启用
conditions Array 条件列表，SceneCondition 对象集合
actions Array 动作列表，SceneAction 对象集合
coverIcon String 一键执行的图标
displayColor String 场景背景颜色
outOfWork Int 场景状态：
  • 0：正常
  • 1：失效
  • 2：异常
ruleGenre Int 场景类型：
  • 1：一键执行
  • 2：自动化

示例代码

const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
TSmartScene.getSceneDetailV1(currentHomeId, this.sceneId, undefined, true).then((response) => {
  if (response && response.result) {
    this.sceneDetail = response.result
  }
}).catch((error: Error) => {
  console.error('加载场景详情失败:', error)
})

场景操作

保存场景

接口说明

创建新场景。

static saveScene(
  relationId: number, 
  sceneData: NormalSceneBean
): Promise<TSmartAtopResponse<NormalSceneBean>>

参数说明

参数 类型 说明
relationId number 关系(家庭) ID
sceneData NormalSceneBean 场景数据模型

返回值说明

返回 Promise<TSmartAtopResponse<NormalSceneBean>>，包含创建后的场景信息。

示例代码

const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
const sceneData: NormalSceneBean = {
  name: '新场景',
  ruleGenre: 1,
  actions: []
  // ... 其他字段
}
TSmartScene.saveScene(currentHomeId, sceneData).then((result) => {
  if (result && result.result) {
    console.info('保存场景成功:', result.result)
  }
}).catch((error: Error) => {
  console.error('保存场景失败:', error)
})

保存场景（新版）

接口说明

新版保存接口，该接口只会返回场景 ID 和场景名称。

static saveRule(
  gid: number, 
  sceneData: NormalSceneBean
): Promise<TSmartAtopResponse<NormalSceneBean>>

参数说明

参数 类型 描述
gid number 家庭 ID
sceneData NormalSceneBean 场景数据模型

返回值说明

返回 Promise<TSmartAtopResponse<NormalSceneBean>>，只包含场景 ID 和名称。

示例代码

const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
const sceneData: NormalSceneBean = {
  name: '新场景',
  ruleGenre: 1,
  actions: []
  // ... 其他字段
}
TSmartScene.saveRule(currentHomeId, sceneData).then((result) => {
  if (result && result.result) {
    console.info('保存场景成功:', result.result)
  }
}).catch((error: Error) => {
  console.error('保存场景失败:', error)
})

编辑场景

接口说明

修改已存在的场景。

static modifyScene(
  sceneId: string, 
  sceneData: NormalSceneBean, 
  needCleanGidSid: boolean | undefined
): Promise<TSmartAtopResponse<NormalSceneBean>>

参数说明

参数 类型 描述
sceneId string 场景 ID
sceneData NormalSceneBean 场景数据模型
needCleanGidSid boolean 是否需要清理 GID 和 SID（可选）

返回值说明

返回 Promise<TSmartAtopResponse<NormalSceneBean>>，包含修改后的场景信息。

示例代码

const sceneData: NormalSceneBean = {
  name: '修改后的场景',
  ruleGenre: 1,
  actions: []
  // ... 其他字段
}
TSmartScene.modifyScene(this.sceneId, sceneData, undefined).then((result) => {
  if (result && result.result) {
    console.info('编辑场景成功:', result.result)
  }
}).catch((error: Error) => {
  console.error('编辑场景失败:', error)
})

执行场景

接口说明

执行一键执行场景，触发场景中设定的所有动作。

该接口只负责发送指令到云端执行场景，具体设备执行成功与否需要监听设备的 DP 变化。

static executeScene(sceneId: string): Promise<TSmartAtopResponse<boolean>>

参数说明

参数 类型 描述
sceneId string 场景 ID

返回值说明

返回 Promise<TSmartAtopResponse<boolean>>，其中 result 字段为 true 表示执行成功，false 表示执行失败。

示例代码

executeScene() {
  TSmartScene.executeScene(this.sceneId).then((result) => {
    if (result && result.result) {
      console.info('执行场景成功')
    }
  }).catch((error: Error) => {
    console.error('执行场景失败:', error)
  })
}

删除场景

接口说明

删除指定的场景或自动化。

static deleteSceneWithHomeId(homeId: number, sceneId: string): Promise<TSmartAtopResponse<boolean>>

参数说明

参数 类型 描述
homeId number 家庭 ID
sceneId string 场景 ID

返回值说明

返回 Promise<TSmartAtopResponse<boolean>>，其中 result 字段为 true 表示删除成功，false 表示删除失败。

示例代码

deleteScene() {
  const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
  TSmartScene.deleteSceneWithHomeId(currentHomeId, this.sceneId).then((result) => {
    if (result && result.result) {
      console.info('删除场景成功')
    }
  }).catch((error: Error) => {
    const errorMessage = error instanceof Error ? error.message : String(error)
    console.error('删除场景失败:', errorMessage)
  })
}

批量删除场景

接口说明

批量删除场景，多个场景 ID 使用英文逗号分隔。

static deleteBatchSceneData(homeId: number, ruleIds: string): Promise<TSmartAtopResponse<boolean>>

参数说明

参数 类型 描述
homeId number 家庭 ID
ruleIds string 场景 ID 列表，多个使用英文逗号分隔，例如："sceneId1,sceneId2"

返回值说明

返回 Promise<TSmartAtopResponse<boolean>>，其中 result 字段为 true 表示删除成功。

示例代码

deleteSceneList() {
  const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
  TSmartScene.deleteBatchSceneData(currentHomeId, this.sceneIdList).then((result) => {
    if (result && result.result) {
      console.info('批量删除场景成功')
    }
  }).catch((error: Error) => {
    const errorMessage = error instanceof Error ? error.message : String(error)
    console.error('批量删除场景失败:', errorMessage)
  })
}

开启自动化场景

只有自动化场景才可以开启和失效。

接口说明

启用一个自动化场景，使其在满足条件时自动执行。

static enableAutomation(sceneId: string): Promise<TSmartAtopResponse<boolean>>

参数说明

参数 类型 描述
sceneId string 场景 ID

返回值说明

返回 Promise<TSmartAtopResponse<boolean>>，其中 result 字段为 true 表示启用成功，false 表示启用失败。

示例代码

TSmartScene.enableAutomation(this.sceneId).then((response) => {
  if (response.result) {
    console.info('启用场景成功')
  }
}).catch((error: Error) => {
  console.error('启用场景失败:', error)
})

失效自动化场景

接口说明

使一个自动化场景失效，不再自动执行。

static disableAutomation(sceneId: string): Promise<TSmartAtopResponse<boolean>>

参数说明

参数 类型 描述
sceneId string 场景 ID

返回值说明

返回 Promise<TSmartAtopResponse<boolean>>，其中 result 字段为 true 表示禁用成功，false 表示禁用失败。

示例代码

TSmartScene.disableAutomation(this.sceneId).then((response) => {
  if (response.result) {
    console.info('禁用场景成功')
  }
}).catch((error: Error) => {
  console.error('禁用场景失败:', error)
})

批量修改场景所属房间

接口说明

批量修改场景所属的房间。

static batchModifySceneRooms(
  relationId: number, 
  ruleIds: string, 
  roomIds: string
): Promise<TSmartAtopResponse<boolean>>

参数说明

参数 类型 描述
relationId number 关系(家庭) ID
ruleIds string 场景 ID 列表，多个使用英文逗号分隔
roomIds string 房间 ID 列表，多个使用英文逗号分隔

返回值说明

返回 Promise<TSmartAtopResponse<boolean>>，其中 result 字段为 true 表示修改成功。

示例代码

const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
TSmartScene.batchModifySceneRooms(currentHomeId, 'sceneId1,sceneId2', 'roomId1,roomId2').then((result) => {
  if (result && result.result) {
    console.info('批量修改场景所属房间成功')
  }
}).catch((error: Error) => {
  console.error('批量修改场景所属房间失败:', error)
})

排序场景列表

接口说明

对场景列表进行排序。

static sortSceneList(relationId: number, sceneIds: string[]): Promise<TSmartAtopResponse<boolean>>

参数说明

参数 类型 描述
relationId number 关系(家庭) ID
sceneIds string[] 排序后的场景 ID 数组

返回值说明

返回 Promise<TSmartAtopResponse<boolean>>，其中 result 字段为 true 表示排序成功。

示例代码

const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
TSmartScene.sortSceneList(currentHomeId, ['sceneId1', 'sceneId2', 'sceneId3']).then((result) => {
  if (result && result.result) {
    console.info('排序场景列表成功')
  }
}).catch((error: Error) => {
  console.error('排序场景列表失败:', error)
})

场景条件和动作类目

获取条件列表

接口说明

获取场景条件列表，包括气象条件、设备条件等。

static getConditionAll(
  relationId: number, 
  showFahrenheit: boolean, 
  windSpeedUnit: string | undefined
): Promise<ConditionItemList>

参数说明

参数 类型 描述
relationId number 关系(家庭) ID
showFahrenheit boolean 是否显示华氏度
windSpeedUnit string 风速单位（可选）

返回值说明

返回 Promise<ConditionItemList>，包含环境条件、设备条件、安防条件等分类的条件列表。

示例代码

const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
TSmartScene.getConditionAll(currentHomeId, false, undefined).then((data) => {
  console.info('获取条件列表成功:', data)
}).catch((error: Error) => {
  console.error('获取条件列表失败:', error)
})

获取扩展条件列表（V2）

接口说明

获取扩展条件列表，该接口从 5.17.0 版本开始支持。

static getExtendConditionsV2(
  relationId: number, 
  appVersion: string
): Promise<TSmartAtopResponse<ExtendItem[]>>

参数说明

参数 类型 描述
relationId number 关系(家庭) ID
appVersion string App 版本号，例如："5.16.0"

返回值说明

返回 Promise<TSmartAtopResponse<ExtendItem[]>>，包含扩展条件列表。

示例代码

const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
TSmartScene.getExtendConditionsV2(currentHomeId, '5.16.0').then((result) => {
  if (result && result.result) {
    console.info('获取扩展条件列表成功:', result.result)
  }
}).catch((error: Error) => {
  console.error('获取扩展条件列表失败:', error)
})

获取扩展动作列表

接口说明

获取扩展动作列表。

static getExtendActions(relationId: number): Promise<TSmartAtopResponse<ExtendItem[]>>

参数说明

参数 说明
relationId 关系(家庭) ID

返回值说明

返回 Promise<TSmartAtopResponse<ExtendItem[]>>，包含扩展动作列表。

示例代码

const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
TSmartScene.getExtendActions(currentHomeId).then((result) => {
  if (result && result.result) {
    console.info('获取扩展动作列表成功:', result.result)
  }
}).catch((error: Error) => {
  console.error('获取扩展动作列表失败:', error)
})

获取扩展动作列表（V2）

接口说明

获取扩展动作列表，该版本接口默认会返回【空间快照】动作类型，按需进行显示或隐藏。

static getExtendActionsV2(gid: number, appVersion: string): Promise<TSmartAtopResponse<ExtendItem[]>>

参数说明

参数 类型 描述
gid number 家庭 ID
appVersion string App 版本号，例如："1.0.0"

返回值说明

返回 Promise<TSmartAtopResponse<ExtendItem[]>>，包含扩展动作列表。

示例代码

const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
TSmartScene.getExtendActionsV2(currentHomeId, '1.0.0').then((result) => {
  if (result && result.result) {
    console.info('获取扩展动作列表成功:', result.result)
  }
}).catch((error: Error) => {
  console.error('获取扩展动作列表失败:', error)
})

场景日志

获取场景执行日志

接口说明

获取场景执行日志（包含本地日志）。

static getSceneLogInfoAll(
  relationId: number, 
  startTime: number, 
  endTime: number, 
  size: number, 
  lastId: string | undefined, 
  logSources: string | undefined, 
  lastRecordTime: number | undefined
): Promise<TSmartAtopResponse<ExecuteLogList>>

参数说明

参数 类型 描述
relationId number 关系(家庭) ID
startTime number 开始时间（时间戳，毫秒）
endTime number 结束时间（时间戳，毫秒）
size number 分页数量
lastId string 上一次获取的最后一条日志 ID（可选，用于分页）
logSources string 日志来源（可选）
lastRecordTime number 上一次获取的最后一条日志时间（可选，用于分页）

返回值说明

返回 Promise<TSmartAtopResponse<ExecuteLogList>>，包含日志列表和总数。

示例代码

const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
const startTime = Date.now() - 7 * 24 * 60 * 60 * 1000 // 7天前
const endTime = Date.now() // 当前时间
TSmartScene.getSceneLogInfoAll(currentHomeId, startTime, endTime, 20, undefined, undefined, undefined).then((result) => {
  if (result && result.result) {
    console.info('获取场景执行日志成功:', result.result)
  }
}).catch((error: Error) => {
  console.error('获取场景执行日志失败:', error)
})

获取场景执行日志详情

接口说明

获取场景执行日志的详细信息。

static getExecuteLogDetail(
  relationId: number, 
  eventId: string | undefined, 
  startTime: number, 
  endTime: number, 
  returnType: number
): Promise<TSmartAtopResponse<ExecuteLogDetail[]>>

参数说明

参数 类型 描述
relationId number 关系(家庭) ID
eventId string 事件 ID（可选）
startTime number 开始时间（时间戳，毫秒）
endTime number 结束时间（时间戳，毫秒）
returnType number 返回类型：
  • 1：获取所有日志信息
  • 0：只返回错误的日志信息

返回值说明

返回 Promise<TSmartAtopResponse<ExecuteLogDetail[]>>，包含日志详情列表。

示例代码

const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
const startTime = Date.now() - 7 * 24 * 60 * 60 * 1000 // 7天前
const endTime = Date.now() // 当前时间
TSmartScene.getExecuteLogDetail(currentHomeId, undefined, startTime, endTime, 1).then((result) => {
  if (result && result.result) {
    console.info('获取场景执行日志详情成功:', result.result)
  }
}).catch((error: Error) => {
  console.error('获取场景执行日志详情失败:', error)
})

检查是否有新产生的场景日志

接口说明

检查用户在当前家庭下是否产生新的场景日志。

static hasNewlyGeneratedSceneLog(relationId: number): Promise<TSmartAtopResponse<boolean>>

参数说明

参数 类型 描述
relationId number 关系(家庭) ID

返回值说明

返回 Promise<TSmartAtopResponse<boolean>>，其中 result 字段为 true 表示有新日志，false 表示没有新日志。

示例代码

const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
TSmartScene.hasNewlyGeneratedSceneLog(currentHomeId).then((result) => {
  if (result && result.result) {
    console.info('有新产生的场景日志')
  } else {
    console.info('没有新产生的场景日志')
  }
}).catch((error: Error) => {
  console.error('检查场景日志失败:', error)
})

推荐场景

获取推荐场景列表

接口说明

统一的获取推荐场景列表接口。

static getUnifiedRecommendAll(
  relationId: number, 
  source: string, 
  size: number, 
  withAdded: boolean, 
  devId: string | undefined, 
  recommendSource?: string
): Promise<TSmartAtopResponse<RecommendScene[]>>

参数说明

参数 类型 描述
relationId number 关系(家庭) ID
source string 来源：
  • TAB：智能 tab 页
  • HOME_TOP：首页顶部
  • DEVICE_BIND：设备配网
size number 推荐场景数量
withAdded boolean 是否需要已添加的推荐场景
devId string 设备 ID（可选），设备配网后需要传入
recommendSource string 推荐类型（可选）

返回值说明

返回 Promise<TSmartAtopResponse<RecommendScene[]>>，包含推荐场景列表。

示例代码

const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
TSmartScene.getUnifiedRecommendAll(currentHomeId, 'TAB', 10, false, undefined, undefined).then((result) => {
  if (result && result.result) {
    console.info('获取推荐场景列表成功:', result.result)
  }
}).catch((error: Error) => {
  console.error('获取推荐场景列表失败:', error)
})

获取推荐场景详情

接口说明

获取推荐场景的详细信息。

static requestRecommendDetail(
  relationId: number, 
  sceneId: string
): Promise<TSmartAtopResponse<RecommendScene>>

参数说明

参数 类型 描述
relationId number 关系(家庭) ID
sceneId string 推荐场景 ID

返回值说明

返回 Promise<TSmartAtopResponse<RecommendScene>>，包含推荐场景详情。

示例代码

const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
TSmartScene.requestRecommendDetail(currentHomeId, this.recommendSceneId).then((result) => {
  if (result && result.result) {
    console.info('获取推荐场景详情成功:', result.result)
  }
}).catch((error: Error) => {
  console.error('获取推荐场景详情失败:', error)
})

获取首页推荐场景

接口说明

获取首页推荐场景列表。

static getHomeRecommend(relationId: number): Promise<TSmartAtopResponse<RecommendScene[]>>

参数说明

参数 类型 描述
relationId number 关系(家庭) ID

返回值说明

返回 Promise<TSmartAtopResponse<RecommendScene[]>>，包含首页推荐场景列表。

示例代码

const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
TSmartScene.getHomeRecommend(currentHomeId).then((result) => {
  if (result && result.result) {
    console.info('获取首页推荐场景成功:', result.result)
  }
}).catch((error: Error) => {
  console.error('获取首页推荐场景失败:', error)
})

移除首页置顶推荐场景

接口说明

移除首页置顶的推荐场景。

static removeHomeRecommend(gid: number, recommendId: string): Promise<TSmartAtopResponse<boolean>>

参数说明

参数 类型 描述
gid number 家庭 ID
recommendId string 推荐场景模版 ID

返回值说明

返回 Promise<TSmartAtopResponse<boolean>>，其中 result 字段为 true 表示移除成功。

示例代码

const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
TSmartScene.removeHomeRecommend(currentHomeId, this.recommendId).then((result) => {
  if (result && result.result) {
    console.info('移除首页置顶推荐场景成功')
  }
}).catch((error: Error) => {
  console.error('移除首页置顶推荐场景失败:', error)
})

添加推荐场景

接口说明

添加推荐场景到家庭。

static addRecommend(
  gid: number, 
  recommendId: string, 
  ruleExpr: RecommendScene
): Promise<TSmartAtopResponse<RecommendScene>>

参数说明

参数 类型 描述
gid number 家庭 ID
recommendId string 推荐场景 ID
ruleExpr RecommendScene 整个推荐场景的数据模型

返回值说明

返回 Promise<TSmartAtopResponse<RecommendScene>>，包含添加后的推荐场景数据。

示例代码

const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
const recommendScene: RecommendScene = {
  // ... 推荐场景数据
}
TSmartScene.addRecommend(currentHomeId, this.recommendId, recommendScene).then((result) => {
  if (result && result.result) {
    console.info('添加推荐场景成功:', result.result)
  }
}).catch((error: Error) => {
  console.error('添加推荐场景失败:', error)
})

移除不喜欢的推荐场景

接口说明

移除不喜欢的推荐场景。

static removeRecommend(
  gid: number, 
  recommendId: string, 
  recommendSource: string
): Promise<TSmartAtopResponse<boolean>>

参数说明

参数 类型 描述
gid number 家庭 ID
recommendId string 推荐场景 ID
recommendSource string 推荐来源：
  • 1：linkage
  • 2：energy
  • 3：warning

返回值说明

返回 Promise<TSmartAtopResponse<boolean>>，其中 result 字段为 true 表示移除成功。

示例代码

const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
TSmartScene.removeRecommend(currentHomeId, this.recommendId, '1').then((result) => {
  if (result && result.result) {
    console.info('移除不喜欢的推荐场景成功')
  }
}).catch((error: Error) => {
  console.error('移除不喜欢的推荐场景失败:', error)
})

根据设备ID获取推荐场景列表

接口说明

根据设备 ID 数组获取推荐场景列表。

static getRecommendListForDeviceIDs(
  deviceIDs: string, 
  gid: number
): Promise<TSmartAtopResponse<RecommendScene[]>>

参数说明

参数 类型 描述
deviceIDs string 设备 ID 字符串，多个用逗号分隔
gid number 家庭 ID

返回值说明

返回 Promise<TSmartAtopResponse<RecommendScene[]>>，包含设备对应的推荐场景列表。

示例代码

const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
TSmartScene.getRecommendListForDeviceIDs('deviceId1,deviceId2', currentHomeId).then((result) => {
  if (result && result.result) {
    console.info('根据设备ID获取推荐场景列表成功:', result.result)
  }
}).catch((error: Error) => {
  console.error('根据设备ID获取推荐场景列表失败:', error)
})

AI 推荐场景

基于设备的AI场景推荐列表

接口说明

基于设备的 AI 场景推荐列表（返回场景模板基本信息）。

static getAIRecommendListForDeviceIDs(
  gid: number, 
  devIds: string, 
  limitCount?: number
): Promise<TSmartAtopResponse<RecommendScene[]>>

参数说明

参数 类型 描述
gid number 家庭 ID
devIds string 设备 ID 组，以逗号隔开，例如：'dsih12e1,3rfsawd2'
limitCount number 限制数量（可选）

返回值说明

返回 Promise<TSmartAtopResponse<RecommendScene[]>>，包含设备对应的 AI 推荐场景列表。

示例代码

const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
TSmartScene.getAIRecommendListForDeviceIDs(currentHomeId, 'deviceId1,deviceId2', 10).then((result) => {
  if (result && result.result) {
    console.info('基于设备的AI场景推荐列表成功:', result.result)
  }
}).catch((error: Error) => {
  console.error('基于设备的AI场景推荐列表失败:', error)
})

添加AI推荐场景

接口说明

添加 AI 推荐场景。

static addAIRecommend(
  gid: number, 
  devId: string, 
  templateId: string
): Promise<TSmartAtopResponse<boolean>>

参数说明

参数 类型 描述
gid number 家庭 ID
devId string 设备 ID
templateId string 模版 ID

返回值说明

返回 Promise<TSmartAtopResponse<boolean>>，其中 result 字段为 true 表示添加成功。

示例代码

const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
TSmartScene.addAIRecommend(currentHomeId, this.deviceId, this.templateId).then((result) => {
  if (result && result.result) {
    console.info('添加AI推荐场景成功')
  }
}).catch((error: Error) => {
  console.error('添加AI推荐场景失败:', error)
})

批量添加AI推荐场景

接口说明

批量添加 AI 推荐场景。

static batchAddAIRecommends(
  gid: number, 
  devId: string, 
  templateIds: string
): Promise<TSmartAtopResponse<boolean>>

参数说明

参数 类型 描述
gid number 家庭 ID
devId string 设备 ID
templateIds string 模版 ID 组，内部以逗号隔开，例如：'7ds23fds,324fdsg9'

返回值说明

返回 Promise<TSmartAtopResponse<boolean>>，其中 result 字段为 true 表示添加成功。

示例代码

const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
TSmartScene.batchAddAIRecommends(currentHomeId, this.deviceId, 'templateId1,templateId2').then((result) => {
  if (result && result.result) {
    console.info('批量添加AI推荐场景成功')
  }
}).catch((error: Error) => {
  console.error('批量添加AI推荐场景失败:', error)
})

场景延时

获取延时任务列表

接口说明

查询指定场景下的延时任务列表。

static getRuleDelayList(
  gid: number, 
  startTime: string, 
  endTime: string, 
  timeZoneId: string, 
  limit: number
): Promise<TSmartAtopResponse<DelayItem[]>>

参数说明

参数 类型 描述
gid number 家庭 ID
startTime string 开始时间，当前时间戳，单位毫秒
endTime string 结束时间，当前时间往后推迟 30 天的时间戳，单位毫秒
timeZoneId string 当前时区，例如：'Asia/Shanghai'
limit number 限制数量

返回值说明

返回 Promise<TSmartAtopResponse<DelayItem[]>>，包含延时任务列表。

示例代码

const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
const startTime = String(Date.now())
const endTime = String(Date.now() + 30 * 24 * 60 * 60 * 1000) // 30天后
TSmartScene.getRuleDelayList(currentHomeId, startTime, endTime, 'Asia/Shanghai', 20).then((result) => {
  if (result && result.result) {
    console.info('获取延时任务列表成功:', result.result)
  }
}).catch((error: Error) => {
  console.error('获取延时任务列表失败:', error)
})

添加延时任务

接口说明

给场景添加延时任务。

static addRuleDelay(
  gid: number, 
  ruleId: string, 
  timeZoneId: string, 
  delaySecond: number
): Promise<TSmartAtopResponse<boolean>>

参数说明

参数 类型 描述
gid number 家庭 ID
ruleId string 场景 ID
timeZoneId string 当前时区，例如：'Asia/Shanghai'
delaySecond number 延时时长，单位秒

返回值说明

返回 Promise<TSmartAtopResponse<boolean>>，其中 result 字段为 true 表示添加成功。

示例代码

const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
TSmartScene.addRuleDelay(currentHomeId, this.sceneId, 'Asia/Shanghai', 300).then((result) => {
  if (result && result.result) {
    console.info('添加延时任务成功')
  }
}).catch((error: Error) => {
  console.error('添加延时任务失败:', error)
})

移除延时任务

接口说明

移除场景的延时任务。

static removeRuleDelay(gid: number, ruleId: string): Promise<TSmartAtopResponse<boolean>>

参数说明

参数 类型 描述
gid number 家庭 ID
ruleId string 场景 ID

返回值说明

返回 Promise<TSmartAtopResponse<boolean>>，其中 result 字段为 true 表示移除成功。

示例代码

const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
TSmartScene.removeRuleDelay(currentHomeId, this.sceneId).then((result) => {
  if (result && result.result) {
    console.info('移除延时任务成功')
  }
}).catch((error: Error) => {
  console.error('移除延时任务失败:', error)
})

电话短信

获取增值服务列表

接口说明

获取增值服务列表。

static getAddServiceAll(): Promise<TSmartAtopResponse<ServiceInfo[]>>

参数说明

无参数。

返回值说明

返回 Promise<TSmartAtopResponse<ServiceInfo[]>>，包含增值服务列表。

示例代码

TSmartScene.getAddServiceAll().then((result) => {
  if (result && result.result) {
    console.info('获取增值服务列表成功:', result.result)
  }
}).catch((error: Error) => {
  console.error('获取增值服务列表失败:', error)
})

获取电话联系人信息

接口说明

获取场景的电话联系人信息。

static getMobileInfo(sceneId: string): Promise<TSmartAtopResponse<VoiceServiceInfo>>

参数说明

参数 类型 描述
sceneId string 场景 ID

返回值说明

返回 Promise<TSmartAtopResponse<VoiceServiceInfo>>，包含电话联系人信息。

示例代码

TSmartScene.getMobileInfo(this.sceneId).then((result) => {
  if (result && result.result) {
    console.info('获取电话联系人信息成功:', result.result)
  }
}).catch((error: Error) => {
  console.error('获取电话联系人信息失败:', error)
})

获取短信联系人信息

接口说明

获取场景的短信联系人信息。

static getSMSInfo(sceneId: string): Promise<TSmartAtopResponse<SMSServiceInfo>>

参数说明

参数 类型 描述
sceneId string 场景 ID

返回值说明

返回 Promise<TSmartAtopResponse<SMSServiceInfo>>，包含短信联系人信息。

示例代码

TSmartScene.getSMSInfo(this.sceneId).then((result) => {
  if (result && result.result) {
    console.info('获取短信联系人信息成功:', result.result)
  }
}).catch((error: Error) => {
  console.error('获取短信联系人信息失败:', error)
})

获取电话提醒剩余次数

接口说明

获取电话提醒服务的剩余次数。

static getMobileLeftTimes(): Promise<TSmartAtopResponse<ServiceLeftTime>>

参数说明

无参数。

返回值说明

返回 Promise<TSmartAtopResponse<ServiceLeftTime>>，包含电话提醒剩余次数信息。

示例代码

TSmartScene.getMobileLeftTimes().then((result) => {
  if (result && result.result) {
    console.info('获取电话提醒剩余次数成功:', result.result)
  }
}).catch((error: Error) => {
  console.error('获取电话提醒剩余次数失败:', error)
})

获取短信提醒剩余次数

接口说明

获取短信提醒服务的剩余次数。

static getSMSLeftTimes(): Promise<TSmartAtopResponse<ServiceLeftTime>>

参数说明

无参数。

返回值说明

返回 Promise<TSmartAtopResponse<ServiceLeftTime>>，包含短信提醒剩余次数信息。

示例代码

TSmartScene.getSMSLeftTimes().then((result) => {
  if (result && result.result) {
    console.info('获取短信提醒剩余次数成功:', result.result)
  }
}).catch((error: Error) => {
  console.error('获取短信提醒剩余次数失败:', error)
})

其他

获取场景样式

接口说明

获取背景色和图标 logo 资源。

static getSceneStyle(): Promise<TSmartAtopResponse<SceneStyle>>

参数说明

无参数。

返回值说明

返回 Promise<TSmartAtopResponse<SceneStyle>>，包含背景色和图标 logo 资源。

示例代码

TSmartScene.getSceneStyle().then((result) => {
  if (result && result.result) {
    console.info('获取场景样式成功:', result.result)
  }
}).catch((error: Error) => {
  console.error('获取场景样式失败:', error)
})

获取App是否支持守护开关

接口说明

获取 App 是否支持守护开关（from 5.1.0）。

static getSceneActionSupportSecurity(): Promise<TSmartAtopResponse<boolean>>

参数说明

无参数。

返回值说明

返回 Promise<TSmartAtopResponse<boolean>>，其中 result 字段为 true 表示支持守护开关。

示例代码

TSmartScene.getSceneActionSupportSecurity().then((result) => {
  if (result && result.result) {
    console.info('App支持守护开关')
  } else {
    console.info('App不支持守护开关')
  }
}).catch((error: Error) => {
  console.error('获取App是否支持守护开关失败:', error)
})

定位以及位置权限上报

接口说明

上报定位和位置权限信息。

static reportPermissionAndLatlon(
  hasPositionPermission: boolean, 
  lon?: string, 
  lat?: string
): void

参数说明

参数 类型 描述
hasPositionPermission boolean 是否有位置权限
lon string 经度（可选）
lat string 纬度（可选）

返回值说明

无返回值。

示例代码

TSmartScene.reportPermissionAndLatlon(true, '120.123456', '30.123456')
console.info('上报定位和位置权限信息成功')

获取引导列表

接口说明

获取场景引导 Banner 列表。

static getGuideBannerAll(): Promise<TSmartAtopResponse<BannerList>>

参数说明

无参数。

返回值说明

返回 Promise<TSmartAtopResponse<BannerList>>，包含引导 Banner 列表。

示例代码

TSmartScene.getGuideBannerAll().then((result) => {
  if (result && result.result) {
    console.info('获取引导列表成功:', result.result)
  }
}).catch((error: Error) => {
  console.error('获取引导列表失败:', error)
})

获取场景数量限制

接口说明

获取场景数量限制信息。

static getCountLimit(relationId: number): Promise<TSmartAtopResponse<CountLimit>>

参数说明

参数 类型 描述
relationId number 关系(家庭) ID

返回值说明

返回 Promise<TSmartAtopResponse<CountLimit>>，包含场景数量限制信息。

示例代码

const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
TSmartScene.getCountLimit(currentHomeId).then((result) => {
  if (result && result.result) {
    console.info('获取场景数量限制成功:', result.result)
  }
}).catch((error: Error) => {
  console.error('获取场景数量限制失败:', error)
})

获取标准场景信息

接口说明

根据设备 ID 数组获取标准场景信息。

static getStandardInfo(meshIds: string[]): Promise<TSmartAtopResponse<StandardSceneInfo[]>>

参数说明

参数 类型 描述
meshIds string[] 标准场景设备 ID 数组

返回值说明

返回 Promise<TSmartAtopResponse<StandardSceneInfo[]>>，包含标准场景信息列表。

示例代码

TSmartScene.getStandardInfo(['meshId1', 'meshId2']).then((result) => {
  if (result && result.result) {
    console.info('获取标准场景信息成功:', result.result)
  }
}).catch((error: Error) => {
  console.error('获取标准场景信息失败:', error)
})

数据类型说明

NormalSceneBean

场景数据模型，包含场景的完整信息。

参数 类型 描述
id String 场景 ID
name String 场景名称
enabled Boolean 自动化是否启用（仅自动化场景有效）
ruleGenre Number 场景类型：
  • 1：一键执行场景
  • 2：自动化场景
outOfWork Number 场景状态：
  • 0：正常
  • 1：失效
  • 2：异常
conditions SceneCondition[] 条件列表（自动化场景才有条件）
actions SceneAction[] 动作列表
coverIcon String 一键执行场景的封面图标 URL
displayColor String 场景背景颜色（十六进制字符串，不包含 #）
boundForPanel Boolean 是否绑定面板
stickyOnTop Boolean 是否在首页显示
boundForWiFiPanel Boolean 是否绑定 WiFi 面板
newLocalScene Boolean 是否是同网关下的一键执行（已废弃）
localLinkage Boolean 是否是同网关下的自动化
linkageType Number 场景类型：
  • 0：云端
  • 1：本地（单网关）
  • 2：局域网
arrowIconUrl String 场景箭头图标 URL
panelType Number 面板支持选择设备类型
disableTime Number 禁用时间
fullData Boolean 是否包含完整数据
hasTimer Boolean 场景规则是否设置有延迟执行
background String 背景图 URL（已废弃）
scenarioRule Boolean 是否为场景规则
needCleanGidSid Boolean 是否需要清理 GID 和 SID
roomIds String[] 房间 ID 数组
categorys String[] 分类数组
gwId String 接管场景的主网关设备 ID
validateDevice Boolean 是否验证设备
matchType Number 条件匹配类型：
  • 1：匹配任一
  • 2：匹配所有
ownerId String 场景所有者 ID
stickOnTop Boolean 是否置顶
boundForWifiPanel Boolean 是否绑定 WiFi 面板
preConditions PreCondition[] 场景生效时间段，前置条件数组
statusConditions SceneCondition[] 状态条件列表
subMatchType Number 状态条件匹配类型：
  • 1：匹配任一
  • 2：匹配所有
deviceIds String[] 场景规则下关联的设备 ID 集合

SceneCondition

场景条件数据模型。

参数 类型 描述
id String 条件 ID（可选）
entityName String 条件名称
entityNameV2 String 场景 2.0 定时模块的日出日落副标题内容：城市 / 重复
entityId String 条件为设备类型时，表示设备 ID
entityType Number 条件类型
entitySubIds String 除设备之外的其它条件标识
defaultIconUrl String 条件默认图标 URL
iconUrl String 条件图标 URL
exprDisplay String 副标题名称，例如 "温度 : 小于-40°F"
productId String 条件为设备类型时，表示设备产品 ID
productPic String 条件为设备类型时，表示设备产品图片
devDelMark Boolean 条件为设备类型时，表示设备是否被移除
deleteDevIcon String 条件为设备类型时，表示设备被删除时的图标
condType Number 条件匹配规则：
  • 1：表达式匹配
  • 2：简单匹配
duration String 持续时间（可选）
expr Array 条件 DP 表达式，例如：[["$temp","<",-40]]
extraInfo ConditionExtraInfo 条件拓展属性

SceneAction

场景动作数据模型。

参数 类型 描述
id String 动作 ID
actionId String 动作 ID（兼容字段）
entityId String 设备 ID
entityName String 设备名称
actionExecutor String 动作类型
executorProperty Object 动作执行信息
extraProperty Object 动作额外信息
actionDisplay String 动作展示信息
actionDisplayNew Object 动作展示信息（新格式）
devDelMark Boolean 设备是否被删除
devIcon String 设备图标
isDevOnline Boolean 设备是否在线
uiid String UI ID
productId String 产品 ID
productPic String 产品图片
deleteDevIcon String 设备被删除时的图标
defaultIconUrl String 默认图标 URL
uiInfo UIInfo UI 信息
i18nTime Number 国际化时间
pid String 产品 ID
androidUiInfo UIInfo Android UI 信息
relationGroup RelationGroup 关系组
ruleId String 规则 ID（可选）
actionStrategy String 动作策略
orderNum Number 排序号（可选）
上一篇消息相关功能
下一篇快速集成鸿蒙 App SDK
语言
简体中文
简体中文
English
400-881-8611
7×24小时服务热线
市场合作
marketing@tuya.com
业务合作
service@tuya.com
媒体联络
pr@tuya.com
关注“涂鸦智能”
涂鸦服务尽在掌握
关注“全球智能商业”
第一时间获取物联网资讯
联系我们加入我们TuyaExpoApp 商城TuyaGoTuyaGo服务商查询
法律声明隐私协议加州隐私权利声明服务条款廉正合规安全应急响应中心
©2014-2025 杭州涂鸦信息技术有限公司 版权
浙ICP备2022000504号
浙B2-20210233号
浙公网安备33010602004238号
简体中文
简体中文
English