#مرجع الواجهة البرمجية (API)

#جانب الخادم

تتوفر واجهات برمجة التطبيقات (APIs) ضمن بنية حزمة جانب الخادم كما هو موضح في الكود التالي:

import PluginWorkflowServer, {
  Trigger,
  Instruction,
  EXECUTION_STATUS,
  JOB_STATUS,
} from '@nocobase/plugin-workflow';

#PluginWorkflowServer

فئة إضافة سير العمل.

عادةً، أثناء تشغيل التطبيق، يمكنك استدعاء app.pm.get<PluginWorkflowServer>(PluginWorkflowServer) في أي مكان يمكنك فيه الحصول على مثيل التطبيق app للحصول على مثيل إضافة سير العمل (يُشار إليه فيما يلي بـ plugin).

#registerTrigger()

يوسع ويسجل نوعًا جديدًا من المشغلات.

Signature

registerTrigger(type: string, trigger: typeof Trigger | Trigger })

Parameters

Example

import PluginWorkflowServer, { Trigger } from '@nocobase/plugin-workflow';

function handler(this: MyTrigger, workflow: WorkflowModel, message: string) {
  // trigger workflow
  this.workflow.trigger(workflow, { data: message.data });
}

class MyTrigger extends Trigger {
  messageHandlers: Map<number, WorkflowModel> = new Map();
  on(workflow: WorkflowModel) {
    const messageHandler = handler.bind(this, workflow);
    // listen some event to trigger workflow
    process.on(
      'message',
      this.messageHandlers.set(workflow.id, messageHandler),
    );
  }

  off(workflow: WorkflowModel) {
    const messageHandler = this.messageHandlers.get(workflow.id);
    // remove listener
    process.off('message', messageHandler);
  }
}

export default class MyPlugin extends Plugin {
  load() {
    // get workflow plugin instance
    const workflowPlugin =
      this.app.pm.get<PluginWorkflowServer>(PluginWorkflowServer);

    // register trigger
    workflowPlugin.registerTrigger('myTrigger', MyTrigger);
  }
}

#registerInstruction()

يوسع ويسجل نوع عقدة جديد.

Signature

registerInstruction(type: string, instruction: typeof Instruction | Instruction })

Parameters

Example

import PluginWorkflowServer, { Instruction, JOB_STATUS } from '@nocobase/plugin-workflow';

class LogInstruction extends Instruction {
  run(node, input, processor) {
    console.log('my instruction runs!');
    return {
      status: JOB_STATUS.RESOVLED,
    };
  },
};

export default class MyPlugin extends Plugin {
  load() {
    // get workflow plugin instance
    const workflowPlugin = this.app.pm.get<PluginWorkflowServer>(PluginWorkflowServer);

    // register instruction
    workflowPlugin.registerInstruction('log', LogInstruction);
  }
}

#trigger()

يشغل سير عمل محددًا. يُستخدم بشكل أساسي في المشغلات المخصصة لتشغيل سير العمل المقابل عند الاستماع إلى حدث مخصص معين.

Signature

trigger(workflow: Workflow, context: any)

Parameters

Example

import { Trigger } from '@nocobase/plugin-workflow';

class MyTrigger extends Trigger {
  timer: NodeJS.Timeout;

  on(workflow) {
    // register event
    this.timer = setInterval(() => {
      // trigger workflow
      this.plugin.trigger(workflow, { date: new Date() });
    }, workflow.config.interval ?? 60000);
  }
}

#resume()

يستأنف سير عمل متوقفًا باستخدام مهمة عقدة محددة.

• يمكن استئناف سير العمل الذي يكون في حالة الانتظار (EXECUTION_STATUS.STARTED) فقط.
• يمكن استئناف مهام العقدة التي تكون في حالة الانتظار (JOB_STATUS.PENDING) فقط.

Signature

resume(job: JobModel)

Parameters

Example

للتفاصيل، راجع الكود المصدري.

#Trigger

الفئة الأساسية للمشغلات، تُستخدم لتوسيع أنواع المشغلات المخصصة.

تُستخدم on/off لتسجيل/إلغاء تسجيل مستمعي الأحداث عند تمكين/تعطيل سير العمل. المعلمة الممررة هي مثيل سير العمل المقابل للمشغل، والذي يمكن معالجته وفقًا للتكوين. قد لا تحتاج بعض أنواع المشغلات التي تستمع بالفعل إلى الأحداث عالميًا إلى تنفيذ هاتين الطريقتين. على سبيل المثال، في المشغل المجدول، يمكنك تسجيل مؤقت في on وإلغاء تسجيله في off.

#Instruction

الفئة الأساسية لأنواع التعليمات، تُستخدم لتوسيع أنواع التعليمات المخصصة.

