حدث Form OnSave (مرجع واجهة برمجة تطبيقات العميل) في التطبيقات المستندة إلى النموذج

يتيح لك حدث النموذج OnSave في التطبيقات المستندة إلى النموذج تشغيل المنطق أو التحقق من صحة البيانات أو إلغاء حفظ قبل حفظ السجل. OnSave يحدث الحدث عندما:

• يحدد المستخدم الزر حفظ أو تحديث في شريط الأوامر، حتى في حالة عدم وجود بيانات تم تغييرها للحفظ.
• تنفذ التعليمات البرمجية طريقة formContext.data.entity.save ، حتى في حالة عدم وجود بيانات متغيرة لحفظها.
• ينتقل المستخدم بعيدا عن النموذج وهناك بيانات غير محفوظة في النموذج.
• يتم تمكين خيار الحفظ التلقائي، بعد 30 ثانية من تغيير البيانات، وهناك بيانات غير محفوظة في النموذج.
• تنفذ التعليمات البرمجية طريقة formContext.data.save وهناك بيانات غير محفوظة في النموذج.
• تنفذ التعليمات البرمجية طريقة formContext.data.refresh التي تمرر قيمة حقيقية كمعلمة أولى وهناك بيانات غير محفوظة في النموذج.

Note

OnSave يلغي الحدث الخاص بسجلات المواعيد أو المواعيد المتكررة أو نشاط الخدمة عملية الحفظ ويستخدم Book الرسالة لحفظ التغيير بدلا من Create أو Update. وبسبب هذا السلوك، OnSavePostSave لا تعمل معالجات الأحداث لهذه الجداول.

لتحديد الزر الذي تم النقر فوقه لتنفيذ الحفظ، استخدم أسلوب getSaveMode .

يمكنك إلغاء إجراء الحفظ باستخدام الأسلوب preventDefault داخل كائن وسيطات الحدث. preventDefault يمكن الوصول إلى الأسلوب باستخدام أسلوب getEventArgs الذي يعد جزءا من سياق التنفيذ. يتم تمرير سياق التنفيذ تلقائيا إلى معالج أحداث النموذج.

دعم معالج الأحداث غير المتزامن

الحدث OnSave لديه القدرة على انتظار الوعود التي تم إرجاعها بواسطة معالجات الأحداث للتسوية قبل الحفظ، ما OnSave يسمح للحدث أن يكون غير متزامن ("غير متزامن").

OnSave يصبح الحدث غير متزامن عندما OnSave يقوم معالج الحدث بإرجاع وعد. يحدث حفظ السجل عند حل كل وعد يتم إرجاعه بواسطة معالج. بالنسبة لأي وعود يتم إرجاعها، هناك حد 10 ثوان لكل وعد، بعد ذلك تعتبر المنصة أن الوعود قد انتهت. يتم تطبيق هذه المهلة لكل وعد. على سبيل المثال، إذا تم إرجاع خمسة وعود، فإن إجمالي وقت الانتظار هو 50 ثانية.

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

يمكنك أيضا إلغاء عملية الحفظ بغض النظر عن الخطأ في المعالج أو عدم استخدام الأسلوب preventDefault داخل كائن وسيطات الحدث. إذا تم استدعاء هذا الأسلوب، ينتظر الحدث Async OnSave جميع الوعود للتسوية، ولكن لن يحدث الحفظ. استدعاء هذا الأسلوب يعني أن المنطق داخل .then() سيتم .catch() تنفيذه.

OnSave ينتظر الحدث وعدا واحدا تم إرجاعه لكل معالج. إذا كانت هناك حاجة إلى وعود متعددة، فمن المستحسن التفاف جميع الوعود في Promise.all() الأسلوب وإرجاع الوعد الناتج الوحيد. بالنسبة لمعالجات متعددة تقوم جميعها بإرجاع وعد، نوصيك بإنشاء معالج واحد يستدعي جميع الأحداث وإرجاع وعد واحد يختتم جميع الوعود المطلوبة. هذه الممارسة هي تقليل أوقات الانتظار الناتجة عن المهلة.

مثال: متى تستخدم معالجات OnSave غير المتزامنة

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

في هذا السيناريو، نظرا لوجود عمليات متعددة غير متزامنة ويعيد كلا الاستدعاءين وعدا واحدا، قم بتضمين كليهما في Promise.all() الأسلوب .

Note

يمكنك استخدام الأسلوب فقط preventDefault بشكل متزامن.

على سبيل المثال:

 function myHandler() {
    return Promise.all([getWorkOrderPromise, getCustomerAssetPromise]).then((values) => {
        var workOrder = values[0];
        var customerAsset = values[1];
        // Perform validation
        if (isValid(workOrder, customerAsset)) {
            return Promise.resolve();
        }
        return Promise.reject(new Error("Validation failed for the work order and customer asset"));
   });
 }

تمكين معالجات OnSave غير المتزامنة باستخدام إعداد تطبيق

لاستخدام معالجات غير متزامنة على حفظ، قم بتشغيل الميزة من خلال إعداد تطبيق:

1. انتقل إلى https://make.powerapps.com.

2. تأكد من تحديد البيئة الصحيحة.

3. من جزء التنقل الأيسر، حدد التطبيقات.

4. حدد التطبيق، وحدد ... (علامات الحذف)، ثم حدد تحرير.

5. حدد الإعدادات من شريط الأوامر.

6. عند فتح مربع الحوار، حدد الميزات.

7. قم بتشغيل معالج Async onSave.

8. حدد حفظ.

   

تعطيل مهلات معالج OnSave غير المتزامن

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

هناك سيناريوهات حيث يلزم إيقاف OnSave المعالج مؤقتا لأكثر من 10 ثوان. مثال على ذلك هو فتح مربع حوار وانتظار إدخال المستخدم قبل متابعة الحفظ. للتأكد من أن العملية غير المتزامنة تنتظر الوعد بالحل، استخدم أسلوب disableAsyncTimeout .

Note

يجب عليك الاتصال disableAsyncTimeout قبل أي عبارات انتظار أو مكالمات غير متزامنة.

على سبيل المثال:

async function myHandler(context) {  
     context.getEventArgs().disableAsyncTimeout();
     // The 10000ms time out will not be disabled if the above line does not come before all async awaits
     await Xrm.Navigation.openConfirmDialog({ text: "Are you sure you want to save?" });
 }

عند استدعاء disableAsyncTimeout، لا يتم تطبيق مهلة هذا المعالج. فإنه لا يزال ينتظر حتى يتم الوفاء بوعد هذا المعالج.

يمكن أن يؤثر هذا النمط على أداء حفظ النموذج.

المقالات ذات الصلة

حدث حفظ الشبكة
الأحداث (مرجع واجهة برمجة تطبيقات العميل)
الأحداث في النماذج والشبكات في التطبيقات التي تستند إلى النموذج