---
title: 文件类型概述
description: 说明各类元数据文件的用途、常见位置、根结构、DTS 入口和编辑注意事项。
navTitle: 概述
---
# 文件类型概述

这些页面说明各类元数据文件的用途、常见位置、根结构、DTS 入口和编辑注意事项。字段、枚举、继承和动态类型分支以 DTS 为准，文件类型页不重复维护完整字段表。

新建元数据文件时，先从要解决的需求选择文件类型，再按文件类型和目录约定确定存放位置。完整选择流程见[根据需求判断文件类型](../rules/choose-file-type.md)；需要按后缀反查根类型时，查看 [`types/meta/file-types/index.d.ts`](../../../../dev-types/types/meta/file-types/index.d.ts)。

## 如何判断文件类型{#identify}

判断文件类型时，先看要解决的需求，不要只看文件内容。SuccApp 元数据文件既包括 Super JSON 类结构化文件，也包括 `.js`、`.ts`、`.less`、`.css`、`.png` 等脚本、样式和静态资源；同样是 JSON，不同位置和后缀也可能对应完全不同的根结构。

本页下方按用途列出常见文件类型、位置线索和说明页。需要从需求开始选择文件类型、确认存放位置和学习格式规范时，阅读[根据需求判断文件类型](../rules/choose-file-type.md)；需要了解新建、修改、移动和重命名时的注意事项，阅读[文件新建和修改规范](../rules/file-editing-rules.md)。

## 数据与模型

| 文件类型 | 常见位置或线索 | 说明页 | 说明 |
| --- | --- | --- | --- |
| `.tbl` | `data/models/`、业务模型目录 | [查看](./data/tbl.md) | 数据模型，用来把业务数据整理成页面、报表、仪表板和流程都能共用的数据口径；需要维护业务对象、分析口径、填报数据或接入外部数据时使用。 |
| `.query` | `data/queries/`、模型相关查询目录 | [查看](./data/query.md) | 可复用查询，用来在已有数据模型上沉淀稳定取数口径；多个页面、报表、接口需要按同一规则取数时使用。 |
| `.kdb` | 知识库资源目录 | [查看](./data/kdb.md) | 知识库，用来把文档、URL、指标说明等素材变成可检索、可被 AI 使用的知识；需要智能问答、知识检索或 RAG 数据准备时使用。 |

## 页面与应用

| 文件类型 | 常见位置或线索 | 说明页 | 说明 |
| --- | --- | --- | --- |
| `.app` | `app/{name}.app/` | [查看](./views/app.md) | 低代码业务应用，用来界定一个相对独立业务系统的资源范围；需要把页面、流程、数据和设置按 CRM、OA 等应用边界组织时使用。 |
| `.spg` | `.app` 内或页面资源目录 | [查看](./views/spg.md) | SuperPage 通用交互页面，用来搭建门户、查询、办理、详情、管理控制台等页面；需要自由编排组件和动作时使用。 |
| `.tpg` | 模板页面或门户页面目录 | [查看](./views/tpg.md) | 超级模板页面，用来按统一模板制作门户、站点或专题页；需要共享视觉框架、只配置节点内容时使用。 |
| `.fapp` | 报表填报应用资源目录 | [查看](./views/fapp.md) | 报表填报应用，用来承载填报、数据采集、提交、锁定和审批等带状态的业务；需要周期上报或多人协作填报时使用。 |
| `.ftl` | 服务端模板资源目录 | [查看](./views/ftl.md) | 服务端模板，用来生成轻量动态页面或自定义文本输出；按文件组织属于视图模板，运行时在服务端渲染。 |
| `.html` | `public/*.html`、应用或扩展目录中的 HTML 文件 | [查看](./views/html.md) | 浏览器端 HTML 文件，用于开放页面、静态片段、自定义展示内容或与脚本、样式配合使用的页面资源。 |
| `.ts` | `custom.ts`、`*.spg.ts`、`*.dash.ts`、`*.rpt.ts` | [查看](./views/ts.md) | 前端脚本源码，用来扩展浏览器端页面交互、页面级工具函数、应用级公共逻辑或项目级钩子逻辑；推荐优先维护 `.ts`，由系统编译为 `.js` 后执行。 |
| `.js` | `custom.js`、`*.spg.js`、`public/*.js` | [查看](./views/js.md) | 前端 JavaScript 脚本，通常是 `.ts` 的编译产物；直接维护可节省编译时间，但会失去 TypeScript 语法和类型辅助，需要自行关注浏览器兼容性。 |
| `.less` | `custom.less`、`*.spg.less`、`*.dash.less`、`*.rpt.less` | [查看](./views/less.md) | 样式脚本源码，用来编写页面、应用、项目或系统级样式定制；推荐优先维护 `.less`，由系统编译为 `.css`。 |
| `.css` | `custom.css`、`*.spg.css`、`public/*.css` | [查看](./views/css.md) | 浏览器直接使用的样式文件，通常是 `.less` 的编译产物，也可作为兼容样式或外部样式资源直接维护。 |

