كائنَات السيَاق

مكتمل

عند إنشَاء معَالجَات الأحدَاث و‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫استخدَام واجهة برمجة تطبيقَات البرمجة النصية للعميل، يجب عليك فهم كائنَات السيَاق المتَاحة وكيفية ‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫استخدَامهَا. الغَرض مِن كائنَات السيَاق هو تزويدك بمعلومَات حول السيَاق الذي يتم فيه تنفيذ التعليمَات البرمجية الخَاصة بك. يضمن هَذا السيَاق أنك لن تضطر إلى ترميز المَعلومَات فِي المنطق الخَاص بك. يتيح لك السيَاق إنشَاء وظَائف أكثر عمومية ويجعل وظَائفك أقل حسَاسية لبنية التخطيط المحددة لمكونَات واجهة ‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫المُستَخدِم التي تعمل معهَا.

سيَاق التنفيذ

عند تسجيل معَالج الأحدَاث، يمكنك الحصول عَلى سيَاق التنفيذ الذي تم تمريره كمَعلمة أولى. عند تسجيل معَالج الأحدَاث با‏‫‏‫‏‫‫‏‫‏ستخدَام خصَائص النموذج، يكون هَذا هو الخيَار الذي يمكنك تمكينه. تعرض الصورة تسجيل معَالج OnLoad وتمكين سيَاق التنفيذ.

عَادةً مَا تكون فكرة جيدة أن يكون هَذا الخيَار محددًا دَائمًا عِندَ تسجيل معَالج الأحدَاث با‏‫‏‫‏‫‫‏‫‏ستخدَام خصَائص النموذج. عندمَا تقوم بتسجيل معَالج حدث با‏‫‏‫‏‫‫‏‫‏ستخدَام التعليمَات البرمجية، يتم تحديد هَذا الخيَار تلقَائيًا.

تعريف وظيفتك الذي يأخذ سيَاق التنفيذ كمَعلمة أولى سيبدو كمَا يلي:

الا‏‫‏‫‏‫‫‏‫‏ستخدَام الأكثر شيوعًا لسيَاق التنفيذ هو استردَاد سيَاقَات النموذج والشبكة. طريقة أخرى مفيدة فِي هَذا السيَاق هي getEventSource. يقوم مصدر الحدث بإرجَاع مرجع إلى الكائن الذي تم تشغيل الحدث فيه. يسمح لك هَذا الكائن بكتَابة معَالجَات عَامة تستجوب مصدر الحدث فِي وقت التشغيل لمعرفة عنصر التحكم الذي تم تشغيل الحدث فيه. يمكن أن يكون هَذا الكائن مفيدًا عندمَا تريد كتَابة طريقة واحدة يمكن تسجيلهَا فِي الأحدَاث عَلى عنَاصر تحكم متعددة، بدلاً مِن إنشَاء معَالج حدث منفصل لكل عنصر تحكم. عَلى سَبيل المِثَال، إذَا كان لدَيك حَدث OnChange لحُقُولٍ مُتعددةٍ، فيمكنُك استخدَام getEventSource لتَحدِيدِ الحَقل الذي قَامَ بتَشغِيل الحَدث واستِخدَامه وفقًا لذلك.

سيَاق النموذج

يشير سيَاق نموذج Client API (formContext) إلى النموذج أو العنصر الموجود فِي النموذج، مثل عنصر تحكم طريقة العرض السريعة أو صف فِي شبكة قَابلة للتحرير، والتي يتم تشغيل التعليمَات البرمجية الحَالية عليهَا. يمكنك استردَاد كائن formContext مِن سيَاق التنفيذ با‏‫‏‫‏‫‫‏‫‏ستخدَام الدَالة getFormContext.

فِي السَابق، كان يتم الوصول إلى العنصر أو النموذج با‏‫‏‫‏‫‫‏‫‏ستخدَام الكائن العَالمي Xrm.Page. ومَعَ ذلك، فِي أحدَث إصدَارٍ، يتمُّ إهمَال الكائن Xrm.Page. بدلاً مِن ذلك، يجبُ عَليك استخدَام الأسلوبِ getFormContext مِن كائن سَيَاق التَنفِيذ للحُصُول عَلى مَرجعٍ إلى النَمُوذج أو العُنصر المُنَاسِب فِي النَمُوذج. لذلك، بدلا مِن كتَابة التعليمَات البرمجية مثل مَا يلي.

var firstName = Xrm.Page.getAttribute("firstname").getValue();

يمكنك بدلاً مِن ذلك كتَابة الكود أدنَاه با‏‫‏‫‏‫‫‏‫‏ستخدَام formContext.

