مقدمة إلى استخدام React فِي مكون Power Apps

  • 10 دقائق

أثناء إنشاء مكونات تعليمات برمجية أكثر تعقيدًا، يوفر Power Apps Component Framework ميزات مضمنة، يمكنك استخدامها كجزء من المنطق الخاص بك. باستخدام هذه الإمكانات، يمكنك التعرف على العميل الذي يستضيف المكون الخاص بك، والجهاز الذي يقوم بتشغيل المكون، والخدمات الأخرى من نوع الأداة المساعدة مثل التنسيق. بالنسبة للمكونات التي تريد التفاعل مع بيانات Dataverse الجدول، يمكنك استخدام ميزة WebAPI للتفاعل مع البيانات.

يعد إنشاء HTML أمرًا شائعًا بالنسبة للمكونات البسيطة، ولكن مع زيادة تعقيد احتياجاتك، قد يكون استخدام مكتبة إطار عمل واجهة المستخدم مفيدًا. هناك العديد من الخيارات لأطر عمل JavaScript UI، لكن React هي إحدى المكتبات الأكثر شيوعًا المستخدمة مع Power Apps مكونات التعليمات البرمجية.

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

استخدم سياق المكون

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

معلمة السياق متاحة للمكونات الموجودة فِي طريقتي init وupdateView. من الشائع أنه فِي أسلوب init تقوم بملء متغير مستوى الفئة للسماح بالوصول إلى السياق بسهولة فِي طرق أخرى فِي المكون الخاص بك. فيما يلي مثال على حفظ السياق لاستخدامه لاحقًا فِي أسلوب init:

export class ChoicesPicker implements ComponentFramework.StandardControl<IInputs, IOutputs> {
    
    private _context: ComponentFramework.Context<IInputs>;

    public init(
        context: ComponentFramework.Context<IInputs>,
        notifyOutputChanged: () => void,
        state: ComponentFramework.Dictionary,
        container: HTMLDivElement,
    ): void {
     
        this._context = context;

        /* other logic goes here */
    }
}

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

  • client - تزودك هذه الخاصية بمعلومات حول العميل (الويب أو Outlook أو الهاتف المحمول)، وعامل التصميم (سطح المكتب أو الجهاز اللوحي أو الهاتف)، وإذا كنت غير متصل بالإنترنت، وإذا كانت الشبكة متاحة.

  • mode - توفر هذه الخاصية معلومات حول الحالة الحالية لمكون التعليمات البرمجية. على سبيل المثال، هل المكون مرئي، وهل هو معطل، وما الحجم المخصص الحالي.

  • userSettings - توفر هذه الخاصية معلومات حول المستخدم الحالي مثل معرف اللغة ومعرف المستخدم والاسم. بالنسبة للتطبيقات المستندة إلى النموذج، يمكن أن تكون خاصية SecurityRoles مفيدة للتعرف على أدوار المستخدم الحالي.

يوفر كائن السياق أيضًا إمكانية الوصول إلى العديد من الخدمات المضمنة المفيدة. وفيما يلي الأكثر شيوعا:

  • device - توفر هذه الخاصية إمكانية الوصول إلى طرق استخدام إمكانيات الجهاز الأصلية. باستخدام هذه الخدمات، يمكنك التقاط الصوت والفيديو والصور والحصول على قيم الرمز الشريطي وتحديد الموقع الجغرافي للجهاز واختيار الملفات.

  • factory - يوفر هذا حاليًا طرقًا للعمل مع خدمة النوافذ المنبثقة فقط، ولكنه قد يدعم خدمات أخرى فِي المستقبل.

  • formatting - يوفر طرقًا تساعدك على تنسيق البيانات من عملة إلى أخرى. يمكن أن تساعدك هذه الطرق فِي الحفاظ على التنسيق متسقًا مع إعدادات مستخدم تطبيق الاستضافة.

  • navigation - يوفر الأساليب المتعلقة بالتنقل مثل النماذج المفتوحة وعناوين URL المفتوحة ومربعات الحوار (التنبيه والتأكيد والخطأ) والمزيد.

  • resources - توفر الوصول إلى الطرق للحصول على جميع المعلومات حول ملفات الموارد المحددة فِي البيان. تعتبر هذه الطرق ضرورية للمساعدة فِي توطين كل محتوى المكون الخاص بك.

  • utils - يوفر الوصول إلى بيانات تعريف الجدول ويسمح لك أيضًا بالتحقق من وصول المستخدم إلى جداول محددة. يسمح أسلوب lookupObjects للمكونات بالوصول إلى مربع حوار البحث القياسي، مما يسمح للمستخدمين باختيار صف واحد أو أكثر.

  • webAPI - يوفر الوصول الأساسي إلى بيانات الجدول Dataverse وقراءتها وتحديثها وحذفها.

فيما يلي مثال على استخدام إمكانيات pickFile فِي الجهاز:

 private onUploadButtonClick(event: Event): void {
    this._context.device.pickFile().then(this.processFile.bind(this), this.showError.bind(this));
  }

من الهام ملاحظة أن بعض هذه الخدمات تتطلب تمكينها فِي قسم استخدام الميزات فِي البيان لكي تعمل. قد يكون بعضها متاحًا فقط فِي أنواع معينة من تطبيقات الاستضافة. على سبيل المثال، يتوفر webAPI فقط فِي التطبيقات التي تستند إلى النموذج Power Pages ولا يتوفر لتطبيقات اللوحة. تحقق من الصفحة المرجعية للخدمة الفردية للحصول على التفاصيل.

استخدم React

هناك العديد من أطر واجهة المستخدم التي يمكنك الاختيار من بينها؛ ومع ذلك، هناك فوائد لاستخدام React. يتم تفضيل React لأن النظام الأساسي Power Apps الأساسي يستخدم React داخليًا. يحتوي Power Apps Component Framework أيضًا على دعم مدمج لاستخدام نفس البنية التحتية. تعني هذه الإمكانية أنك لن تضطر إلى تجميع مكتبات React وFluent UI يدويًا فِي كل عنصر تحكم. ستتشارك جميع عناصر التحكم فِي نسخة ومثيل مكتبة مشتركين لتوفير تجربة سلسة ومتسقة.

يوضح الأمر التالي كيفية تهيئة المكون واستخدام إطار عمل React:

pac pcf init -n ReactSample -ns SampleNamespace -t field -fw react -npm

الاختلاف الوحيد الذي قد تلاحظه هو الخيار -fw (أو--framework) الذي يتيح استخدام React. سيؤدي هذا الخيار إلى تضمين الملفات الأولية التي تم إنشاؤها لك تكوينات React الضرورية.

لاحقًا فِي هذه الوحدة، ستبني مكونًا برمجيًا باستخدام إمكانية React هذه.