## 报表与可视化

| 文件类型 | 常见位置或线索 | 说明页 | 说明 |
| --- | --- | --- | --- |
| `.dash` | 仪表板资源目录 | [查看](./ana/dash.md) | 仪表板，用来把指标、图表和筛选交互组织成可视化分析页面；需要看经营状态、做专题分析或搭建大屏时使用。 |
| `.rpt` | 报表资源目录 | [查看](./ana/rpt.md) | 报表，用来制作固定版式、可打印、可导出、可归档的数据结果；需要复杂表头、明细汇总、套打或 Excel 风格输出时使用。 |
| `.theme` | `settings/themes/` 下的主题目录 | [查看](./ana/theme.md) | 主题，用来统一页面、报表和仪表板的视觉风格；需要品牌色、明暗模式、图表配色或字体保持一致时使用。 |

## 后端流程与控制

| 文件类型 | 常见位置或线索 | 说明页 | 说明 |
| --- | --- | --- | --- |
| `.afl` | 动作流、程序流资源目录 | [查看](./backend/afl.md) | 程序流或动作流，用来把一次业务动作编排成可复用的自动化流程；需要读写数据、调用接口、生成文件或响应页面按钮时使用。 |
| `.wfl` | 工作流资源目录 | [查看](./backend/wfl.md) | 工作流，用来控制人工审批和任务流转；需要请假报销、资料审核、上报确认等多人办理流程时使用。 |
| `.action.ts` | `hooks.action.ts`、`API/*.action.ts`、`*.tbl.action.ts` | [查看](./backend/action-ts.md) | 后端脚本源码，用来编写程序流、自定义接口、数据加工、系统事件监听和项目或应用级后端钩子；推荐优先维护 `.action.ts`。 |
| `.action` | `hooks.action`、`API/*.action` | [查看](./backend/action.md) | 后端 JavaScript/Rhino 脚本，常见于旧资源兼容或 `.action.ts` 编译后的运行形式；直接维护时必须遵守 Rhino 支持的语法要求。 |

## 配置与元信息

| 文件类型 | 常见位置或线索 | 说明页 | 说明 |
| --- | --- | --- | --- |
| `.jdbc` | `sysdata/data/sources/*.jdbc` | [查看](./config/jdbc.md) | 数据源连接，用来让 SuccApp 接入业务库、数据仓库或外部数据库；部署环境需要新增或调整系统级数据库连接时使用。 |
| `/sysdata/settings/settings.json` | 系统项目 `sysdata` | [查看](./config/sys-settings-json.md) | 系统设置，用来控制整个 SuccApp 部署环境的全局能力；涉及登录、安全、域名、静态资源、文件存储或运维配置时使用。 |
| `/{project}/settings/settings.json` | 普通项目 `settings/` 目录 | [查看](./config/project-settings-json.md) | 项目设置，用来控制单个元数据项目的可用资源和默认能力；只影响某个项目的数据源范围、显示格式、语言等配置时使用。 |
| `/{project}/app/{app}.app/settings.json` | 应用目录内部 | [查看](./config/app-settings-json.md) | 应用设置，用来控制单个低代码应用的入口和应用级覆盖项；需要调整首页、短路由、语言、显示格式或支付配置时使用。 |
| `.meta` | 各级元数据目录中 | [查看](./config/meta.md) | 资源元信息，用来维护目录下资源在产品资源树中的附加信息；需要理解或调整资源说明、图标、排序、隐藏状态时使用。 |

## 资源文件

| 文件类型 | 常见位置或线索 | 说明页 | 说明 |
| --- | --- | --- | --- |
| 图片、字体、附件、压缩包等 | `public/`、`images/`、主题素材目录、应用素材目录 | [查看](./assets/README.md) | 资源文件通常不是 Super JSON 元数据文件，但会被页面、报表、模板、主题、脚本或配置引用；移动或重命名时要同步检查引用路径和 `.meta`。 |