云存储

CloudStorage 提供基于云端的键值对存储服务，数据在用户的所有设备之间同步。通过 Telegram.WebApp.CloudStorage 访问。

限制

项目	限制
最大键数量	1024
键名最大长度	128 字符
值最大长度	4096 字符
键名字符	A-Z、a-z、0-9、_、-

方法

setItem

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

存储一个键值对到云存储。

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

Telegram.WebApp.CloudStorage.setItem('user_settings', JSON.stringify({
  theme: 'dark',
  language: 'zh'
}), (error, success) => {
  if (error) {
    console.error('存储失败:', error);
  } else {
    console.log('存储成功');
  }
});

getItem

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

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

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

Telegram.WebApp.CloudStorage.getItem('user_settings', (error, value) => {
  if (error) {
    console.error('读取失败:', error);
  } else {
    const settings = JSON.parse(value);
    console.log('用户设置:', settings);
  }
});

getItems

Telegram.WebApp.CloudStorage.getItems(keys, callback)

批量读取多个键的值。

参数	类型	必填	描述
keys	Array of String	是	键名数组
callback	Function	是	回调函数，参数 (error, values)，values 为键值对象

Telegram.WebApp.CloudStorage.getItems(['key1', 'key2', 'key3'], (error, values) => {
  if (!error) {
    console.log('key1:', values.key1);
    console.log('key2:', values.key2);
  }
});

removeItem

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

从云存储中删除指定键。

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

removeItems

Telegram.WebApp.CloudStorage.removeItems(keys, callback)

批量删除多个键。

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

getKeys

Telegram.WebApp.CloudStorage.getKeys(callback)

获取云存储中所有键名。

参数	类型	必填	描述
callback	Function	是	回调函数，参数 (error, keys)，keys 为键名数组

Telegram.WebApp.CloudStorage.getKeys((error, keys) => {
  if (!error) {
    console.log('所有键:', keys);
    console.log('已使用:', keys.length, '/ 1024');
  }
});

使用示例

const storage = Telegram.WebApp.CloudStorage;

// 保存用户偏好
function savePreferences(prefs) {
  storage.setItem('preferences', JSON.stringify(prefs), (err) => {
    if (err) console.error('保存失败:', err);
  });
}

// 加载用户偏好
function loadPreferences(callback) {
  storage.getItem('preferences', (err, value) => {
    if (err || !value) {
      callback(null);
    } else {
      callback(JSON.parse(value));
    }
  });
}

// 清除所有数据
function clearAll() {
  storage.getKeys((err, keys) => {
    if (!err && keys.length > 0) {
      storage.removeItems(keys, (err) => {
        if (!err) console.log('已清除所有数据');
      });
    }
  });
}