الصيغ

يمكنك استخدام الصيغ لإنشاء نماذج أذكى مع ArcGIS Survey123.

تجب دائمًا الإشارة إلى الأسئلة السابقة في الصيغ بتنسيق ${field_name}.

العوامل

فيما يلي العوامل المدعومة في Survey123:

مُشغل	الوصف	مثال
.	الإجابة الحالية	.=1
+	إضافة	${question_one} + 4
-	طرح	${question_one} - 4
*	علامة الضرب	${question_one} * 4
div	تقسيم	${question_one} div 4
=	مساوي	${price}=9.80
!=	غير مساوي	${price}!=9.80
<	أقل من	${price}<9.80
<=	أقل من أو يساوي	${price}<=9.80
>	أكبر من	${price}>9.80
>=	أكبر من أو يساوي	${price}>=9.80
and	و	${price}>9.00 and ${price}<9.90
mod	النموذج (القسمة المتبقية)	${question_one} mod ${question_two}
or	أو	${price}=9.80 or ${price}=9.70

الدوال

الوظائف التالية مدعومة في Survey123:

وظيفة	الوصف	مثال
boolean(question, expression, or value)	إرجاع صحيح إذا كانت القيمة المقدمة غير فارغة. يوصى باستخدام boolean-from-string() بدلاً من ذلك. تنبيه: ستُرجع هذه الدالة دائمًا "صواب" في تطبيق Survey123 على الويب. للاطلاع على البدائل، راجع القيم الفارغة.	boolean(${question_one})
boolean-from-string()	إرجاع صحيح إذا كانت السلسلة المقدمة 'صحيحة' أو تساوي '1'. وبخلاف ذلك يكون الإرجاع خطأ.	boolean-from-string(${question_one})
coalesce(value1, value2)	يعود بالقيمة الأولى غير الفارغة. تدعم هذه الدالة قيمتين فقط.	coalesce(${question_one}, ${question_two})
concat(value1, value2, …)	إرجاع السلسلة من قيم السلسلة.	concat(${question_one}, ' and ', ${question_two})
contains(string, substring)	إرجاع صحيح إذا كانت السلسلة المقدمة تتضمن سلسلة فرعية.	contains(${question_one}, 'red')
count(repeat)	يعود بكمية الاستجابات إلى السؤال المحدد عبر التكرارات. لمزيد من المعلومات، راجع دوال التجميع. ملاحظة:‏ عند استخدام هذه الدالة في تطبيق Survey123 الميداني، يمكن وضعها داخل التكرار أو خارجه. في حال عدم استخدام الدالة في تطبيق ويب Survey123، يلزم وضعها خارج التكرار. يمكن الإشارة إلى قيمة العدد من خارج التكرار في عملية حسابية داخل التكرار.	count(${question})
count-selected(question)	لعرض عدد الإجابات المحددة لأسئلة select_one و select_multiple. تُرجع هذه الدالة أيضًا عدد الملفات المرفقة لأسئلة الصور والصوت والملفات باستخدام المظهر المتعدد الأسطر.	count-selected(${question_one})
date(question, expression, or value)	تحويل رقم أو سلسلة إلى كائن تاريخ، دون الاحتفاظ بالتاريخ.	date('2017-05-28T04:39:02+10:00')
date-time(question, expression, or string)	تحويل رقم أو سلسلة إلى كائن تاريخ.	date-time('2017-05-28T04:39:02+10:00')
decimal-date-time(question, expression, or string)	تحويل كائن تاريخ إلى رقم وقت-تاريخ عشري.	decimal-date-time(${date_question})
decimal-time(question, expression, or string)	تحويل كائن زمني إلى رقم يمثل يومًا جزئيًا في المنطقة الزمنية للجهاز.	decimal-time(${time_question})
ends-with(string, substring)	إرجاع صحيح إذا كانت السلسلة المقدمة تنتهي بسلسلة فرعية.	ends-with(${question_one}, 'hand.')
false()	خطأ	false()
format-date()	يلائم قيمة التاريخ أو الوقت الحالية لتنسيق محدد.	format-date(${previous_time}, '%H:%M')
if(condition, a, b)	إذا تم تقييم الشرط إلى صحيح، يتم إرجاع أ؛ خلاف ذلك، يتم إرجاع ب.	if(selected(${question_one}, 'yes') and selected(${question_two}, 'yes'), 'yes', 'no')
مكرر مفهرس (سؤال، تكرار، رقم فهرس)	ترجع القيمة من سؤال محدد في سجل مكرر. للحصول على مزيد من المعلومات، راجع التكرارات.	indexed-repeat(${room_no}, ${floor}, 3)
int(question, expression, or value)	تحويل إلى عدد صحيح. يتنوع التحويل بناءً على نوع البيانات. ملاحظة:‏ إذا كانت هذه الوظيفة فارغة، فستعيد NaN وسيظل السؤال فارغًا.	int(${question_one})
join(separator, question)	يسلسل كل الإجابات إلى سؤال محدد في تكرار، مفصول بفاصلة محددة.	join(',', ${question_in_repeat})
jr:choice-name(choice_name, 'question')	تُستخدم لأسئلة select_one. يُرجع التسمية المقترنة باسم الاختيار في السؤال المقدم. انتبه إلى إنه يجب تعريف السؤال داخل اقتباسات.	jr:choice-name(${select_one}, '${select_one}')
	مستخدم لأسئلة select_multiple. يُرجع التسمية المقترنة باسم الاختيار في السؤال المقدم. يجب استخدام دالة selected-at() لاستخراج تسمية الإجابات الفردية. انتبه إلى إنه يجب تعريف السؤال داخل اقتباسات.	jr:choice-name(selected-at(${select_multiple}, 3), '${select_multiple}')
