Power Fxقواعد صيغة YAML

‏‫ملاحظة‬

Microsoft Power Fx هو الاسم الجديد للغة الصيغة لتطبيقات اللوحة. هذه المقالات عبارة عن عمل قيد التقدم حيث نقوم باستخراج اللغة من تطبيقات اللوحة ودمجها مع منتجات Microsoft Power Platform الأخرى وجعلها متوفرة كمصدر مفتوح. ابدأ بـ نظرة عامة على Microsoft Power Fx لمقدمة عن اللغة.

يشتمل Microsoft Power Fx على قواعد جيدة للتعبيرات المستندة إلى Excel. ومع ذلك، لا توجد طريقة قياسية لتحرير ربط الصيغة كنص عند استخدامها في Power Apps والمضيفين الآخرين حيث توفر واجهة المستخدم ربط الاسم إلى التعبير للصيغة.

لقد قمنا باختيار معيار الصناعة YAML كلغتنا لهذا الربط. يوجد بالفعل عدد كبير من المحررين والأدوات ومكتبات العمل مع YAML. تصف هذه المقالة كيفية تمثيلنا للصيغ في YAML.

وفي هذا الوقت، ندعم مجموعة فرعية مقيدة فقط من YAML. يتم دعم البنى الموضحة في هذه المقالة فقط.

لا يتم هنا تقديم كل ما يعرّف تطبيق اللوحة؛ تتدفق المعلومات الإضافية عبر الملفات الأخرى التي تنتجها الأداة وتستهلكها.

علامة المساواة البادئة

أولاً وقبل كل شيء، يجب أن تبدأ جميع التعبيرات بعلامة تساوي أولية =:

Visible: =true
X: =34
Text: |
	="Hello, " &
	"World"

ونستخدم = هذا الأسلوب لثلاثة أسباب:

• إنه متوافق مع Excel، الذي يستخدم = بادئة لربط تعبير بخلية.
• إنه يهرب بشكل فعال من بناء جملة لغة الصيغة بحيث لا يحاول YAML تحليلها. عادة، يعامل YAML text: 1:00 كالدقائق والثواني، وتحويلها إلى رقم. عن طريق إدخال = لن تستخدم YAML قواعد الكتابة الضمنية ولن تتضرر الصيغ. يغطي استخدام = معظم الحالات، ولكن ليس كلها، ويتم وصف هذه الاستثناءات في القسم التالي، صيغ السطر الواحد.
• في المستقبل، سندعم كلا الصيغتين (تبدأ بـ =) غير صيغ (لا =) في نفس الملف، تمامًا كما يفعل Excel، يمكننا القيام بذلك في ملفات YAML وغير YAML على حد سواء عبر ملفات مصدر Microsoft Power Platform. وفي أي مكان يتم فيه دعم صيغة، يفرق = الرئيسي تعبير الصيغة Power Apps عن قيمة التوسع الثابتة.

صيغ سطر نصي واحد‬

تكون صيغ السطر الواحد مكتوبة في النموذج:

الاسم:SPACE=التعبير

يجب أن تكون المساحة بين العلامة "نقطتين" و"علامة يساوي" متوافقة مع YAML. تعطل علامة المساواة تفسير YAML الطبيعي للتعبير، مما يسمح بتفسير باقي السطر على أنه Power Fx. على سبيل المثال:

Text1: ="Hello, World"
Text2: ="Hello " & ", " & "World"
Number1: =34
Boolean1: =true
Time1: =1:34

علامة الرقم # والنقطتين : غير مسموح به في أي مكان في صيغ ذات سطر واحد، حتى لو كانت في سلسلة نصية مقتبسة أو اسم معرف. لاستخدام علامة الرقم أو النقطتين، يجب التعبير عن الصيغة كصيغة متعددة الأسطر. يتم تفسير علامة الرقم على أنها تعليق في YAML، ويتم تفسير علامة النقطتين على أنها خريطة اسم جديدة في YAML. لإضافة تعليق إلى تعليق من سطر واحد، استخدم تعليق سطر Power Fx بدءًا من //.

استخدام الهروب العادي في YAML بعلامات اقتباس مفردة وشُرط مائلة للخلف على شكل حرف C غير مدعوم ؛ استخدم صيغة متعددة الأسطر بدلاً من ذلك. هذا من أجل الاتساق ولتسهيل القص / اللصق بين شريط الصيغة في Power Apps Studio وملفات مصدر YAML.

راجع عوامل التشغيل ووثائق المعرفات لتطبيقات اللوحة للحصول على تفاصيل حول الأسماء المسموح بها هيكل أحد التعبيرات.

صيغ متعددة الأسطر

يمكن أن تمتد الصيغ على عدة أسطر باستخدام مؤشرات كتلة YAML العددية:

Name:SPACE ( | أو |+ أو |- ) =Expression-LineExpression-Line ...

يجب بادئة جميع الأسطر التي تكون جزءا من الكتلة مسافة واحدة على الأقل في مستوى السطر الأول.

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

