> ## Documentation Index
> Fetch the complete documentation index at: https://docs.karzoun.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# إجراء: دالة JavaScript

> مرجع كامل لإجراء الكود المخصص داخل الأتمتة: محرر الكود، معاملات الدخل وقيم الاختبار، استيراد مكتبات npm، وربط المخرجات بحقول ومتغيرات.

## بطاقة سريعة

|                      |                                                                                           |
| -------------------- | ----------------------------------------------------------------------------------------- |
| **الاسم البرمجي**    | `javaScriptFunction`                                                                      |
| **الفئة في المنتقي** | متقدّم                                                                                    |
| **أين يعيش**         | إجراء واحد داخل [عقدة الإجراء](/ar/help-center/guides/automations/nodes/actions/overview) |

عندما يعجز الشرط والتقسيم الجاهزان عن التعبير عن منطقك، تكتب كوداً. هذا الإجراء ينفّذ **JavaScript حقيقياً** كخطوة كاملة الصلاحية داخل المسار — لا مجرد تعبير حسابي بسيط.

## الحقول

| الحقل             | ماذا يعني                                                                                                                                              |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **الكود**         | محرر JavaScript كامل بإبراز الصياغة (Syntax Highlighting)                                                                                              |
| **معاملات الدخل** | لكل معامل: اسم + قيمة (متغيّر من المسار) + **قيمة اختبار مستقلة**                                                                                      |
| **المكتبات**      | أسماء مكتبات npm تريد استيرادها داخل الكود، لاستخدام وظائف جاهزة بدل إعادة كتابتها                                                                     |
| **ربط المخرجات**  | لكل ناتج من الكود تريد استخدامه لاحقاً: القيمة المصدر (اسم المتغيّر داخل الكود) + الحقل الهدف (على العميل أو متغيرات المسار) + قيمة افتراضية عند الفشل |

<Info>
  **وسائط مطلوبة:** محرر دالة JavaScript مفتوحاً بكود بسيط (مثال: تحويل تاريخ لصيغة نصية)، مع معامل دخل واحد وربط مخرج واحد.
  المسار المقترح: `/images/help/automations/action-js-function.webp`
</Info>

## معاملات الدخل: القيمة الحقيقية وقيمة الاختبار

كل معامل يقبل متغيراً ديناميكياً من المسار (بيانات العميل، إجابة سؤال سابق، نتيجة إجراء سابق)، بالإضافة إلى **قيمة اختبار مستقلة** تُستخدم فقط عند تجربة الكود أثناء البناء — دون التأثير على القيمة الحقيقية المستخدمة عند التشغيل الفعلي.

<Tip>
  استخدم قيم اختبار قريبة من الحالات الحدّية الحقيقية (نص فارغ، رقم سالب، تاريخ غير صالح) لا فقط حالة "الطريق السعيد" — هذا يكشف أخطاء الكود قبل أن يكشفها عميل حقيقي.
</Tip>

## ربط المخرجات

بعد تنفيذ الكود، تحتاج أن تحدد أي قيمة من نتيجته تريد الاحتفاظ بها لاستخدامها في خطوات لاحقة (شرط، رسالة، طلب HTTP آخر). لكل مخرج تربطه:

1. **القيمة المصدر**: اسم المتغيّر أو الحقل في نتيجة الكود.
2. **الحقل الهدف**: أين تُحفظ — حقل على بطاقة العميل، أو متغيّر مسار عادي.
3. **قيمة افتراضية عند الفشل**: تُستخدم إن فشل تنفيذ الكود أو لم يُرجع القيمة المتوقعة، بحيث لا يتوقف المسار بقيمة فارغة غير متوقعة.

## متى تستخدمه؟

| احتياجك                                 | مثال                                                             |
| --------------------------------------- | ---------------------------------------------------------------- |
| حسابات مخصصة لا يغطيها الشرط أو التقسيم | حساب فرق الأيام بين تاريخين، أو نسبة خصم متدرجة                  |
| تحويل صيغة بيانات                       | تحويل تاريخ ISO لصيغة عربية مقروءة، أو تنسيق رقم هاتف            |
| منطق شرطي متداخل معقد                   | قواعد متعددة الشروط يصعب التعبير عنها بمجموعات شرط بسيطة         |
| دمج نتائج من أكثر من مصدر               | دمج استجابة طلب HTTP مع بيانات العميل قبل تمريرها للخطوة التالية |

<Warning>
  لا تكتب منطقاً بسيطاً (مثل "أكبر من ١٠٠") في كود JavaScript إن كان [الشرط](/ar/help-center/guides/automations/nodes/condition) يكفي — الشرط أسهل للفريق غير التقني أن يقرأه ويعدّله لاحقاً. استخدم الكود فقط عندما يتجاوز المنطق ما تعبّر عنه العقد الجاهزة.
</Warning>

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

| الخطأ                                   | النتيجة                                       | الصواب                                        |
| --------------------------------------- | --------------------------------------------- | --------------------------------------------- |
| كود بلا معالجة أخطاء (try/catch)        | فشل صامت أو توقف المسار عند بيانات غير متوقعة | تحقق من صحة المدخلات داخل الكود قبل استخدامها |
| نسيان ربط مخرج تحتاجه لاحقاً            | خطوات لاحقة ترى قيمة فارغة                    | راجع كل قيمة تحتاجها وتأكد من ربطها           |
| قيمة افتراضية غير منطقية عند الفشل      | سلوك غير متوقع في حالات نادرة                 | اختر قيمة افتراضية آمنة تعكس "لا توجد بيانات" |
| استيراد مكتبة غير مدعومة أو خاطئة الاسم | فشل تنفيذ الكود بالكامل                       | تحقق من اسم المكتبة ودعمها قبل النشر          |
| استخدام بيانات حقيقية في قيم الاختبار   | تسريب بيانات حساسة عند مشاركة الشاشة          | استخدم قيم اختبار مصطنعة دائماً               |

## ذات صلة

* [عقدة: إجراء — نظرة عامة](/ar/help-center/guides/automations/nodes/actions/overview)
* [عمليات JSON](/ar/help-center/guides/automations/nodes/actions/json-operations)
* [طلب HTTP](/ar/help-center/guides/automations/nodes/actions/http-request)
* [عقدة: شرط](/ar/help-center/guides/automations/nodes/condition)


## Related topics

- [عقدة: إجراء — نظرة عامة](/ar/help-center/guides/automations/nodes/actions/overview.md)
- [إجراء: عمليات JSON](/ar/help-center/guides/automations/nodes/actions/json-operations.md)
- [إجراء: طلب HTTP](/ar/help-center/guides/automations/nodes/actions/http-request.md)
- [إجراء: تحديث خاصية العميل](/ar/help-center/guides/automations/nodes/actions/set-property.md)
- [الإجراءات](/ar/miniapps/guides/actions.md)