---
name: "SmartLampAdvancedAbility"
mode: "api"
versionRequirements:
  - { name: "", version: "1.15.0" }
title: "SDM 照明高级能力使用指南 - 色温转换与千分之一亮度"
summary: "SDM 照明高级能力使用指南，介绍色温转换与千分之一亮度能力的接入方式。照明色温/千分之一亮度高级能力 SDK 针对以下场景做了标准化抽象：获取高级能力是否开启, 转换色温值及单位, 转换亮度值及单位, 获取 VAS 关键点信息。"
questions:
  - "getAdvanceHighEnabled 传入 'bright_value' 和 'temp_value' 分别检查什么高级能力是否启用？"
  - "convertTemperature 如何将色温原始值转换为带单位的显示值（如 2700K），返回的 result 包含哪些字段？"
  - "convertBrightness 如何将亮度原始值转换为带单位的显示值，返回的 value 和 unit 分别是什么？"
  - "SmartLampAdvancedAbility 初始化时 debug 和 waitForInit 选项分别控制什么行为？"
  - "SmartLampAdvancedAbility 自 @ray-js/panel-sdk 哪个版本开始支持（1.15.0）？"
  - "照明面板中如何根据 getAdvanceHighEnabled 的结果决定显示原始数值还是转换后的带单位值？"
  - "getAdvancedTemperatureVas 和 getAdvancedBrightnessVas 获取的 VAS 关键点信息包含什么内容（显示范围、单位）？"
  - "如何通过 useInstance() 获取 lampAdv 实例并在 React 组件中调用 convertTemperature？"
  - "SDM 模式下如何在 devices/index.ts 中将 SmartLampAdvancedAbility 注入 SmartDeviceModel 的 abilities？"
  - "色温滑动条场景中，如何结合 getAdvanceHighEnabled 和 convertTemperature 实现动态显示？"
---

# 使用

<div style={{ display: 'flex', gap: '8px', marginBottom: '16px' }}>
  <span style={{ backgroundColor: '#52c41a', color: 'white', padding: '2px 8px', borderRadius: '4px', fontSize: '12px' }}>单设备支持</span>
  <span style={{ backgroundColor: '#52c41a', color: 'white', padding: '2px 8px', borderRadius: '4px', fontSize: '12px' }}>群组支持</span>
</div>

<Callout type="info" emoji="ℹ️">
照明色温/千分之一亮度高级能力 SDK 针对以下场景做了标准化抽象：
- 获取高级能力是否开启
- 转换色温值及单位
- 转换亮度值及单位
- 获取 VAS 关键点信息
</Callout>

## 起步

SmartLampAdvancedAbility 自 @ray-js/panel-sdk@1.15.0 开始加入。

## SmartLampAdvancedAbility

> [VERSION] v1.15.0+

> 💡 通过 SmartDeviceModel 的 abilities 配置挂载后使用。
> 同时支持单设备和群组设备。

### 描述

照明高级能力，提供色温/亮度的高级转换与 VAS 信息查询

### 参数

`Params`

| 参数 | 类型 | 必填 | 描述 |
| --- | --- | --- | --- |
| `props` | `SmartLampAdvancedAbilityOptions` | 是 | 照明高级能力初始化配置 |

### 返回值

类型: `SmartLampAdvancedAbility`

SmartLampAdvancedAbility 实例

#### 方法

| 方法名 | 说明 |
| --- | --- |
| `convertTemperature` | 转换色温值：若设备启用高级色温能力则返回带单位的显示值（如 2700K），否则返回原始值与空单位。 |
| `convertBrightness` | 转换亮度值：若设备启用千分之一亮度能力则返回带单位的显示值，否则返回原始值与空单位。 |
| `getAdvancedTemperatureVas` | 获取高级色温 VAS（增值服务）信息，包含关键点（显示值、原始值、单位），用于色温条范围与展示。 |
| `getAdvancedBrightnessVas` | 获取高级亮度（千分之一亮度）VAS 信息，包含关键点，用于亮度条显示范围与单位。 |
| `getAdvanceHighEnabled` | 查询指定 DP 的高级能力是否启用：支持 bright_value（千分之一亮度）、temp_value（标准色温）、color_temp_control（Matter 色温）。 |
| `convertDp` | 按功能点将原始 DP 值转为带单位的显示值；支持 bright_value、temp_value、color_temp_control。 |

### 引用对象

##### `interface` SmartLampAdvancedAbilityOptions

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `deviceId` | `string` | 设备 id，不填默认使用 getLaunchOptions 获取当前环境下的设备 ID |
| `groupId` | `string` | 群组 id，不填默认使用 getLaunchOptions 获取当前环境下的群组 ID |
| `debug` | `boolean` | 是否开启调试模式 |
| `waitForInit` | `boolean` | 是否预加载数据 |


### 示例代码

#### 示例

```typescript
import { SmartDeviceModel, SmartLampAdvancedAbility } from '@ray-js/panel-sdk';

const sdm = new SmartDeviceModel({ abilities: [new SmartLampAdvancedAbility({})] });
```