max(value1, value2, ...)	يعود بالحد الأقصى للقيمة في النطاق المحدد، أو إلى سؤال أحادي عبر التكرارات.	max(${question_one}, ${question_two})
min(value1, value2, ...)	يعود بالحد الأدنى للقيمة في النطاق المحدد، أو إلى سؤال أحادي عبر التكرارات.	min(${question_one}, ${question_two})
not(expression)	إرجاع قيمة خاطئة إذا كان التعبير سيعود صحيحًا، وقيمة صحيحة إذا كان التعبير سيعيد خطأ.	not(selected(., 'yes'))
now()	يعود بالطابع الزمني لهذه اللحظة. تُستخدم هذه الدالة في أسئلة الوقت وأسئلة التاريخ-الوقت. يتصرف مثل اليوم() في أسئلة التاريخ.	now()
number(question, expression, or value)	تحويل إلى رقم. يتنوع التحويل بناءً على نوع البيانات. ملاحظة:‏ إذا كانت هذه الوظيفة فارغة، فستعيد NaN وسيظل السؤال فارغًا.	number(${question_one})
once()	إذا كان السؤال يحتوي على قيمة، يتم إرجاع القيمة الحالية. هذه الدالة مفيدة عند استخدام عشوائي() أو uuid() في سؤال متكرر لضمان عدم تغيير القيمة عند الاستعراض من خلال سجلات التكرار في النموذج.	once(uuid())
موضع (..)	إرجاع فهرس السجل الحالي بشكل متكرر. للحصول على مزيد من المعلومات، راجع التكرارات.	position(..)
pulldata()	يرجع قيمة من ملف CSV خارجي. للحصول على مزيد من المعلومات، راجع استرداد قيمة من CSV.	pulldata('users', 'email', 'name', ${respondent_name})
pulldata("@exif")	يرجع قيمة من بيانات تعريف EXIF في صورة. للحصول على مزيد من المعلومات، راجع استخراج بيانات التعريف الخاصة بالصورة.	pulldata("@exif", ${photo}, "GpsLatitude")
pulldata("@geopoint")	يرجع قيمة من سؤال نقطة جغرافية. للحصول على مزيد من المعلومات، راجع استخراج قيم النقطة الجغرافية.	pulldata("@geopoint", ${location}, "horizontalAccuracy")
pulldata("@javascript")	يشغل دالة JavaScript في النموذج ويرجع النتيجة. للحصول على مزيد من المعلومات، راجع دوال JavaScript في نماذج الاستطلاع.	pulldata("@javascript", "functions.js", "uniqueID", ${buildings})
pulldata("@json")	يرجع قيمة من كائن JSON. للحصول على مزيد من المعلومات، راجع استرداد قيمة من JSON.	pulldata("@json", ${json_output}, "attributes.ZIP_CODE")
pulldata("@layer")	الاستعلام عن طبقة معالم ArcGIS أو جدول المعالم أو خدمة الخريطة الممكنة للاستعلام وإرجاع النتيجة. لمزيد من المعلومات، راجع الاستعلام عن طبقة معالم.	pulldata("@layer", "getRecordAt", "https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/World_Time_Zones/FeatureServer/0", ${location})
pulldata("@property")	يرجع المعلومات المتعلقة بالجهاز أو المستخدم الذي سجل الدخول. للحصول على مزيد من المعلومات، راجع الجهاز وخصائص المستخدم.	pulldata("@property", 'username')
random()	إرجاع قيمة عشوائية بين 0 (شامل) و1 (حصري).	random()
regex()	يطبق تعبيرًا عاديًا على مدخلات السؤال. يرجع قيمة صحيحة في حال تطابق النمط. لمزيد من المعلومات، راجع موضوع التعبيرات العادية.	regex(., '^\d{5}$')
محدد(السؤال, القيمة)	تحقق مما إذا تم تحديد الإجابة. تُستخدم هذه الدالة لأسئلة الاختيار_الواحد والاختيار_المتعدد.	selected(${question_one}, 'a')
selected-at(question, number)	مستخدم لأسئلة select_multiple. يُرجع اسم الاختيار المحدد للرقم المقدم؛ الذي يُحتسب من الصفر، على سبيل المثال، سيرجع الرقم '2' الاختيار الثالث المحدد.	selected-at(${question_one}, 2)
starts-with(string, substring)	إرجاع صحيح إذا كانت السلسلة المقدمة تبدأ بسلسلة فرعية.	starts-with(${question_one}, 'The')
string(question, expression, or value)	تحويل إلى سلسلة. يتنوع التحويل بناءً على نوع البيانات.	string(${question_one})
string-length(question, expression, or value)	إرجاع طول سلسلة ليست فارغة.	string-length(${question_one})
substr(question, start, end)	إرجاع السلسلة الفرعية بدءًا من البداية المحددة وتمتد إلى الحرف في نهاية الفهرس -1، حيث تبدأ البداية والنهاية عند 0.	substr(${question_one}, 1, 2)
sum(repeat)	يعود بإجمالي جميع الاستجابات إلى السؤال المحدد عبر التكرارات. لمزيد من المعلومات، راجع دوال التجميع. ملاحظة:‏ عند استخدام هذه الدالة في تطبيق Survey123 الميداني، يمكن وضعها داخل التكرار أو خارجه. في حال عدم استخدام الدالة في تطبيق ويب Survey123، يلزم وضعها خارج التكرار. يمكن الإشارة إلى قيمة مجموع من خارج التكرار في عملية حسابية داخل التكرار.	sum(${question})
today()	إرجاع تاريخ اليوم، المخزن داخليًا في منتصف النهار المحلي. تُستخدم هذه الدالة في أسئلة التاريخ.	today()
true()	صواب	true()
uuid()	إرجاع سلسلة UUID عشوائية.	uuid()
version()	إرجاع إصدار المسح المعرف في مصنف إعدادات	version()

