#سكريبت JavaScript

#مقدمة

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

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

#إنشاء عقدة

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

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

#المعاملات

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

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

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

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

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

الوحدة بالمللي ثانية، وعند ضبطها على 0 فهذا يعني عدم تعيين مهلة.

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

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

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

#إصدار Node.js

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

#دعم الوحدات

يمكن استخدام الوحدات في السكريبت بشكل محدود، بما يتوافق مع CommonJS، ويتم استخدام تعليمة require() في الكود لاستيراد الوحدات.

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

WORKFLOW_SCRIPT_MODULES=crypto,timers,lodash,dayjs

في البيئات غير المنشورة من المصدر، إذا لم يتم تثبيت وحدة معينة في 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 في السكريبت (يجب أن يكون اسم require متطابقًا تمامًا مع ما تم تعريفه في متغير البيئة):

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

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

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

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

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

ستعمل المعاملات المكونة في العقدة كمتغيرات عامة في السكريبت ويمكن استخدامها مباشرة. تدعم المعاملات الممرة إلى السكريبت الأنواع الأساسية فقط، مثل boolean و number و string و number و 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;