函數
字符串函數
在表達式中使用字符串時，使用單引號（’’）括住字面字符串很重要。但是，當您想在字面字符串中包含單引號時，例外情況出現了。在這種情況下，您可以使用雙引號（""）括住整個字符串。
例如：
- 正確：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')可用作相關性表達式，僅當受訪者選取「Blue」作為最喜歡的顏色時才顯示群組或字段。 - 注意：第二個參數應始終指定選項值，而不是選項標籤。使用表單定義的選項工作表中的值欄中的值。
- 範例：
selected-at(field, number)：返回 select_multiple 字段中指定位置的選定項目。當傳遞的數字為 0 時，返回第一個選定項目；當數字為 1 時，返回第二個選定項目，以此類推。- 範例：
selected-at(${fruits}, 0) = 'Apple'可用作相關性表達式，僅當第一個選定選項為「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)當名稱字段位於名為「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)：返回傳入字段或值的以十為底的對數。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 格式的字符串儲存。Datetime 值以 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)：將值轉換為 datetime 字符串。- 範例：
date-time(${event_timestamp})
- 範例：
decimal-date-time(value)：將日期或 datetime 字符串轉換為表示自 Unix 紀元以來毫秒數除以 86400000 的十進位數字（即自 1970-01-01 以來的小數天數）。使用此函數對日期進行算術運算。- 範例：兩個日期之間的天數：
decimal-date-time(${end_date}) - decimal-date-time(${start_date}) - 範例：兩個 datetime 之間的分鐘數：
(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)：使用格式模式字符串格式化 datetime 值。接受所有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'))— 僅當未選取「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中但在replace_chars中沒有對應字符的字符將被刪除。- 範例：
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欄中用於基於模式的驗證。- 模式使用標準正則表達式語法（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()：返回設定工作表中設定的表單version屬性的值。- 範例：
version()→'3.1' - 在
calculate字段中用於將表單版本嵌入匯出資料。
- 範例：
position()：在重複群組中調用時，返回當前重複實例的基於 1 的索引。- 範例：在第一個實例中
position()返回1，在第二個實例中返回2，以此類推。
- 範例：在第一個實例中
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 回應中提取特定值。
- 範例：