M365Con 2027 – כנס אונליין חינמי · 11–22 Jan 2027 · 120 sessions m365con.net

בלוג · Mirko Peters

כרטיסיות אדפטיביות ב-Teams: איך להשתמש ב-Designer, עם דוגמאות

By ·

איך לעצב כרטיס אדפטיבי ל-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 ושולחים אותו מהבוט או מהאפליקציה שלכם. המדריך הזה מכסה את תהליך העבודה ב-Designer, מה ש-Teams תומך בו, כללי פריסה שמונעים כרטיסים חתוכים, ודוגמה מינימלית.

עיקרי הדברים

  • ה-Adaptive Card Designer מבוסס הדפדפן נמצא בכתובת adaptivecards.microsoft.com/designer.html. מוסיפים רכיבים בצורה ויזואלית, מעתיקים את מטען ה-JSON ומשתמשים בו באפליקציה שלכם.
  • בוטים והרחבות הודעות של Teams תומכים בגרסת סכמה 1.6 של Adaptive Card או נמוכה ממנה, ו-Teams למובייל תומך עד 1.6.
  • webhooks נכנסים תומכים בכל רכיבי הכרטיס המקוריים, למעט Action.Submit. הפעולות הנתמכות שם כוללות את Action.OpenURL, Action.ShowCard, Action.ToggleVisibility ו-Action.Execute.
  • מעצבים קודם למסכים צרים, מגדירים wrap ל-true בטקסט ובקבוצות בחירה, ומשתמשים בפעולה ראשית אחת עד שלוש, עם מקסימום שש.
  • כרטיסים ב-Teams אינם תומכים בהעלאת קבצים או תמונות, והמאפיין isEnabled של Action.Submit אינו נתמך.

הערה לגבי המקורות: דפי Microsoft Learn שנקראו לכתבה הזו אינם מתארים את בוחר אפליקציית המארח של ה-Designer או את עורך נתוני הדוגמה שלו עבור Teams. השלבים שלהלן נשארים בתוך מה שהדפים כן קובעים.

פתיחת ה-Designer

התיעוד של Adaptive Cards מפנה ל-Designer מבוסס דפדפן בכתובת adaptivecards.microsoft.com/designer.html. אפשר גם להטמיע אותו באפליקציית רשת משלכם באמצעות חבילת ה-npm adaptivecards-designer. מדריך Teams SDK של Microsoft מתאר זרימה בת שלושה שלבים:

  1. מוסיפים רכיבים בצורה ויזואלית עד שהכרטיס נראה נכון.
  2. מעתיקים את מטען ה-JSON מחלונית העורך.
  3. מדביקים את ה-JSON בפרויקט שלכם, או ממירים אותו לקריאות builder.

אם אתם מעדיפים עורך, דף הכלים של Adaptive Cards מציין הרחבה ל-Visual Studio Code בשם Adaptive Card Viewer, שמציגה תצוגה מקדימה של הכרטיס בזמן עריכה של קובץ .json עם מאפיין $schema. הוא מציין גם את AdaptiveCards Studio, שמאפשר לערוך תבניות כרטיס ונתוני דוגמה ב-VS Code.

מה Teams תומך בו

עיון הכרטיסים של Teams מציין את המגבלות הבאות:

| תחום | תמיכה מתועדת | |---|---| | Schema version | גרסה 1.6 או מוקדמת יותר עבור כרטיסי בוט, הרחבות הודעה, יצירת תצוגה מקדימה לקישורים ותיבות דו-שיח | | Teams mobile | עד גרסה 1.6. גרסאות מאוחרות יותר עשויות להציג באופן לא עקבי | | Incoming webhooks | כל הרכיבים המקוריים למעט Action.Submit | | Action.Submit | מאפיין ה-isEnabled אינו נתמך | | Action styles | עיצוב חיובי או הרסני אינו נתמך | | Uploads | העלאת קבצים או תמונות אינה נתמכת | | Surfaces | בוטים, הרחבות הודעה ו-Bot Framework מסומנים כנתמכים. לשוניות (Tabs) ומחברים (connectors) מסומנים כלא נתמכים. Incoming webhooks תומכים ב-Adaptive Cards רק עבור סוג המחבר של קבוצות Microsoft 365. |

ערכות ה-SDK מוסיפות כי חבילות הכרטיסים שלהן כוללות את סכמת Adaptive Card v1.5 כטיפוסים מחמירים. זה נמצא בתוך המגבלה של גרסה 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. מדריך ה-SDK של Teams מציג תבנית builder עם חבילות עבור C# (Microsoft.Teams.Cards), Python (microsoft-teams-cards) ו-TypeScript (@microsoft/teams.cards). דוגמה קצרה ב-Python מהמדריך בונה כרטיס עם בלוק טקסט ושולחת אותו באמצעות MessageActivityInput(text="Hello text!").add_card(card). ה-builders בודקים כל מאפיין מול הסכמה, ולכן שגיאות נתפסות already בזמן הבנייה.

כללי פריסה ל-Teams

