---
order: 6
navTitle: 表达式脚本函数
---
# 前端表达式脚本函数

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

如果函数需要访问数据库、文件系统或服务端权限上下文，改用[后端表达式函数脚本](../backend/expression-functions.md)。

## 写在哪里{#where}

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

## 编写和调用{#usage}

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

```ts
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`](../../../exp/func/others/SCRIPT.md) 调用脚本函数。第一个参数写去掉 `expfunc_` 前缀后的函数名，后续参数会先按表达式计算，再传给脚本函数。

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

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

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

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

## 加载范围和优先级{#scope}

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

`custom.ts` 的基础写法见 [custom.ts](./custom-ts.md)。