后端表达式函数脚本

后端表达式函数脚本运行在服务器端，适合把需要服务端能力的逻辑接入表达式。例如读取当前用户、判断权限、访问服务端 API、查询数据库或处理不能暴露到浏览器端的业务规则。

如果逻辑只在浏览器页面内使用，优先使用前端表达式脚本函数。如果函数需要沉淀成像内置函数一样的通用能力，再参考表达式函数扩展。

写在哪里

按复用范围选择脚本位置：只给一个页面用，写在页面同目录的同名 .action.ts；应用或项目内多个页面都要用，写到对应层级的 hooks.action.ts；多个项目都要用，才写到系统级脚本。具体路径和作用范围见脚本文件组织。

编写和调用

在后端脚本中导出以 expfunc_ 开头的函数。函数第一个参数是服务端表达式计算上下文，后面的参数来自表达式调用。

export function expfunc_RISKLEVEL(_ctx: unknown, amount: number): string {
  if (amount == null) {
    return 'unknown';
  }
  if (amount >= 1000000) {
    return 'high';
  }
  if (amount >= 100000) {
    return 'medium';
  }
  return 'low';
}

写法要求：

1. 必须 export 函数。
2. 函数名必须以 expfunc_ 开头；表达式调用时去掉这个前缀。
3. 表达式通过 SCRIPT 调用脚本函数，第一个参数写去掉 expfunc_ 后的函数名。
4. 后端表达式函数不返回 Promise。需要调用外部系统时，应使用服务端脚本中可用的同步 API 或封装成后端可执行的接口。
5. 函数内不要依赖浏览器对象，例如 window、document、DOM 组件实例或前端页面状态。

表达式中这样调用：

SCRIPT('RISKLEVEL', [订单].[金额])

表达式会先计算 SCRIPT 后面的参数，再把参数值传给脚本函数。例如 SCRIPT('RISKLEVEL', [订单].[金额]) 会调用 expfunc_RISKLEVEL(_ctx, amount)，amount 的值来自 [订单].[金额]。

脚本函数从第二个参数开始接收表达式传入的值。参数建议使用字符串、数值、布尔值、日期等基础类型；对空值、非法值要在函数内显式处理。

export function expfunc_ORDERLABEL(_ctx: unknown, orderNo: string, amount: number): string {
  if (!orderNo) {
    return '';
  }
  return `${orderNo}-${amount ?? 0}`;
}

表达式调用：

SCRIPT('ORDERLABEL', [订单].[订单号], [订单].[金额])

函数可以返回字符串、数值、布尔值、日期或 JSON 对象等表达式可处理的结果。函数返回 undefined 时，表达式通常会按空值处理；函数抛出异常时，会导致对应表达式计算失败。

export function expfunc_CANSUBMIT(_ctx: unknown, status: string): boolean {
  return status === 'draft' || status === 'returned';
}

表达式调用：

SCRIPT('CANSUBMIT', [单据].[状态])

控制权限

后端表达式函数的权限通常跟随页面和数据查询权限。用户能打开页面、能计算页面中的表达式时，表达式脚本函数就按这次页面访问的上下文执行；数据查询仍按普通数据查询权限、数据范围和页面权限生效。

因此，常规场景优先把页面权限、模型权限和数据查询权限配置好，不需要在每个表达式脚本函数里重复判断。只有在确实有特殊展示需求时，才在脚本中读取当前用户或上下文，返回不同结果，让前端页面根据结果显示不同内容。

例如：

export function expfunc_AMOUNTDISPLAY(_ctx: unknown, amount: number, masked: boolean): string {
  if (masked) {
    return "******";
  }
  return amount == null ? "" : String(amount);
}

表达式调用：

SCRIPT('AMOUNTDISPLAY', [订单].[金额], params.maskAmount)

如果不是表达式计算，而是单独开放后端 WEB API、导出、写入或删除数据，权限控制方式见后端 WEB API 脚本权限控制。

与扩展函数的区别

应用或项目内的表达式函数优先写在页面同名 .action.ts 或 hooks.action.ts 中。只有当函数需要作为产品级通用能力发布、出现在函数列表中、配置参数说明、支持多运行环境或 SQL 翻译时，再开发表达式函数扩展。