Hàm
Hàm chuỗi
Khi làm việc với chuỗi trong biểu thức, hãy dùng dấu ngoặc đơn (’’) để bao quanh chuỗi ký tự. Ngoại lệ là khi bạn muốn đưa dấu ngoặc đơn vào trong chuỗi — khi đó dùng dấu ngoặc kép ("") để bao quanh toàn bộ chuỗi.
Ví dụ:
- Đúng: if(${yesno} = 1, “a string with ‘single quotes’ in it”, “no single quotes here”)
- Sai: if(${yesno} = 1, ‘a string with ‘single quotes’ in it’, ’no single quotes here’)
Về dấu ngoặc thông minh (smart quotes): nhiều trình soạn thảo văn bản phong phú tự động chuyển dấu ngoặc thẳng ("" hoặc ‘’) thành dấu ngoặc cong ("" hoặc ‘’), có thể gây lỗi cú pháp hoặc hành vi bất ngờ. Hãy đảm bảo dùng nhất quán dấu ngoặc thẳng trong biểu thức.
rtSurvey hỗ trợ các hàm sau đây:
string(field): Chuyển đổi trường sang chuỗi.- Ví dụ:
string(34.8)sẽ được chuyển thành'34.8'.
- Ví dụ:
string-length(field): Trả về độ dài chuỗi của trường.- Ví dụ:
string-length(.) > 3 and string-length(.) < 10có thể dùng để đảm bảo trường hiện tại có từ 3 đến 10 ký tự.
- Ví dụ:
substr(fieldorstring, startindex, endindex): Trả về chuỗi con bắt đầu từstartindexvà kết thúc ngay trướcendindex. Chỉ số bắt đầu từ 0 cho ký tự đầu tiên.- Ví dụ:
substr(${phone}, 0, 3)trả về ba chữ số đầu của số điện thoại.
- Ví dụ:
concat(a, b, c, ...): Ghép các trường (và/hoặc chuỗi) lại với nhau.- Ví dụ:
concat(${firstname}, ' ', ${lastname})trả về họ tên đầy đủ bằng cách kết hợp giá trị trong các trườngfirstnamevàlastname.
- Ví dụ:
linebreak(): Trả về ký tự xuống dòng.- Ví dụ:
concat(${field1}, linebreak(), ${field2}, linebreak(), ${field3})trả về danh sách ba giá trị trường với xuống dòng ở giữa.
- Ví dụ:
lower(): Chuyển chuỗi thành chữ thường.- Ví dụ:
lower('Street Name')trả về “street name”.
- Ví dụ:
upper(): Chuyển chuỗi thành chữ hoa.- Ví dụ:
upper('Street Name')trả về “STREET NAME”.
- Ví dụ:
Hàm select_one và select_multiple
count-selected(field): Trả về số mục đã chọn trong trườngselect_multiple.- Ví dụ:
count-selected(.) = 3có thể dùng làm biểu thức constraint để đảm bảo đúng ba lựa chọn được chọn.
- Ví dụ:
selected(field, value): Trả về true hoặc false tùy thuộc vào việc giá trị đã chỉ định có được chọn trong trườngselect_onehoặcselect_multiplehay không.- Ví dụ:
selected(${color}, 'Blue')có thể dùng làm biểu thức relevant để chỉ hiển thị nhóm hoặc trường nếu người trả lời chọn “Blue”. - Lưu ý: Tham số thứ hai phải luôn chỉ định giá trị lựa chọn, không phải nhãn. Dùng giá trị từ cột value trong bảng tính choices.
- Ví dụ:
selected-at(field, number): Trả về mục được chọn tại vị trí chỉ định trong trườngselect_multiple. Số 0 trả về mục đầu tiên; số 1 trả về mục thứ hai, v.v.- Ví dụ:
selected-at(${fruits}, 0) = 'Apple'có thể dùng làm biểu thức relevant để chỉ hiển thị nếu lựa chọn đầu tiên là “Apple”. - Lưu ý: Giá trị trả về là giá trị lựa chọn, không phải nhãn.
- Ví dụ:
choice-label(field, value): Trả về nhãn cho một lựa chọn trong trườngselect_onehoặcselect_multiple, như được định nghĩa trong bảng tính choices.- Ví dụ 1:
choice-label(${country}, ${country})trả về nhãn của lựa chọn đang được chọn trong trườngcountry. - Ví dụ 2:
choice-label(${languages}, selected-at(${languages}, 0))trả về nhãn của lựa chọn đầu tiên trong trườnglanguages. - Lưu ý: Hàm này lấy nhãn lựa chọn, không phải giá trị.
- Ví dụ 1:
Hàm cho trường lặp
Trong rtSurvey, nếu bạn muốn hỏi cùng một câu hỏi nhiều lần, bạn có thể đặt trường trong nhóm lặp. Điều này tạo ra nhiều phiên bản của cùng một trường. Các hàm sau giúp làm việc với các trường lặp và dữ liệu lặp chúng tạo ra.
join(string, repeatedfield): Với trường trong nhóm lặp, tạo danh sách các giá trị phân cách bởi chuỗi. Tham số đầu tiên chỉ định ký tự phân cách.- Ví dụ:
join(', ', ${member_name})tạo danh sách tên phân cách bởi dấu phẩy từ tất cả tên đã nhập.
- Ví dụ:
join-if(string, repeatedfield, expression): Hoạt động giốngjoin(), nhưng kiểm tra từng phiên bản bằng biểu thức. Nếu biểu thức là false, mục đó bị loại.- Ví dụ:
join-if(', ', ${member_name}, ${age} >= 18)tạo danh sách tên người lớn phân cách bởi dấu phẩy.
- Ví dụ:
count(repeatgroup): Trả về số lần nhóm lặp đã lặp lại.- Ví dụ:
count(${groupname})trả về số phiên bản của nhóm.
- Ví dụ:
count-if(repeatgroup, expression): Hoạt động giốngcount(), nhưng kiểm tra từng phiên bản bằng biểu thức.- Ví dụ:
count-if(${members}, ${age} >= 18)trả về số thành viên là người lớn.
- Ví dụ:
sum(repeatedfield): Với trường trong nhóm lặp, tính tổng tất cả các giá trị.- Ví dụ:
sum(${loan_amount})trả về tổng giá trị tất cả các khoản vay.
- Ví dụ:
sum-if(repeatedfield, expression): Hoạt động giốngsum(), nhưng kiểm tra từng phiên bản bằng biểu thức.- Ví dụ:
sum-if(${loan_amount}, ${loan_amount} > 500)trả về tổng các khoản vay trên 500.
- Ví dụ:
min(repeatedfield): Với trường trong nhóm lặp, tính giá trị nhỏ nhất.- Ví dụ:
min(${member_age})trả về tuổi thành viên nhỏ nhất.
- Ví dụ:
min-if(repeatedfield, expression): Hoạt động giốngmin(), nhưng kiểm tra từng phiên bản bằng biểu thức.- Ví dụ:
min-if(${member_age}, ${member_age} >= 18)trả về tuổi người lớn trẻ nhất.
- Ví dụ:
max(repeatedfield): Với trường trong nhóm lặp, tính giá trị lớn nhất.- Ví dụ:
max(${member_age})trả về tuổi thành viên lớn nhất.
- Ví dụ:
max-if(repeatedfield, expression): Hoạt động giốngmax(), nhưng kiểm tra từng phiên bản bằng biểu thức.- Ví dụ:
max-if(${member_age}, ${member_age} >= 18)trả về tuổi người lớn nhất trong nhóm.
- Ví dụ:
index(): Được gọi trong nhóm lặp, trả về số thứ tự (bắt đầu từ 1) của phiên bản hiện tại.- Ví dụ:
index()trong nhóm lặp trả về 1 cho phiên bản đầu tiên, 2 cho phiên bản thứ hai, v.v.
- Ví dụ:
indexed-repeat(repeatedfield, repeatgroup, index): Tham chiếu trường trong nhóm lặp từ bên ngoài. Tham số đầu chỉ định trường lặp, tham số hai chỉ định nhóm lặp, tham số ba chỉ định số thứ tự phiên bản.- Ví dụ 1:
indexed-repeat(${name}, ${names}, 1)trả về tên đầu tiên khi trườngnamenằm trong nhóm lặp “names”. - Ví dụ 2:
indexed-repeat(${name}, ${names}, index())lấy tên tương ứng với phiên bản nhóm lặp hiện tại.
- Ví dụ 1:
rank-index(index, repeatedfield): Tính thứ hạng theo thứ tự của phiên bản lặp cụ thể để dùng bên ngoài nhóm lặp. Thứ hạng 1 cho phiên bản có giá trị cao nhất. Trả về 999 nếu chỉ số không hợp lệ.- Ví dụ:
rank-index(1, ${random_draw})tính thứ hạng của phiên bản đầu tiên so với các phiên bản khác.
- Ví dụ:
rank-index-if(index, repeatedfield, expression): Hoạt động giốngrank-index(), nhưng kiểm tra từng phiên bản bằng biểu thức. Trả về 999 nếu phiên bản bị loại do không thỏa biểu thức.- Ví dụ:
rank-index-if(1, ${age}, ${age} >= 18)tính thứ hạng tuổi trong nhóm người lớn.
- Ví dụ:
Hàm số học
| Toán tử | Phép toán | Ví dụ | Kết quả |
|---|---|---|---|
+ | Cộng | 1 + 1 | 2 |
- | Trừ | 3 - 2 | 1 |
* | Nhân | 3 * 2 | 6 |
div | Chia | 10 div 2 | 5 |
mod | Chia lấy dư | 9 mod 2 | 1 |
rtSurvey hỗ trợ các hàm số học, bao gồm:
number(field): Chuyển đổi giá trị trường sang số.- Ví dụ:
number('34.8')= 34.8
- Ví dụ:
int(field): Chuyển đổi giá trị trường sang số nguyên.- Ví dụ:
int('39.2')= 39
- Ví dụ:
min(field1, ..., fieldx): Trả về giá trị nhỏ nhất trong các trường được truyền vào.- Ví dụ:
min(${father_age}, ${mother_age})trả về tuổi của bố hoặc mẹ, tùy theo ai trẻ hơn.
- Ví dụ:
max(field1, ..., fieldx): Trả về giá trị lớn nhất trong các trường được truyền vào.- Ví dụ:
max(${father_age}, ${mother_age})trả về tuổi của bố hoặc mẹ, tùy theo ai lớn hơn.
- Ví dụ:
format-number(field): Định dạng giá trị trường số nguyên hoặc thập phân theo cài đặt ngôn ngữ người dùng.- Ví dụ:
format-number(${income})có thể định dạng “120000” thành “120,000”.
- Ví dụ:
round(field, digits): Làm tròn giá trị trường số đến số chữ số thập phân chỉ định.- Ví dụ:
round(${interest_rate}, 2)
- Ví dụ:
abs(number): Trả về giá trị tuyệt đối của một số.pow(base, exponent): Trả về giá trị của tham số đầu lũy thừa tham số hai.- Mỗi tham số có thể là trường, số hoặc biểu thức.
log10(fieldorvalue): Trả về logarit cơ số 10 của trường hoặc giá trị.sin(fieldorvalue): Trả về sin của trường hoặc giá trị, tính bằng radian.cos(fieldorvalue): Trả về cos của trường hoặc giá trị, tính bằng radian.tan(fieldorvalue): Trả về tan của trường hoặc giá trị, tính bằng radian.asin(fieldorvalue): Trả về arcsin của trường hoặc giá trị, tính bằng radian.acos(fieldorvalue): Trả về arccos của trường hoặc giá trị, tính bằng radian.atan(fieldorvalue): Trả về arctan của trường hoặc giá trị, tính bằng radian.atan2(x, y): Trả về góc tính bằng radian của điểm (x, y) so với trục x dương. Kết quả trong khoảng -pi() đến pi().sqrt(fieldorvalue): Trả về căn bậc hai không âm của trường hoặc giá trị.exp(x): Trả về giá trị e^x.pi(): Trả về giá trị số pi.
Hàm ngày và giờ
Giá trị ngày trong rtSurvey được lưu dưới dạng chuỗi YYYY-MM-DD. Giá trị datetime được lưu dưới dạng chuỗi ISO 8601 (YYYY-MM-DDTHH:MM:SS). Dùng decimal-date-time() để chuyển đổi sang số cho phép tính số học (ví dụ: tính khoảng thời gian).
today(): Trả về ngày hôm nay dưới dạng chuỗiYYYY-MM-DD. Được đánh giá một lần khi biểu mẫu mở.- Ví dụ:
today()→'2024-03-15' - Dùng phổ biến: cột
defaultđể điền sẵn ngày hôm nay, hoặc trongrelevant/constraintđể so sánh với trường ngày.
- Ví dụ:
now(): Trả về ngày và giờ hiện tại dưới dạng chuỗi ISO 8601. Được đánh giá mỗi lần biểu thức được tính.- Ví dụ:
now()→'2024-03-15T14:32:00.000+03:00' - Dùng phổ biến: Ghi lại dấu thời gian chính xác của một sự kiện cụ thể trong khảo sát.
- Ví dụ:
date(value): Chuyển đổi giá trị (chuỗi hoặc số) thành chuỗi ngày.- Ví dụ:
date('2024-03-15')→'2024-03-15'
- Ví dụ:
date-time(value): Chuyển đổi giá trị thành chuỗi datetime.- Ví dụ:
date-time(${event_timestamp})
- Ví dụ:
decimal-date-time(value): Chuyển đổi chuỗi ngày hoặc datetime thành số thập phân đại diện cho mili giây kể từ Unix epoch chia cho 86400000 (tức là số ngày phân số kể từ 1970-01-01). Dùng để thực hiện tính toán số học trên ngày.- Ví dụ: Khoảng thời gian tính theo ngày giữa hai ngày:
decimal-date-time(${end_date}) - decimal-date-time(${start_date}) - Ví dụ: Khoảng thời gian tính theo phút giữa hai datetime:
(decimal-date-time(${end_time}) - decimal-date-time(${start_time})) * 1440
- Ví dụ: Khoảng thời gian tính theo ngày giữa hai ngày:
format-date(date, format): Định dạng giá trị ngày theo chuỗi mẫu.- Mã định dạng:
%Y(năm 4 chữ số),%y(năm 2 chữ số),%m(tháng 01–12),%d(ngày 01–31),%a(tên ngày viết tắt),%b(tên tháng viết tắt) - Ví dụ:
format-date(today(), '%d/%m/%Y')→'15/03/2024' - Ví dụ:
format-date(${dob}, '%B %d, %Y')→'March 15, 1990'
- Mã định dạng:
format-date-time(datetime, format): Định dạng giá trị datetime theo chuỗi mẫu. Chấp nhận tất cả mãformat-datecộng thêm:%H(giờ 00–23),%h(giờ 01–12),%M(phút 00–59),%S(giây 00–59),%3(mili giây),%P(SA/CH)- Ví dụ:
format-date-time(now(), '%d/%m/%Y %H:%M')→'15/03/2024 14:32' - Ví dụ:
format-date-time(${event_time}, '%I:%M %p')→'02:32 PM'
Hàm boolean
boolean(value): Chuyển đổi bất kỳ giá trị nào thành boolean. Trả vềtruecho chuỗi không rỗng, số khác không, vàtrue; trả vềfalsecho chuỗi rỗng,0, vàfalse.- Ví dụ:
boolean(${name})trả vềtruenếunamekhông rỗng.
- Ví dụ:
boolean-from-string(string): Trả vềtruenếu chuỗi là'1'hoặc'true'(không phân biệt hoa thường); trả vềfalsetrong trường hợp khác.- Ví dụ:
boolean-from-string(${enabled_flag})— hữu ích khi trường lưu'true'/'false'dưới dạng văn bản.
- Ví dụ:
true(): Trả về giá trị booleantrue.- Ví dụ: Trong cột
required,true()tương đương vớiyes.
- Ví dụ: Trong cột
false(): Trả về giá trị booleanfalse.- Ví dụ:
if(${skip_section} = 'yes', false(), true())— đặt required động.
- Ví dụ:
not(expression): Trả về phủ định logic của biểu thức. Trả vềtruenếu biểu thức là false, và ngược lại.- Ví dụ:
not(${consent} = 'yes')— hiển thị cảnh báo khi đồng ý KHÔNG được cho. - Ví dụ:
not(selected(${issues}, 'none'))— chỉ yêu cầu chi tiết khi “none” không được chọn.
- Ví dụ:
Hàm chuỗi bổ sung
starts-with(string, prefix): Trả vềtruenếustringbắt đầu bằngprefix.- Ví dụ:
starts-with(${phone}, '+84')kiểm tra nếu số điện thoại bắt đầu bằng mã quốc gia Việt Nam.
- Ví dụ:
contains(string, substring): Trả vềtruenếustringchứasubstring.- Ví dụ:
contains(${email}, '@')kiểm tra địa chỉ email có ký tự@. - Ví dụ:
contains(${notes}, 'urgent')kích hoạt câu hỏi tiếp theo nếu ghi chú đề cập đến “urgent”.
- Ví dụ:
substring-before(string, needle): Trả về phần củastringxuất hiện trước lần xuất hiện đầu tiên củaneedle.- Ví dụ:
substring-before(${full_name}, ' ')trích xuất từ đầu tiên (tên).
- Ví dụ:
substring-after(string, needle): Trả về phần củastringxuất hiện sau lần xuất hiện đầu tiên củaneedle.- Ví dụ:
substring-after(${email}, '@')trích xuất phần tên miền của địa chỉ email.
- Ví dụ:
normalize-space(string): Loại bỏ khoảng trắng đầu/cuối và thu gọn tất cả chuỗi khoảng trắng nội tại thành một dấu cách.- Ví dụ:
normalize-space(${name})— làm sạch tên có thể đã được nhập với khoảng trắng thừa.
- Ví dụ:
translate(string, search_chars, replace_chars): Thay thế từng ký tự trongstringxuất hiện trongsearch_charsbằng ký tự tương ứng trongreplace_chars. Các ký tự trongsearch_charskhông có ký tự tương ứng trongreplace_charssẽ bị xóa.- Ví dụ:
translate(${phone}, ' -()', '')loại bỏ dấu cách, gạch ngang và dấu ngoặc khỏi số điện thoại.
- Ví dụ:
Hàm toán học bổ sung
floor(number): Trả về số nguyên lớn nhất nhỏ hơn hoặc bằngnumber(làm tròn về âm vô cùng).- Ví dụ:
floor(4.9)= 4,floor(-2.1)= -3
- Ví dụ:
ceiling(number): Trả về số nguyên nhỏ nhất lớn hơn hoặc bằngnumber(làm tròn về dương vô cùng).- Ví dụ:
ceiling(4.1)= 5,ceiling(-2.9)= -2
- Ví dụ:
random(): Trả về số thập phân ngẫu nhiên từ 0.0 (bao gồm) đến 1.0 (không bao gồm). Thường dùng trong trườngcalculateđể gán giá trị ngẫu nhiên.- Ví dụ:
random()→ ví dụ0.7341 - Ví dụ:
int(random() * 6) + 1→ số ngẫu nhiên từ 1–6 (tung xúc xắc)
- Ví dụ:
coalesce(a, b): Trả vềanếuakhông rỗng; ngược lại trả vềb. Hữu ích làm giá trị dự phòng khi trường có thể rỗng.- Ví dụ:
coalesce(${preferred_name}, ${full_name})— dùng tên ưa thích nếu có, ngược lại dùng tên đầy đủ.
- Ví dụ:
once(value): Đánh giávaluevà lưu lại, nhưng chỉ khi trường hiện tại rỗng. Nếu trường đã có giá trị,once()trả về giá trị hiện tại không thay đổi. Điều này ngăn tính lại ghi đè đầu vào của người dùng.- Ví dụ:
once(today())trong cộtdefaultđặt ngày hôm nay một lần và không cập nhật nếu người điều tra mở lại biểu mẫu. - Ví dụ:
once(uuid())tạo UUID một lần và giữ ổn định qua các lần chỉnh sửa.
- Ví dụ:
Hàm địa lý
area(geoshape_value): Tính diện tích tính bằng mét vuông của một geoshape (đa giác).- Tham số là giá trị trường geoshape theo định dạng
lat1 lon1 0 0; lat2 lon2 0 0; ... - Ví dụ:
area(${field_boundary})— tính diện tích thửa đất khảo sát tính bằng m². - Ví dụ:
round(area(${field_boundary}) div 10000, 2)— chuyển sang hecta.
- Tham số là giá trị trường geoshape theo định dạng
distance(coordinates): Tính tổng chiều dài đường đi tính bằng mét của geotrace (đường), hoặc khoảng cách giữa hai geopoint.- Với geotrace:
distance(${route})trả về tổng chiều dài đường đi tính bằng mét. - Với hai geopoint:
distance(concat(${point_a}, ' ', ${point_b}))trả về khoảng cách giữa chúng. - Ví dụ:
round(distance(${road_trace}) div 1000, 3)— chiều dài đường tính bằng km.
- Với geotrace:
Hàm xác thực
regex(value, pattern): Trả vềtruenếuvaluekhớp với biểu thức chính quypattern. Dùng trong cộtconstraintđể xác thực dựa trên mẫu.- Mẫu dùng cú pháp regex tiêu chuẩn (tập con POSIX ERE).
- Ví dụ:
regex(., '^[0-9]{10}$')— xác thực số 10 chữ số. - Ví dụ:
regex(., '^[A-Z]{2}[0-9]{6}$')— xác thực định dạng số hộ chiếu (2 chữ hoa + 6 chữ số). - Ví dụ:
regex(., '^[^@]+@[^@]+\.[^@]{2,}$')— kiểm tra định dạng email cơ bản.
checklist(min, max, v1, v2, ...): Đánh giá danh sách biểu thức boolean và trả vềtruenếu số giá trịtruenằm trong khoảngminđếnmax(bao gồm). Truyền-1chominhoặcmaxđể bỏ qua giới hạn đó.- Ví dụ:
checklist(2, 3, ${q1} = 'yes', ${q2} = 'yes', ${q3} = 'yes')— đúng nếu chính xác 2 hoặc 3 trong ba điều kiện là true. - Ví dụ:
checklist(1, -1, ${smoke_alarm}, ${fire_ext}, ${emergency_plan})— ít nhất một biện pháp an toàn phải là true.
- Ví dụ:
weighted-checklist(min, max, v1, w1, v2, w2, ...): Giốngchecklist(), nhưng mỗi giá trị có trọng số. Tổng trọng số của các giá trịtruephải nằm trong khoảngminđếnmax.- Ví dụ:
weighted-checklist(10, -1, ${has_toilet}, 4, ${has_sink}, 3, ${has_shower}, 5)— tổng trọng số của các tiện nghi có mặt phải ít nhất là 10.
- Ví dụ:
Hàm tiện ích
uuid(): Tạo UUID ngẫu nhiên (định dạng RFC 4122 v4) dưới dạng chuỗi.- Ví dụ:
uuid()→'a3f8b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c' - Thường dùng với
once()để tạo ID duy nhất ổn định:once(uuid())
- Ví dụ:
version(): Trả về giá trị thuộc tínhversioncủa biểu mẫu được đặt trong bảng tính settings.- Ví dụ:
version()→'3.1' - Hữu ích trong trường
calculateđể nhúng phiên bản biểu mẫu vào dữ liệu xuất.
- Ví dụ:
position(): Khi được gọi trong nhóm lặp, trả về chỉ số (bắt đầu từ 1) của phiên bản lặp hiện tại.- Ví dụ:
position()trong phiên bản đầu tiên trả về1, phiên bản thứ hai trả về2, v.v. - Xem thêm:
index()(bí danh),indexed-repeat()để tham chiếu giá trị lặp từ bên ngoài nhóm.
- Ví dụ:
thousandsep(length, separator, value): Định dạng số với ký tự phân cách hàng nghìn.lengthlà độ dài chuỗi tối thiểu (đệm bằng dấu cách nếu ngắn hơn),separatorlà ký tự dùng (ví dụ:','), vàvaluelà số cần định dạng.- Ví dụ:
thousandsep(0, ',', 1234567)→'1,234,567' - Ví dụ:
thousandsep(0, '.', ${income})→ định dạng thu nhập với dấu chấm làm ký tự phân cách hàng nghìn.
- Ví dụ:
substr-jsonpath(value, jsonpath): Trích xuất chuỗi con từ chuỗi JSON bằng biểu thức JSONPath.- Ví dụ:
substr-jsonpath(${api_response}, '$.data.name')— trích xuất trườngnametừ chuỗi JSON lưu trongapi_response. - Thường dùng cùng với
callapi()để trích xuất giá trị cụ thể từ phản hồi API.
- Ví dụ: