---
title: 文件新建和修改规范
description: 说明新建、修改、移动和重命名元数据文件前需要确认的文件类型、格式规范、DTS、脚本 API 和校验事项。
navTitle: 新建和修改规范
---
# 文件新建和修改规范

直接维护元数据文件前，先确认文件类型，再按该类型的规范修改。不同文件类型的格式、存放位置、编译方式、引用关系和校验方式不同，不能只按后缀或 JSON 字段猜测。

## 基本流程{#workflow}

新建或修改文件时，建议按下面顺序处理：

1. 根据需求确认文件大类和具体文件类型。判断方法见[根据需求判断文件类型](./choose-file-type.md)。
2. 打开对应[文件类型页](../file-types/overview.md)，确认用途、常见位置、格式规范、DTS 入口和编辑注意事项。
3. 新建文件时，先确认所属项目、应用目录和存放位置，再参考同目录同类文件确定命名、字段顺序和伴随文件。
4. 修改文件时，先读取当前文件、同目录同类文件、相关 `.meta`、引用方和被引用资源，避免只改一个文件造成引用断裂。
5. 修改完成后检查 diff，确认没有无意义格式化、字段顺序大幅扰动、路径遗漏或伴随文件遗漏。

## 按类型读取规范{#references}

| 文件类型 | 修改前先读 |
| --- | --- |
| SuccApp Super JSON 类文件，例如 `.tbl`、`.query`、`.spg`、`.dash`、`.rpt`、`.fapp`、`.tpg`、`.afl`、`.wfl` | 对应文件类型页、[SuccApp Super JSON](./super-json.md) 和页面中的 DTS 链接。字段结构、枚举、动态类型分支和可选项以 DTS 为准。 |
| 系统设置、项目设置、应用设置、数据源连接等配置文件 | 对应配置文件类型页和 DTS。先确认作用范围是系统、项目、应用还是数据源。 |
| 后端脚本 `.action.ts`、`.action` | [.action.ts 后端脚本文件](../file-types/backend/action-ts.md)、[.action 后端脚本文件](../file-types/backend/action.md) 和[后端脚本 API 索引](../../script/backend/api-index.md)。 |
| 前端脚本 `.ts`、`.js` | 对应脚本文件类型页。确认脚本运行在浏览器端，不要使用后端脚本 API。 |
| 样式 `.less`、`.css` | 对应样式文件类型页。确认源码文件和编译产物的关系，避免只改编译产物导致后续被覆盖。 |
| 图片、字体、附件、压缩包等资源文件 | [资源文件](../file-types/assets/README.md)、[资源引用与路径](./reference-paths.md)和当前资源的引用方。 |
| `.meta` | [.meta 资源元信息](../file-types/config/meta.md)。它维护同级子资源的附加信息，不是某个业务文件的主体内容。 |

## 新建文件{#create}

新建文件时，先确认它是否真的需要新增。能复用已有页面、模型、查询、脚本或主题时，优先复用；需要新增时再按文件类型创建。

新建时至少确认：

1. 文件属于哪个项目、`sysdata`，还是某个 `.app` 应用目录。
2. 文件名、后缀、约定文件名和目录位置是否符合对应文件类型页。
3. 是否需要同步创建同名脚本、样式、说明文件或素材目录。
4. 是否需要维护父目录或子目录中的 `.meta`。
5. 是否需要在其他页面、配置、脚本或资源中新增引用路径。

## 修改文件{#edit}

修改已有文件时，优先小步修改，保持原有格式和字段顺序。不要为了局部调整格式化整份元数据文件。

修改时至少确认：

1. 当前文件类型和格式规范是否已经确认。
2. 同目录同类文件是否有可参考的字段顺序、命名方式和引用写法。
3. 修改字段是否被其他资源、脚本、表达式、数据集或动作节点引用。
4. 重命名、移动或删除文件时，是否同步维护 `.meta`、同名伴随文件和引用路径。
5. 修改后是否需要在设计器、预览页面、脚本日志或业务功能中验证效果。

## 校验结果{#check}

文件修改完成后，至少做这些检查：

1. 使用 SuccApp CLI 或 SuccApp for VS Code 的 Changes / diff 视图检查差异。
2. 确认没有无关格式化、无关字段重排或临时调试内容。
3. 确认 `.meta`、引用路径、同名伴随文件和静态资源引用仍然一致。
4. 推送到测试环境后，在对应设计器、预览页面、脚本日志或业务功能中验证运行结果。

工具入口见 [SuccApp CLI](../../ai-building/basics/cli.md) 和 [SuccApp for VS Code](../../ai-building/basics/vscode.md)。