Dictionary Operations

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

📥 المدخلات

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

• Dict — بيانات القاموس للعمل عليها (عند الحاجة)

• Keys — مفتاح واحد (string) أو قائمة مفاتيح للإنشاء

• Values — قيمة واحدة أو قائمة قيم للإنشاء

• Input Dict — قاموس المصدر لعمليات update/remove/extend/get/copy

• Key — سلسلة المفتاح المستخدمة في عمليات update/remove/get

• Value — القيمة المستخدمة في عملية update

• New Dict — القاموس الذي سيتم دمجه في قاموس موجود (extend)

• Text — نص JSON للتحليل (parse)

• Dict (للتحويل) — القاموس الذي سيتم تحويله إلى نص

📤 المخارج

تعتمد المخارج أيضًا على الطريقة المختارة. المخارج النموذجية تشمل:

• Dict — القاموس الناتج بعد عمليات create/update/remove/extend/copy

• Text — سلسلة JSON الناتجة عند استخدام to_string أو بعد parse

عند استخدام get لمفتاح واحد، قد يُرجع المخرج القيمة المطلوبة مباشرة.

🕹️ عناصر التحكم

Select Method اختر عملية القاموس المطلوبة. الطرق المتاحة:

• create

• update

• remove

• extend

• get

• copy

• parse

• to_string

Info مساحة نصية سياقية تعرض ملاحظات مساعدة وأمثلة للاستخدام للطريقة المختارة حاليًا.

ملاحظة: تغيير Select Method سيحدّث منافذ البلوك فورًا لتتطابق مع العملية المختارة.

🎨 الميزات

• منافذ ديناميكية: المداخل والمخارج تتحدث تلقائيًا بناءً على الطريقة المختارة بحيث تظهر لك فقط الحقول ذات الصلة.

• تعامل سريع مع JSON: تحليل نص JSON إلى قاموس وتحويل القواميس إلى سلاسل JSON بواسطة طرق مخصصة.

• دعم الدمج والتعديل: تحديث مفاتيح مفردة، إزالة مفاتيح، أو توسيع قاموس موجود بواسطة قاموس آخر.

• دعم النسخ: إنشاء نسخ آمنة لتجنّب التغييرات غير المقصودة في الكتل الأخرى.

• مساعدة داخلية: إرشادات خاصة بالطريقة تظهر في منطقة Info لتقليل التخمين.

⚙️ آلية التشغيل

• اختر طريقة باستخدام Select Method ثم قم بربط المنافذ التي تظهر.

• عند تشغيل السيناريو، ينفّذ البلوك العملية المحددة على المداخل المقدمة ويخرج البيانات الناتجة على منافذ الخرج المطابقة.

• إذا كانت المداخل غير صالحة للعملية المختارة (مثل اختلاف أطوال القوائم عند create، أو فقدان مفتاح في get/remove، أو نص JSON غير صالح في parse)، سيعرض البلوك رسالة خطأ لمساعدتك في تصحيح الإعدادات.

📝 تعليمات الاستخدام

1. أضف البلوك وانقر على Select Method لاختيار العملية المناسبة.

2. قم بربط المصادر بالمنافذ التي تظهر (مثلاً ربط Keys وValues عند استخدام create).

3. استخدم منطقة Info للأمثلة السريعة والملاحظات الخاصة بالطريقة المختارة.

4. شغل السيناريو وفحص المخرجات على المنافذ المطابقة.

💡 نصائح وحيل

• الاحتفاظ بالقيم: ادمجه مع Data Memory أو Data Write Local / Data Write Global للحفاظ على القواميس متاحة عبر السيناريو أو بين عمليات التشغيل.

• التصحيح (Debugging): استخدم Debug Input لعرض محتوى القاموس أثناء التطوير.

• تدفقات JSON: زوج parse مع String Input (لنص JSON يدوي) أو مع بلوك ينتج نصًا، ثم استخدم القاموس الناتج لاحقًا. استخدم to_string قبل الحفظ أو النشر.

• حفظ/تصدير: بعد to_string، أرسل النص إلى CSV Export أو File/Folder Operations إذا احتجت لتخزين النتائج.

• الاستخدام الشرطي: افحص المفاتيح المفقودة باستخدام Is None بعد عملية get لتجنب أخطاء في البلوكات اللاحقة.

• تحديثات الدمج: لبناء إعدادات تدريجيًا، استخدم extend مع عمليات دورية من Data Read Local / Data Write Local للحفاظ على قاموس رئيسي.

• التعامل مع السلاسل: استخدم String Merge أو Find Substring لإنشاء أو التحقق من المفاتيح/القيم قبل تمريرها لعمليات update/create.

🛠️ استكشاف المشاكل وإصلاحها

• اختلاف القوائم عند الإنشاء

  • السبب: تم تقديم Keys وValues كقوائم بأطوال مختلفة.

  • الحل: تأكد من تطابق أطوال القوائم أو قدّم أزواج مفتاح/قيمة مفردة.

• المفتاح غير موجود في get/remove

  • السبب: Key المطلوب غير موجود في Input Dict المقدم.

  • الحل: تحقق من المفاتيح باستخدام عرض تصحيح أو استخدم فحصًا آمنًا (مثلاً التحقق من الوجود قبل استدعاء get/remove).

• JSON غير صالح عند استخدام parse

  • السبب: النص المقدم في Text ليس JSON صالحًا (مطلوب علامات اقتباس مزدوجة للمفاتيح/السلاسل).

  • الحل: صحّح نص JSON (استخدم String Input أو انسخ من مصدر JSON صالح). منطقة Info تعرض مثالًا للتنسيق.

• تغييرات غير متوقعة مشتركة

  • السبب: تغييرات لاحقة على مرجع القاموس تؤثر على البلوكات الأخرى.

  • الحل: استخدم copy أو ادمجه مع Data Memory للتحكم فيما إذا كنت تعمل على نسخة أم الأصلي.

إذا كنت بحاجة لمعاينة أو فحص الصور الوسيطة أو القيم أثناء العمل بمنطق قائم على القواميس، فكر في ربط بلوكات العرض أو التصدير المناسبة (على سبيل المثال استخدم Show Image لمخرجات الصور أو CSV Export لسجلات النتائج).