---
order: 1
navTitle: hooks.action.ts
---
# hooks.action.ts

`hooks.action.ts`是后端嵌入式脚本的约定文件名。

`hooks.action.ts`分系统级别、项目级别、应用级别，常用于监听系统事件、定义程序流脚本或后端表达式函数脚本。在约定的位置存在`hooks.action.ts`文件时（具体见[脚本文件组织](../file-organization.md#hook-script)），系统就会自动使用它。

ts是typescript文件，一种js的扩展语法，见 https://www.typescriptlang.org/ 最终系统会自动将ts文件编译成java的字节码在jvm中运行。

:::tip
什么时候需要`export`函数？

1. 要导出给其它脚本文件调用的函数。
2. 由系统定义并在特定情况下调用的函数，比如嵌入脚本中的[监听事件函数](#listen-event)、[数据加工脚本节点函数](../backend/etl-script-node.md#脚本模板)等。
3. 需要通过[web请求访问的函数](../backend/web-api-script.md)。
4. 需要程序流的执行后端脚本节点执行的函数

:::

## 监听事件{#listen-event}

监听事件函数由系统按约定调用。需要在对应层级的 `hooks.action.ts` 中导出同名函数，函数参数和返回值以 DTS 为准：

- 系统级事件类型：[`svr-api/types/syshooks.types.d.ts`](../../../../dev-types/svr-api/types/syshooks.types.d.ts)
- 项目级、应用级事件类型：[`svr-api/types/apphooks.types.d.ts`](../../../../dev-types/svr-api/types/apphooks.types.d.ts)

系统级事件写在 `/sysdata/settings/hooks.action.ts`，用于处理服务器启动关闭、登录、权限、单点登录等全局逻辑。

| 事件函数 | 触发时机 |
| :--- | :--- |
| `onBeforeServerStartup` | 服务器启动前，系统内部初始化完成但启动状态还未标记为已启动时。 |
| `onDidServerStartup` | 服务器启动完成后。 |
| `onBeforeServerShutdown` | 服务器准备关闭时。 |
| `onCustomWebAPI` | 收到 `/api/...` 请求，且没有匹配到系统内置 API 时。 |
| `onFilter` | 系统接收到任意 Web 请求时。 |
| `onDidProjectCreate` | 元数据项目创建成功后。 |
| `onDidProjectDelete` | 元数据项目即将删除时。 |
| `onPersistEvents` | 系统日志事件准备写入数据库前。 |
| `onVerifyLoginPassword` | 使用用户名密码登录并校验账号密码时。 |
| `onVerifyLoginUser` | 无密码登录场景下，需要根据用户 ID 获取登录用户时。 |
| `onEncryptUserPassword` | 需要用脚本加密用户明文密码时。 |
| `onCompareUserPassword` | 需要用脚本比较明文密码和数据库记录密码时。 |
| `onResolveUserGroups` | 登录过程中需要动态决定用户所属用户组时。 |
| `onDidSignin` | 用户登录成功后。 |
| `onAccessTokenSignin` | URL 携带 `access_token` 登录，且系统默认 token 库没有命中时。 |
| `onCheckPermission` | 用户主动查看或操作系统资源，需要进行权限判断时。 |
| `onSSOCheckAppSupported` | 脚本单点登录中，需要判断当前 App 或浏览器是否受支持时。 |
| `onSSOGetAuthRedirectURL` | 脚本单点登录中，需要构造第三方认证授权地址时。 |
| `onSSOCheckTicket` | 第三方授权回调后，需要校验票据并获取用户信息时。 |
| `onSSOGetLogoutRedirectURL` | 本系统注销后，需要构造第三方系统注销地址时。 |

项目级事件写在 `{project}/settings/hooks.action.ts`，应用级事件写在 `{project}/app/{app}/hooks.action.ts`。应用内操作调用应用级脚本，项目内操作调用项目级脚本，不会同时调用两级脚本。

| 事件函数 | 触发时机 |
| :--- | :--- |
| `onPrepareImportData` | 导入模型数据时，系统读取一批导入数据并即将执行导入前。 |
| `onInitImportDataResultField` | 导入模型数据前，系统初始化导入结果文件字段时。 |

## 程序流脚本{#action-flow-script}

`hooks.action.ts` 中可以定义 `action_` 开头的函数，供程序流的**执行后端脚本**节点调用。函数参数、返回值和节点配置方式见[后端程序流脚本节点](../backend/action-flow-script-node.md)。

## 自定义表达式函数{#custom-expression-function}

需要把服务端脚本逻辑接入表达式时，见[后端表达式函数脚本](../backend/expression-functions.md)。