前端表达式脚本函数

前端表达式脚本函数运行在浏览器端，适合把当前页面、应用或项目内的个性化逻辑接入表达式。例如在 JSON 数据集中按参数请求前端可访问的接口，或在组件属性表达式中复用一段格式化逻辑。

如果函数需要访问数据库、文件系统或服务端权限上下文，改用后端表达式函数脚本。

写在哪里

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

编写和调用

在 custom.ts 或页面级 .ts 中导出以 expfunc_ 开头的函数。函数第一个参数是表达式计算上下文，后面的参数来自表达式调用。

export function expfunc_formatRegion(_ctx: unknown, code: string): string {
  const regionNames: Record<string, string> = {
    '3301': '杭州',
    '3302': '宁波'
  };
  return regionNames[code] ?? code ?? '';
}

export async function expfunc_weatherForecast15(
  _ctx: unknown,
  longitude: number,
  latitude: number
): Promise<Array<Record<string, unknown>>> {
  if (!Number.isFinite(longitude) || !Number.isFinite(latitude)) {
    return [];
  }
  const response = await fetch(
    `https://api.open-meteo.com/v1/forecast?latitude=${latitude}&longitude=${longitude}&forecast_days=15&daily=temperature_2m_max`
  );
  const forecast = await response.json();
  return forecast.daily?.time?.map((time: string, index: number) => ({
    time,
    temperature: forecast.daily.temperature_2m_max?.[index] ?? null
  })) ?? [];
}

写法要求：

1. 必须 export 函数，否则页面脚本服务无法发现它。
2. 函数名必须以 expfunc_ 开头；表达式调用时去掉这个前缀。
3. 函数名大小写按脚本导出的名称匹配，建议保持英文、数字和驼峰命名。
4. 参数建议使用字符串、数值、布尔值、日期，以及这些基础类型的数组；不要把组件对象、DOM 对象或复杂运行时对象直接作为参数传入。

前端表达式中使用 SCRIPT 调用脚本函数。第一个参数写去掉 expfunc_ 前缀后的函数名，后续参数会先按表达式计算，再传给脚本函数。

SCRIPT('formatRegion', [客户].[地区编码])
SCRIPT('weatherForecast15', treeSelector1.LNG, treeSelector1.LAT)

SCRIPT 可以返回字符串、数值、布尔值、对象或数组等结果。需要字符串时，脚本函数直接返回字符串即可。

前端表达式脚本函数可以同步返回结果，也可以返回 Promise。返回 Promise 时，表达式计算会先进入等待状态，待异步结果返回后继续计算。

export async function expfunc_currentUserName(_ctx: unknown): Promise<string> {
  const response = await fetch('/api/user/current');
  const user = await response.json();
  return user.name ?? '';
}

函数返回 undefined 时，表达式按空值处理。函数抛出异常时，页面表达式计算可能失败；面向终端用户的页面中，应优先在函数内部处理可预期异常并返回兜底值。

加载范围和优先级

前端脚本函数按当前页面加载到的脚本范围生效。同一个函数被多个页面使用时，不要复制到每个页面脚本里，应上移到应用或项目的 custom.ts；只在一个页面临时使用时，不要放到项目级或系统级脚本里。

custom.ts 的基础写法见 custom.ts。