设备存储

DeviceStorage 提供基于设备本地的持久化存储服务，数据仅存储在当前设备上，不会跨设备同步。通过 Telegram.WebApp.DeviceStorage 访问。Bot API 8.0+

限制

项目	限制
最大存储容量	5 MB
键名最大长度	128 字符
键名字符	A-Z、a-z、0-9、_、-

方法

setItem

Telegram.WebApp.DeviceStorage.setItem(key, value, callback)

存储一个键值对到设备存储。

参数	类型	必填	描述
key	String	是	键名，1-128 字符
value	String	是	值
callback	Function	否	回调函数，参数 (error, success)

Telegram.WebApp.DeviceStorage.setItem('cache_data', JSON.stringify({
  timestamp: Date.now(),
  data: largeDataSet
}), (error, success) => {
  if (error) {
    console.error('存储失败:', error);
  }
});

getItem

Telegram.WebApp.DeviceStorage.getItem(key, callback)

从设备存储中读取指定键的值。

参数	类型	必填	描述
key	String	是	键名
callback	Function	是	回调函数，参数 (error, value)

removeItem

Telegram.WebApp.DeviceStorage.removeItem(key, callback)

从设备存储中删除指定键。

参数	类型	必填	描述
key	String	是	键名
callback	Function	否	回调函数，参数 (error, success)

clear

Telegram.WebApp.DeviceStorage.clear(callback)

清除设备存储中的所有数据。

参数	类型	必填	描述
callback	Function	否	回调函数，参数 (error, success)

与云存储的区别

特性	CloudStorage	DeviceStorage
数据同步	跨设备同步	仅本地存储
容量限制	1024 键 × 4KB 值	5 MB 总容量
适用场景	用户偏好、小型数据	缓存、大量本地数据
最低版本	—	Bot API 8.0+

使用示例

const deviceStorage = Telegram.WebApp.DeviceStorage;

// 缓存 API 响应
function cacheResponse(endpoint, data) {
  const cacheEntry = JSON.stringify({
    data: data,
    cachedAt: Date.now()
  });
  deviceStorage.setItem('cache_' + endpoint, cacheEntry);
}

// 读取缓存
function getCachedResponse(endpoint, maxAge, callback) {
  deviceStorage.getItem('cache_' + endpoint, (error, value) => {
    if (error || !value) {
      callback(null);
      return;
    }
    const entry = JSON.parse(value);
    if (Date.now() - entry.cachedAt > maxAge) {
      callback(null); // 缓存已过期
    } else {
      callback(entry.data);
    }
  });
}