---
name: "SmartStorageAbility"
mode: "api"
versionRequirements:
  - { name: "@ray-js/panel-sdk", version: "1.0.0" }
title: "SDM 存储能力使用指南 - 本地与云端数据自动同步, 如何将面板数据存储到云端?"
summary: "SDM 存储能力使用指南，介绍如何将面板数据存储到本地与云端，并实现数据自动同步的接入方式。自动添加存储 key 前缀为 devId 值，防止同产品不同设备存储时导致的数据冲突。开发者操作自定义数据时会自动存储为本地（使用 getStorage/setStorage 实现 ）和云端数据（使用 getDevProperty/saveDevProperty 实现），并保持其同步，同时选取最新的数据返回，在弱网环境下防止本地操作未同步云端导致的数据丢失。"
questions:
  - "SmartStorageAbility 的本地存储（getStorage/setStorage）和云端存储（getDevProperty/saveDevProperty）是如何自动同步的？"
  - "存储 key 值自动添加 devId 前缀的目的是什么，如何防止同产品不同设备的数据冲突？"
  - "storage.set 的 value 字符串长度建议不超过 256、最大不超过 900，超过 900 会怎样？"
  - "storage.get 返回的 __isEqual__ 字段为 true 时代表什么，如何用它优化更新频率？"
  - "SmartStorageAbility.isReady() 静态方法需要 panel-sdk 升级到哪个版本才支持？"
  - "基础用法中为什么只在项目进入时调用一次 init，后续直接使用 storage 实例即可？"
  - "storage.getAll 返回的是本地与云端组合后的最新数据，如果云端请求失败会返回什么？"
  - "SDM 模式下如何通过 devices.common.model.abilities.storage 访问存储实例？"
  - "SmartStorageAbility 同时支持单设备和群组设备，在弱网或接口频繁调用场景下有什么优势？"
  - "storage.remove 删除指定 key 的数据后，本地和云端是否同时清除？"
---

# 使用

<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 针对以下能力做了抽象：
- key 值前缀： 自动添加存储 key 前缀为 devId 值，防止同产品不同设备存储时导致的数据冲突。
- 数据自动同步：开发者操作自定义数据时会自动存储为本地（使用 getStorage/setStorage 实现 ）和云端数据（使用 getDevProperty/saveDevProperty 实现），并保持其同步，同时选取最新的数据返回，在弱网环境下防止本地操作未同步云端导致的数据丢失。
</Callout>

## SmartStorageAbility

> [VERSION] @ray-js/panel-sdk >= 1.0.0

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

### 描述

智能存储能力，提供基于设备维度的键值对云端持久化存储

### 参数

`Params`

| 参数 | 类型 | 必填 | 描述 |
| --- | --- | --- | --- |
| `options` | `DeviceId \| Object` | 否 | 存储能力初始化配置 |

##### SmartStorageAbility.options 的属性

| 属性 | 类型 | 必填 | 默认值 | 描述 |
| --- | --- | --- | --- | --- |
| `deviceId` | `string` | 否 | - |  |
| `groupId` | `string` | 否 | - |  |
| `storageType` | `"local" \| "cloud" \| "both"` | 否 | - |  |


### 返回值

类型: `SmartStorageAbility`

SmartStorageAbility 实例

#### 方法

| 方法名 | 说明 |
| --- | --- |
| `init` | 初始化存储能力，建立与云端和本地的存储通道 |
| `get` | 读取指定 key 的存储数据 |
| `getAll` | 读取当前设备/群组下的所有存储数据 |
| `set` | 存储指定 key 的数据 |
| `setAll` | 批量存储多个键值对 |
| `remove` | 删除指定 key 的存储数据 |

### 引用对象

##### `type` DeviceId

```typescript
export type DeviceId = string;
```


### 示例代码

#### 示例

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

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