الأزرار والقوائم والنماذج

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

ما تحتاج إليه

نية الاتصال INTERACTIONS. تصل كل نقرة في صورة InteractionCreate من نوع Component، وكل نموذج من نوع ModalSubmit. ولكليهما الثواني الثلاث نفسها كالأمر: انظر المهل الزمنية.

الأزرار

في الرسالة components، وهي قائمة كتل. يحمل ActionRow حتى خمسة أزرار أو قائمة اختيار واحدة.

{
  "content": "Heads or tails?",
  "components": [
    {
      "type": "ActionRow",
      "components": [
        { "type": "Button", "style": "Primary", "label": "Heads", "custom_id": "flip:heads" },
        { "type": "Button", "style": "Secondary", "label": "Tails", "custom_id": "flip:tails" },
        { "type": "Button", "style": "Link", "label": "Rules", "url": "https://example.com/rules" }
      ]
    }
  ]
}

ضع ما تحتاج إليه في custom_id، مثل flip:heads أو note:3، فيعود إليك في interaction.component.custom_id. رد بـUpdateMessage لتغيير الرسالة، أو Message لرسالة جديدة.

لا تحمل الرسالة الأولى في الموضوع مكوّنات بعد. ابدأ الموضوع، ثم أرسل الرسالة ذات الأزرار فيه؛ انظر القنوات والويب هوك.

من يستطيع النقر

{ "restrict": { "users": ["USER_ID"], "roles": ["ROLE_ID"] } }

حتى 25 معرّفًا لكل منهما. يرفض السيرفر نقرات غيرهم، فلا يراها بوتك. لا يصلح لأزرار Link ولا لحقول النماذج.

قوائم الاختيار

تأخذ كلها custom_id وplaceholder (حتى 150) وmin_values وmax_values (من 0 إلى 25، والافتراضي 1) وdisabled وrestrict.

لعنصر options الحقلان label وvalue (كل منهما حتى 100، في سطر واحد)، وله أن يحمل description وemoji وdefault. القيم فريدة.

{
  "type": "ActionRow",
  "components": [
    {
      "type": "StringSelect",
      "custom_id": "colour",
      "placeholder": "Pick a colour",
      "options": [
        { "label": "Red", "value": "red" },
        { "label": "Blue", "value": "blue" }
      ]
    }
  ]
}

يصل الاختيار في interaction.component.values. وتأتي المستخدمون والأدوار والقنوات كائنات أيضًا في interaction.component.resolved.

كتل التخطيط

للصورة url أو attachment (معرّف ملف في الرسالة نفسها)، ولها أن تحمل description وspoiler. لا تتداخل الحاويات.

حدود الرسالة

تتخطى التطبيقات الكتل التي لا تعرفها. أما الويب هوك الذي لا يتبع بوتًا فلا ينشر إلا كتلًا لا يمكن التفاعل معها: نصوصًا وصورًا وأزرار روابط.

النماذج

يفتح النموذج على شاشة الشخص ردًا على أمر أو نقرة. لا يكون ردًا على نموذج آخر ولا على إكمال تلقائي.

{
  "type": "Modal",
  "modal": {
    "custom_id": "note-form",
    "title": "New note",
    "components": [
      {
        "type": "Field",
        "label": "Title",
        "description": "Short and clear.",
        "component": {
          "type": "TextInput",
          "custom_id": "title",
          "style": "Short",
          "max_length": 80
        }
      }
    ]
  }
}

لحقل title حتى 45 حرفًا. في النموذج حتى 5 حقول، وحتى 10 كتل مع Text. يحمل Field الحقول label وdescription (حتى 100) وcomponent واحدًا:

required يساوي true ما لم تحدد غير ذلك. يسرد file_types القيم image أو video أو audio أو امتدادًا مثل .pdf.

حين يرسل الشخص النموذج يصلك تفاعل من نوع ModalSubmit:

{
  "custom_id": "note-form",
  "fields": [{ "custom_id": "title", "value": "Hello" }]
}

رد خلال 3 ثوانٍ. لا يعمل UpdateMessage إلا إذا فُتح النموذج من زر.

قد يغلق الشخص النموذج ولا يسمع بوتك شيئًا، فلا تنتظره.

الأخطاء الشائعة

التالي

• ابنِ بوتًا كاملًا
• ألعاب بالأزرار