数据转换

在任何文本输入中使用数据转换函数来转换和组合数据

为什么需要数据转换

传递数据允许您将上一步骤的值插入到当前步骤的输入中。数据转换则让您在数据被使用之前对其进行转换——将两个值合并为一个、更改格式、执行计算、在值为空时回退到默认值，或根据条件进行分支判断。

如果说引用（mention）回答的是”这里该用什么值？“，那么数据转换函数回答的就是”在使用该值之前，我应该对它做什么？“

斜杠触发

将光标放在任意文本输入框中，键入 /。会出现一个搜索弹窗，列出所有可用的函数。输入内容进行筛选，点击即可插入。每个函数会以一个带有空参数槽的样式化标签（badge）形式插入——在参数槽中填入文本、数字或上一步骤的引用。

数据转换函数的结构

插入后，函数在输入框中显示如下：

函数名称以药丸形状显示在左侧。
参数之间使用分号（;） 分隔，而非逗号。
右侧有一个匹配的药丸形状闭合函数。
输入框下方有一个预览面板，在编辑时显示计算结果。如果函数存在类型错误（例如传入了文本但期望的是数字），面板会显示错误信息。

您可以在同一个输入框中混合使用纯文本、引用和函数。当工作流运行时，函数的结果会替换掉该标签。

引用文本值

对于文本参数，引号是可选的。编辑器支持两种风格，结果相同：

不带引号：combine(John; Smith; -) → John-Smith
带引号：combine("John"; "Smith"; "-") → John-Smith

使用哪种方式取决于您的习惯。引号在以下情况下很有用：

文本中包含分号（否则会被解析为下一个参数的分隔符）
您想明确文本的开始和结束位置

空值或仅含空白的值是唯一需要引号的情况。 如果不使用引号，编辑器会将空槽位视为”没有参数”并去除任何空白，因此：

对于空字符串，请写 ""——例如 coalesce(""; John) → John
对于单个空格作为分隔符，请写 " "——例如 combine(John; Smith; " ") → John Smith

如果不使用引号，combine(John; Smith; ) 会将第三个参数视为缺失，并回退为不使用分隔符。

实用示例

合并名和姓

combine(first_name; " "; last_name) → "Sara Mitchell"

当您需要将多个值用分隔符连接在一起时，使用 combine。

将客户姓名转换为首字母大写

titlecase(customer_name) → "Sara Mitchell"

如果您希望全部大写，使用 uppercase（结果为 "SARA MITCHELL"），反之使用 lowercase。

格式化日期以便显示

format_date(order.created_at; MMM DD, YYYY) → "Jan 15, 2025"

如需完整拼写的日期，请使用 format_date_long(order.created_at) → "Friday, January 15, 2025"。

获取列表的第一项

first_item(tags) → 返回第一个元素。使用 last_item 获取最后一个，或使用 item_at(tags; 2) 按索引选取。

值为空时使用回退值

coalesce(customer.preferred_name; customer.first_name; "Friend") → 返回第一个非空值，跳过空值。

使用 if_empty(value; fallback) 进行单个回退，或当字段可能为 null 时使用 if_null(value; fallback)。

根据条件分支判断

if(order.total > 1000; "高价值"; "标准")

第一个参数是条件，第二个参数是条件为真时返回的值，第三个参数是条件为假时返回的值。

去除空白并检查长度

length(trim(user_input)) → 返回去除首尾空格后的字符数。函数可以自由嵌套——内部函数先执行。

从较长字符串中提取电子邮件

extract_email(message_body) → 返回文本中找到的第一个电子邮件地址。提取 URL 请使用 extract_url。

四舍五入计算总金额

round(subtotal * 1.0825; 2) → 49.99

第二个参数是要保留的小数位数。

对列表中某个数字字段求和

sum(line_items; amount) → 将列表中每个项目的 amount 字段相加。使用 average 计算平均值，或使用 max_in_list / min_in_list 获取极值。

计算两个日期之间的天数

days_between(order.created_at; today()) → 返回整数天数。结合 if 可以标记逾期记录。

通过查找表映射值

switch(country_code; "US"; "北美"; "DE"; "欧洲"; "JP"; "亚洲") → 当传入 "US" 时返回 "北美"。将键值对依次写入即可。

高级技巧

嵌套函数

任何函数都可以将其它函数作为参数。从内向外阅读：uppercase(trim(customer_name)) 先去除空白，再转换为大写。每个标签上的悬停弹窗会显示每个参数期望的类型。

将静态文本与函数混合

您可以在常规文本输入框的任意位置插入函数。输入一些文本，插入一个函数，再输入更多文本。最终输出是一个字符串，函数的结果会被替换在其中。

将引用与函数混合

像 {{step.field}} 这样的引用可以作为函数参数使用。将引用拖入任意参数槽，函数会在运行时使用解析后的值。

当预览显示错误时

如果您在输入框下方看到红色错误消息，通常是因为以下原因之一：

参数数量错误——参数太多或太少。请查看悬停弹窗了解期望的参数数量。
类型不匹配——您传入了文本但期望的是数字，或类似情况。如果需要，请将值包装在 to_number(...) 或 to_date(...) 中进行转换。
未知函数——函数名称已被重命名或移除。请使用 / 重新插入以选择当前可用的名称。

存在函数错误的步骤将无法运行——请在发布前修复它。