---
read_when:
    - إنشاء عملاء Matrix يعرضون استجابات OpenClaw الغنية
    - تصحيح أخطاء محتوى حدث com.openclaw.presentation
summary: بيانات Matrix الوصفية لـ MessagePresentation للعملاء المتوافقين مع OpenClaw
title: بيانات Matrix الوصفية للعرض
x-i18n:
    generated_at: "2026-07-12T05:35:35Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: c0de4d13c6cefc6f91dcc7a4b0edeea6bf001f3bd71f52c9f0498ad422783d8a
    source_path: channels/matrix-presentation.md
    workflow: 16
---

يرفق OpenClaw بيانات تعريف `MessagePresentation` الموحّدة بأحداث Matrix الصادرة من النوع `m.room.message` ضمن مفتاح المحتوى `com.openclaw.presentation`.

تستمر تطبيقات Matrix القياسية في عرض النص العادي في `body`. ويمكن للتطبيقات المتوافقة مع OpenClaw قراءة بيانات التعريف المنظّمة وعرض واجهة مستخدم أصلية، مثل الأزرار وقوائم الاختيار وصفوف السياق والفواصل.

## محتوى الحدث

```json
{
  "msgtype": "m.text",
  "body": "Select model\n\nChoose model:\n- DeepSeek",
  "com.openclaw.presentation": {
    "version": 1,
    "type": "message.presentation",
    "title": "Select model",
    "tone": "info",
    "blocks": [
      {
        "type": "select",
        "placeholder": "Choose model",
        "options": [
          {
            "label": "DeepSeek",
            "value": "/model deepseek/deepseek-chat"
          }
        ]
      }
    ]
  }
}
```

- يمثّل `version` إصدار مخطط بيانات التعريف؛ والإصدار الحالي هو `1`. أما `type` فهو مُميّز ثابت، وقيمته دائمًا `"message.presentation"`. ولا يُصدر محوّل Matrix إلا حمولات تحمل هذا الإصدار والنوع بالضبط؛ وبالمثل، ينبغي للتطبيقات تجاهل الإصدارات غير المعروفة التي لا يمكنها تفسيرها بأمان، وقيم `type` غير المعروفة، وأنواع الكتل غير المعروفة.
- يُعدّ `title` و`tone` (`info`، و`success`، و`warning`، و`danger`، و`neutral`) تلميحين اختياريين.
- يمكن للأزرار وخيارات قوائم الاختيار أن تحمل `action` ذا نوع محدد (`{ "type": "command", "command": "/..." }` أو `{ "type": "callback", "value": "..." }`) إلى جانب السلسلة القديمة `value`. فضّل `action` عند وجود كليهما.

## سلوك الرجوع الاحتياطي

يعرض OpenClaw دائمًا نصًا عاديًا احتياطيًا قابلًا للقراءة داخل `body`. وتُعدّ بيانات التعريف المنظّمة إضافة اختيارية، ويجب ألا تكون مطلوبة لتحقيق التوافق الأساسي مع Matrix.

قواعد العرض الاحتياطي:

- يُعرض محتوى `title` و`text` و`context` كأسطر نصية عادية.
- تُعرض الأزرار التي تتضمن إجراء `command` بالصيغة ``label: `/command` `` حتى يبقى الأمر قابلًا للنسخ. أما الأزرار التي تتضمن إجراء `callback` أو قيمة `value` قديمة فقط، فتُعرض بتسميتها وحدها كي تظل قيم الاستدعاء غير الشفافة خاصة؛ وتُعرض الأزرار المعطّلة دائمًا بتسميتها وحدها. وتُعرض أزرار عناوين URL وتطبيقات الويب بالصيغة `label: URL`.
- تعرض كتل الاختيار النص النائب (أو `Options:`) كعنوان، متبوعًا بأسطر خيارات تحتوي على التسميات فقط.
- إذا لم يُعرض أي شيء، كما في عرض تقديمي لا يحتوي إلا على فاصل، يرجع النص في `body` إلى `---`.

تستمر التطبيقات غير المدعومة في إظهار النص الاحتياطي. ويمكن للتطبيقات المتوافقة مع OpenClaw تفضيل بيانات التعريف المنظّمة للعرض، مع الاحتفاظ بالنص الاحتياطي لأغراض النسخ والبحث والإشعارات وإمكانية الوصول.

## الكتل المدعومة

يعلن محوّل Matrix الصادر عن دعم أصلي لما يلي:

- `buttons`
- `select`
- `context`
- `divider`

تُدعم كتل `text` دائمًا عبر النص الاحتياطي في `body`. تعامل مع جميع الكتل كتلميحات عرض تُطبّق بأفضل جهد ممكن؛ وتجاهل الحقول وأنواع الكتل غير المعروفة بدلًا من رفض الرسالة بأكملها.

## التفاعلات

لا تضيف بيانات التعريف هذه دلالات استدعاء إلى Matrix. تمثّل قيم الأزرار وقوائم الاختيار حمولات تفاعل احتياطية، وتكون عادةً أوامر تبدأ بشرطة مائلة أو أوامر نصية. وعلى تطبيق Matrix الذي يريد دعم التفاعل أن يستخرج قيمة عنصر التحكم (`action.command`، ثم `action.value`، ثم `value`) ويرسلها مجددًا إلى الغرفة كرسالة عادية.

على سبيل المثال، يمكن التعامل مع زر قيمته `/model deepseek/deepseek-chat` بإرسال تلك القيمة كرسالة Matrix نصية مشفّرة في الغرفة نفسها.

## العلاقة ببيانات تعريف الموافقة

يُستخدم `com.openclaw.presentation` للعرض العام للرسائل الغنية.

تستخدم مطالبات الموافقة بيانات التعريف المخصصة `com.openclaw.approval` لأن الموافقات تحمل حالة وقرارات وتفاصيل تنفيذ/Plugin حساسة للسلامة. وإذا وُجد مفتاحا بيانات التعريف كلاهما في الحدث نفسه، فينبغي للتطبيقات تفضيل عارض الموافقة المخصص.

## رسائل الوسائط

عندما يحتوي الرد على عدة عناوين URL لوسائط، يرسل OpenClaw حدث Matrix واحدًا لكل عنوان URL لوسيط. ولا يُرفق نص التسمية التوضيحية وبيانات تعريف العرض إلا بالحدث الأول، بحيث تحصل التطبيقات على حمولة منظّمة واحدة ثابتة دون عارضات مكررة. وتنطبق القاعدة نفسها عند تقسيم النص الطويل على عدة أحداث: تُرفق بيانات التعريف بالحدث الأول فقط.

حافظ على إيجاز بيانات تعريف العرض. وينبغي أن يبقى النص الكبير الظاهر للمستخدم في `body` وأن يستخدم مسار تقسيم نص Matrix المعتاد.