一、类概述

“未来之窗仙盟创梦数据太虚” 是一个基于浏览器localStorage的前端数据管理类，主要用于实现数据的存储、加载、新增、更新、删除、查询等操作，支持基础条件查询与类 SQL 风格的高级查询，适用于前端轻量级数据管理场景（如小游戏、小型 Web 应用的本地数据存储）。

类核心特性：

• 数据持久化：依托localStorage实现数据本地持久化，页面刷新后数据不丢失
• 功能全面：覆盖数据 CRUD（创建、读取、更新、删除）全流程
• 灵活查询：支持多条件基础查询与中文 / 英文操作符的高级查询
• 命名风格：采用 “仙盟”“灵蕴阁”“神通” 等国风命名，贴合 “未来之窗仙盟” 业务场景

二、核心概念说明

概念（类内属性 / 变量）	含义解释	作用
仙盟创梦数据太虚_STORAGE_PREFIX	数据存储前缀	拼接在localStorage的 key 前，避免不同业务数据 key 冲突，固定值为 “未来之窗仙盟数据_”
神通	数据标识（自定义 key）	实例化类时传入的参数，与前缀拼接后作为localStorage的最终 key，用于区分不同数据集
灵蕴阁	数据存储容器	类内部的数组，加载localStorage数据后存储在此，所有 CRUD 操作均基于此数组

三、类方法详解

1. 构造函数（constructor）

功能

初始化数据管理实例，指定数据集标识并加载本地存储的对应数据。

语法

javascript

new 仙盟创梦数据太虚(神通);

参数

参数名	类型	说明	示例
神通	String	数据集的唯一标识，将与前缀拼接为localStorage的 key	"玩家信息"、"道具列表"

示例

javascript

// 初始化“玩家信息”数据集实例
const 玩家数据管理 = new 仙盟创梦数据太虚("玩家信息");

2. 加载数据（加载数据）

功能

从localStorage中读取当前数据集（神通对应的 key）的内容，若数据不存在则返回空数组。

语法

javascript

实例.加载数据();

说明

• 类实例化时会自动调用此方法，无需手动调用
• 返回值为解析后的 JSON 数组（localStorage中存储的是 JSON 字符串，此方法会自动转为数组）

3. 保存数据（保存）

功能

将当前灵蕴阁（数据容器）中的数据转为 JSON 字符串，存入localStorage对应 key 中，实现数据持久化。

语法

javascript

实例.保存();

说明

• 新增、更新、删除、清空等方法内部会自动调用此方法，无需手动调用
• 若需手动触发保存（如直接修改灵蕴阁后），可主动调用

4. 新增数据（新增）

功能

向灵蕴阁数组中添加一条新数据，并自动保存到localStorage。

语法

javascript

实例.新增(仙纪);

参数

参数名	类型	说明	示例
仙纪	Object	待新增的数据对象，需包含自定义字段（如 ID、名称等）	{玩家ID: 1001, 昵称: "仙尊", 等级: 50}

返回值

新增的仙纪数据对象

示例

javascript

// 向“玩家信息”数据集新增一条玩家数据
const 新玩家 = 玩家数据管理.新增({
  玩家ID: 1001,
  昵称: "仙尊",
  等级: 50,
  门派: "青云门"
});
console.log("新增的玩家数据：", 新玩家);

5. 更新数据（更新）

功能

根据指定条件匹配灵蕴阁中的数据，匹配成功后用新数据覆盖原数据，并自动保存。

语法

javascript

实例.更新(param1, value1, updatedItem, param2, value2);

参数

参数名	类型	说明	示例
param1	String	第一个匹配条件的字段名	"玩家 ID"
value1	任意类型	第一个匹配条件的字段值	1001
updatedItem	Object	更新后的完整数据对象（会覆盖原数据）	{玩家ID: 1001, 昵称: "仙尊", 等级: 51, 门派: "青云门"}
param2（可选）	String	第二个匹配条件的字段名（多条件匹配）	"门派"
value2（可选）	任意类型	第二个匹配条件的字段值	"青云门"

返回值

更新后的数据对象（若未匹配到数据则返回undefined）

示例

javascript

// 将“玩家ID=1001”的玩家等级更新为51
const 更新后玩家 = 玩家数据管理.更新(
  "玩家ID", 1001,
  {玩家ID: 1001, 昵称: "仙尊", 等级: 51, 门派: "青云门"} // 更新后的完整数据
);
console.log("更新后的玩家数据：", 更新后玩家);

6. 删除数据（删除）

功能

