# 文件与“偏好设置”

> 轻量持久化已被移除 —— 该用什么替代（SQLite 键值表或 homeFolder 中的文件）。

Source: https://crossfly.dev/zh/docs/data-and-services/files-and-preferences — CrossFly documentation. Full docs as one file: https://crossfly.dev/llms-full.txt

# 文件与“偏好设置”

本页面**坦诚地说明一次移除**。如果你在找 `SharedPreferences`/`UserDefaults`，请停下：
在 CrossFly 中这个机制**不存在**。

## ⚠️ 轻量持久化已被移除
`Settings.appSettings`、`appSecretKey`、`refresh()` 以及旧的“偏好设置”**都不存在了** ——
而且**退出时不会自动写入**。你要在合适的时机**显式**写入。

## 该用什么替代
| 需要存储… | 使用 |
|---|---|
| 标志、主题、上次登录（键→值） | **SQLite 中的键/值表**（[指南](/docs/data-and-services/storage-sqlite)） |
| blob / 文件 | `Device.homeFolder` 中的一个**文件** |

### SQLite 中的键/值（推荐用于配置）
```java
try (SqliteDb db = SqliteDb.open("app.db")) {
   db.exec("CREATE TABLE IF NOT EXISTS kv(k TEXT PRIMARY KEY, v TEXT)");
   db.execute("INSERT OR REPLACE INTO kv(k, v) VALUES(?, ?)", "tema", "escuro");
   String tema = db.queryString("SELECT v FROM kv WHERE k=?", "tema");   // 若不存在则为 null
}
```

### `Device.homeFolder` 中的简单文件
`Device.homeFolder` 是应用的基础目录（因平台而异）：
| 平台 | `homeFolder` |
|---|---|
| 桌面 | 工作目录（cwd） |
| Android | 应用的私有存储 |
| iOS | *documents* 文件夹 |

```java
String path = Device.homeFolder + "config.json";

byte[] bytes = Utils.readBytes(path);   // ⚠️ 若文件不存在则为 null
if (bytes != null) {
   String json = new String(bytes);
   // … 解析 …
}
// FileHandle (libGDX)，用于需要更多控制的情况：
FileHandle fh = Utils.loadFile(path);   // 若未找到则为 null
```

## 最佳实践
- **在正确的时机显式写入**（保存配置时、离开某个屏幕时）—— 没有任何东西会
  自动持久化。
- 配置优先选择 **SQLite 键值**而非零散文件（可事务、可查询）。
- 读取时**始终检查 `Utils.readBytes`/`loadFile` 的 `null`**（文件可能不存在）。

## 常见错误
- 寻找 `Settings.appSettings`/`SharedPreferences` —— 已被移除；不会回来。
- 假定关闭时会自动写入 —— 没有；请自己写入。
- 读取不存在的文件时不处理 `null`。

## 另见
- [使用 SQLite 持久化](/docs/data-and-services/storage-sqlite)