الدوال الرياضية التالية مدعومة في Survey123:

وظيفة	الوصف	مثال
acos(القيمة)	يرجع جيب التمام القوسي للقيمة.	acos(${question_one})
asin(القيمة)	يرجع جيب الزاوية القوسي للقيمة.	asin(${question_one})
atan(القيمة)	يرجع ظل القوس للقيمة.	atan(${question_one})
atan2(القيمة1, القيمة2)	يرجع ظل القوس لحاصل قسمة القيم.	atan2(${question_one}, ${question_two})
cos(القيمة)	يرجع جيب التمام للقيمة كزاوية بوحدات الراديان.	cos(${question_one})
sin(القيمة)	يرجع جيب الزاوية للقيمة كزاوية بوحدات الراديان.	sin(${question_one})
tan(القيمة)	يرجع ظل القيمة كزاوية بوحدات الراديان.	tan(${question_one})
exp(القيمة)	إرجاع الأس الطبيعي للقيمة.	exp(${question_one})
exp10(القيمة)	إرجاع 10 إلى قوة القيمة.	exp10(${question_one})
السجل(القيمة)	إرجاع اللوغاريتم الطبيعي للقيمة.	log(${question_one})
log10(القيمة)	إرجاع اللوغاريتم العشر الأساسي للقيمة.	log10(${question_one})
pi()	إرجاع pi.	pi()
pow(القيمة, القوة)	إرجاع القيمة إلى القوة المحددة.	pow(${question_one}, 3)
الجولة (القيمة، القوة)	إرجاع القيمة المستديرة.	round(${question_one}, 5)
sqrt(القيمة)	إرجاع الجذر التربيعي للقيمة.	sqrt(${question_one})

القيود

تقيد إضافة قيد إلى سؤال استطلاع المدخلات المقبولة للحصول على إجابة. يمكن أن يشمل هذا مجموعة محددة من الأرقام ومجموعات الحروف والأعداد، أو مطابقة نمط عام. في جدول البيانات، يتم إدخال تعبير القيود في حقل القيود ويتم إدخال نص معلوماتي في عمود constraint_message بجدول عمل الاستطلاع. في تعبير القيود، يتم دائمًا تمثيل مدخلات السؤال بنقطة.

على سبيل المثال، يمكنك استخدام الصيغ التالية لتقتصر مدخلات حقل العدد الصحيح على الأرقام الموجبة فقط:

.>= 0

تمنع هذه الصيغة، عند تطبيقها على حقل date، المستخدم من إدخال قيمة قبل اليوم:

.>= today()

يمكنك أيضًا استخدام عمليات حسابية بقيود. تنفذ هذه الصيغة عملية حسابية للسماح فقط للمستخدم بتحديد تواريخ بين اليوم و14 يومًا من اليوم:

(.>= today()) and (.<=(today() + (1000 * 60 * 60 * 24 * 14)))

تلميح:

لتجنب الأخطاء غير المتوقعة، إذا كانت الصيغة تحتوي على قيم عشرية بين -1 و1، فقم بتضمين صفر بادئ في القيم الخاصة بك. بدون الصفر البادئ، يمكن أن يتم كتابة الرقم العشري بشكل خطأ لحرف العملية . (أو -.). على سبيل المثال، سوف يفشل التعبير التالي:

.> .25 and .< 24.25

سيتم تشغيل التعبير التالي على النحو المتوقع:

.> 0.25 and .< 24.25

التعبيرات العادية

التعبير العادي هو سلسلة من الرموز المستخدمة لمطابقة الأنماط في السلاسل. في Survey123، في حالة مطابقة النمط، سيعود التعبير صحيحًا؛ فإذا لم يكن النمط مطابقًا، فسيعود التعبير خطأً.

يمكنك استخدام تعبيرات عادية بطرق متنوعة لمطابقة النمط لتقييد الإجابات الصالحة على تنسيق محدد أو ضمان أنها تحتوي على محتوى محدد. يتطلب هذا المثال أن تشتمل الإجابة عن السؤال كلمة طريق في أي مكان فيه:

regex(., 'road')

تُطبِّق المدة المستخدمة في بداية هذه الأمثلة التعبير على الحقل الحالي. وبدلاً من ذلك، تطبق إضافة اسم حقل آخر في مكانه التعبير العادي على ذلك الحقل، وهو ما يُعد مثاليًا للتعبيرات ذات الصلة. تعمل الفاصلة كفاصل بين تعريف الحقل والتعبير.

ويضمن هذا التعبير المنتظم مطابقة الإجابة لكلمة طريق تمامًا، مع عدم وجود أي شيء قبلها أو بعدها:

regex(., '^road$')

تعد التعبيرات المنتظمة مثاليةً لتقييد مُدخل سؤال بتنسيق قياسي. لا يقبل هذا المثال إلا إدخال رمز بريدي مكون من خمسة أرقام للولايات المتحدة:

