# CSV 配置表模板说明

本文档参考 `../index.html` 和 `../js/config-table-editor.js` 的读取逻辑，说明配置表 CSV 应该怎么写。可直接参考 `../samples/sample_skill_list_template.csv`。

## 1. 文件基础要求

- 文件后缀必须是 `.csv`，网页上传控件只接受 CSV 文件。
- 建议使用 UTF-8 编码。网页会用 UTF-8 读取文件，也能兼容文件开头的 BOM。
- 分隔符必须是英文逗号 `,`。
- 如果某个单元格内容里包含英文逗号、换行或英文双引号，需要用 CSV 标准写法：
  - 整个单元格用英文双引号包住。
  - 单元格内部的英文双引号写成两个英文双引号。
  - 示例：`"备注里有逗号, 需要包住"`、`"他说 ""OK"""`。

## 2. 整体结构

CSV 分两块：

1. 元数据区：从文件开头到 `TYPES::` 这一行。网页会从这里读取表名、字段名、必填、主键、版本列、类型等规则。
2. 数据区：从 `TYPES::` 下一行开始。网页会把这里的每一行当作注释行或数据行读取。

不要删除这些关键标记：`TBLNM::`、`REQUIRED::`、`COL-OPT::`、`EXPCOL::`、`COLUMNS::`、`TYPES::`。这些标记必须放在每行第 1 列，且文字不要改。

## 3. 元数据区怎么写

### 第 1 行：中文显示名

示例：

```csv
# 备注,技能列表模板,,,,,,,,,,
```

- 第 1 列必须以 `#` 开头，网页会把这一行识别成表的中文显示名来源。
- 第 2 列可以替换成你希望页面顶部显示的中文名，例如 `技能列表`、`怪物配置`。
- 第 1 列的 `#` 不要删。

### `TBLNM::`：程序表名

示例：

```csv
TBLNM::,skill_list,,,,,,,,,,
```

- 第 1 列 `TBLNM::` 不可替换。
- 第 2 列填写程序使用的表名，可以替换，例如 `skill_list`、`monster_config`。
- 后面的空列可以保留为空，主要用于对齐。

### `REQUIRED::`：每列是否必填

示例：

```csv
REQUIRED::,FALSE,TRUE,TRUE,TRUE,FALSE,TRUE,FALSE,TRUE,FALSE,TRUE,FALSE
```

- 第 1 列 `REQUIRED::` 不可替换。
- 从第 2 列开始，必须和 `COLUMNS::` 后面的字段一一对应。
- 只能写大写 `TRUE` 或 `FALSE`。
- `TRUE` 表示数据行保存时不能为空。
- `FALSE` 表示可以为空。
- 注释行不会触发必填校验。

### `COL-OPT::`：特殊列标记

示例：

```csv
COL-OPT::,VER,PK,,,,,,,,,
```

- 第 1 列 `COL-OPT::` 不可替换。
- `VER` 表示版本列，页面会用版本列样式显示。
- `PK` 表示主键列，页面会用主键样式显示。
- 普通字段留空即可。
- 只有 `VER` 和 `PK` 有特殊效果，其他文字不会被当前页面识别成特殊列。

### `EXPCOL::`：是否导出

示例：

```csv
EXPCOL::,FALSE,TRUE,TRUE,TRUE,FALSE,TRUE,FALSE,TRUE,TRUE,TRUE,TRUE
```

- 第 1 列 `EXPCOL::` 不可替换。
- 从第 2 列开始，和 `COLUMNS::` 字段一一对应。
- 只能写大写 `TRUE` 或 `FALSE`。
- 当前网页会读取这一行，但保存时仍会保留所有字段；如果你的后续导表工具依赖它，请按真实导出需求填写。

### `# 标题`：页面显示标题

示例：

```csv
# 标题,版本号,技能ID,技能名称,技能品质,# 技能品质,技能类型,# 技能类型,技能原型组,效果动画,技能描述,备注
```

- 第 1 列以 `#` 开头，不要删。
- 从第 2 列开始，是每个字段在页面表头里显示的中文名。
- 它必须放在 `COLUMNS::` 前面；网页会找 `COLUMNS::` 上方最近的一行 `#` 作为显示标题行。
- 普通标题可以替换，例如 `技能ID` 改成 `技能编号`。
- 如果某个标题以 `#` 开头，它不是普通显示列：
  - 如果它去掉 `#` 后和前一列标题相同，会被当作前一列的备注/tooltip 列，默认不单独显示。例如 `技能品质` 后面紧跟 `# 技能品质`。
  - 如果它和前一列标题不同，会被当作注释列，默认隐藏，需要打开“注释列”开关才显示。

### `COLUMNS::`：字段 ID

示例：

```csv
COLUMNS::,version,skill_id,skill_name,skill_quality,s_deck,skill_type,st_deck,skill_prototype_group,animation_id,skill_description,note
```

- 第 1 列 `COLUMNS::` 不可替换。
- 从第 2 列开始，是程序字段 ID。
- 字段 ID 可以根据新表替换，但不要随意改现有表正在使用的字段 ID，否则后续程序或导表工具可能找不到字段。
- 字段数量必须和 `REQUIRED::`、`COL-OPT::`、`EXPCOL::`、`TYPES::` 以及 `# 标题` 的列数量保持一致。

### `TYPES::`：字段类型

示例：

```csv
TYPES::,long(14),INT,STRING,ENUM,STRING,ENUM,STRING,STRING,STRING,STRING,STRING
```

