---
name: "saveLightScene"
mode: "kit"
versionRequirements:
  - { name: "@tuya-miniapp/cloud-api", version: "1.2.0" }
---

## saveLightScene

> [VERSION] @tuya-miniapp/cloud-api >= 1.2.0

> 💡 接口依赖云能力，需在[小程序开发者平台](https://platform.tuya.com/miniapp/)开发设置-云能力进行授权配置, 具体操作: 找到 小程序照明场景能力 卡片, 点击卡片右下角 授权 按钮, 完成该云能力授权。

### 描述

新增、编辑并保存照明场景。该接口用于保存灯光场景的规则配置，包括场景名称、图标、执行动作等信息。

### 参数

`Params`

| 参数 | 类型 | 必填 | 默认值 | 描述 |
| --- | --- | --- | --- | --- |
| `data` | `SaveLightSceneParams` | 是 | - | 请求参数：ownerId（家庭 ID）、sceneExpr（场景规则 JSON 数据，包含场景的完整配置信息；SaveExprData 字段说明见文档「sceneExpr 字段说明」） |

### 引用对象

##### `interface` SaveLightSceneParams

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `ownerId` | `string` | 家庭 ID |
| `sceneExpr` | `string` | 场景规则 JSON 数据（SaveExprData 对象序列化后的字符串） |

##### `interface` LinkageActionVO

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `actionExecutor` | `string` | 执行器类型，如 "lightDevice" |
| `entityId` | `string` | 实体 ID（设备 ID） |
| `entityName` | `string` | 实体名称（设备名称） |
| `executorProperty` | `Record<string, any>` | 执行属性，包含设备控制指令 |
| `extraProperty` | `Record<string, any>` | 额外属性，包含场景相关信息 |

##### `interface` LinkageConditionVO

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `conditionType` | `string` | 条件类型 |
| `entityId` | `string` | 实体 ID |
| `expr` | `Record<string, any>` | 条件表达式 |


### 示例代码

#### 请求示例

```typescript
import { saveLightScene } from '@tuya-miniapp/cloud-api';

const params = {
  ownerId: '194137',
  sceneExpr: JSON.stringify({
    actions: [
      {
        actionExecutor: 'lightDevice',
        entityId: 'vdevo176127325226099',
        entityName: '调试-步进调光-vdevo',
        executorProperty: {
          switch_led: true,
          work_mode: 'scene',
          smb_scene: '0132010100000000000003e80000320101000000000000000a0000',
        },
        extraProperty: {
          parentRegionId: '57939115',
          sceneName: '500毫秒渐变（暖光）',
          sceneId: '22304912',
          sceneType: 1,
          selectCellBackground: 'https://images.tuyacn.com/light/library/icon/img_scene.png',
        },
      },
    ],
    parentRegionId: 57939115,
    name: '500毫秒渐变（暖光）',
    displayColor: 'BA7B69',
    sceneType: 3,
    matchType: 1,
    icon: 'https://images.tuyacn.com/smart/rule/light/dianji_default.png',
  }),
};

saveLightScene(params)
  .then(result => {
    console.log('场景保存成功:', result);
  })
  .catch(error => {
    console.error('场景保存失败:', error);
  });
```

#### 返回示例

```json
{
  "id": 123456,
  "code": "light_scene_001",
  "name": "500毫秒渐变（暖光）",
  "parentRegionId": "57939115",
  "ownerId": "194137",
  "uid": "ay1234567890",
  "icon": "https://images.tuyacn.com/smart/rule/light/dianji_default.png",
  "enabled": 1,
  "status": 1,
  "sort": 1,
  "sceneType": 3,
  "displayColor": "BA7B69",
  "matchType": 1,
  "gmtCreate": 1766558627585,
  "gmtModified": 1766558627585
}
```