> For the complete documentation index, see [llms.txt](https://docs.augelab.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.augelab.com/arabic/alblwkat-alwzyfyh/blocks-reference/data-logic/data-operations/dictionary-operations.md).

# Dictionary Operations

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

## 📥 المدخلات <a href="#inputs" id="inputs"></a>

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

* `Dict` — بيانات القاموس للعمل عليها (عند الحاجة)
* `Keys` — مفتاح واحد (string) أو قائمة مفاتيح للإنشاء
* `Values` — قيمة واحدة أو قائمة قيم للإنشاء
* `Input Dict` — قاموس المصدر لعمليات update/remove/extend/get/copy
* `Key` — سلسلة المفتاح المستخدمة في عمليات update/remove/get
* `Value` — القيمة المستخدمة في عملية update
* `New Dict` — القاموس الذي سيتم دمجه في قاموس موجود (extend)
* `Text` — نص JSON للتحليل (parse)
* `Dict` (للتحويل) — القاموس الذي سيتم تحويله إلى نص

## 📤 المخارج <a href="#outputs" id="outputs"></a>

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

* `Dict` — القاموس الناتج بعد عمليات create/update/remove/extend/copy
* `Text` — سلسلة JSON الناتجة عند استخدام to\_string أو بعد parse

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

## 🕹️ عناصر التحكم <a href="#controls" id="controls"></a>

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

* `create`
* `update`
* `remove`
* `extend`
* `get`
* `copy`
* `parse`
* `to_string`

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

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

## 🎨 الميزات <a href="#features" id="features"></a>

* منافذ ديناميكية: المداخل والمخارج تتحدث تلقائيًا بناءً على الطريقة المختارة بحيث تظهر لك فقط الحقول ذات الصلة.
* تعامل سريع مع JSON: تحليل نص JSON إلى قاموس وتحويل القواميس إلى سلاسل JSON بواسطة طرق مخصصة.
* دعم الدمج والتعديل: تحديث مفاتيح مفردة، إزالة مفاتيح، أو توسيع قاموس موجود بواسطة قاموس آخر.
* دعم النسخ: إنشاء نسخ آمنة لتجنّب التغييرات غير المقصودة في الكتل الأخرى.
* مساعدة داخلية: إرشادات خاصة بالطريقة تظهر في منطقة `Info` لتقليل التخمين.

## ⚙️ آلية التشغيل <a href="#running-mechanism" id="running-mechanism"></a>

* اختر طريقة باستخدام `Select Method` ثم قم بربط المنافذ التي تظهر.
* عند تشغيل السيناريو، ينفّذ البلوك العملية المحددة على المداخل المقدمة ويخرج البيانات الناتجة على منافذ الخرج المطابقة.
* إذا كانت المداخل غير صالحة للعملية المختارة (مثل اختلاف أطوال القوائم عند create، أو فقدان مفتاح في get/remove، أو نص JSON غير صالح في parse)، سيعرض البلوك رسالة خطأ لمساعدتك في تصحيح الإعدادات.

## 📝 تعليمات الاستخدام <a href="#usage" id="usage"></a>

1. أضف البلوك وانقر على `Select Method` لاختيار العملية المناسبة.
2. قم بربط المصادر بالمنافذ التي تظهر (مثلاً ربط `Keys` و`Values` عند استخدام `create`).
3. استخدم منطقة `Info` للأمثلة السريعة والملاحظات الخاصة بالطريقة المختارة.
4. شغل السيناريو وفحص المخرجات على المنافذ المطابقة.

## 💡 نصائح وحيل <a href="#tips-and-tricks" id="tips-and-tricks"></a>

* الاحتفاظ بالقيم: ادمجه مع `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.

## 🛠️ استكشاف المشاكل وإصلاحها <a href="#troubleshooting" id="troubleshooting"></a>

* اختلاف القوائم عند الإنشاء
  * السبب: تم تقديم `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` لسجلات النتائج).