M365Con 2027 – konferensi online gratis · 11–22 Jan 2027 · 120 sessions m365con.net

Blog · Mirko Peters

Adaptive Card di Teams: Cara Menggunakan Designer, dengan Contoh

By ·

Cara merancang Adaptive Card untuk Microsoft Teams dengan Adaptive Card Designer, versi skema dan aksi yang didukung Teams, aturan tata letak untuk seluler, serta contoh JSON minimal.

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

Adaptive Card di Teams adalah deskripsi JSON dari sebagian kecil antarmuka yang ditampilkan Teams sebagai kartu pesan. Cara tercepat untuk membuatnya adalah dengan Adaptive Card Designer di browser: tambahkan elemen, salin JSON, lalu kirim dari bot atau aplikasi Anda. Panduan ini membahas alur kerja designer, fitur yang didukung Teams, aturan tata letak untuk menghindari kartu yang terpotong, serta contoh minimal.

Poin Penting

  • Designer Adaptive Card berbasis browser tersedia di adaptivecards.microsoft.com/designer.html. Tambahkan elemen secara visual, salin payload JSON, dan gunakan di aplikasi Anda.
  • Bot dan message extension Teams mendukung Adaptive Card skema versi 1.6 atau lebih lama, dan aplikasi seluler Teams mendukung hingga 1.6.
  • Incoming webhook mendukung semua elemen kartu native kecuali Action.Submit. Aksi yang didukung di sana meliputi Action.OpenURL, Action.ShowCard, Action.ToggleVisibility, dan Action.Execute.
  • Rancang untuk layar sempit terlebih dahulu, atur wrap ke true pada teks dan choice set, dan gunakan satu hingga tiga aksi utama, dengan maksimal enam.
  • Kartu di Teams tidak mendukung unggahan file atau gambar, dan properti isEnabled pada Action.Submit tidak didukung.

Catatan mengenai sumber: halaman Microsoft Learn yang dibaca untuk artikel ini tidak menjelaskan pemilih aplikasi host pada designer maupun editor data contoh untuk Teams. Langkah-langkah di bawah ini hanya mengikuti apa yang dinyatakan halaman tersebut.

Membuka designer

Dokumentasi Adaptive Cards mengarahkan ke designer berbasis browser di adaptivecards.microsoft.com/designer.html. Designer ini juga dapat disematkan ke aplikasi web Anda dengan paket npm adaptivecards-designer. Panduan Teams SDK dari Microsoft menjelaskan alur tiga langkah:

  1. Tambahkan elemen secara visual hingga kartu terlihat sesuai.
  2. Salin payload JSON dari panel editor.
  3. Tempelkan JSON ke proyek Anda, atau konversikan menjadi panggilan builder.

Jika Anda lebih suka editor, halaman alat Adaptive Cards mencantumkan ekstensi Visual Studio Code bernama Adaptive Card Viewer, yang menampilkan pratinjau kartu saat Anda mengedit file .json dengan properti $schema. Halaman itu juga mencantumkan AdaptiveCards Studio, yang memungkinkan Anda mengedit templat kartu dan data contoh di VS Code.

Yang didukung Teams

Referensi kartu Teams memberikan batasan berikut:

| Area | Dukungan yang didokumentasikan | |---|---| | Versi skema | Versi 1.6 atau lebih lama untuk kartu bot, ekstensi pesan, link unfurling, dan dialog | | Teams seluler | Hingga versi 1.6, versi yang lebih baru mungkin ditampilkan secara tidak konsisten | | Incoming webhooks | Semua elemen native kecuali Action.Submit | | Action.Submit | Properti isEnabled tidak didukung | | Gaya tindakan | Gaya positif atau destruktif tidak didukung | | Unggahan | Unggahan file atau gambar tidak didukung | | Surface | Bot, ekstensi pesan, dan Bot Framework ditandai didukung. Tab dan konektor ditandai tidak didukung. Incoming webhooks hanya mendukung Adaptive Cards untuk jenis konektor grup Microsoft 365. |

Dokumentasi SDK menambahkan bahwa paket kartunya menyertakan skema Adaptive Card v1.5 sebagai tipe ketat. Itu masih dalam batas versi 1.6.

Contoh minimal

Ini adalah struktur yang dikirim bot sebagai lampiran. Struktur ini diadaptasi dari format di halaman referensi kartu Teams. Kartu ditempatkan di content, dan contentType adalah 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" } ] } } ``

Properti wrap adalah tambahan berdasarkan panduan desain di bawah. Halaman ini juga menampilkan nilai dinamis dengan templating, misalnya blok teks yang nilai text-nya adalah ${titleText}.

Mengirim kartu

Referensi kartu tidak menyertakan panduan lengkap untuk pengiriman. Halaman tersebut mengarah ke contoh Bot Framework untuk .NET dan Node.js. Panduan Teams SDK menampilkan pola builder dengan paket untuk C# (Microsoft.Teams.Cards), Python (microsoft-teams-cards), dan TypeScript (@microsoft/teams.cards). Contoh Python singkat dari panduan membangun kartu dengan blok teks dan mengirimkannya dengan MessageActivityInput(text="Hello text!").add_card(card). Builder memvalidasi setiap properti terhadap skema, sehingga kesalahan tertangkap saat build.

