البطاقات التكيفية في Teams: كيفية استخدام المصمم مع أمثلة
By Mirko Peters ·
كيفية تصميم بطاقة تكيفية لـ Microsoft Teams باستخدام Adaptive Card Designer، وما هي إصدارات المخطط والإجراءات التي يدعمها Teams، وقواعد التخطيط للأجهزة المحمولة، ومثال JSON مبسّط.
Automatically translated with AI from the original post. Read the English original
البطاقة التكيفية في Teams هي وصف بتنسيق JSON لجزء صغير من الواجهة يعرضه Teams كبطاقة رسالة. أسرع طريقة لإنشائها هي Adaptive Card Designer في المتصفح: أضف العناصر، وانسخ JSON، وأرسله من الروبوت أو التطبيق الخاص بك. يغطي هذا الدليل سير عمل المصمم، وما يدعمه Teams، وقواعد التخطيط التي تتجنب قطع البطاقات، ومثالًا مبسّطًا.
النقاط الرئيسية
- يقع Adaptive Card Designer المستند إلى المتصفح على العنوان adaptivecards.microsoft.com/designer.html. أضف العناصر بصريًا، وانسخ حمولة JSON واستخدمها في تطبيقك.
- تدعم روبوتات Teams وامتدادات الرسائل الإصدار 1.6 أو أقدم من مخطط البطاقات التكيفية، ويدعم تطبيق Teams للأجهزة المحمولة حتى الإصدار 1.6.
- تدعم Incoming Webhooks جميع عناصر البطاقات الأصلية باستثناء Action.Submit. وتشمل الإجراءات المدعومة هناك Action.OpenURL وAction.ShowCard وAction.ToggleVisibility وAction.Execute.
- صمّم للشاشات الضيقة أولًا، واضبط الخاصية wrap على القيمة true للنص وقوائم الاختيار، واستخدم من إجراء رئيسي واحد إلى ثلاثة، بحد أقصى ستة.
- لا تدعم البطاقات في Teams رفع الملفات أو الصور، كما أن الخاصية isEnabled في Action.Submit غير مدعومة.
ملاحظة حول المصادر: صفحات Microsoft Learn التي اعتُمدت في إعداد هذه المقالة لا تصف محدد تطبيق المضيف في المصمم ولا محرر بيانات العينة الخاص به لـ Teams. تلتزم الخطوات التالية بما تذكره الصفحات فقط.
افتح المصمم
تشير وثائق البطاقات التكيفية إلى مصمم يعمل في المتصفح على العنوان adaptivecards.microsoft.com/designer.html. ويمكن أيضًا تضمينه في تطبيق الويب الخاص بك باستخدام حزمة adaptivecards-designer من npm. يصف دليل Teams SDK من Microsoft سير عمل من ثلاث خطوات:
- أضف العناصر بصريًا حتى تبدو البطاقة كما تريد.
- انسخ حمولة JSON من لوحة المحرر.
- الصق JSON في مشروعك، أو حوّله إلى استدعاءات للمنشئ.
إذا كنت تفضّل محررًا، تسرد صفحة أدوات البطاقات التكيفية إضافةً لـ Visual Studio Code تُسمى Adaptive Card Viewer، تعرض معاينة للبطاقة أثناء تحرير ملف .json يحتوي على الخاصية $schema. كما تذكر AdaptiveCards Studio، الذي يتيح تحرير قوالب البطاقات وبيانات العينة داخل VS Code.
ما يدعمه Teams
يحدد مرجع بطاقات Teams الحدود التالية:
| المنطقة | الدعم الموثّق |
|---|---|
| إصدار المخطط | الإصدار 1.6 أو أقدم لبطاقات الروبوت وامتدادات الرسائل وتوسيع الروابط والحوارات |
| Teams على الجوال | حتى الإصدار 1.6، وقد تُعرض الإصدارات الأحدث بشكل غير متسق |
| Incoming webhooks | جميع العناصر الأصلية باستثناء Action.Submit |
| Action.Submit | الخاصية isEnabled غير مدعومة |
| أنماط الإجراءات | التنسيق الإيجابي أو المدمّر غير مدعوم |
| عمليات الرفع | رفع الملفات أو الصور غير مدعوم |
| الأسطح | الروبوتات وامتدادات الرسائل وBot Framework مُعلَّمة على أنها مدعومة. التبويبات والموصلات مُعلَّمة على أنها غير مدعومة. تدعم Incoming webhooks بطاقات Adaptive فقط لنوع موصل مجموعات Microsoft 365. |
وتضيف وثائق SDK أن حزم البطاقات الخاصة به تتضمن مخطط Adaptive Card v1.5 بأنواع صارمة (strict types). وهذا ضمن حد الإصدار 1.6.
مثال بسيط
هذه هي البنية التي يرسلها الروبوت كمرفق. وهي مقتبسة من التنسيق الوارد في صفحة مرجع بطاقات Teams. تُوضع البطاقة في content، وقيمة contentType هي application/vnd.microsoft.card.adaptive.
``json { "contentType": "application/vnd.microsoft.card.adaptive", "content": { "$schema": "http://adaptivecards.io/schemas/adaptive-card.json", "type": "AdaptiveCard", "version": "1.0", "body": [ { "type": "TextBlock", "text": "Publish Adaptive Card schema", "weight": "bolder", "size": "medium", "wrap": true } ], "actions": [ { "type": "Action.Submit", "title": "OK" } ] } } ``
خاصية wrap إضافة مبنية على إرشادات التصميم أدناه. وتعرض الصفحة أيضاً القيم الديناميكية باستخدام القوالب، مثل كتلة نص يكون فيها text هو ${titleText}.
إرسال البطاقة
لا يتضمن مرجع البطاقات شرحاً كاملاً لعملية الإرسال، بل يشير إلى نماذج Bot Framework لـ .NET وNode.js. ويعرض دليل Teams SDK نمط Builder مع حزم لـ C# (Microsoft.Teams.Cards) وPython (microsoft-teams-cards) وTypeScript (@microsoft/teams.cards). ويُظهر مثال قصير بلغة Python من الدليل بناء بطاقة تحتوي على كتلة نص وإرسالها باستخدام MessageActivityInput(text="Hello text!").add_card(card). وتتحقق أدوات Builder من كل خاصية مقابل المخطط، مما يلتقط الأخطاء وقت البناء.
قواعد التخطيط في Teams
تتضمن إرشادات تصميم Microsoft هذه القواعد:
- ابدأ بالشاشات الضيقة. صمّم أولاً للشاشات الضيقة. تتوسع البطاقات بشكل جيد نحو الأكبر، لكنها لا تتقلص بالشكل نفسه نحو الأصغر.
- التفاف النص. اضبط
"wrap": trueعلىTextBlockوColumnSetوInput.ChoiceSet. - الأعمدة. استخدم أعمدة أقل لعرض أفضل على الجوال. لا تحدد الإرشادات حداً عددياً للأعمدة.
- قيم عرض الأعمدة. تُكيّف
autoالعرض مع المحتوى، وهي مناسبة للأعمدة التي تحتوي على أزرار يجب أن تبقى ظاهرة بالكامل. أماstretchفتوزع العرض المتاح بالتساوي. والرقم المجرد يمثل نسبة، و<number>pxعرض ثابت ينبغي ألا يتجاوز عرض الجهاز. لا تضبطautoعلى كل الأعمدة. - الصور. استخدم خلفيات شفافة حتى تتكيف الصور مع أي سمة في Teams. تبقى صورة بحجم 100 × 100 بكسل واضحة عند عرضها بحجم 50 × 50، أما العكس فيسبب تشويش البكسلات. استخدم
widthوheightللتحكم في الحجم الدقيق. - البطاقات بعرض كامل. اختبرها في التخطيطات الضيقة، مثل الجوال والألواح الجانبية للاجتماعات، حتى لا يُقتطع المحتوى.
- الإجراءات. استخدم من إجراء أساسي إلى ثلاثة، بحد أقصى ستة.
- الحاويات. استخدم
styleللتأكيد، وselectActionلربط إجراء، وAction.ToggleVisibilityللمجموعات القابلة للطي. لا تستخدم الحاويات لأغراض أخرى.
تُصنّف Microsoft أيضاً أنواع البطاقات حسب الاستخدام، مثل Hero للمقالات، وThumbnail لرسالة بسيطة قابلة للإجراء، وList للاختيار من بين عناصر، وChoiceSet لجمع عدة مدخلات. وتشير صفحة التصميم إلى أن إرشاداتها هي دليل Teams القديم، وتحيل إلى مركز وثائق Adaptive Cards بوصفه المصدر الحالي لأفضل ممارسات التصميم.
الأخطاء الشائعة
- تصميم بطاقة عريضة ثم اكتشاف على الجوال أن النص مقطوع.
- استخدام إصدار مخطط أعلى من 1.6.
- استخدام Action.Submit في بطاقة Webhook واردة.
- إضافة عدد كبير جداً من الأزرار.
- استخدام عروض ثابتة بالبكسل في عدة أعمدة.
مواد البدء
تربط صفحة التصميم بمستودع لقوالب البدء، وهو Microsoft-Teams-Adaptive-Card-Samples على GitHub، وبـ Teams UI Kit في Figma الذي يغطي السمات وإمكانية الوصول والتحجيم المتجاوب.
ذات صلة
المصادر
- Microsoft Learn: أدوات Adaptive Cards
- Microsoft Learn: إنشاء أنواع البطاقات واستكشافها في Teams
- Microsoft Learn: تصميم Adaptive Cards لتطبيقك
- Microsoft Learn: بناء Adaptive Cards (Teams SDK)
FAQ
أين يقع Adaptive Card Designer؟
تشير وثائق Microsoft Learn إلى المصمم المستند إلى المتصفح على العنوان adaptivecards.microsoft.com/designer.html. توضح وثائق Teams SDK سير العمل: أضف العناصر بصريًا حتى تبدو البطاقة كما تريد، ثم انسخ حمولة JSON من لوحة المحرر، والصقها في مشروعك، أو حوّلها إلى استدعاءات للمنشئ.
ما إصدار البطاقات التكيفية الذي يدعمه Teams؟
وفقًا لوثائق منصة Teams في Microsoft Learn، تدعم البطاقات المرسلة من الروبوتات، وامتدادات الرسائل المستندة إلى الإجراءات، وامتدادات الرسائل المستندة إلى البحث، وتوسيع الروابط، والحوارات، الإصدار 1.6 أو أقدم من المخطط. يدعم تطبيق Teams للأجهزة المحمولة حتى الإصدار 1.6، وقد لا تُعرض الإصدارات الأحدث بشكل صحيح هناك.
لماذا يُقتطع نص البطاقة على الأجهزة المحمولة؟
تنص وثائق Microsoft Learn على ضبط الخاصية wrap على القيمة true في TextBlock وColumnSet وInput.ChoiceSet. فدونها يُقتطع النص على الأجهزة المحمولة. كما تنصح بالتصميم للشاشات الضيقة أولًا واستخدام أعمدة أقل، فهي تُعرض بشكل أفضل على الأجهزة المحمولة.
هل يمكنني استخدام Action.Submit في بطاقة Incoming Webhook؟
لا. يذكر مرجع بطاقات Microsoft Learn أن Incoming Webhooks تدعم جميع عناصر البطاقات التكيفية الأصلية باستثناء Action.Submit. استخدم بدلًا من ذلك Action.OpenURL أو Action.ShowCard أو Action.ToggleVisibility أو Action.Execute.
كم عدد الأزرار التي ينبغي أن تحتويها البطاقة؟
توصي وثائق Microsoft Learn بإجراء رئيسي واحد إلى ثلاثة، وتسمح بحد أقصى ستة، مع الإشارة إلى أن الأقل هو الأفضل. وتذكر أيضًا أن البطاقات ينبغي أن تبقى موجزة، لأنها تفقد فائدتها عندما تخرج من نطاق الرؤية بالتمرير، خاصةً في القنوات.