根据指定条件匹配灵蕴阁中的数据，匹配成功后删除该数据，并自动保存。

语法

javascript

实例.删除(param1, value1, param2, value2);

参数

参数名	类型	说明	示例
param1	String	第一个匹配条件的字段名	"玩家 ID"
value1	任意类型	第一个匹配条件的字段值	1001
param2（可选）	String	第二个匹配条件的字段名	"门派"
value2（可选）	任意类型	第二个匹配条件的字段值	"青云门"

示例

javascript

// 删除“玩家ID=1001”的玩家数据
玩家数据管理.删除("玩家ID", 1001);

7. 读取单条数据（读取）

功能

根据指定条件匹配灵蕴阁中的数据，返回第一条匹配的数据（若多条匹配仅返回第一条）。

语法

javascript

实例.读取(param1, value1, param2, value2);

参数

同 “删除数据” 方法的参数

返回值

匹配到的第一条数据对象（若未匹配到则返回undefined）

示例

javascript

// 读取“玩家ID=1001”的玩家数据
const 目标玩家 = 玩家数据管理.读取("玩家ID", 1001);
console.log("读取到的玩家数据：", 目标玩家);

8. 读取多条数据（选择）

功能

根据指定条件匹配灵蕴阁中的数据，返回所有匹配的数据（数组形式）。

语法

javascript

实例.选择(param1, value1, param2, value2);

参数

同 “删除数据” 方法的参数

返回值

匹配到的所有数据组成的数组（若未匹配到则返回空数组）

示例

javascript

// 读取“门派=青云门”的所有玩家数据
const 青云门玩家列表 = 玩家数据管理.选择("门派", "青云门");
console.log("青云门玩家列表：", 青云门玩家列表);

9. 清空数据（清空）

功能

清空灵蕴阁数组，并删除localStorage中当前数据集的所有数据。

语法

javascript

实例.清空();

示例

javascript

// 清空“玩家信息”数据集的所有数据
玩家数据管理.清空();

10. 读取全部数据（读取全部）

功能

返回灵蕴阁中的所有数据（即当前数据集的完整数据）。

语法

javascript

实例.读取全部();

返回值

当前数据集的完整数组

示例

javascript

// 读取“玩家信息”数据集的所有数据
const 所有玩家 = 玩家数据管理.读取全部();
console.log("所有玩家数据：", 所有玩家);

11. 注入数据（注入数据）

功能

用自定义数组覆盖灵蕴阁中的原有数据，并自动保存到localStorage（适用于批量导入数据场景）。

语法

javascript

实例.注入数据(仙纪);

参数

参数名	类型	说明	示例
仙纪	Array	用于覆盖的新数据数组，数组内需为数据对象	[{玩家ID: 1002, 昵称: "仙童"}, {玩家ID: 1003, 昵称: "仙子"}]

返回值

注入的新数据数组

示例

javascript

// 批量注入两条玩家数据
const 批量玩家数据 = [
  {玩家ID: 1002, 昵称: "仙童", 等级: 20, 门派: "天音寺"},
  {玩家ID: 1003, 昵称: "仙子", 等级: 30, 门派: "鬼王宗"}
];
玩家数据管理.注入数据(批量玩家数据);

12. 高级 SQL 查询（选择高级 SQL）

功能

支持类 SQL 的自然语言查询，可使用中文 / 英文操作符与逻辑运算符，实现复杂条件筛选。

语法

javascript

实例.选择高级SQL(sql);

支持的操作符

中文操作符	英文操作符	作用	示例
等于	=	匹配字段值等于指定值	"等级 = 30"
不等于	!=	匹配字段值不等于指定值	"门派！= 青云门"
大于	>	匹配字段值大于指定值（仅数字有效）	"等级 > 25"
大于等于	>=	匹配字段值大于等于指定值（仅数字有效）	"等级 >=30"
小于	<	匹配字段值小于指定值（仅数字有效）	"等级 < 40"
小于等于	<=	匹配字段值小于等于指定值（仅数字有效）	"等级 <=35"
包含	like	匹配字段值包含指定字符串	"昵称包含仙"

支持的逻辑运算符

中文逻辑符	英文逻辑符	作用	示例
并且	and	同时满足多个条件	"门派 = 青云门 并且 等级 > 40"
或者	or	满足任意一个条件	"等级 > 40 或者 门派 = 鬼王宗"

参数

参数名	类型	说明	示例
sql	String	类 SQL 查询语句（无需写select * from，直接写条件）	"门派 = 青云门 并且 等级 > 40"

返回值

匹配到的所有数据组成的数组（若未匹配到则返回空数组）

