函数
字符串函数
在表达式中处理字符串时，使用单引号（’’）括起字面字符串非常重要。但是，当您想在字面字符串中包含单引号时，可以使用双引号（""）括起整个字符串。
例如：
- 正确：if(${yesno} = 1, “a string with ‘single quotes’ in it”, “no single quotes here”)
- 错误：if(${yesno} = 1, ‘a string with ‘single quotes’ in it’, ’no single quotes here’)
关于智能引号，请注意它们的存在，因为它们可能在表达式中引起问题。许多富文本编辑器会自动将直引号（"" 或 ‘’）转换为智能引号或弯引号（"" 或 ‘’），这可能导致语法错误或意外行为。为避免这种情况，请确保在表达式中始终使用直引号（’’）。
rtSurvey 支持各种函数，包括：
string(field)：将字段转换为字符串。- 示例：
string(34.8)将转换为'34.8'。
- 示例：
string-length(field)：返回字符串字段的长度。- 示例：
string-length(.) > 3 and string-length(.) < 10可用于确保当前字段在 3 到 10 个字符之间。
- 示例：
substr(fieldorstring, startindex, endindex)：返回从startindex开始到endindex之前结束的子字符串。索引从字符串第一个字符的 0 开始。- 示例：
substr(${phone}, 0, 3)将返回电话号码的前三位。
- 示例：
concat(a, b, c, ...)：将字段（和/或字符串）连接在一起。- 示例：
concat(${firstname}, ' ', ${lastname})将通过组合firstname和lastname字段的值返回全名。
- 示例：
linebreak()：返回换行符。- 示例：
concat(${field1}, linebreak(), ${field2}, linebreak(), ${field3})将返回三个字段值的列表，值之间带有换行符。
- 示例：
lower()：将字符串转换为全小写字符。- 示例：
lower('Street Name')将返回"street name"。
- 示例：
upper()：将字符串转换为全大写字符。- 示例：
upper('Street Name')将返回"STREET NAME"。
- 示例：
select_one 和 select_multiple 函数
count-selected(field)：返回 select_multiple 字段中选定项目的数量。- 示例：
count-selected(.) = 3可用作约束表达式，确保恰好选择三个选项。
- 示例：
selected(field, value)：根据是否在 select_one 或 select_multiple 字段中选择了指定值，返回 true 或 false。- 示例：
selected(${color}, 'Blue')可用作相关性表达式，仅在受访者选择了"蓝色"作为最喜欢颜色时显示组或字段。 - 注意：第二个参数应始终指定选项值，而不是选项标签。使用表单定义 choices 工作表值列中的值。
- 示例：
selected-at(field, number)：返回 select_multiple 字段中指定位置的已选项目。当传递的数字为 0 时，返回第一个已选项目；为 1 时返回第二个，以此类推。- 示例：
selected-at(${fruits}, 0) = 'Apple'可用作相关性表达式，仅在第一个已选选项为"苹果"时显示组或字段。 - 注意：返回值将是选项值，而不是选项标签。
- 示例：
choice-label(field, value)：返回 select_one 或 select_multiple 字段选项的标签。- 示例 1：
choice-label(${country}, ${country})将返回名为country字段中当前选定选项的选项标签。 - 示例 2：
choice-label(${languages}, selected-at(${languages}, 0))将返回名为languages字段中第一个已选选项的标签。
- 示例 1：
重复字段函数
在 rtSurvey 中，如果您想多次提出相同的问题，可以将字段放在重复组内。这将产生同一字段的多个实例。以下函数可以帮助您处理这些重复字段及其产生的重复数据。
join(string, repeatedfield)：对于重复组内的字段，生成以字符串分隔的值列表。第一个参数指定用于分隔值的分隔符。- 示例：
join(', ', ${member_name})将从所有输入的名称生成一个以逗号分隔的列表。
- 示例：
join-if(string, repeatedfield, expression)：与join()完全相同，但它使用提供的表达式检查重复组中的每个实例。如果表达式评估为 false，该项目将从输出中省略。- 示例：
join-if(', ', ${member_name}, ${age} >= 18)将生成仅包含成年成员（年龄 18 岁及以上）姓名的逗号分隔列表。
- 示例：
count(repeatgroup)：返回重复组当前重复的次数。- 示例：
count(${groupname})将返回该组的实例数量。
- 示例：
count-if(repeatgroup, expression)：与count()完全相同，但它使用提供的表达式检查重复组中的每个实例。- 示例：
count-if(${members}, ${age} >= 18)将根据"members"重复组内的年龄字段返回成年成员的数量。
- 示例：
sum(repeatedfield)：对于重复组内的字段，计算所有值的总和。- 示例：
sum(${loan_amount})将返回所有贷款的总价值。
- 示例：
sum-if(repeatedfield, expression)：与sum()完全相同，但它使用提供的表达式检查重复组中的每个实例。- 示例：
sum-if(${loan_amount}, ${loan_amount} > 500)将返回所有超过 500 的贷款总价值。
- 示例：
min(repeatedfield)：对于重复组内的字段，计算所有值的最小值。- 示例：
min(${member_age})将返回组中最年轻成员的年龄。
- 示例：
min-if(repeatedfield, expression)：与min()完全相同，但使用提供的表达式过滤。- 示例：
min-if(${member_age}, ${member_age} >= 18)将返回组中最年轻成年人的年龄。
- 示例：
max(repeatedfield)：对于重复组内的字段，计算所有值的最大值。- 示例：
max(${member_age})将返回组中最年长成员的年龄。
- 示例：
max-if(repeatedfield, expression)：与max()完全相同，但使用提供的表达式过滤。- 示例：
max-if(${member_age}, ${member_age} >= 18)将返回组中最年长成年人的年龄。
- 示例：
index()：在重复组内调用时，返回当前组或实例的索引号。- 示例：在重复组内使用
index()时，第一个实例返回 1，第二个实例返回 2，以此类推。
- 示例：在重复组内使用
indexed-repeat(repeatedfield, repeatgroup, index)：从重复组外部引用重复组内的字段或组。- 示例 1：
indexed-repeat(${name}, ${names}, 1)将在 name 字段位于名为"names"的先前重复组内时返回第一个可用名称。 - 示例 2：
indexed-repeat(${name}, ${names}, index())将提取与当前重复组实例编号对应的名称。
- 示例 1：
rank-index(index, repeatedfield)：计算重复字段指定实例的序数排名，供在重复组外部使用。排名 1 分配给具有最高值的实例，排名 2 分配给下一个最高值的实例，以此类推。- 示例：
rank-index(1, ${random_draw})根据其random_draw字段的值与其他实例相比计算第一个实例的排名。
- 示例：
rank-index-if(index, repeatedfield, expression)：与rank-index()类似，但使用提供的表达式过滤。- 示例：
rank-index-if(1, ${age}, ${age} >= 18)在只考虑年龄大于或等于 18 的实例的情况下计算成年人组中的年龄排名。
- 示例：
数字函数
| 运算符 | 操作 | 示例 | 示例答案 |
|---|---|---|---|
+ | 加法 | 1 + 1 | 2 |
- | 减法 | 3 - 2 | 1 |
* | 乘法 | 3 * 2 | 6 |
div | 除法 | 10 div 2 | 5 |
mod | 取模 | 9 mod 2 | 1 |
rtSurvey 支持数字函数，包括：
number(field)：将字段的值转换为数字。- 示例：
number('34.8')= 34.8
- 示例：
int(field)：将字段的值转换为整数。- 示例：
int('39.2')= 39
- 示例：
min(field1, ..., fieldx)：返回传入字段中的最小值。- 示例：
min(${father_age}, ${mother_age})将返回父亲或母亲中较小的年龄。
- 示例：
max(field1, ..., fieldx)：返回传入字段中的最大值。- 示例：
max(${father_age}, ${mother_age})将返回父亲或母亲中较大的年龄。
- 示例：
format-number(field)：根据用户的本地设置格式化整数或小数字段的值。- 示例：
format-number(${income})可能将"120000"格式化为"120,000"。
- 示例：
round(field, digits)：将数值字段值四舍五入到小数点后指定位数。- 示例：
round(${interest_rate}, 2)
- 示例：
abs(number)：返回数字的绝对值。pow(base, exponent)：返回第一个参数的第二个参数次幂的值。log10(fieldorvalue)：返回传入字段或值的以 10 为底的对数。sin(fieldorvalue)：返回传入字段或值的正弦值，以弧度表示。cos(fieldorvalue)：返回传入字段或值的余弦值，以弧度表示。tan(fieldorvalue)：返回传入字段或值的正切值，以弧度表示。asin(fieldorvalue)：返回传入字段或值的反正弦值，以弧度表示。acos(fieldorvalue)：返回传入字段或值的反余弦值，以弧度表示。atan(fieldorvalue)：返回传入字段或值的反正切值，以弧度表示。atan2(x, y)：返回坐标为 (x, y) 的点与正 x 轴在原点处所夹角的弧度值。结果在 -pi() 到 pi() 的范围内。sqrt(fieldorvalue)：返回传入字段或值的非负平方根。exp(x)：返回 e^x 的值。pi()：返回 pi 的值。
日期和时间函数
rtSurvey 中的日期值以 YYYY-MM-DD 格式的字符串存储。日期时间值以 ISO 8601 字符串（YYYY-MM-DDTHH:MM:SS）存储。使用 decimal-date-time() 转换为数字进行算术运算（例如计算持续时间）。
today()：以YYYY-MM-DD格式的字符串返回今天的日期。在表单打开时评估一次。- 示例：
today()→'2024-03-15' - 常见用途：
default列预填今天的日期，或在relevant/constraint中与日期字段比较。
- 示例：
now()：以 ISO 8601 字符串返回当前日期和时间。每次计算表达式时都会评估。- 示例：
now()→'2024-03-15T14:32:00.000+03:00' - 常见用途：记录调查期间特定事件的精确时间戳。
- 示例：
date(value)：将值（字符串或数字）转换为日期字符串。- 示例：
date('2024-03-15')→'2024-03-15'
- 示例：
date-time(value)：将值转换为日期时间字符串。- 示例：
date-time(${event_timestamp})
- 示例：
decimal-date-time(value)：将日期或日期时间字符串转换为代表自 Unix 纪元以来的毫秒数除以 86400000 的小数（即自 1970-01-01 以来的小数天数）。用于对日期进行算术运算。- 示例：两个日期之间的天数：
decimal-date-time(${end_date}) - decimal-date-time(${start_date}) - 示例：两个日期时间之间的分钟数：
(decimal-date-time(${end_time}) - decimal-date-time(${start_time})) * 1440
- 示例：两个日期之间的天数：
format-date(date, format)：使用模式字符串格式化日期值。- 格式标记：
%Y（4 位年份）、%y（2 位年份）、%m（月份 01–12）、%d（日期 01–31）、%a（缩写星期几）、%b（缩写月份名称） - 示例：
format-date(today(), '%d/%m/%Y')→'15/03/2024' - 示例：
format-date(${dob}, '%B %d, %Y')→'March 15, 1990'
- 格式标记：
format-date-time(datetime, format)：使用模式字符串格式化日期时间值。接受所有format-date标记以及：%H（小时 00–23）、%h（小时 01–12）、%M（分钟 00–59）、%S（秒 00–59）、%3（毫秒）、%P（AM/PM）- 示例：
format-date-time(now(), '%d/%m/%Y %H:%M')→'15/03/2024 14:32' - 示例：
format-date-time(${event_time}, '%I:%M %p')→'02:32 PM'
Boolean 函数
boolean(value)：将任意值转换为 boolean。非空字符串、非零数字和true返回true；空字符串、0和false返回false。- 示例：
boolean(${name})如果name不为空则返回true。
- 示例：
boolean-from-string(string)：如果字符串为'1'或'true'（不区分大小写）则返回true；否则返回false。- 示例：
boolean-from-string(${enabled_flag})— 当字段将'true'/'false'存储为文本时很有用。
- 示例：
true()：返回 boolean 值true。- 示例：在
required列中，true()等同于yes。
- 示例：在
false()：返回 boolean 值false。- 示例：
if(${skip_section} = 'yes', false(), true())— 动态设置必填。
- 示例：
not(expression)：返回表达式的逻辑否定。如果表达式为 false 则返回true，反之亦然。- 示例：
not(${consent} = 'yes')— 未获得同意时显示警告。 - 示例：
not(selected(${issues}, 'none'))— 仅在未选择"无"时要求详情。
- 示例：
其他字符串函数
starts-with(string, prefix)：如果string以prefix开头则返回true。- 示例：
starts-with(${phone}, '+254')检查电话号码是否以肯尼亚国家代码开头。
- 示例：
contains(string, substring)：如果string包含substring则返回true。- 示例：
contains(${email}, '@')检查邮箱地址是否有@符号。 - 示例：
contains(${notes}, 'urgent')如果备注中提到"urgent"则触发后续问题。
- 示例：
substring-before(string, needle)：返回string中第一次出现needle之前的部分。- 示例：
substring-before(${full_name}, ' ')提取第一个词（名字）。
- 示例：
substring-after(string, needle)：返回string中第一次出现needle之后的部分。- 示例：
substring-after(${email}, '@')提取邮箱地址的域名部分。
- 示例：
normalize-space(string)：去除前后空格，并将所有内部空格序列折叠为单个空格。- 示例：
normalize-space(${name})— 清理可能带有多余空格输入的名称。
- 示例：
translate(string, search_chars, replace_chars)：将string中出现在search_chars中的每个字符替换为replace_chars中对应的字符。在search_chars中没有对应字符的字符将被删除。- 示例：
translate(${code}, 'abcdefghijklmnopqrstuvwxyz', 'ABCDEFGHIJKLMNOPQRSTUVWXYZ')转换为大写（等同于upper()）。 - 示例：
translate(${phone}, ' -()', '')从电话号码中删除空格、连字符和括号。
- 示例：
其他数学函数
floor(number)：返回小于或等于number的最大整数（向负无穷方向舍入）。- 示例：
floor(4.9)= 4，floor(-2.1)= -3
- 示例：
ceiling(number)：返回大于或等于number的最小整数（向正无穷方向舍入）。- 示例：
ceiling(4.1)= 5，ceiling(-2.9)= -2
- 示例：
random()：返回 0.0（含）到 1.0（不含）之间的随机小数。通常在calculate字段中使用以分配随机值或随机化问题顺序。- 示例：
random()→ 例如0.7341 - 示例：
int(random() * 6) + 1→ 随机数 1–6（骰子）
- 示例：
coalesce(a, b)：如果a非空则返回a；否则返回b。当字段可能为空时用作回退值很有用。- 示例：
coalesce(${preferred_name}, ${full_name})— 如果设置了首选名称则使用，否则回退到全名。
- 示例：
once(value)：评估value并存储它，但仅在当前字段为空时。如果字段已有值（例如之前已设置），once()返回现有值不变。这防止重新计算覆盖用户输入。- 示例：在
default列中的once(today())设置一次今天的日期，如果调查员重新打开表单也不会更新。 - 示例：
once(uuid())生成一次 UUID，并在重新编辑时保持稳定。
- 示例：在
地理函数
area(geoshape_value)：计算 geoshape（多边形）值围成的面积（平方米）。- 参数是格式为
lat1 lon1 0 0; lat2 lon2 0 0; ...的 geoshape 字段值 - 示例：
area(${field_boundary})— 计算调查田地的面积（平方米）。 - 示例：
round(area(${field_boundary}) div 10000, 2)— 转换为公顷。
- 参数是格式为
distance(coordinates)：计算 geotrace（线）的总路径长度（米），或两个 geopoint 之间的距离。- 对于 geotrace：
distance(${route})返回总路径长度（米）。 - 对于两个 geopoint：
distance(concat(${point_a}, ' ', ${point_b}))返回它们之间的距离。 - 示例：
round(distance(${road_trace}) div 1000, 3)— 道路长度（公里）。
- 对于 geotrace：
验证函数
regex(value, pattern)：如果value与正则表达式pattern匹配则返回true。在constraint列中用于基于模式的验证。- 该模式使用标准 regex 语法（POSIX ERE 子集）。
- 示例：
regex(., '^[0-9]{10}$')— 验证 10 位数字。 - 示例：
regex(., '^[A-Z]{2}[0-9]{6}$')— 验证护照号码格式（2 个大写字母后跟 6 位数字）。 - 示例：
regex(., '^[^@]+@[^@]+\.[^@]{2,}$')— 基本邮箱格式检查。
checklist(min, max, v1, v2, ...)：评估 boolean 表达式列表，如果true值的数量在min和max（含）之间则返回true。传递-1给min或max以跳过该边界。- 示例：
checklist(2, 3, ${q1} = 'yes', ${q2} = 'yes', ${q3} = 'yes')— 如果三个条件中恰好有 2 或 3 个为真则通过。 - 示例：
checklist(1, -1, ${smoke_alarm}, ${fire_ext}, ${emergency_plan})— 至少一个安全措施必须为真。
- 示例：
weighted-checklist(min, max, v1, w1, v2, w2, ...)：与checklist()类似，但每个值有一个权重。true值的权重之和必须在min和max之间。- 示例：
weighted-checklist(10, -1, ${has_toilet}, 4, ${has_sink}, 3, ${has_shower}, 5)— 现有设施的权重之和必须至少为 10。
- 示例：
实用函数
uuid()：生成随机 UUID（RFC 4122 v4 格式）字符串。- 示例：
uuid()→'a3f8b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c' - 通常与
once()一起使用以生成稳定的唯一 ID：once(uuid())
- 示例：
version()：返回 settings 工作表中设置的表单version属性的值。- 示例：
version()→'3.1' - 在
calculate字段中用于将表单版本嵌入导出数据中很有用。
- 示例：
position()：在重复组内调用时，返回当前重复实例的从 1 开始的索引。- 示例：在第一个实例中
position()返回1，在第二个实例中返回2，以此类推。 - 另请参见：
index()（别名），indexed-repeat()用于从组外部引用重复值。
- 示例：在第一个实例中
thousandsep(length, separator, value)：用千位分隔符格式化数字。length是最小总字符串长度（如果较短则用空格填充），separator是要使用的字符（例如','），value是要格式化的数字。- 示例：
thousandsep(0, ',', 1234567)→'1,234,567' - 示例：
thousandsep(0, '.', ${income})→ 使用句点作为千位分隔符格式化收入。
- 示例：
substr-jsonpath(value, jsonpath)：使用 JSONPath 表达式从 JSON 字符串中提取子字符串。- 示例：
substr-jsonpath(${api_response}, '$.data.name')— 从存储在api_response中的 JSON 字符串中提取name字段。 - 通常与
callapi()一起使用以从 API 响应中提取特定值。
- 示例：