脚本文件的组织

脚本文件按作用范围分为系统级、项目级、应用级和页面级。选择位置时先看复用范围：只给一个页面用，写在页面同目录的同名脚本；一个应用内多页复用，写在应用目录；一个项目内多页复用，写在项目公共脚本；多个项目都要用，才写到 /sysdata。

脚本类别

SuccApp 应用开发常用以下几类脚本：

1. .ts：前端脚本，运行在浏览器端，使用 TypeScript 语法。
2. .action.ts：后端脚本，运行在服务器端，使用 TypeScript 语法，系统会编译后执行。
3. .less：前端样式脚本，运行在浏览器端，使用 Less 语法，兼容 CSS。

目录总览

约定脚本放在固定位置后，系统会按页面、应用、项目或系统范围自动加载或调用。常见目录如下：

/sysdata
├── settings
│   └── hooks.action.ts        # 系统级后端钩子脚本
└── public
    ├── custom.ts              # 系统级前端脚本
    └── custom.less            # 系统级前端样式

/{project}
├── settings
│   └── hooks.action.ts        # 项目级后端钩子脚本
├── public
│   ├── custom.ts              # 项目级前端脚本
│   └── custom.less            # 项目级前端样式
├── ana
│   ├── sales.dash             # 页面、仪表板、报表等元数据文件
│   ├── sales.dash.ts          # 页面级前端脚本
│   ├── sales.dash.less        # 页面级前端样式
│   └── sales.dash.action.ts   # 页面级后端脚本
└── app
    └── sales.app
        ├── hooks.action.ts    # 应用级后端钩子脚本
        ├── custom.ts          # 应用级前端脚本
        ├── custom.less        # 应用级前端样式
        └── pages
            ├── order.spg
            ├── order.spg.ts
            ├── order.spg.less
            └── order.spg.action.ts

前端脚本位置

前端脚本运行在浏览器端，用于页面交互、组件联动、脚本数据集、前端表达式函数和样式扩展。按作用范围选择位置：

使用范围	脚本位置	适用场景
只在一个页面使用	页面同目录的同名 .ts，例如 order.spg.ts、sales.dash.ts	页面私有交互、只服务当前页面的前端表达式函数。
一个应用内多个页面使用	/{project}/app/{app}.app/custom.ts	应用内公共交互、公共工具函数、应用级前端表达式函数。
一个项目内多个页面使用	/{project}/public/custom.ts	项目内公共前端逻辑。
多个项目或系统功能页使用	/sysdata/public/custom.ts	全局前端逻辑，影响范围最大，应只放稳定通用逻辑。

前端样式脚本与前端脚本的层级一致，只是后缀改为 .less，例如 order.spg.less、/{project}/public/custom.less。

页面运行时会合并可用的前端脚本。脚本函数同名时，优先使用更靠近当前页面的实现，顺序通常是：页面级脚本、父页面所在应用脚本、当前文件所在应用脚本、项目级脚本、系统级脚本。

注意

public/custom.ts 和 public/custom.less 会被浏览器加载，不要在里面保存密钥、数据库账号或只能留在服务器端的业务规则。需要访问数据库、文件系统或服务端权限上下文时，使用后端脚本。

后端脚本位置

后端脚本运行在服务器端，用于 WEB API、程序流、数据加工、后端事件、服务端表达式函数和需要权限判断的业务逻辑。按作用范围选择位置：

使用范围	脚本位置	适用场景
只在一个页面或资源中使用	页面或资源同目录的同名 .action.ts，例如 order.spg.action.ts、sales.dash.action.ts	页面私有服务端计算、校验、后端表达式函数。
一个应用内多个页面使用	/{project}/app/{app}.app/hooks.action.ts	应用内公共后端钩子、应用级服务端表达式函数。
一个项目内多个页面使用	/{project}/settings/hooks.action.ts	项目级后端钩子、项目级服务端表达式函数。
多个项目或系统事件使用	/sysdata/settings/hooks.action.ts	系统级后端钩子或全局服务端表达式函数。

后端脚本不暴露给浏览器，适合放需要服务端能力和权限控制的逻辑。只给当前页面用的函数不要上移到项目级或系统级；应用或项目内多个页面都要用时，再放到对应层级的 hooks.action.ts。

页面级脚本

在页面设计器中，点击 视图 > 底部面板 > 前端脚本｜样式脚本，可以开发只作用于当前页面的前端脚本和样式脚本。页面级脚本会自动存储在页面所在目录，与页面同名、后缀不同。

• page1.spg
• page1.spg.ts：页面级前端脚本，加载到当前页面内。
• page1.spg.less：页面级前端样式，加载到当前页面内。
• page1.spg.action.ts：页面级后端脚本，在服务端表达式计算或服务端调用场景中使用。

如果页面存在于应用或项目中，页面级前端脚本还会与对应的应用、项目、系统前端脚本一起加载。

最佳实践

1. 优先把脚本放在最小可用范围内：页面私有逻辑写页面级，应用公共逻辑写应用级，项目公共逻辑写项目级。
2. 不要为了复用方便把临时函数放到系统级脚本；系统级脚本影响所有项目，修改前应确认兼容性和权限风险。
3. 多个脚本需要复用同一段逻辑时，可以把公共函数拆到独立模块，再通过 import 引入。
4. 前端脚本只处理浏览器端逻辑；涉及数据库、文件、用户权限、服务端 API 的逻辑放到后端脚本。
5. 自定义表达式函数的写法分别见前端表达式脚本函数和后端表达式函数脚本。