#JavaScript سكريبت

#مقدمة

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

يتم تشغيل السكريبت في خيط عمل (worker thread) على خادم تطبيق NocoBase ويدعم معظم ميزات Node.js، ولكن لا تزال هناك بعض الاختلافات عن بيئة التنفيذ الأصلية. للاطلاع على التفاصيل، راجع قائمة الميزات.

#إنشاء عقدة

في واجهة تكوين سير العمل، انقر على زر علامة الجمع ("+") في التدفق لإضافة عقدة "JavaScript".

#تكوين العقدة

#المعاملات

تُستخدم لتمرير المتغيرات أو القيم الثابتة من سياق التدفق إلى السكريبت لاستخدامها في منطق الكود. هنا، name هو اسم المعامل، والذي يصبح اسم المتغير بمجرد تمريره إلى السكريبت. value هي قيمة المعامل، ويمكن اختيارها كمتغير أو إدخال ثابت.

#محتوى السكريبت

يمكن اعتبار محتوى السكريبت دالة. يمكنك كتابة أي كود JavaScript مدعوم في بيئة Node.js واستخدام عبارة return لإرجاع قيمة كنتيجة لتنفيذ العقدة، والتي يمكن استخدامها كمتغير بواسطة العقد اللاحقة.

بعد كتابة الكود، يمكنك النقر على زر الاختبار أسفل مربع التحرير لفتح مربع حوار تنفيذ الاختبار، حيث يمكنك ملء المعاملات بقيم ثابتة لإجراء تشغيل محاكاة. بعد التنفيذ، يمكنك رؤية قيمة الإرجاع ومحتوى الإخراج (السجل) في مربع الحوار.

#إعداد المهلة

الوحدة هي المللي ثانية. تعني القيمة 0 عدم تعيين مهلة.

#المتابعة عند الخطأ

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

#قائمة الميزات

#إصدار Node.js

يتوافق مع إصدار Node.js الذي يعمل عليه التطبيق الرئيسي.

#دعم الوحدات (Modules)

يمكن استخدام الوحدات (modules) في السكريبت بقيود، بما يتوافق مع CommonJS، وذلك باستخدام توجيه require() لاستيراد الوحدات.

يدعم وحدات Node.js الأصلية والوحدات المثبتة في node_modules (بما في ذلك حزم التبعيات التي يستخدمها NocoBase بالفعل). يجب الإعلان عن الوحدات المراد توفيرها للكود في متغير البيئة الخاص بالتطبيق WORKFLOW_SCRIPT_MODULES، مع فصل أسماء الحزم المتعددة بفاصلة، على سبيل المثال:

WORKFLOW_SCRIPT_MODULES=crypto,timers,lodash,dayjs

في بيئة غير منشورة من المصدر (non-source-deployed)، إذا لم يتم تثبيت وحدة معينة في node_modules، يمكنك تثبيت الحزمة المطلوبة يدويًا في دليل storage. على سبيل المثال، لاستخدام حزمة exceljs، يمكنك تنفيذ الخطوات التالية:

cd storage
npm i --no-save --no-package-lock --prefix . exceljs

ثم أضف المسار النسبي (أو المطلق) للحزمة، بناءً على دليل العمل الحالي للتطبيق (CWD)، إلى متغير البيئة WORKFLOW_SCRIPT_MODULES:

WORKFLOW_SCRIPT_MODULES=./storage/node_modules/exceljs

بعد ذلك، يمكنك استخدام حزمة exceljs في السكريبت الخاص بك:

const ExcelJS = require('exceljs');
// ...

#المتغيرات العامة

لا يدعم المتغيرات العامة مثل global وprocess و__dirname و__filename.

console.log(global); // will throw error: "global is not defined"

#معاملات الإدخال

تصبح المعاملات المكونة في العقدة متغيرات عامة داخل السكريبت ويمكن استخدامها مباشرة. تدعم المعاملات التي يتم تمريرها إلى السكريبت الأنواع الأساسية فقط، مثل boolean وnumber وstring وobject والمصفوفات. سيتم تحويل كائن Date إلى سلسلة نصية بتنسيق ISO عند تمريره. لا يمكن تمرير الأنواع المعقدة الأخرى مباشرة، مثل مثيلات الفئات المخصصة.

#قيمة الإرجاع

يمكن استخدام عبارة return لإرجاع بيانات من الأنواع الأساسية (وفقًا لقواعد المعاملات نفسها) إلى العقدة كنتيجة. إذا لم يتم استدعاء عبارة return في الكود، فلن يكون لتنفيذ العقدة قيمة إرجاع.

return 123;

#الإخراج (السجل)

يدعم استخدام console لإخراج السجلات.

console.log('hello world!');

عند تنفيذ سير العمل، يتم أيضًا تسجيل إخراج عقدة السكريبت في ملف سجل سير العمل المقابل.

#غير متزامن

يدعم استخدام async لتعريف الدوال غير المتزامنة وawait لاستدعائها. يدعم استخدام الكائن العام Promise.

async function test() {
  return Promise.resolve(1);
}

const value = await test();
return value;

#المؤقتات

لاستخدام دوال مثل setTimeout أو setInterval أو setImmediate، يجب استيرادها من حزمة timers الخاصة بـ Node.js.

const { setTimeout, setInterval, setImmediate, clearTimeout, clearInterval, clearImmediate } = require('timers');

async function sleep(time) {
  return new Promise((resolve) => setTimeout(resolve, time));
}

await sleep(1000);

return 123;