كيفية تمييز الحقول النصية الفارغة في النماذج باستخدام نص إرشادي معيّن عبر ماكرو في “ONLYOFFICE”

تُعد نماذج “ONLYOFFICE” أداة فعالة لجمع البيانات المنظمة، لكن الحقول النصية غير الإلزامية قد تُترك فارغة دون ملاحظة. في هذه التدوينة، نعرض كيفية إنشاء ماكرو يتيح لكم تمييز هذه الحقول تلقائيًا، سواء كانت جميع الحقول الفارغة أو فقط تلك التي تحتوي على نص إرشادي معين.

إنشاء الماكرو

1. الحصول على بيانات النموذج والكائنات الحية الخاصة به

يبدأ الماكرو بالوصول إلى المستند النشط باستخدام ‎Api.GetDocument()‎. ومن ثم نستخرج مجموعتين من البيانات:

•  بيانات النماذج: باستخدام ‎doc.GetFormsData()‎، نحصل على تمثيل بصيغة “JSON” لجميع الحقول في النموذج، متضمنًا خصائص مثل: المفتاح، النوع، القيمة، النص الإرشادي، وما إذا كان الحقل إلزاميًا.
•  الكائنات الحية للنموذج: نستخدم ‎doc.GetAllForms()‎ لاستخراج الكائنات الحية المقابلة لتلك الحقول.

    var doc = Api.GetDocument();
    var forms = doc.GetAllForms();
    var formsData = JSON.parse(JSON.stringify(doc.GetFormsData()));

2. التحقق الاختياري بناءً على النص الإرشادي

في بعض الحالات، قد تحتاجون إلى التحقق فقط من الحقول الفارغة التي تحتوي على نص إرشادي معيّن. يتيح لكم هذا الماكرو تفعيل هذه الميزة أو تعطيلها من خلال المتغيّر ‎checkSpecificTip‎. فعلى سبيل المثال، يمكنكم تمييز الحقول التي يظهر فيها النص الإرشادي: «يرجى إدخال العنوان الثاني».

   // Optional: set to true to check only fields with a specific tip text.
    var checkSpecificTip = false;
    var requiredTipText = "Please enter your second address"; // Change this as needed.

3. المرور على كل حقل في النموذج

ينتقل الماكرو بعد ذلك عبر جميع الحقول داخل بيانات “JSON”. نركز فقط على الحقول النصية (حيث يكون النوع “text”). وبالنسبة لكل حقل نصي غير إلزامي، يتم التحقق مما إذا كانت قيمته فارغة.

 forms.forEach(function(form) {
        if (form.GetFormType() === "textForm") {
            var key = form.GetFormKey();
            var required = form.IsRequired()
            // Find corresponding form data by key.
            var formData = formsData.find(function(fd) {
                return fd.key === key;
            });
            if (formData) {
                // A field is considered empty if its value is missing or only whitespace.
                var isEmpty = !formData.value || formData.value.trim() === "";
                // Use the live form's GetTip() to get the tip (if available).
                var tip = form.GetTipText() ? form.GetTipText() : "";
                
                var shouldCheck = !checkSpecificTip || (checkSpecificTip && tip.trim() === requiredTipText.trim());


                if (shouldCheck && isEmpty && !required) {
                    form.SetBorderColor(0,255,127); // spring green border.
                    form.SetBackgroundColor(171, 242, 255); // Light blue background.
                    invalidCount++;
                }
            }
        }

•  التحقق من القيمة:
  يُعتبر الحقل فارغًا إذا كانت خاصية ‎”value”‎ غير موجودة أو تحتوي فقط على فراغات.

•  التحقق بناءً على النص الإرشادي:
  إذا كان ‎checkSpecificTip‎ مفعّلاً، فسيتم التحقق فقط من الحقول التي يتطابق نصها الإرشادي مع ‎requiredTipText‎.
•  تمييز الحقول:
  بالنسبة للحقول التي تنطبق عليها المعايير، يتم تحديد الكائن الحي المطابق لها (بناءً على المفتاح) وتطبيق حد بلون أخضر ربيعي وخلفية بلون أزرق فاتح.

4. تسجيل النتائج

في النهاية، يقوم الماكرو بتسجيل عدد الحقول النصية غير الإلزامية الفارغة التي تم تمييزها.

console.log("Form Field Validator complete. " + invalidCount + " empty unrequired text field(s) highlighted.");

الكود الكامل للماكرو

(function () {
    // Optional: set to true to check only fields with a specific tip text.
    var checkSpecificTip = false;
    var requiredTipText = "Please enter your second address"; // Change this as needed.


    var doc = Api.GetDocument();
    var forms = doc.GetAllForms();
    var formsData = JSON.parse(JSON.stringify(doc.GetFormsData()));
    var invalidCount = 0;



    forms.forEach(function(form) {
        if (form.GetFormType() === "textForm") {
            var key = form.GetFormKey();
            var required = form.IsRequired()
            // Find corresponding form data by key.
            var formData = formsData.find(function(fd) {
                return fd.key === key;
            });
            if (formData) {
                // A field is considered empty if its value is missing or only whitespace.
                var isEmpty = !formData.value || formData.value.trim() === "";
                // Use the live form's GetTip() to get the tip (if available).
                var tip = form.GetTipText() ? form.GetTipText() : "";
                
                var shouldCheck = !checkSpecificTip || (checkSpecificTip && tip.trim() === requiredTipText.trim());


                if (shouldCheck && isEmpty && !required) {
                    form.SetBorderColor(0,255,127); // spring green border.
                    form.SetBackgroundColor(171, 242, 255); // Light blue background.
                    invalidCount++;
                }
            }
        }
    });
    console.log("Form Field Validator complete. " + invalidCount + " empty unrequired text field(s) highlighted.");
})();

والآن، دعونا نشغّل الماكرو ونرى كيف يعمل!

هذا الماكرو يكتشف تلقائيًا الحقول النصية الفارغة التي تحتوي على نص إرشادي محدد ويقوم بتمييزها، ما يساعدكم على توفير الوقت وتقليل المهام المتكررة. نأمل أن يكون مفيدًا في تحسين نماذجكم على “ONLYOFFICE” وزيادة كفاءة سير العمل بشكل عام.

لا تترددوا في استكشاف المزيد من إمكانيات واجهة “ONLYOFFICE” البرمجية لتطوير مهامكم المكتبية بشكل أسرع وأكثر ذكاء. وإذا كانت لديكم أفكار أو أسئلة أو اقتراحات لماكروهات مستقبلية، يسعدنا التواصل معكم وسماع آرائكم.

حول الكاتب