mirror of
https://github.com/motajs/template.git
synced 2026-10-20 05:40:18 +08:00
63 lines
2.7 KiB
Markdown
63 lines
2.7 KiB
Markdown
# Flag 变量
|
||
|
||
有些状态要跨事件、跨楼层一直保留，还要跟着存档走——比如「Boss 是否已被击败」「这道门开过没有」「某处计数到了几」。这些状态放哪？Flag 系统（`state.flags`）就是数据端提供的**全局可存档变量**：任何需要跨事件、跨楼层保留的简单状态，都可以存进 Flag，它会随存档一起保存与恢复。
|
||
|
||
## 字段
|
||
|
||
Flag 中的每一项是一个**字段**（`IFlagCommonField`），字段名与值一一对应。字段对象提供 `set(value)`（设置值）、`add(value)`（对数字值增减）与 `get()`（取值）。一般不需要直接操作字段对象，用下面的系统接口即可。
|
||
|
||
## 全部接口
|
||
|
||
`IFlagSystem` 提供如下接口：
|
||
|
||
| 接口 | 说明 |
|
||
| --- | --- |
|
||
| `occupied(field)` | 判断字段是否被占用 |
|
||
| `setField(field, value)` | 以指定值插入字段，返回字段对象 |
|
||
| `getField(field)` | 取字段对象，不存在返回 `null` |
|
||
| `getOrInsert(field, defaultValue)` | 取字段，不存在则以默认值创建 |
|
||
| `getOrInsertComputed(field, defaultValue)` | 同上，但默认值由函数惰性计算 |
|
||
| `deleteField(field)` | 删除字段 |
|
||
| `setFieldValue(field, value)` | 设置字段的值 |
|
||
| `addFieldValue(field, value)` | 对数字字段增减 |
|
||
| `getFieldValue(field)` | 取字段的值，不存在返回 `undefined` |
|
||
| `getFieldValueDefaults(field, defaultValue)` | 取字段的值，不存在则以默认值创建并返回 |
|
||
|
||
`getOrInsertComputed` 只在字段确实不存在时才执行默认值函数，适合默认值计算量较大的场景。`getFieldValue` 没有默认值，需要默认值时用 `getFieldValueDefaults`。
|
||
|
||
```ts
|
||
state.flags.setFieldValue('door-open', true);
|
||
const open = state.flags.getFieldValue('door-open');
|
||
|
||
state.flags.addFieldValue('kill-count', 1);
|
||
const count = state.flags.getFieldValueDefaults('kill-count', 0);
|
||
```
|
||
|
||
## 使用建议
|
||
|
||
Flag 会进入存档，因此**不建议滥用**：不再需要的变量应及时用 `deleteField` 删除，否则它会一直留在存档里。能用局部状态或对象自身数据表达的，就不必放进 Flag。
|
||
|
||
```ts
|
||
if (!state.flags.occupied('temp-flag')) {
|
||
state.flags.setFieldValue('temp-flag', 1);
|
||
}
|
||
|
||
// 用完后删除，避免残留进存档
|
||
state.flags.deleteField('temp-flag');
|
||
```
|
||
|
||
Flag 常与游戏关键动作配合使用，例如在钩子中读写，见[钩子](./hooks.md)。
|
||
|
||
## 示例：记录开关与计数
|
||
|
||
```ts
|
||
// 记录一个开关
|
||
state.flags.setFieldValue('boss-defeated', true);
|
||
|
||
// 记录一个计数
|
||
const times = state.flags.getOrInsert('open-count', 0);
|
||
times.add(1);
|
||
```
|
||
|
||
想从 `state` 出发找到 Flag 对象，见[数据端总览](./data-state-overview.md)。
|