regex(., '^\d{5}$')

يُطابق هذا المثال الرد على التنسيق الحالي للوحات السيارات الإندونيسية، كما في الصورة التالية:

regex(., '^[A-Z]{1,2}\d{4}[A-Z]{2,3}$')

قد تتطلب التنسيقات الموحدة الأكثر مرونة تعبيرات عادية معقدة. هذا التعبير المنتظم المستخدم بواسطة تطبيق الويب Survey123 يعمل على تقييد المدخلات الخاصة بحقل السلسلة لمطابقة تنسيق عنوان البريد الإلكتروني:

regex(., '^(([^<>()\[\]\\.,;:\s@"]+(\.[^<>()\[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$')

يقوم تعديل التعبير أعلاه بتقييد المدخل لمطابق تنسيق عنوان البريد الإلكتروني، في حين قبول الأحرف غير الإنجليزية:

regex(., '^(([^<>()\[\]\\.,;:\s@"]+(\.[^<>()\[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}])|(([a-zA-Z\u0400-\uffff\-0-9]+\.)+[a-zA-Z\u0400-\uffff]{2,}))$')

تقتصر هذه العينة، أيضًا باستخدام تعبير منتظم من تطبيق ويب Survey123، على حقل لقبول فقط الاستجابات التي تطابق تنسيق عنوان الويب:

regex(., '^((https?|ftps?)\://|)(((?:(?:[\da-zA-Z](?:[-\da-zA-Z]{0,61}[\da-zA-Z])?)\.)+(?:[a-zA-Z](?:[-\da-zA-Z]{0,61}[\da-zA-Z])?)\.?)|localhost)(\:\d+)?(/(?:[^?#\s/]+/)*(?:[^?#\s/]+(?:\?[^?#\s/]*)?(?:#[A-Za-z][\w.:-]*)?)?)?')

لمزيد من المعلومات عن التعبيرات العادية، راجع وثائق شبكة مطور Mozilla. للحصول على قائمة بالأحرف ووظائفها في التعبيرات العادية، راجع جدول بيانات المرجع في قوالب Survey123 أو راجع المرجع السريع.

حسابات

يتم تنفيذ العمليات الحسابية في عمود الحساب "calculation" لسؤال. يتم غالبًا إقران العمليات الحسابية بنوع حساب السؤال، ولكن يمكن أيضًا تطبيقها على أسئلة العدد الصحيح والكسر العشري والأسئلة النصية وأسئلة select_one. يمكن استخدام نتيجة العملية الحسابية لتعبئة تعبيرات القيود أو ذات الصلة عن طريق الإشارة إلة اسم الحقل الخاص باحتساب السؤال.

يكون نوع سؤال الحساب مخفي، ولا يُعرض في نموذج. وهو ما يعني أنه يمكن أيضًا استخدامها لتعليق قيم لا يجب عرضها على النموذج، ولكن يتم تضمينها في طبقة المعلم.

على سبيل المثال، يمكنك إنشاء سؤال لحساب النوع وتسميته calc، وإدراج التعبير التالي في عمود الحساب التابع له:

${question_1} + ${question_2} + ${question_3}

استخدم النتيجة لتعيين الصلة الخاصة بالسؤال التالي:

${calc} <= 100

يمكن استخدام العمليات الحسابية مع الاستجابات في حقول date. تقدر هذه العملية الحسابية عدد السنوات بين التاريخ الذي تم إدخاله واليوم، وهو مثالي لاحتساب عمر شخص ما:

int((today() - ${birth_date}) div (1000 * 24 * 60 * 60 * 365.25))

لن تحتاج أحيانًا إلا إلى جزء من القيمة أو إصدار تم اقتطاعه من إجابة كاملة. لا يُرجِع عامل substr سوى جزء من سلسلة محددة بالأعداد الواردة بعدها. يحدد الحرف الأول نقطة بداية التحديد، في حين تحدد القيمة الثانية الطول (إذا لم توجد قيمة ثانية، فستستمر حتى نهاية السلسلة). في هذا المثال، يقوم عامل التشغيل substr بإزالة الكل لكن السلسلة من الأحرف 10 إلى 15:

substr(${previous_question}, 10, 15)

عندما يكون الرقم الأول سالبًا، سيبدأ substr العد من نهاية السلسلة بدلاً من بدايتها. يعيد هذا المثال آخر خمسة أحرف فقط من الإجابة:

substr(${previous_question}, -5)

يمكنك استخدام معلمة calculationMode للتحكم في وقت حساب العمليات الحسابية في النموذج. لمزيد من المعلومات، راجع وضع الحساب.

يمكنك أيضًا استخدام عمود الحساب للوظائف المجمعة في التكرارات. للحصول على مزيد من المعلومات، راجع التكرارات.

التزم بأفضل الممارسات التالية عند استخدام العمليات الحسابية:

• عند استخدام random()، ضع في الاعتبار إضافة ثابت لتجنب الحصول على صفر (0) في صورة نتيجة، على سبيل المثال random()+0.5. قد ينتج عن قيمة 0 إجابة فارغة.
• كما هو الحال مع القيود، تأكد أن جميع القيم العشرية بين -1 و1 في الصيغة بها 0 بادئ إذ إن البدء بنقطة عشرية يسبب أخطاءً.
• يعتمد نوع البيانات الخاص بنتيجة العملية الحسابية على نوع البيانات الخاص بكل عنصر من العملية الحسابية. إذا تم تنفيذ عملية حسابية على عددين صحيحين، تكون نتيجة العملية الحسابية عدد صحيح. إذا كانت العملية الحسابية تتضمن نوع بيانات سلسلة، فقد تجد أن عامل + يسلسل القيم بدلاً من إضافتها. لتجنب النتائج غير المتوقعة، استخدم الوظيفة number() لضمان أن قيم السلسلة في العملية الحسابية يتم التعامل معها في صورة أرقام. على سبيل المثال، تساوي العملية الحسابية لإضافة question1 (من نوع العدد الصحيح) إلى question2 (من نوع النص) ${question1} + number(${question2}).