- 第 1 列 `TYPES::` 不可替换。
- 从第 2 列开始，和 `COLUMNS::` 字段一一对应。
- 当前页面实际识别的类型：
  - `INT` 或 `LONG` 开头：按整数校验。
  - `TIME`：识别为时间类型，但当前页面没有额外格式校验。
  - 其他类型，包括 `STRING`、`ENUM`：按字符串处理。
- 整数列保存时只能写整数，例如 `1001`、`-1`；不能写 `1.5` 或 `abc`。

## 4. 数据区怎么写

`TYPES::` 下一行开始都是数据区。空白行会被忽略。

### 普通数据行

示例：

```csv
,,1001,基础斩击,Common,白色 普通,ActiveSkill,主动技能,[101],anim_slash_01,对单个敌人造成物理伤害,白色品质主动技能
```

- 第 1 列必须留空，表示这是普通数据行。
- 第 2 列对应 `version`。模板里通常留空，保存时也可以留空，因为 `REQUIRED::` 里它是 `FALSE`。
- 第 3 列对应 `skill_id`，这里是主键且必填，必须写整数，建议不要重复。
- 后续列按 `COLUMNS::` 的顺序填写。
- `s_deck` 和 `st_deck` 是 tooltip/备注列：它们的显示标题以 `#` 开头，并且分别跟前一列标题相同，所以页面默认把它们显示成前一列旁边的提示内容，不作为独立主列展示。

### 注释行

示例：

```csv
# 关联表格,,,,,,,,skill_prototype_config,animation_config,,
```

- 第 1 列以 `#` 开头，网页会把整行当作注释行。
- 注释行可以写说明、关联表、示例数据。
- 注释行不会参与必填和整数校验。
- 页面上可以通过“注释行”开关显示或隐藏。
- 如果只是想写一个不会导入为正式数据的示例行，可以像模板这样写：

```csv
# ,,1,TEST,Common,白色 普通,ActiveSkill,主动技能,[101],anim_slash_01,测试技能描述,测试备注
```

## 5. 字段备注文件（可选）

如果想给表头字段补充说明，可以额外提供一个字段备注 CSV。字段备注文件会被编辑器读取，但不会作为一张可编辑表显示，也不会生成文件 tab。

### 文件命名

字段备注文件的文件名必须在主表文件名前加 `#`。

示例：

```text
bun_config.csv
#bun_config.csv
```

- `#bun_config.csv` 会自动匹配 `bun_config.csv`。
- 匹配规则只看文件名；去掉开头的 `#` 后，必须和主表文件名一致。
- 字段备注文件可以和主表一起上传，也可以在主表已打开后再拖入或添加。

### 文件格式

字段备注文件只需要前两列：

```csv
字段名称,说明
bun_id,这里是测试的说明
```

- 第 1 列必须填写英文字段 ID，对应主表 `COLUMNS::` 后面的字段名。
- 第 2 列填写这个字段的说明。
- 第 1 行是表头，建议固定写成 `字段名称,说明`。
- 编辑器只读取第 2 列“说明”。第 3 列及后面的内容会被忽略。
- 如果某个字段的说明为空，编辑器不会给它显示问号。

### 显示效果

当字段备注文件里的英文字段 ID 和主表 `COLUMNS::` 中的字段相同时，编辑器会在对应中文表头右侧显示一个 `?` 图标。

例如主表中有：

```csv
# 标题,版本号,包子ID
COLUMNS::,version,bun_id
```

字段备注文件中有：

```csv
字段名称,说明
bun_id,这里是测试的说明
```

那么页面表头里的“包子ID”右侧会出现 `?`，鼠标悬停后显示“这里是测试的说明”。

## 6. 哪些可以替换，哪些不要替换

可以替换：

- 第 1 行第 2 列的中文显示名。
- `TBLNM::` 第 2 列的表名，但要确认后续工具也使用新表名。
- `# 标题` 后面的中文显示名。
- `COLUMNS::` 后面的字段 ID，用于新建一张新表；已有表谨慎修改。
- `REQUIRED::`、`COL-OPT::`、`EXPCOL::`、`TYPES::` 后面的配置值。
- `TYPES::` 下面的数据行内容。
- 以 `#` 开头的数据区注释行内容。

不要替换或删除：

- 每个元数据行第 1 列的固定标记：`TBLNM::`、`REQUIRED::`、`COL-OPT::`、`EXPCOL::`、`COLUMNS::`、`TYPES::`。
- `COLUMNS::` 和 `TYPES::` 的相对顺序。数据必须在 `TYPES::` 后面。
- 各元数据行的列数量对应关系。第 N 个字段在每一行都必须对齐到第 N 个位置。
- 用来表示 tooltip 的 `#` 标题规则，除非你确实想取消该字段的备注列行为。
- 主键字段的唯一性和整数格式，例如 `skill_id`。

## 7. 常见错误

- 把普通数据行第 1 列写成了 `#`：这一行会变成注释行，不会按正式数据处理。
- 忘记给包含英文逗号的单元格加双引号：列会错位。
- `TRUE` / `FALSE` 写成小写：网页只把大写 `TRUE` 当作真值。
- `REQUIRED::`、`TYPES::` 等配置列数和 `COLUMNS::` 不一致：页面仍可能显示，但字段会错位或漏值。
- 在 `INT` / `LONG` 类型列写了小数、中文或字母：保存会报“须为整数”。
- 删除了 `TYPES::`：网页无法识别数据区。