示例

javascript

// 查询“门派=青云门且等级>45”的玩家
const 高等级青云门玩家 = 玩家数据管理.选择高级SQL("门派=青云门 并且 等级>45");

// 查询“等级<30或门派=天音寺”的玩家
const 新手或天音寺玩家 = 玩家数据管理.选择高级SQL("等级<30 或者 门派=天音寺");

// 查询“昵称包含仙且等级>=25”的玩家
const 仙字昵称玩家 = 玩家数据管理.选择高级SQL("昵称包含仙 并且 等级>=25");

四、完整 Demo 示例

场景

实现 “未来之窗仙盟” 玩家数据的新增、查询、更新、删除全流程操作。

javascript

// 1. 初始化“玩家信息”数据集实例
const 玩家数据管理 = new 仙盟创梦数据太虚("玩家信息");

// 2. 新增3条玩家数据
玩家数据管理.新增({玩家ID: 1001, 昵称: "仙尊", 等级: 50, 门派: "青云门", 战力: 10000});
玩家数据管理.新增({玩家ID: 1002, 昵称: "仙童", 等级: 20, 门派: "天音寺", 战力: 2000});
玩家数据管理.新增({玩家ID: 1003, 昵称: "仙子", 等级: 35, 门派: "鬼王宗", 战力: 5000});
console.log("步骤2：新增后所有玩家数据：", 玩家数据管理.读取全部());

// 3. 基础查询：读取“门派=青云门”的玩家
const 青云门玩家 = 玩家数据管理.选择("门派", "青云门");
console.log("步骤3：青云门玩家：", 青云门玩家);

// 4. 高级查询：查询“战力>3000且等级<40”的玩家
const 中战力玩家 = 玩家数据管理.选择高级SQL("战力>3000 并且 等级<40");
console.log("步骤4：中战力玩家（战力>3000且等级<40）：", 中战力玩家);

// 5. 更新数据：将“玩家ID=1002”的等级更新为25，战力更新为3000
玩家数据管理.更新(
  "玩家ID", 1002,
  {玩家ID: 1002, 昵称: "仙童", 等级: 25, 门派: "天音寺", 战力: 3000}
);
console.log("步骤5：更新后所有玩家数据：", 玩家数据管理.读取全部());

// 6. 删除数据：删除“玩家ID=1003”的玩家
玩家数据管理.删除("玩家ID", 1003);
console.log("步骤6：删除后所有玩家数据：", 玩家数据管理.读取全部());

// 7. 清空数据（可选，用于测试后清理）
// 玩家数据管理.清空();
// console.log("步骤7：清空后所有玩家数据：", 玩家数据管理.读取全部());

Demo 运行结果说明

1. 步骤 2 后，localStorage中会新增key="未来之窗仙盟数据_玩家信息"的条目，存储 3 条玩家数据的 JSON 字符串。
2. 步骤 3 会返回[{玩家ID: 1001, ...}]（青云门玩家）。
3. 步骤 4 会返回[{玩家ID: 1003, ...}]（战力 5000>3000 且等级 35<40）。
4. 步骤 5 后，玩家 1002 的等级变为 25，战力变为 3000。
5. 步骤 6 后，玩家 1003 的数据被删除，仅剩 2 条玩家数据。

五、注意事项

1. 数据类型限制：localStorage仅支持存储字符串，类内部已通过JSON.stringify/JSON.parse自动转换，但需注意：
   • 不支持存储Function、Symbol等特殊类型数据
   • 日期类型会被转为字符串，读取后需手动转换回Date对象
2. 浏览器兼容性：支持所有现代浏览器（Chrome、Firefox、Edge 等），不支持 IE8 及以下（localStorage兼容性问题）。
3. 数据大小限制：localStorage单个域名存储上限约为 5MB，避免存储过大数据集。
4. 条件匹配规则：基础查询（读取、选择、删除）使用==松散匹配（如1001与"1001"会匹配），若需严格匹配需自行修改类内==为===。

阿雪技术观

让我们积极投身于技术共享的浪潮中，不仅仅是作为受益者，更要成为贡献者。无论是分享自己的代码、撰写技术博客，还是参与开源项目的维护和改进，每一个小小的举动都可能成为推动技术进步的巨大力量

Embrace open source and sharing, witness the miracle of technological progress, and enjoy the happy times of humanity! Let's actively join the wave of technology sharing. Not only as beneficiaries, but also as contributors. Whether sharing our own code, writing technical blogs, or participating in the maintenance and improvement of open source projects, every small action may become a huge force driving technological progrss.