تلميح:

نوع الربط الافتراضي لـ XLSForm لسؤال الحساب هو string. لاستبدال هذا الإعداد الافتراضي، أدخل النوع المطلوب (على سبيل المثال، عدد صحيح أو عدد عشري) في عمود bind::type لسؤالك. أو يمكنك استخدام نوع السؤال المطلوب (على سبيل المثال، integer أو decimal) وتعيين مظهر هذا السؤال على مخفي.

تنبيه:

يؤدي استخدام الدوال أو العوامل الرياضية مع الأسئلة النصية إلى إرجاع نتيجة NaN في تطبيق الويب Survey123. لتسلسل الأسئلة النصية، استخدم دالة concat() بدلاً من العامل +.

وظائف الرياضيات المعقدة

يمكن أيضًا أن يقوم عمود الحساب بمعالجة المزيد من العمليات الرياضية المعقدة. يُحدد هذا المثال مساحة قطعة الأرض المتوفر نصف قطرها، باستخدام دوال pi و power:

pi() * pow(${plot_radius}, 2)

من الطرق الشائعة لقياس ارتفاع شجرة قياس الزاوية من مستوى العين عند نقطة مراقبة إلى أعلى الشجرة، والمسافة من نفس نقطة المراقبة إلى قاعدة الشجرة. إذا تم قياس الزاوية إلى أعلى الشجرة بالدرجات، فسيتم استخدام الحساب التالي لتحويلها إلى راديان:

${angle_to_top_degrees} * (pi() div 180)

مع قياس الزاوية الآن بالراديان، يمكن تحديد ارتفاع الشجرة (مقربًا إلى خانتين عشريتين) بالحساب التالي:

round(((tan(${angle_to_top_radians}) * ${distance_to_tree}) + ${height_to_eyes}),2)

تنسيق التاريخ

يمكنك استخدام الدالة format-date في حقل calculation لتنسيق قيم التاريخ والوقت. يمكن أن يكون هذا مفيدًا عندما ترغب في عرض أجزاء التواريخ للمستخدمين أو الاحتفاظ بها في صورة سلاسل.

في هذا المثال، القيمة المتضمنة في الوقت السابق أو سؤال dateTime يتم إرجاعها في توقيت 24 ساعة:

format-date(${previous_time},'%H:%M')

فيما يلي المؤهلات التي يمكن استخدامها في الدالة format-date:

المؤهل	الوصف
%3	0-علامات تجزئة ميلي ثانية (000-999)
%a	يوم نص قصير من ثلاثة أحرف
%b	اسم الشهر المختصر
%d	يوم من الشهر من 0
%e	يوم من الشهر
%h	ساعة (24-ساعة)
%H	0-ساعة (24-ساعة)
%m	شهر بـ 0 - تعبئة
%M	0 - دقيقة
%n	الشهر الرقمي
%S	0 - ثانية
%W	رقم الأسبوع ملاحظة:‏ لا يمكن استخدام مؤهل ٪W في دالة تنسيق التاريخ التي يستخدم فيها سؤال التاريخ عملية حسابية. يتعامل هذا المؤهل مع سؤال تاريخ له قيمة افتراضية.
%y	سنة من رقمين
%Y	سنة من 4 أرقام

ملاحظة:‏

اعلم أن أسئلة التاريخ والوقت لا تدعم دقة الوقت التي تقل عن دقيقة واحدة. لالتقاط دقة وقت بتواريخ أقل من دقيقة واحدة، ضع في اعتبارك استخدام أسئلة start و end.

قيم فارغة

عند استخدام القيود والعمليات الحسابية التي تشير إلى الأسئلة الأخرى، ضع في الاعتبار ما يحدث عندما يكون هذا السؤال فارغًا (بمعنى، أن لا يحتوي على استجابات). يتم تمثيل القيم الفارغة على النحو التالي:

• NaN (ليس رقم) للأعداد الصحيحة والأسئلة العشرية. هذه تعتبر قيمة خاصة تُمثل عدم وجود قيمة صحيحة.
• " (سلسلة فارغة) للأسئلة النصية. نوع البيانات الافتراضي لأسئلة select_one وselect_mulitple وأسئلة التصنيف والأسئلة المخفية يكون نصًا أيضًا. عندما تكون أنواع الأسئلة select_one وselect_multiple والأسئلة المخفية فارغة، أو عندما لا يغير المستخدم سؤال تصنيف، فإنها تحتوي على سلسلة فارغة.

بناءً على إذا ما كانت القيمة رقمًا أو نصًا، فإن السلوك في العملية الحسابية يختلف.

في أسئلة الأعداد الصحيحة أو العشرية، تحدث السلوكيات التالية:

• سيفشل اكتمال أي تعبير رياضي بقيمة NaN، وسيظل السؤال فارغًا.
• تكمل الدالتان min() وmax() أي قيم NaN وتتجاهلها.
• لن تكون قيمة NaN مقارنةً بأي قيمة أخرى صحيحة إلا في عملية حسابية لمقارنة قيمة is not equal. ستؤدي جميع التعبيرات الأخرى إلى نتيجة خاطئة.

في أسئلة الاختبار، تحدُث السلوكيات التالية:

• يكتمل تسلسل الأسئلة النصية إذا كانت القيم الفارغة موجودة. على سبيل المثال، سوف تؤدي concat("Hello" + ${firstName}, ", how are you?") إلى "Hello , how are you?" عندما يكون السؤال firstNAme فارغًا.
• تكمل الدالتان min() وmax() أي سلاسل فارغة وتتجاهلها.
• تكون إجابة نص فارغ مساوي لإجابة نص فارغ أخر وتكون دائمًا أقل من أي نص غير فارغ.

يمكنك تحديد ما إذا كان السؤال فارغًا باستخدام دالة string-length. يمكن استخدام دالة string-length مع جميع أنواع الأسئلة. على سبيل المثال، يُرجع string-length(${Question1}) القيمة 0 إذا كان Question1 فارغًا.

يمكنك تحديد ما إذا كان سؤال select_one أو select_multiple فارغًا باستخدام دالة count-selected. على سبيل المثال، يُرجع count-selected(${question2}) القيمة 0 إذا لم يتم أي تحديد لـ question2.

أسئلة Select_multiple وأسئلة التصنيف

يتم تخزين الإجابات عن أنواع أسئلة select_multiple وأسئلة التصنيف بشكل مختلف عن جميع أنواع الأسئلة الأخرى. يتم إدخال كل إجابة تم التأشير عليها في سؤال select_multiple بالترتيب المحدد، مفصولة بفواصل. على سبيل المثال، يمثل تحديد الإجابتين "أ" و"ب" في ذلك الترتيب الإجابة في صورة "أ،ب". يخزن سؤال التصنيف أيضًا إجاباته في قائمة مفصولة بفواصل، بالترتيب من الأعلى إلى الأدنى في وقت الإرسال.

لن تعمل بعض معالم XLSForm مع أسئلة select_multiple وأسئلة التصنيف. على سبيل المثال، إذا قمت بإدخال الإجابة 'A' في العمود ذي الصلة لسؤال يشير إلى سؤال select_multiple، تكون استجابة الاستطلاع هي 'A,B'، ولن تعتبر الاستجابة ذات صلة. في هذه الحالة، فإن الحل هو استخدام دالة selected() والتي ستقرر ما إذا كانت أي قيمة من القيم تظهر في القائمة.

سوف يعرض التعبير التالي، عند استخدام العمود ذي الصلة من الأسئلة، السؤال إذا قام المستخدم بتحديد 'A' كأحد الاستجابات في السؤال select_multiple المشار إليه. لا تغير الإجابات الإضافية في سؤال select_multiple هذا السلوك.

selected(${previous_question}, 'A')

استرداد قيمة من ملف CSV

يمكنك استخدام دالة pulldata() في عمود الحساب الخاص بالسؤال لتحميل البيانات مسبقًا من ملف .csv. توجد طريقتان لتضمين ملف .csv: وضع الملف يدويًا في مجلد media الخاص بالاستطلاع أو الربط بملف .csv مستضاف في ArcGIS.

تتطلب دالة pulldata() المعلمات الأربع التالية ليتم تحديدها، من أجل:

1. اسم ملف .csv الذي يحتوي على قائمة القيم. لا يتضمن الاسم لاحقة اسم الملف .csv.
2. اسم العمود في ملف .csv الذي يحتوي على القيمة التي ترغب في إرجاعها.
3. اسم الحقل الرئيسي في ملف .csv الذي ستستخدمه للبحث عن القيمة.
4. القيمة الأساسية للبحث عنها في الحقل الرئيسي.

يمكن تعريف هذه القيم مباشرةً أو من خلال متغيرات تم تعريفها في مكام أخر داخل الاستطلاع. في المثال التالي، تُرجع العملية الحسابية عنوان البريد الإلكتروني لشخص ما مذكور في سؤال سابق من معلومات محددة لملف .csv:

pulldata('info', 'email', 'name', ${respondent_name})

تعمل أيضًا دالة pulldata() نفسها في عمود القيود، مما يمنع المستخدم من إرسال إجابات ليست موجودة في ملف .csv. في عمود القيود، سوف تمنع هذه الصيغة نفسها النموذج من قبول أي قيم ليست موجودة في عمود اسم ملف .csv.

يوجد بعض القيود على دالة pulldata(). يحتوي اسم الحقل الرئيسي على نفس القيود مثل عمود الاسم الموجود في جدول بيانات الاختيارات، مما يعني أن تلك القيم لا يمكن أن يكون لديها مسافات أو أحرف غير ASCII. بالإضافة إلى ذلك، ولأن هذه الملفات من نوع .csv، يؤدي استخدام فاصلة في أي من تلك الحقول إلى تقديم دالة pulldata() نتائج غير صحيحة.

إذا تجاوزت القيم في ملف .csv 255 حرفًا، يجب عليك إدخال قيمة أعلى في عمود bind::esri:fieldLength للسؤال الذي تقوم بتعبئته بمحتوى .csv وأي أسئلة يجري استخدامها كإدخالات لدالة pulldata(). إذا اشتمل ملف .csv على قيم تتجاوز أقصى طول في أحد هذه الحقول، فستفشل استجابة الاستطلاع في الإرسال وستعرض خطأ "رمز 1000".