Aturan tata letak untuk Teams

Panduan desain Microsoft mencakup aturan berikut:

  • Mulai dari layar sempit. Rancang untuk layar sempit terlebih dahulu. Kartu dapat diperbesar dengan baik, tetapi tidak diperkecil dengan baik.
  • Bungkus teks. Atur "wrap": true pada TextBlock, ColumnSet, dan Input.ChoiceSet.
  • Kolom. Gunakan lebih sedikit kolom agar tampilan seluler lebih baik. Panduan ini tidak memberikan batas jumlah kolom secara numerik.
  • Nilai lebar kolom. auto menyesuaikan lebar dengan konten dan cocok untuk kolom berisi tombol yang harus tetap terlihat penuh, stretch membagi lebar yang tersedia secara merata, angka biasa adalah proporsi, dan <number>px adalah lebar tetap yang sebaiknya tidak melebihi lebar perangkat. Jangan atur auto pada setiap kolom.
  • Gambar. Gunakan latar belakang transparan agar gambar menyesuaikan dengan tema Teams apa pun. Gambar 100 x 100 piksel yang ditampilkan pada 50 x 50 tetap tajam, tetapi sebaliknya akan pecah. Gunakan width dan height untuk mengontrol ukuran pasti.
  • Kartu lebar penuh. Uji pada tata letak sempit seperti seluler dan panel samping rapat agar konten tidak terpotong.
  • Tindakan. Gunakan satu hingga tiga tindakan utama, dengan maksimum enam.
  • Kontainer. Gunakan style untuk penekanan, selectAction untuk melampirkan tindakan, dan Action.ToggleVisibility untuk grup yang dapat diciutkan. Jangan gunakan kontainer untuk keperluan lain.

Microsoft juga mencantumkan jenis kartu berdasarkan penggunaannya, seperti Hero untuk artikel, Thumbnail untuk pesan sederhana yang dapat ditindaklanjuti, List untuk memilih dari sejumlah item, dan ChoiceSet untuk mengumpulkan beberapa input. Halaman desain mencatat bahwa panduannya adalah panduan Teams lama dan mengarahkan ke pusat dokumentasi Adaptive Cards sebagai sumber terkini untuk praktik desain terbaik.

Kesalahan umum

  1. Mendesain kartu lebar lalu menemukan di ponsel bahwa teks terpotong.
  2. Menggunakan versi skema di atas 1.6.
  3. Menggunakan Action.Submit dalam kartu webhook masuk.
  4. Menambahkan terlalu banyak tombol.
  5. Menggunakan lebar piksel tetap pada beberapa kolom.

Materi awal

Halaman desain menautkan ke repositori templat awal, Microsoft-Teams-Adaptive-Card-Samples di GitHub, dan ke Teams UI Kit di Figma yang mencakup tema, aksesibilitas, dan ukuran responsif.

Terkait

Sumber

FAQ

Di mana Adaptive Card Designer?

Microsoft Learn mengarahkan ke designer berbasis browser di adaptivecards.microsoft.com/designer.html. Dokumentasi Teams SDK menjelaskan alurnya: tambahkan elemen secara visual hingga kartu terlihat sesuai, salin payload JSON dari panel editor, lalu tempelkan ke proyek Anda atau konversikan menjadi panggilan builder.

Versi Adaptive Card apa yang didukung Teams?

Menurut dokumentasi platform Teams di Microsoft Learn, kartu yang dikirim bot, message extension berbasis aksi, message extension berbasis pencarian, link unfurling, dan dialog mendukung skema versi 1.6 atau lebih lama. Aplikasi seluler Teams mendukung hingga 1.6, dan versi yang lebih baru mungkin tidak ditampilkan dengan benar di sana.

Mengapa teks kartu saya terpotong di seluler?

Microsoft Learn menyarankan untuk mengatur wrap ke true pada TextBlock, ColumnSet, dan Input.ChoiceSet. Tanpa pengaturan ini, teks akan terpotong di seluler. Panduan tersebut juga menyarankan untuk merancang dari layar sempit terlebih dahulu dan menggunakan lebih sedikit kolom, yang tampil lebih baik di seluler.

Bisakah saya menggunakan Action.Submit dalam kartu incoming webhook?

Tidak. Referensi kartu Microsoft Learn menyatakan bahwa incoming webhook mendukung semua elemen Adaptive Card native kecuali Action.Submit. Gunakan Action.OpenURL, Action.ShowCard, Action.ToggleVisibility, atau Action.Execute sebagai gantinya.

Berapa banyak tombol yang sebaiknya dimiliki sebuah kartu?

Microsoft Learn merekomendasikan satu hingga tiga aksi utama dan memperbolehkan maksimal enam, dengan catatan bahwa lebih sedikit itu lebih baik. Panduan tersebut juga menyatakan bahwa kartu sebaiknya ringkas, karena kartu menjadi kurang berguna setelah tergulir keluar dari layar, terutama di saluran.

Entities in this article

Topik artikel ini:

Adaptive Cards – Produk Adaptive Cards Designer – Bagian dari Adaptive Cards Microsoft Teams – Alat kolaborasi dari Microsoft

Related articles

Artikel lain tentang Adaptive Cards:

RSS