إنتقل إلى المحتوى الرئيسي

التواصل عبر الوحدات المدارية (Cross-Orbital)

المصدر: tests/schemas/05-cross-orbital.orb

الوحدات المدارية مستقلة بذاتها، لكن التطبيقات الحقيقية تحتاج أن تتحدث الميزات مع بعضها. Orb يربط الوحدات المدارية من خلال ناقل أحداث مُنمَّط: وحدة مدارية تُرسل، وأخرى تستمع.

OrderLifecycleFulfillment/orders/track
Orbital Unit = Entity + Traits + Pages

النمط​

CartManager orbital          NotificationManager orbital
      |                               |
  CartActions trait              NotificationHandler trait
      |                               |
  emits: ITEM_ADDED  ──────────►  listens: ITEM_ADDED
  emits: CART_CLEARED ─────────►  listens: CART_CLEARED

الخصائص الأساسية:

  • emits - تُعلَن على السمة وعلى الوحدة المدارية (ما هي الأحداث التي تنشرها)
  • listens - تُعلَن على السمة (أي أحداث تتفاعل معها) وعلى الوحدة المدارية (أي وحدات مدارية تشترك فيها)
  • scope: "external" - تحدد الحدث كعابر لحدود الوحدات المدارية

الخطوة 1 - إعلان Emits على السمة المُرسلة​

السمة تُعلن الأحداث التي يمكنها نشرها، بما في ذلك عقد الحمولة:

{
  "اسم": "CartActions",
  "كيان_مرتبط": "Cart",
  "فئة": "interaction",
  "يصدر": [
    {
      "حدث": "ITEM_ADDED",
      "نطاق": "external",
      "وصف": "Emitted when an item is added to cart",
      "حمولة": [
        {
          "اسم": "itemCount",
          "نوع": "رقم",
          "مطلوب": true
        },
        {
          "اسم": "total",
          "نوع": "رقم",
          "مطلوب": true
        }
      ]
    }
  ],
  "آلة_حالة": {
    "...": "..."
  }
}

scope: "external" مطلوب للأحداث العابرة للوحدات المدارية. بدونه، يبقى الحدث داخلياً للسمة.

الخطوة 2 - إطلاق الحدث في الانتقال​

داخل effects للانتقال، استخدم ["emit", "EVENT_NAME", payload]:

{
  "من": "empty",
  "حدث": "ADD_ITEM",
  "إلى": "hasItems",
  "تأثيرات": [
    [
      "increment",
      "@كيان.itemCount",
      1
    ],
    [
      "تعيين",
      "@كيان.total",
      [
        "جمع",
        "@كيان.total",
        "@حمولة.price"
      ]
    ],
    [
      "بث",
      "ITEM_ADDED",
      {
        "itemCount": "@كيان.itemCount",
        "total": "@كيان.total"
      }
    ]
  ]
}

الخطوة 3 - إعلان Emits على مستوى الوحدة المدارية​

على مستوى الوحدة المدارية، اذكر كل حدث تنشره:

{
  "اسم": "CartManager",
  "كيان": {
    "...": "..."
  },
  "سمات": [
    {
      "...": "..."
    }
  ],
  "صفحات": [
    {
      "...": "..."
    }
  ],
  "يصدر": [
    "ITEM_ADDED",
    "CART_CLEARED"
  ]
}

الخطوة 4 - إعلان Listens على السمة المستقبلة​

السمة المستقبلة تُعلن الأحداث الخارجية التي تعالجها:

{
  "اسم": "NotificationHandler",
  "كيان_مرتبط": "Notification",
  "فئة": "interaction",
  "يستمع": [
    {
      "حدث": "ITEM_ADDED",
      "نطاق": "external"
    },
    {
      "حدث": "CART_CLEARED",
      "نطاق": "external"
    }
  ],
  "آلة_حالة": {
    "...": "..."
  }
}

هذه الأحداث تصبح مفاتيح أحداث صالحة في آلة الحالة. أضفها إلى events واكتب انتقالات لها.

الخطوة 5 - إعلان Listens على مستوى الوحدة المدارية​

على مستوى الوحدة المدارية المستقبلة، أعلن من أين تأتي الأحداث:

{
  "اسم": "NotificationManager",
  "كيان": {
    "...": "..."
  },
  "سمات": [
    {
      "...": "..."
    }
  ],
  "صفحات": [
    {
      "...": "..."
    }
  ],
  "يستمع": [
    {
      "حدث": "ITEM_ADDED",
      "من": "CartManager"
    },
    {
      "حدث": "CART_CLEARED",
      "من": "CartManager"
    }
  ]
}

قائمة التحقق: الأحداث عبر الوحدات المدارية​

استخدم هذه القائمة عند ربط وحدتين مداريتين:

  • السمة المُرسلة لديها "emits": [...] مع scope: "external" وعقد payload
  • انتقال الإرسال يستدعي ["emit", "EVENT_NAME", {...payload}] في effects
  • الوحدة المدارية المُرسلة لديها "emits": ["EVENT_NAME"] على المستوى الأعلى
  • السمة المستمعة لديها "listens": [{ "event": "EVENT_NAME", "scope": "external" }]
  • آلة حالة السمة المستمعة لديها الحدث في events وtransition له
  • الوحدة المدارية المستمعة لديها "listens": [{ "event": "EVENT_NAME", "from": "EmittingOrbital" }] على المستوى الأعلى

الخطوات التالية​