ملاحظة:‏

يتعذر استخدام دالة pulldata() لملء قيم أسئلة select_multiple.

عند استخدام الدالة pulldata()، لا يمكن ترك أسماء عمود .csv فارغة ولا يمكن تضمين مسافات أو واصلات أو رموز خاصة أخرى.

يوصى بترميز ملف .csv باستخدام ترميز أحرف UTF-8. إذا كنت تستخدم Microsoft Excel لإنشاء ملف .csv الخاص بك، فاحفظه في صورة CSV UTF-8.

استرداد قيمة من JSON

يمكنك استخدام دالة pulldata("@json") لاستخراج الخصائص الفردية من كائن JSON. تُستخدم هذه الدالة عادةً للتكامل مع الدوال الأخرى، مثل pulldata("@javascript") وpulldata("@layer"). تتضمن الدالة بناء الجملة التالي:

pulldata("@json", <question name>, "<JSON property>")

تكون معلمات pulldata("@json") كما يلي:

• question name—اسم السؤال الذي يحتوي على كائن JSON، على سبيل المثال: ${json_response}.
• JSON property—الخاصية التي ترغب في استردادها من JSON. استخدم النقاط لتحديد موقع الخاصية في بنية كائن JSON. على سبيل المثال، لاسترداد خاصية City من كائن address، استخدم "address.City".

في المثال التالي، يتم إرجاع نتيجة عملية التكويد الجغرافي العكسي في صورة JSON في سؤال نصي يسمى json_response:

يتم إرجاع استجابة من محدد المواقع مشابهة لما يلي:

{
	"address": {
		"Match_addr": "Eiffel Tower",
		"LongLabel": "Eiffel Tower, Paris, Île-de-France, FRA",
		"ShortLabel": "Eiffel Tower",
		"Addr_type": "POI",
		"Type": "Historical Monument",
		"PlaceName": "Eiffel Tower",
		"AddNum": "",
		"Address": "",
		"Block": "",
		"Sector": "",
		"Neighborhood": "Paris 07",
		"District": "Paris",
		"City": "Paris",
		"MetroArea": "",
		"Subregion": "Paris",
		"Region": "Île-de-France",
		"RegionAbbr": "",
		"Territory": "",
		"Postal": "",
		"PostalExt": "",
		"CntryName": "France",
		"CountryCode": "FRA"
	},
	"location": {
		"x": 2.294520000000034,
		"y": 48.85832000000005,
		"spatialReference": {
			"wkid": 4326,
			"latestWkid": 4326
		}
	}
}

تُستخدم دالة pulldata("@json") لاسترداد خاصية City من كائن address:

pulldata("@json", ${json_response}, "address.City")

يتم استرداد خط العرض وخط الطول من كائن location:

pulldata("@json", ${json_response}, "location.x")

pulldata("@json", ${json_response}, "location.y")

ملاحظة:‏

يتم استخدام الفترة للوصول إلى الخصائص الفردية لكائن رئيسي. عندما تشكل الفترة أيضًا جزءًا من خاصية، يجب وضعها بين قوسين مربعين [ ]. على سبيل المثال، لاسترداد خاصية باسم City.Population من كائن address، سيكون التعبير pulldata("@json", ${json_response}, "address.[City.Population]").

الاستعلام عن طبقة معالم

يمكنك استخدام دالة pulldata("@layer") للاستعلام عن طبقة المعالم أو جدول المعالم أو الاستعلام عن خدمة الخريطة الممكنة. يمكنك إجراء استعلام عن البيانات الجدولية أو استعلام مكاني. يستخدم الاستعلام عن البيانات الجدولية عملية getRecord أو getValue:

pulldata("@layer", "getRecord", "<URL>", "<WHERE clause>")
pulldata("@layer", "getValue", "<JSON property>", "<URL>", "<WHERE clause>")

يستخدم الاستعلام المكاني عملية getRecordAt أو getValueAt:

pulldata("@layer", "getRecordAt", "<URL>", <location>, "<WHERE clause>")
pulldata("@layer", "getValueAt", "<JSON property>", "<URL>", <location>, "<WHERE clause>")

تُرجع عمليات getRecord وgetRecordAt كائن معلم JSON يتضمن معلمًا فرديًا وجميع بياناته الجدولية. تُرجع عمليات getValue وgetValueAt قيمة فردية من كائن المعلم، بدلاً من الاستجابة الكاملة للاستعلام.

تكون معلمات pulldata("@layer") كما يلي:

المعلمة	الوصف
JSON property	مطلوب لعمليات getValue وgetValueAt. القيمة التي ترغب في استردادها من استجابة الاستعلام. مثال: "attributes.COUNTRY"
location	مطلوب لعمليات getRecordAt وgetValueAt. موقع النقطة الذي ترغب في الاستعلام عنه باستخدام طبقة المعالم. يلزم أن يكون هذا سؤال نقطة جغرافية. مثال: ${location}
URL	مطلوب. عنوان URL الخاص بطبقة المعالم أو الجدول الذي ترغب في الاستعلام عنه. تقبل هذه المعلمة معلمات طلب إضافية. مثال: "https://services.arcgis.com/P3ePLMYs2RVChkJx/ArcGIS/rest/services/World_Countries/FeatureServer/0"
WHERE clause	اختياري. تعبير أين الذي يعمل على تصفية طبقة المعالم أو الجدول. عندما لا يتم توفير عبارة أين، يتم استخدام "1=1" الافتراضي. مثال: "COUNTRY='Canada'"