Text1: |
    ="Hello, World"
Text2: |
    ="Hello" &
    "," &
    "World"

يتم قبول جميع أشكال الرموز العددية متعددة الأسطر YAML عند الاستيراد، بما في ذلك >+، مثلاً. ومع ذلك، فقط لضمان الحفاظ على المسافات البيضاء بشكل صحيح، يتم إنتاج | أو |+, أو |- فقط.

مثيل المكون

يتم تثبيت المكونات باستخدام تدوين كائن YAML. يتم تحديد نوع الكائن بعامل As كجزء من علامة YAML على الجانب الأيسر. بالنسبة عناصر تحكم حاوية، يمكن تداخل الكائنات.

NameAsComponent-Type [ .Component-Template ] : ( Single-Line-Formula أو Multi-Line-Formula أو Object-instance ) ...

يجب بادئة جميع الأسطر التي تكون جزءا من الكتلة مسافة واحدة على الأقل في مستوى السطر الأول.

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

Gallery1 As Gallery.horizontalGallery:
    Fill: = Color.White
    Label1 As Label:
        Text: ="Hello, World"
        X: =20
        Y: =40
        Fill: |
            =If( Lower( Left( Self.Text, 6 ) ) = "error:",
                Color.Red,
                Color.Black
            ) 

يمكن أن يكون Component-Type أي مكون لوحة أو عنصر تحكم. أنواع القاعدة، مثل الرقم غير مدعومة.

Component-Template هو محدد اختياري للمكونات التي بها قوالب مختلفة مثل المعرض. ليست كل المكونات بها قوالب.

إذا كان الاسم يحتوي على أحرف خاصة وملفوفة بعلامات اقتباس مفردة، يجب تخطي العبارة الكاملة الموجودة على الجانب الأيسر من النقطتين. يمكن القيام بذلك بإحدى الطرق التالية:

• استخدم علامات الاقتباس المفردة لالتفاف الجانب الأيسر بالكامل، الأمر الذي يتطلب استخدام علامات الاقتباس المفردة الموجودة مرتين:

  '''A name with a space'' As Gallery':
  

• استخدم علامات الاقتباس المزدوجة لالتفاف الجانب الأيسر بالكامل، ولكن تأكد من عدم وجود علامات اقتباس مزدوجة في الاسم:

  "'A name with a space' As Gallery":
  

تعريف مكون

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

أنواع القواعد المدعومة: CanvasComponent

تعريف خاصية بسيطة

تستخدم المكونات الخصائص للتواصل مع التطبيق الذي تستضيفه.

Name: ( Single-Line-Expression أو Multi-Line-Expression )

يتم استخدام نوع الصيغة حسب نوع التعبير.

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

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

في الوقت الحالي، تعتبر جميع الخصائص عبارة عن تدفق بيانات فقط ولا يمكن أن تحتوي على آثار جانبية.

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

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

DateRangePicker As CanvasComponent:
    DefaultStart: |-
		=// input property, customizable default for the component instance
		Now()                      
    DefaultEnd: |-
		=// input property, customizable default for the component instance
		DateAdd( Now(), 1, Days )    
    SelectedStart: =DatePicker1.SelectedDate   // output property
    SelectedEnd: =DatePicker2.SelectedDate     // output property

توافق YAML

تعليقات YAML

تعليقات سطر YAML محددة بعلامة الرقم # لا يتم حفظها في أي مكان بتنسيق المصدر. بدلاً من ذلك، ضمن صيغة، حدد تعليقات السطر باستخدام // الأحرف أو حظر التعليقات باستخدام /* و*/. مزيد من المعلومات: التعليقات

أخطاء الأخطاء الشائعة

هناك عدد قليل من الأماكن التي تكون فيها القواعد النحوية لـ Power Fx وYAML غير متوافقة أو قد تكون مربكة للمستخدم. في هذه الحالات، يتم طرح خطأ.

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

Text: ="Hello #PowerApps"
Record: ={ a: 1, b: 2 }

يتم التعامل مع علامة الرقم # كتعليق بواسطة YAML، على الرغم من أنه مضمن في ما يعتبره Excel سلسلة نصية (ملفوفة بعلامات اقتباس مزدوجة). لتجنب الارتباك، ستؤدي هذه الحالة إلى حدوث خطأ أثناء الاستيراد. يمكن استخدام نموذج YAML متعدد الأسطر بدلاً من ذلك.

في حالة قيمة record، تراعي YAML a: وb: ليكون رابطًا آخر لمخطط الاسم. يسمح YAML بإعادة استخدام نفس خريطة الاسم، مع تجاوز آخر خريطة بصمت أي تعريفات سابقة. نظرًا لأن هذا قد يكون مربكًا لصانع التعليمات البرمجية المنخفضة ويمكن أن يؤدي إلى فقدان صيغة الخاصية، يتم إلقاء خطأ إذا تمت مواجهة نفس الاسم مرتين.