الدالة JSON

مقالة
10/16/2024

ينطبق على: تطبيقات اللوحة التطبيقات المستندة إلى النموذج Power Pages

إنشاء سلسلة نصية JSON لجدول أو سجل أو قيمة.

‏‏الوصف

تقوم وظيفة JSON بإرجاع تمثيل JavaScript Object Notation (JSON) لهيكل البيانات كنص بحيث يكون مناسبًا للتخزين أو الإرسال عبر الشبكة. يصف [ECMA-404](https://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf وIETF RFC 8259 التنسيق، الذي يستخدم على نطاق واسع من قِبل JavaScript ولغات البرمجة الأخرى.

تدعم تطبيقات اللوحة أنواع البيانات التي يسردها هذا الجدول مع تفاصيل العرض الخاص به لتمثيل النص:

نوع البيانات	‏‏الوصف	مثال للنتيجة
منطقي	صواب أم خطأ.	`true`
لون	سلسلة تحتوي على تمثيل سداسي عشري مكون من 8 أرقام للون. يأخذ هذا التنسيق التنسيق #rrggbbaa، حيث يشير rr إلى المكون الأحمر، ويشير gg إلى الأخضر، ويشير bb إلى الأزرق، ويشير aa إلى قناة ألفا. بالنسبة لقناه ألفا، يكون 00 شفافًا بالكامل، ويكون ff معتمًا بالكامل. يمكنك تمرير السلسلة إلى وظيفة ColorValue.	`"#102030ff"`
عملة	الرقم الذي يستخدم الفاصل العشري المناسب للغة المستخدم. يتم استخدام الرموز العلمية إذا لزم الأمر.	`1.345`
تاريخ	السلسلة التي تحتوي على التاريخ بتنسيق ISO 8601 yyyy-mm-dd.	`"2019-03-31"`
التاريخ والوقت	سلسلة تحتوي على تاريخ / وقت ISO 8601. قيم التاريخ / الوقت بالتوقيت العالمي المنسق، كما تشير النهاية إلى "Z".	`"2019-03-31T22:32:06.822Z"`
المعرف الفريد العمومي (GUID)	السلسلة التي تحتوي على قيمة GUID. الأحرف صغيرة.	`"751b58ac-380e-4a04-a925-9f375995cc40"`
صورة, وسائط	إذا تم تحديد JSONFormat.IncludeBinaryData، فسيتم ترميز ملفات الوسائط في سلسلة. لم يتم تعديل مراجع الويب التي تستخدم http: أو https: مخطط URL. يتم ترميز مراجع البيانات الثنائية في الذاكرة بتنسيق "data:mimetype;base64,...". تتضمن البيانات الموجودة في الذاكرة الصور التي يلتقطها المستخدمون باستخدام عنصر تحكم Camera وأي مراجع أخرى مع عمليات الموافقة: وblob: مخططات عناوين URL.	`"data:image/jpeg;base64,/9j/4AA..."`
رقم	الرقم الذي يستخدم الفاصل العشري المناسب للغة المستخدم. يتم استخدام الرموز العلمية إذا لزم الأمر.	`1.345`
مجموعة خيارات	قيمة رقمية للاختيار، وليس التسمية المستخدمة للعرض. يتم استخدام القيمة الرقمية لأنها لغة مستقلة.	`1001`
الوقت	السلسلة التي تحتوي على تنسيق ISO 8601 hh:mm:ss.fff.	`"23:12:49.000"`
سجل	قائمة مفصولة بفواصل، بين{ و} للحقول وقيمها. يشبه هذا التدوين السجلات الموجودة في تطبيقات اللوحة، ولكن الاسم دائمًا بين علامتي اقتباس مزدوجتين. لا يدعم هذا التنسيق السجلات التي تستند إلى علاقات كثير إلى واحد.	`{ "First Name": "Fred", "Age": 21 }`
الجَدوَل	قائمة مفصولة بفواصل، بين [ و] للسجلات. لا يدعم هذا التنسيق الجداول التي تستند إلى علاقات واحد إلى كثير. استخدم الخيار JSONFormat.FlattenValueTable لإزالة السجل الخاص بجداول الأعمدة المفردة مع العمود المسمى قيمة.	`[ { "First Name": "Fred", "Age": 21 }, { "First Name": "Jean", "Age": 20 } ]`
خياران	القيمة المنطقية للخيارين، صواب أو خطأ، ليست التسمية التي يتم استخدامها للعرض. يتم استخدام القيمة المنطقية لأنها لغة مستقلة.	`false`
ارتباط تشعبي، نص	سلسله بين علامتي اقتباس مزدوجتين. تفلت الوظيفة من علامات الاقتباس المزدوجة المضمنة بشرطة مائلة للخلف، وتستبدل الأسطر الجديدة بعلامات "\n"، وتقوم باستبدال JavaScript قياسي آخر.	`"This is a string."`

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

تعداد JSONFormat	الوصف
JSONFormat.Compact	الإعداد الافتراضي. الإخراج مضغوط قدر الإمكان مع عدم وجود مسافات أو خطوط جديدة.
JSONFormat.flattenValueTables	كجدول قيمة، `[1,2,3]` ينتج عن التدوين جدول يحتوي على سجلات حيث يحتوي كل سجل على عمود قيمة واحد. في JSON، يمثل نفس الترميز مصفوفة من ثلاثة أرقام. لتسهيل التشغيل البيني بين الاثنين، يقوم هذا الخيار بتسوية جدول القيم ‏‎Power Fx إلى مصفوفة صديقة لـ JSON بدلاً من مصفوفة من السجلات.
JSONFormat.IndentFour	لتحسين إمكانية القراءة ، يحتوي الإخراج على سطر جديد لكل عمود ومستوى تداخل ويستخدم أربعة مسافات لكل مستوى مسافة بادئة.
JSONFormat.IncludeBinaryData	تتضمن النتيجة أعمدة صور وفيديو ومقطع صوتي. يمكن أن يزيد هذا التنسيق بشكل كبير من حجم النتيجة ويقلل من أداء تطبيقك.
JSONFormat.IgnoreBinaryData	لا تتضمن النتيجة أعمدة صورة أو فيديو أو مقطع صوتي. إذا لم تحدد JSONFormat.IncludeBinaryData ولا JSONFormat.IgnoreBinaryData، فستنتج الدالة خطأ إذا واجهت بيانات ثنائية.
JSONFormat.Ignore أنواع غير مدعومة	يُسمح بأنواع البيانات غير المدعومة ، لكن النتيجة لن تتضمنها. بشكل افتراضي ، تنتج أنواع البيانات غير المدعومة خطأ.

استخدم وظيفتي ShowColumns وDropColumns للتحكم في البيانات التي تتضمنها النتيجة وإزالة أنواع البيانات غير المدعومة.

ونظرًا لأن وظيفة JSON يمكن أن يكون الذاكرة والحساب بشكل مكثف، يمكنك استخدام هذه الوظيفة فقط في وظائف السلوك. يمكنك التقاط النتيجة من وظيفة JSON في متغير، والذي يمكنك استخدامه بعد ذلك في تدفق البيانات.

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

بناء الجملة

JSON ( هيكل البيانات [، التنسيق ])

هيكل البيانات- مطلوب. بنية البيانات المراد تحويلها إلى JSON. الجداول والسجلات والقيم الأولية مدعومة ومتداخلة بشكل تعسفي.
الشكل - اختياري. JSONFormat قيمة التعداد. القيمة الافتراضية هي JSONFormat.Compact، التي لا تضيف أسطرًا أو مسافات جديدة وتحظر البيانات الثنائية والأعمدة غير المدعومة.

الأمثلة

البيانات الهرمية

أدرج عنصر تحكم Button، وقم بتعيين خاصية OnSelect الخاصة به إلى هذه الصيغة.

ClearCollect( CityPopulations,
    { City: "London",    Country: "United Kingdom", Population: 8615000 },
    { City: "Berlin",    Country: "Germany",        Population: 3562000 },
    { City: "Madrid",    Country: "Spain",          Population: 3165000 },
    { City: "Hamburg",   Country: "Germany",        Population: 1760000 },
    { City: "Barcelona", Country: "Spain",          Population: 1602000 },
    { City: "Munich",    Country: "Germany",        Population: 1494000 }
);
ClearCollect( CitiesByCountry, GroupBy( CityPopulations, "Country", "Cities" ) )

حدد الزر أثناء الضغط باستمرار على مفتاح Alt.

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

يمكنك أيضًا إظهار هذه المجموعة عن طريق تحديد الإعدادات>الميزات القادمة>تمكين عرض نتائج شريط الصيغة، وتحديد اسم المجموعة في شريط الصيغة، ثم تحديد السهم لأسفل بجوار اسم المجموعة أسفل شريط الصيغة.
أدرج زرًا آخر، وقم بتعيين خاصية OnSelect الخاصة به إلى هذه الصيغة:
```
Set( CitiesByCountryJSON, JSON( CitiesByCountry ) )
```
تقوم هذه الصيغة بتعيين المتغير العام CitiesByCountryJSON إلى تمثيل JSON لـ CitiesByCountry.
حدد الزر أثناء الضغط باستمرار على مفتاح Alt.

أدرج عنصر تحكم Label، وقم بتعيين خاصية Text الخاصة به إلى هذا المتغير.

CitiesByCountryJSON

تُظهر التسمية هذه النتيجة، كلها على خط واحد دون مسافات، وهي مناسبة للإرسال عبر الشبكة:

[
  {
    "Cities": [{ "City": "London", "Population": 8615000 }],
    "Country": "United Kingdom"
  },
  {
    "Cities": [
      { "City": "Berlin", "Population": 3562000 },
      { "City": "Hamburg", "Population": 1760000 },
      { "City": "Munich", "Population": 1494000 }
    ],
    "Country": "Germany"
  },
  {
    "Cities": [
      { "City": "Madrid", "Population": 3165000 },
      { "City": "Barcelona", "Population": 1602000 }
    ],
    "Country": "Spain"
  }
]

قم بتغيير صيغة الزر الثاني لجعل الإخراج أكثر قابلية للقراءة.
```
Set( CitiesByCountryJSON, JSON(CitiesByCountry, JSONFormat.IndentFour ))
```

حدد الزر الثاني أثناء الضغط باستمرار على مفتاح Alt.

تُظهر التسمية النتيجة الأكثر قابليةً للقراءة.

[
  {
    "Cities": [
      {
        "City": "London",
        "Population": 8615000
      }
    ],
    "Country": "United Kingdom"
  },
  {
    "Cities": [
      {
        "City": "Berlin",
        "Population": 3562000
      },
      {
        "City": "Hamburg",
        "Population": 1760000
      },
      {
        "City": "Munich",
        "Population": 1494000
      }
    ],
    "Country": "Germany"
  },
  {
    "Cities": [
      {
        "City": "Madrid",
        "Population": 3165000
      },
      {
        "City": "Barcelona",
        "Population": 1602000
      }
    ],
    "Country": "Spain"
  }
]

الصور والوسائط في base64

أضف عنصر تحكم Image.

يحضر عنصر التحكم هذا SampleImage باستخدامه.
أضف عنصر تحكم Button، وقم بتعيين خاصية OnSelect الخاصة به إلى هذه الصيغة.
```
Set( ImageJSON, JSON( SampleImage, JSONFormat.IncludeBinaryData ) )
```
حدد الزر أثناء الضغط باستمرار على مفتاح Alt.
أضف تسمية، وقم بتعيين خاصية Text الخاصة بها إلى هذا المتغير.
```
ImageJSON
```

قم بتغيير حجم عنصر التحكم وتقليل حجم الخط حسب الحاجة لإظهار معظم النتيجة.

تُظهر التسمية السلسلة النصية التي التقطتها وظيفة JSON.

"data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4NCjxzdmcgdmVyc2lvbj0iMS4xIg0KCSB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHhtbG5zOnhsaW5rPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5L3hsaW5rIiB4bWxuczphPSJodHRwOi8vbnMuYWRvYmUuY29tL0Fkb2JlU1ZHVmlld2VyRXh0ZW5zaW9ucy8zLjAvIg0KCSB4PSIwcHgiIHk9IjBweCIgd2lkdGg9IjI3MHB4IiBoZWlnaHQ9IjI3MHB4IiBlbmFibGUtYmFja2dyb3VuZD0ibmV3IDAgMCAyNzAgMjcwIiB4bWw6c3BhY2U9InByZXNlcnZlIj4NCgk8ZyBjbGFzcz0ic3QwIj4NCgkJPHJlY3QgeT0iMC43IiBmaWxsPSIjRTlFOUU5IiB3aWR0aD0iMjY5IiBoZWlnaHQ9IjI2OS4zIi8+DQoJCTxwb2x5Z29uIGZpbGw9IiNDQkNCQ0EiIHBvaW50cz0iMjc3LjksMTg3LjEgMjQ1LDE0My40IDE4OC42LDIwMi44IDc1LDgwLjUgLTQuMSwxNjUuMyAtNC4xLDI3MiAyNzcuOSwyNzIiLz4NCgkJPGVsbGlwc2UgZmlsbD0iI0NCQ0JDQSIgY3g9IjIwMi40IiBjeT0iODQuMSIgcng9IjI0LjQiIHJ5PSIyNC4zIi8+DQoJPC9nPg0KPC9zdmc+"

جداول القيم

هذه الصيغة:

JSON( [1,2,3] )

ينتج سلسلة النص [{"Value":1},{"Value":2},{"Value":3}].

نفس الصيغة مع خيار JSONFormat.FlattenValueTables:

JSON( [1,2,3], JSONFormat.FlattenValueTables )

تنتج سلسلة النص [1,2,3].

لاحظ أن خيار FlattenValueTables ليس له أي تأثير عند استخدام JSON مع مجموعات CityPopulations أو CitiesByCountry لأن هذه الجداول ليست جداول قيمة. يحتوي جدول القيمة على عمود واحد ويجب أن يسمى "القيمة".

مشاركة عبر