Related Types

export type Job =
  | {
      status: JOB_STATUS[keyof JOB_STATUS];
      result?: unknown;
      [key: string]: unknown;
    }
  | JobModel
  | null;

export type InstructionResult = Job | Promise<Job>;

export type Runner = (
  node: FlowNodeModel,
  input: JobModel,
  processor: Processor,
) => InstructionResult;

export class Instruction {
  run: Runner;
  resume?: Runner;
}

بالنسبة لـ getScope، يمكنك الرجوع إلى تنفيذ عقدة التكرار، والذي يُستخدم لتوفير محتوى المتغير المحلي للفروع.

#EXECUTION_STATUS

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

باستثناء الحالات الثلاث الأولى، تمثل جميع الحالات الأخرى حالة فشل، ولكن يمكن استخدامها لوصف أسباب مختلفة للفشل.

#JOB_STATUS

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

#جانب العميل

تتوفر واجهات برمجة التطبيقات (APIs) ضمن بنية حزمة جانب العميل كما هو موضح في الكود التالي:

import PluginWorkflowClient, {
  Trigger,
  Instruction,
} from '@nocobase/plugin-workflow/client';

#PluginWorkflowClient

#registerTrigger()

يسجل لوحة التكوين المقابلة لنوع المشغل.

Signature

registerTrigger(type: string, trigger: typeof Trigger | Trigger): void

Parameters

#registerInstruction()

يسجل لوحة التكوين المقابلة لنوع العقدة.

Signature

registerInstruction(type: string, instruction: typeof Instruction | Instruction): void

Parameters

#registerInstructionGroup()

يسجل مجموعة أنواع العقد. يوفر NocoBase أربع مجموعات افتراضية لأنواع العقد:

• 'control': التحكم
• 'collection': عمليات المجموعة
• 'manual': المعالجة اليدوية
• 'extended': الإضافات الأخرى

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

Signature

registerInstructionGroup(type: string, group: { label: string }): void

Parameters

Example

export default class YourPluginClient extends Plugin {
  load() {
    const pluginWorkflow = this.app.pm.get(PluginWorkflowClient);

    pluginWorkflow.registerInstructionGroup('ai', { label: `{{t("AI", { ns: "${NAMESPACE}" })}}` });
  }
}

#Trigger

الفئة الأساسية للمشغلات، تُستخدم لتوسيع أنواع المشغلات المخصصة.

• إذا لم يتم تعيين useVariables، فهذا يعني أن هذا النوع من المشغلات لا يوفر وظيفة استرداد القيمة، ولا يمكن تحديد بيانات سياق المشغل في عقد سير العمل.

#Instruction

الفئة الأساسية للتعليمات، تُستخدم لتوسيع أنواع العقد المخصصة.

Related Types

export type NodeAvailableContext = {
  workflow: object;
  upstream: object;
  branchIndex: number;
};

• إذا لم يتم تعيين useVariables، فهذا يعني أن نوع العقدة هذا لا يوفر وظيفة استرداد القيمة، ولا يمكن تحديد بيانات نتيجة هذا النوع من العقد في عقد سير العمل. إذا كانت قيمة النتيجة مفردة (غير قابلة للتحديد)، فيمكنك إرجاع محتوى ثابت يعبر عن المعلومات المقابلة (انظر: الكود المصدري لعقدة الحساب). إذا كانت قابلة للتحديد (مثل خاصية في كائن)، فيمكنك تخصيص مخرج مكون التحديد المقابل (انظر: الكود المصدري لعقدة إنشاء البيانات).
• يُعد Component مكون عرض مخصصًا للعقدة. عندما لا يكون العرض الافتراضي للعقدة كافيًا، يمكن استبداله بالكامل لتخصيص عرض العقدة. على سبيل المثال، إذا كنت بحاجة إلى توفير المزيد من أزرار الإجراءات أو التفاعلات الأخرى لعقدة البداية من نوع الفرع، فستحتاج إلى استخدام هذه الطريقة (انظر: الكود المصدري للفرع المتوازي).
• يُستخدم useInitializers لتوفير طريقة لتهيئة الكتل. على سبيل المثال، في العقدة اليدوية، يمكنك تهيئة كتل المستخدم ذات الصلة بناءً على العقدة السابقة. إذا تم توفير هذه الطريقة، فستكون متاحة عند تهيئة الكتل في تكوين واجهة العقدة اليدوية (انظر: الكود المصدري لعقدة إنشاء البيانات).
• يُستخدم isAvailable بشكل أساسي لتحديد ما إذا كانت العقدة يمكن استخدامها (إضافتها) في البيئة الحالية. تتضمن البيئة الحالية سير العمل الحالي، والعقد السابقة، وفهرس الفرع الحالي.