var formContext = executionContext.getFormContext();

var firstName = formContext.getAttribute("firstname").getValue();

يمكنك معرفة المزيد حول إهمَال Xrm.Page.

الرسم التخطيطي الموجود أدنَاه هو نظرة عَامة عَالية المستوى عَلى الخصَائص والطرق المتوفرة دَاخل سيَاق النموذج:

كائن بيَانَات

كائن البيَانَات (formContext.data) مخصص للا‏‫‏‫‏‫‏‫ستخدَام مع أي جدول للتعَامل مع البيَانَات دَاخل النموذج.

يعد هَذا الجدول ملخصًا لكل كائنَات ومجموعَات البيَانَات:

الاسم	الوَصف
السِمَات	مجموعة مِن البيَانَات غير المتعلقة بالكيَان فِي النموذج. العنَاصر الموجودة فِي هذه المجموعة هي مِن نفس نوع البيَانَات مثل مجموعة السمَات فِي الكيَان، ولكن مِن المهم ملاحظة أنهَا ليست سمَات جدول النموذج.
الكيَان	الأسَاليب الخَاصة باستردَاد المَعلومَات الخَاصة بالصف المعروض عَلى الصَفحَة، وأسلوب الحفظ، ومجموعة مِن كافة السمَات المضمنة فِي النموذج. تقتصر بيَانَات السمة عَلى السمَات التي يتم تمثيلهَا بالحقول فِي النموذج مقَابل جَمِيع الحقول المتَاحة فِي تكوين الكيَان. لمزيد مِن المَعلومَات، رَاجع formContext.data.entity.
العملية	الكائنَات والطرق الخَاصة بالتعَامل مع بيَانَات سير إجرَاءَات العمل فِي نموذج. لمزيد مِن المَعلومَات، رَاجع formContext.data.process.

كائن واجهة ‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫المُستَخدِم

يوفرُ كائن واجهة ‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫المُستَخدِم (formContext.ui) طرقًا لاستردَاد معلومَات حول واجهة ‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫المُستَخدِم، وكذلك مجموعَات للعديد مِن المكونَات الفرعية للنموذج أو الشبكة.

يلخص هَذا الجدول كل كائنَات ومجموعَات واجهة ‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫المُستَخدِم:

الاسم	‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫الوَصف‏‎‏‎‏‎‏‎‏‎‏‎‏‎
عنَاصر التَحكّم	مجموعة مِن كافة عنَاصر التحكم عَلى الصَفحَة. رَاجع المجموعَات للحصول عَلى معلومَات حول المجموعَات وعنَاصر التحكم وكائنَات التحكم فِي المجموعة.
FormSelector	طُرق الحُصُول عَلى مَعلومَاتٍ حَول النمَاذج. استخدم طريقة formSelector.getCurrentItem لاستردَاد معلومَات عن النموذج ‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫المُستَخدِم حَاليًا. استخدم مجموعة formSelector.items لإرجَاع معلومَات حول جَمِيع النمَاذج المتوفرة للمستخدم.
التنقل	مَجموعة جَمِيع عنَاصر التنقل فِي الصَفحَة. رَاجع العُنصُر formContext.ui.navigation للحصول عَلى معلومَات حول العنَاصر الموجودة فِي المجموعة. لا يتوفر التنقل لـ Microsoft Dynamics 365 لأجهزة الكمبيوتر اللوحية‬. لأتمتة التنقل العَام فِي التطبيق، نستخدم عَادةً مسَاحة الاسم Xrm.Navigation.
العملية	توفر عنَاصرَ وطرقًا للتفاعل مع عنصر تحكم سير إجرَاءَات العمل فِي نموذج، مثل إعدَاد الرؤية الخَاصة به. للحصول عَلى مزيد مِن المَعلومَات، رَاجع formContext.ui.process.
QuickForms	مجموعة جَمِيع عنَاصر تحكم طريقة العرض السريعة فِي نموذج. للحصول عَلى مزيد مِن المَعلومَات، رَاجع formContext.ui.quickForms.
علامَات التبويب	مجموعة جَمِيع علامَات التبويب الموجودة فِي الصَفحَة. رَاجع ‎formContex.ui.tabs للحصول عَلى معلومَات حول الأصنَاف الموجودة فِي المجموعة.

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

إن ‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫استخدَام كائنَات السيَاق فِي البرَامج النصية الخَاصة بك يجعلهَا أكثر مرونة للتغيير فِي النموذج وفِي واجهة برمجة تطبيقَات العميل.