M365Con 2027 – 무료 온라인 컨퍼런스 · 11–22 Jan 2027 · 120 sessions m365con.net

블로그 · Mirko Peters

Teams의 Adaptive Card: Designer 사용법과 예제

By ·

Adaptive Card Designer로 Microsoft Teams용 Adaptive Card를 설계하는 방법을 다룹니다. Teams가 지원하는 스키마 버전과 액션, 모바일 레이아웃 규칙, 최소한의 JSON 예제를 함께 설명합니다.

Automatically translated with AI from the original post. Read the English original

Teams의 Adaptive Card는 Teams가 메시지 카드로 렌더링하는 작은 인터페이스를 설명하는 JSON입니다. 가장 빠르게 만드는 방법은 브라우저의 Adaptive Card Designer를 사용하는 것입니다. 요소를 추가하고 JSON을 복사한 뒤 봇이나 앱에서 전송하면 됩니다. 이 가이드에서는 디자이너 작업 흐름, Teams가 지원하는 기능, 카드가 잘리지 않도록 하는 레이아웃 규칙, 최소한의 예제를 다룹니다.

핵심 포인트

  • 브라우저 기반 Adaptive Card Designer는 adaptivecards.microsoft.com/designer.html에서 사용할 수 있습니다. 요소를 시각적으로 추가하고, JSON 페이로드를 복사하여 앱에서 사용하세요.
  • Teams 봇과 메시지 확장은 Adaptive Card 스키마 버전 1.6 이하를 지원하며, Teams 모바일은 1.6까지 지원합니다.
  • 들어오는 웹후크는 Action.Submit을 제외한 모든 기본 카드 요소를 지원합니다. 지원되는 액션에는 Action.OpenURL, Action.ShowCard, Action.ToggleVisibility, Action.Execute가 포함됩니다.
  • 먼저 좁은 화면을 기준으로 설계하고, 텍스트와 선택 세트에는 wrap을 true로 설정하세요. 기본 작업은 1~3개를 사용하고, 최대 6개를 넘기지 마세요.
  • Teams의 카드는 파일 또는 이미지 업로드를 지원하지 않으며, Action.Submit의 isEnabled 속성도 지원되지 않습니다.

출처에 대한 참고 사항입니다. 이 글을 작성하면서 참고한 Microsoft Learn 페이지에는 디자이너의 호스트 앱 선택기나 Teams용 샘플 데이터 편집기에 대한 설명이 없습니다. 아래 단계는 해당 페이지에 명시된 내용만 따릅니다.

디자이너 열기

Adaptive Cards 문서는 브라우저 기반 디자이너인 adaptivecards.microsoft.com/designer.html을 안내합니다. 또한 adaptivecards-designer npm 패키지를 사용해 자체 웹 앱에 포함할 수도 있습니다. Microsoft의 Teams SDK 가이드는 다음 세 단계 흐름을 설명합니다.

  1. 카드가 원하는 모습이 될 때까지 요소를 시각적으로 추가합니다.
  2. 편집기 창에서 JSON 페이로드를 복사합니다.
  3. JSON을 프로젝트에 붙여 넣거나 빌더 호출 코드로 변환합니다.

편집기를 선호한다면, Adaptive Cards 도구 페이지에 Adaptive Card Viewer라는 Visual Studio Code 확장도 나와 있습니다. 이 확장은 $schema 속성이 있는 .json 파일을 편집하는 동안 카드를 미리 보여 줍니다. 또한 AdaptiveCards Studio도 소개되어 있는데, VS Code에서 카드 템플릿과 샘플 데이터를 편집할 수 있습니다.

Teams가 지원하는 기능

Teams 카드 참조 문서에는 다음 제한 사항이 나와 있습니다.

| 영역 | 공식 지원 범위 | |---|---| | 스키마 버전 | 봇 카드, 메시지 확장, 링크 미리 보기, 대화 상자에는 버전 1.6 이하 | | Teams 모바일 | 버전 1.6까지. 그 이후 버전에서는 렌더링이 일관되지 않을 수 있음 | | 수신 웹후크 | Action.Submit을 제외한 모든 기본 요소 | | Action.Submit | isEnabled 속성은 지원되지 않음 | | 작업 스타일 | 긍정 또는 파괴적 스타일은 지원되지 않음 | | 업로드 | 파일 또는 이미지 업로드는 지원되지 않음 | | 표면 | 봇, 메시지 확장, Bot Framework는 지원됨으로 표시됨. 탭과 커넥터는 지원되지 않음으로 표시됨. 수신 웹후크는 Microsoft 365 그룹 커넥터 유형에 한해서만 Adaptive Cards를 지원함 |

SDK 문서에 따르면, 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}인 텍스트 블록이 있습니다.

카드 보내기

카드 참조 문서에는 보내기 과정에 대한 전체 설명이 없습니다. 대신 .NET과 Node.js용 Bot Framework 샘플을 안내합니다. Teams SDK 가이드에서는 빌더 패턴을 보여 주며, C#(Microsoft.Teams.Cards), Python(microsoft-teams-cards), TypeScript(@microsoft/teams.cards) 패키지를 제공합니다. 가이드의 짧은 Python 예제는 텍스트 블록이 있는 카드를 만든 뒤 MessageActivityInput(text="Hello text!").add_card(card)로 보냅니다. 빌더는 모든 속성을 스키마에 맞춰 검증하므로 오류를 빌드 시점에 찾아낼 수 있습니다.

Teams의 레이아웃 규칙

