JavaScript دوال في نماذج الاستطلاع

يمكنك استخدام دالة pulldata("@javascript") لاستدعاء دوال JavaScript، مما يتيح لك استخدام تقنيات ومنطق متقدم يتجاوز ما هو ممكن من خلال XLSForm وحده.

يمكنك إدارة وتحرير دوال JavaScript في علامة تبويب البرامج النصية في Survey123 Connect. في علامة التبويب هذه، يمكنك إنشاء ملف JavaScript ومراجعة الرمز واختبار الدالة. علامة التبويب هذه ليست بديلاً كاملاً لبيئة التطوير المتكاملة (IDE)، والتي يمكن أن توفر التحقق من صحة التعليمات البرمجية وتحليل أفضل الممارسات للمساعدة في تطوير دوال JavaScript، ولكنها مصممة للمساعدة في تكامل هذه الدوال في Survey123.

أدوات البرنامج النصي هي Survey123 Connect

تتوفر الأدوات التالية في القائمة الموجودة في علامة التبويب البرامج النصية في Survey123 Connect:

• ملفات البرامج النصية - إظهار كافة ملفات JavaScript الموجودة في مجلد Scripts للاستطلاع. حدد ملفًا لعرضه وتحريره.
• فتح مجلد البرامج النصية - قم بتشغيل مستعرض الملفات في موقع مجلد Scripts للاستطلاع.
• ملف نصي جديد - أنشئ ملفًا نصيًا في مجلد Scripts للاستطلاع. اكتب اسم الملف وانقر فوق إنشاء.
• تحديد الدالة — قم بتمييز الدالة الأولى في الملف المفتوح وتقديم المعلمات للاختبار.
• حفظ — حفظ التغييرات على الملف المفتوح.
• بدء تشغيل المحرر الخارجي—قم بتشغيل JavaScript IDE الافتراضي للأنظمة بالملف المفتوح.

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

ملاحظة:‏

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

بناء الجملة الأساسية

يمكنك استدعاء دوال JavaScript مخصصة لإعادة القيم. استخدم بناء الجملة التالية لاستدعاء دوال JavaScript مخصصة باستخدام دالة pulldata("@javascript").

pulldata("@javascript", "yourJSFile.js", "yourFunction", "parameter1", "parameter2")

يجب عليك تخزين ملفات JavaScript المخصصة في مجلد يسمى البرامج النصية في دليل الاستطلاع. في المثال أعلاه، تتوقع الدالة JavaScript معلمتين، ولكن يمكنك إضافة أي عدد من معلمات الدوال.

يمكنك أيضًا استخدام دالة pulldata("@json") لاستخراج قيم محددة من كائن JSON الذي تنتجه دالة JavaScript. للحصول على مزيد من المعلومات، راجع استرداد قيمة من JSON.

في بعض الأحيان، خاصة عند استخدام JavaScript للوصول إلى خدمات الويب وخدمات ArcGIS الآمنة، قد يتعين عليك الوصول إلى خصائص الجهاز والمستخدم. يمكنك استخدام دالة pulldata("@property") لاستخراج معلومات عن الأجهزة التي تُرسل من خلالها إجابات الاستطلاع، والمستخدمين الذين سجلوا الدخول والذين أرسلوا هذه الإجابات. للحصول على مزيد من المعلومات، راجع الجهاز وخصائص المستخدم.

تلميح:

للاستعلامات المكانية والمتعلقة بالبيانات الجدولية في طبقات معالم ArcGIS، فكر في استخدام الدالة pulldata("@layer") بدلاً من pulldata("@javascript"). صُمم بناء الجملة pulldata("@layer") خصوصًا لاستعلامات طبقة المعالم وهو مدعوم للاستطلاعات العامة. لمزيد من المعلومات، راجع الاستعلام عن طبقة معالم.

تكرار

يمكنك تمرير جميع القيم عبر تكرار إلى دوال JavaScript. تدعم دالة pulldata("@javascript") نمطين من التنفيذ لاسترداد القيم من تكرار. يعتمد الخيار الذي يجب استخدامه على ما إذا كنت تريد أن تتفاعل دالة JavaScript مع حقل واحد أو العديد من الحقول في التكرار.

إذا تم تمرير سؤال من تكرار كمعامل دالة، فإن دالة JavaScript تتلقى مصفوفة من القيم من السؤال المحدد على النحو التالي:

pulldata("@javascript", "yourJSFile.js", "yourFunction", ${question1})

إذا تم تمرير اسم متكرر كمعامل دالة، فستتلقى دالة JavaScript المعلمة كمصفوفة من صفوف جميع القيم في التكرار على النحو التالي:

pulldata("@javascript", "yourJSFile.js", "yourFunction", ${repeat1}, "question1")

ينتج كل منها كائن JSON مع أسئلة فردية كخصائص في ذلك الكائن.

ملاحظة:‏

الوصول إلى القيم في عمليات التكرار باستخدام pulldata("@javascript") غير مدعوم في تطبيق Survey123 على الويب. يمكنك جمع القيم لكل سؤال على حدة بشكل متكرر في تطبيق الويب باستخدام join() لتحويل قائمة القيم إلى سلسلة منفصلة الرموز ثم اقسم القيم في دالة JavaScript.

اعتبارًا من الإصدار 3.14 لتطبيق Survey123، يمكن الآن للقيم الفارغة التي تم تمريرها عبر دالة JavaScript إرجاع إما undefined أو null. لهذا السبب، يجب عليك كتابة دوال JavaScript لحساب إمكانية وجود قيمة undefined.

القيود المعروفة

فيما يلي القيود المعروفة عند استخدام دوال JavaScript في نماذج الاستطلاع:

• نموذج كائن المستند (DOM) غير مدعوم.
• الأطر مثل JQuery وEmber وAngular غير مدعومة.
• لا يمكنك الوصول إلى الملفات المحلية.
• لا يتم دعم المكالمات غير المتزامنة.
• يتم دعم دوال JavaScript فقط في النماذج التي يكملها المستخدمون في نفس المؤسسة مثل مؤلف النموذج.
• دوال JavaScript غير مدعومة للاستطلاعات العامة.
• لا يمكن استدعاء دالة pulldata("@javascript") داخل دالة pulldata("@json") في تطبيق الويب Survey123.