ההנחיות העיצוביות של Microsoft כוללות את הכללים הבאים:

  • קודם צר. תכננו קודם למסכים צרים. כרטיסים מתרחבים היטב, אבל לא מצטמצמים היטב.
  • עטיפת טקסט. הגדירו "wrap": true ב-TextBlock, ב-ColumnSet וב-Input.ChoiceSet.
  • עמודות. השתמשו בפחות עמודות לתצוגה טובה יותר במכשירים ניידים. ההנחיות אינן מציינות מגבלה מספרית לעמודות.
  • ערכי רוחב עמודה. auto מתאים את הרוחב לתוכן ומתאים לעמודות עם כפתורים שחייבים להישאר גלויים במלואם, stretch מחלק את הרוחב הזמין באופן שווה, מספר רגיל הוא פרופורציה, ו-<number>px הוא רוחב קבוע שלא צריך לעלות על רוחב המכשיר. אל תגדירו auto בכל העמודות.
  • תמונות. השתמשו ברקעים שקופים כדי שהתמונות יתאימו לכל ערכת נושא של Teams. תמונה בגודל 100 על 100 פיקסלים שמוצגת בגודל 50 על 50 נשארת חדה, אבל ההפך גורם לפיקסול. השתמשו ב-width וב-height כדי לשלוט בגודל המדויק.
  • כרטיסים ברוחב מלא. בדקו אותם בפריסות צרות, כמו נייד ו-panels צדדיים בפגישות, כדי שהתוכן לא ייחתך.
  • פעולות. השתמשו בפעולה ראשית אחת עד שלוש, ולכל היותר שש.
  • מיכלים. השתמשו ב-style להדגשה, ב-selectAction לחיבור פעולה, וב-Action.ToggleVisibility לקבוצות שניתנות לכיווץ. אל תשתמשו במיכלים למטרות אחרות.

Microsoft מפרטת גם סוגי כרטיסים לפי שימוש, למשל Hero לכתבות, Thumbnail להודעה פעילה פשוטה, List לבחירה מתוך פריטים, ו-ChoiceSet לאיסוף כמה קלטים. דף העיצוב מציין שההנחיות שלו הן מדריך Teams מדור קודם, ומפנה לאתר התיעוד של Adaptive Cards כמקור העדכני לשיטות עבודה מומלצות בעיצוב.

טעויות נפוצות

  1. תכנון כרטיס רחב וגילוי בנייד שהטקסט נחתך.
  2. שימוש בגרסת סכמה גבוהה מ-1.6.
  3. שימוש ב-Action.Submit בכרטיס של webhook נכנס.
  4. הוספת יותר מדי כפתורים.
  5. שימוש ברוחבים קבועים בפיקסלים בכמה עמודות.

חומרי פתיחה

דף התכנון מקשר למאגר של תבניות פתיחה, Microsoft-Teams-Adaptive-Card-Samples ב-GitHub, וגם לערכת UI של Teams ב-Figma שמכסה עיצוב ערכות נושא, נגישות וגודל רספונסיבי.

קישורים קשורים

מקורות

עקבו אחרי הפודקאסטApple PodcastsSpotify

FAQ

איפה נמצא Adaptive Card Designer?

Microsoft Learn מפנה ל-Designer מבוסס הדפדפן בכתובת adaptivecards.microsoft.com/designer.html. התיעוד של Teams SDK מתאר את תהליך העבודה: מוסיפים רכיבים בצורה ויזואלית עד שהכרטיס נראה נכון, מעתיקים את מטען ה-JSON מחלונית העורך, ומדביקים אותו בפרויקט או ממירים אותו לקריאות builder.

איזו גרסה של Adaptive Card ש-Teams תומך בה?

לפי התיעוד של פלטפורמת Teams ב-Microsoft Learn, כרטיסים שנשלחים מבוטים, הרחבות הודעות מבוססות פעולות, הרחבות הודעות מבוססות חיפוש, הרחבת קישורים ו-dialogs תומכים בגרסת סכמה 1.6 או נמוכה ממנה. אפליקציית Teams למובייל תומכת עד 1.6, וגרסאות מאוחרות יותר עלולות שלא להיטען שם כראוי.

למה הטקסט בכרטיס שלי נחתך במובייל?

Microsoft Learn קובע להגדיר wrap ל-true ב-TextBlock, ב-ColumnSet וב-Input.ChoiceSet. בלי זה הטקסט נחתך במובייל. התיעוד ממליץ גם לעצב קודם למסכים צרים ולהשתמש בפחות עמודות, שמוצגות טוב יותר במובייל.

אפשר להשתמש ב-Action.Submit בכרטיס של webhook נכנס?

לא. עיון הכרטיסים ב-Microsoft Learn קובע ש-webhooks נכנסים תומכים בכל רכיבי Adaptive Card המקוריים, למעט Action.Submit. במקומו השתמשו ב-Action.OpenURL, Action.ShowCard, Action.ToggleVisibility או Action.Execute.

כמה כפתורים צריך שיהיו בכרטיס?

Microsoft Learn ממליץ על פעולה ראשית אחת עד שלוש, ומתיר עד שישה לכל היותר, ומציין שפחות זה יותר. הוא מוסיף שכרטיסים צריכים להישאר תמציתיים, כי הם מאבדים מערכם ברגע שהם יוצאים משטח הצפייה, במיוחד בערוצים.

Entities in this article

הנושאים של המאמר הזה:

Adaptive Cards – מוצר Adaptive Cards Designer – חלק מ-Adaptive Cards Microsoft Teams – כלי לשיתוף פעולה של Microsoft

Related articles

מאמרים נוספים על Adaptive Cards:

RSS