تلميح:

تُرجع دالة pulldata("@layer") السجل الأول في استجابة الاستعلام. صمم استعلامك واختبره لضمان حصولك على الإجابات المرغوب فيها. يمكنك تحسين استعلامك باستخدام عبارة أين ومعلمات الطلب الإضافية الموضحة بالأسفل.

تقوم دالة pulldata("@layer") بتخزين استجابات الاستعلام مؤقتًا لتحقيق الكفاءة. للتغلب على ذاكرة التخزين المؤقت والتأكد من تقديم طلب جديد في كل مرة يتم فيها تشغيل الدالة، قم بإضافة معلمة time=now إلى عنوان URL - على سبيل المثال، concat(${layer_url}, "?t=", now()).

يستعلم المثال التالي عن طبقة معلم مضلع للمناطق الزمنية العالمية ويُرجع المنطقة الزمنية التي تقع فيها النقطة الجغرافية:

تُستخدم عملية getRecordAt لاسترداد المنطقة الزمنية التي تتقاطع فيها النقطة الجغرافية باستخدام بناء الجملة التالي:

pulldata("@layer", "getRecordAt", "https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/World_Time_Zones/FeatureServer/0", ${location})

تُستخرج بعد ذلك البيانات الجدولية ZONE من استجابة الاستعلام باستخدام دالة pulldata("@json"). بدلاً من ذلك، يمكنك استخدام عملية getValueAt في العملية الحسابية pulldata("@layer") لاسترداد البيانات الجدولية ZONE مباشرةً، دون الحاجة إلى سؤال منفصل لتخزين استجابة الاستعلام. راجع الأمثلة التالية:

pulldata("@layer", "getValueAt", "attributes.ZONE", "https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/World_Time_Zones/FeatureServer/0", ${location})

يمكنك استخدام pulldata("@layer") في القيود. على سبيل المثال، يمكنك تطبيق أحد الحدود على سؤال النقطة الجغرافية لمنع المستخدمين من إرسال المواقع التي تكون خارج منطقة الاهتمام.

تُرجع العملية getRecordAt كائن معلم JSON الخاص بالدولة التي تقع فيها النقطة الجغرافية، باستخدام بناء الجملة التالي:

pulldata("@layer", "getRecordAt", "https://services.arcgis.com/P3ePLMYs2RVChkJx/ArcGIS/rest/services/World_Countries/FeatureServer/0", ${location}, "COUNTRY='Canada'")

يُستخرج اسم الدولة في سؤال نصي باستخدام pulldata("@json"). ينطبق القيد ${country}='Canada' بعد ذلك على سؤال النقطة لضمان وجود الموقع في نطاق منطقة كندا.

معلمات الطلبات

يمكنك تحسين استعلام pulldata("@layer") باستخدام معلمات طلب إضافية، مثل distance وorderByFields وresultOffset. للحصول على مزيد من المعلومات عن معلمات الطلب، راجع موضوع الاستعلام (خدمة المعالم/طبقة). تدعم دالة pulldata("@layer") فقط الطلبات التي تُرجع كائن معلم.

لتضمين هذه المعلمات في استعلام، ألحقها بعنوان URL بعد علامة الاستفهام. تُفصل المعلمات الإضافية بواسطة علامات العطف. في المثال التالي، تجد معلمات orderByFields وresultOffset ملحقة بعنوان URL الخاص بطبقة المعالم لإرجاع اسم عاشر مقاطعة مكتظة بالسكان في كاليفورنيا:

pulldata("@layer", "getValue", "attributes.NAME", "https://services5.arcgis.com/jMCHJcLe13FaKCFB/arcgis/rest/services/US_Counties/FeatureServer/1?orderByFields=POPULATION DESC&resultOffset=9", "STATE_NAME = 'California'")

يمكن استخدام الاستعلام المجمع لإرجاع الإحصائيات على طبقة المعالم باستخدام معلمة outStatistics. تتضمن الإحصائيات التي يمكن حسابها باستخدام هذه المعلمة العدد أو المجموع أو الحد الأدنى أو الحد الأقصى أو المتوسط أو الانحراف المعياري أو التباين.

في المثال التالي، يتم إرجاع عدد المقاطعات في الولاية المحددة:

pulldata("@layer", "getValue", "attributes.TotalCount", concat("https://services5.arcgis.com/jMCHJcLe13FaKCFB/arcgis/rest/services/US_Counties/FeatureServer/1", '?outStatistics=[{"statisticType": "count","onStatisticField": "objectId","outStatisticFieldName": "TotalCount"}]'), concat("STATE_NAME = '", ${state_name}, "'"))

في المثال التالي، يتم إرجاع مجموع حقل السكان لجميع المقاطعات في الولاية المحددة:

pulldata("@layer", "getValue", "attributes.TotalPopulation", concat("https://services5.arcgis.com/jMCHJcLe13FaKCFB/arcgis/rest/services/US_Counties/FeatureServer/1", '?outStatistics=[{"statisticType": "sum","onStatisticField": "POPULATION","outStatisticFieldName": "TotalPopulation"}]'), concat("STATE_NAME = '", ${state_name}, "'"))

ملاحظة:‏

تدعم دالة pulldata("@layer") جميع معلمات الطلب المدرجة في الاستعلام (خدمة/طبقة المعلم) باستثناء ما يلي:

• f
• outFields
• outSR
• resultRecordCount
• returnCountOnly
• returnGeometry
• returnIDsOnly
• token