跳转到内容
Estella

数据存储

Estella 提供了 Storage API 用于本地数据持久化，在 Web（localStorage）和微信小游戏（wx storage）平台上使用统一的接口。

基本用法

import { Storage } from 'esengine';


// 字符串
Storage.setString('playerName', 'Alice');
const name = Storage.getString('playerName'); // 'Alice'


// 数字
Storage.setNumber('highScore', 9999);
const score = Storage.getNumber('highScore', 0); // 9999


// 布尔值
Storage.setBoolean('musicEnabled', true);
const music = Storage.getBoolean('musicEnabled', false); // true


// JSON（对象、数组等）
Storage.setJSON('settings', { volume: 0.8, language: 'zh' });
const settings = Storage.getJSON<{ volume: number; language: string }>('settings');

默认值

所有 getter 方法接受可选的第二个参数作为默认值。当 key 不存在或存储的值损坏时返回默认值：

const score = Storage.getNumber('score', 0);           // 不存在时返回 0
const name = Storage.getString('name', 'Player');       // 不存在时返回 'Player'
const items = Storage.getJSON<string[]>('items', []);   // 不存在或 JSON 无效时返回 []

检查与删除

if (Storage.has('highScore')) {
    console.log('找到存档数据');
}


Storage.remove('highScore');


// 清除所有 Estella 存储的数据
Storage.clear();

游戏存档示例

import { Storage } from 'esengine';


interface SaveData {
    level: number;
    hp: number;
    position: { x: number; y: number };
    inventory: string[];
}


function saveGame(data: SaveData): void {
    Storage.setJSON('save:slot1', data);
}


function loadGame(): SaveData {
    return Storage.getJSON<SaveData>('save:slot1', {
        level: 1,
        hp: 100,
        position: { x: 0, y: 0 },
        inventory: [],
    })!;
}

玩家设置示例

function loadSettings() {
    return {
        musicVolume: Storage.getNumber('settings:musicVolume', 1.0),
        sfxVolume: Storage.getNumber('settings:sfxVolume', 1.0),
        language: Storage.getString('settings:language', 'zh'),
    };
}


function saveMusicVolume(volume: number) {
    Storage.setNumber('settings:musicVolume', volume);
}

API 参考

方法说明
getString(key, default?)获取字符串
setString(key, value)存储字符串
getNumber(key, default?)获取数字
setNumber(key, value)存储数字
getBoolean(key, default?)获取布尔值
setBoolean(key, value)存储布尔值
getJSON<T>(key, default?)获取 JSON 解析后的值
setJSON<T>(key, value)存储可序列化为 JSON 的值
has(key)检查 key 是否存在
remove(key)删除指定 key
clear()清除所有 Estella 存储的数据

平台说明

平台底层实现容量限制
WeblocalStorage~5 MB
微信小游戏wx.getStorageSync10 MB

下一步