Microsoft의 디자인 가이드에는 다음 규칙이 있습니다.

  • 좁은 화면을 먼저 고려하십시오. 카드는 화면이 넓어질 때는 잘 확장되지만 좁아질 때는 잘 줄어들지 않으므로 좁은 화면을 먼저 기준으로 설계하십시오.
  • 텍스트를 줄바꿈하십시오. TextBlock, ColumnSet, Input.ChoiceSet에 "wrap": true를 설정하십시오.
  • 열. 모바일에서 더 잘 보이도록 열 수를 줄이십시오. 가이드에는 열 수의 구체적인 상한이 제시되어 있지 않습니다.
  • 열 너비 값. auto는 내용에 맞게 크기가 정해지므로 완전히 보여야 하는 버튼이 있는 열에 적합합니다. stretch는 사용 가능한 너비를 균등하게 나눕니다. 숫자만 지정하면 비율이 됩니다. <number>px는 고정 너비이며 기기 너비를 넘지 않아야 합니다. 모든 열에 auto를 설정하지 마십시오.
  • 이미지. 어떤 Teams 테마에도 맞도록 배경을 투명하게 하십시오. 100×100픽셀 이미지를 50×50으로 표시하면 선명하게 보이지만, 반대로 하면 픽셀이 깨집니다. 정확한 크기는 width와 height로 조절하십시오.
  • 전체 너비 카드. 모바일이나 모임 측면 패널과 같은 좁은 레이아웃에서 테스트하여 내용이 잘리지 않는지 확인하십시오.
  • 작업. 기본 작업은 1~3개를 사용하고, 최대 6개를 넘기지 마십시오.
  • 컨테이너. 강조에는 style을, 작업을 연결할 때는 selectAction을, 접을 수 있는 그룹에는 Action.ToggleVisibility를 사용하십시오. 다른 용도로 컨테이너를 사용하지 마십시오.

Microsoft는 용도에 따라 카드 유형도 소개합니다. 예를 들어 글에는 Hero, 간단한 실행 가능 메시지에는 Thumbnail, 항목 중 선택에는 List, 여러 입력을 받을 때는 ChoiceSet을 사용합니다. 디자인 페이지에는 이 가이드가 기존 Teams 가이드이며, 최신 디자인 모범 사례는 Adaptive Cards 문서 허브를 참고하라고 나와 있습니다.

흔한 실수

  1. 넓은 카드를 설계했는데 모바일에서 텍스트가 잘리는 것을 뒤늦게 발견하는 경우
  2. 버전 1.6을 초과하는 스키마 버전을 사용하는 경우
  3. 수신 웹후크 카드에서 Action.Submit 사용하기
  4. 버튼을 너무 많이 추가하기
  5. 여러 열에 고정 픽셀 너비를 사용하기

시작용 자료

디자인 페이지에는 시작용 템플릿 저장소인 GitHub의 Microsoft-Teams-Adaptive-Card-Samples와, 테마, 접근성, 반응형 크기 조정을 다루는 Figma의 Teams UI Kit로 연결되는 링크가 있습니다.

관련 자료

데이터 원본

쇼 팔로우하기Apple PodcastsSpotify

FAQ

Adaptive Card Designer는 어디에 있나요?

Microsoft Learn은 브라우저 기반 디자이너인 adaptivecards.microsoft.com/designer.html을 안내합니다. Teams SDK 문서에서 설명하는 작업 흐름은 다음과 같습니다. 카드가 원하는 모습이 될 때까지 요소를 시각적으로 추가한 다음, 편집기 창에서 JSON 페이로드를 복사하고, 이를 프로젝트에 붙여 넣거나 빌더 호출 코드로 변환합니다.

Teams는 어떤 Adaptive Card 버전을 지원하나요?

Microsoft Learn의 Teams 플랫폼 문서에 따르면, 봇이 보내는 카드, 작업 기반 메시지 확장, 검색 기반 메시지 확장, 링크 미리 보기, 대화 상자는 스키마 버전 1.6 이하를 지원합니다. Teams 모바일 앱은 1.6까지 지원하며, 그 이후 버전은 모바일에서 올바르게 렌더링되지 않을 수 있습니다.

모바일에서 카드 텍스트가 잘리는 이유는 무엇인가요?

Microsoft Learn에서는 TextBlock, ColumnSet, Input.ChoiceSet에 wrap을 true로 설정하라고 안내합니다. 이 설정이 없으면 모바일에서 텍스트가 잘립니다. 또한 좁은 화면을 기준으로 먼저 설계하고, 모바일에서 더 잘 보이는 적은 수의 열을 사용하라고 권장합니다.

들어오는 웹후크 카드에서 Action.Submit을 사용할 수 있나요?

아니요, 사용할 수 없습니다. Microsoft Learn의 카드 참조 문서에 따르면 들어오는 웹후크는 Action.Submit을 제외한 모든 기본 Adaptive Card 요소를 지원합니다. 대신 Action.OpenURL, Action.ShowCard, Action.ToggleVisibility 또는 Action.Execute를 사용하세요.

카드에는 버튼을 몇 개까지 넣는 것이 좋나요?

Microsoft Learn은 기본 작업을 1~3개로 권장하며 최대 6개까지 허용합니다. 적을수록 좋다고도 설명합니다. 또한 카드는 간결해야 한다고 강조합니다. 특히 채널에서는 카드가 화면 밖으로 스크롤되면 유용성이 떨어지기 때문입니다.

Entities in this article

이 글의 주제:

Adaptive Cards – 제품 Adaptive Cards Designer – Adaptive Cards의 일부 Microsoft Teams – Microsoft의 공동 작업 도구

Related articles

Adaptive Cards에 관한 다른 글:

RSS