SDK Templat Kartu yang Adaptif

SDK Templat Kartu Adaptif memudahkan untuk mengisi templat kartu dengan data nyata di platform yang didukung.

Silakan baca ini untuk gambaran umum Templat Kartu Adaptif

Penting

Perubahan yang Memutus dalam Kandidat Rilis Mei 2020

Kami telah bekerja keras untuk pembuatan templat, dan akhirnya kami berada di tahap akhir! Kami harus membuat beberapa perubahan kecil saat kami menutup rilis.

Perubahan mencolok per Mei 2020

1. Sintaks pengikatan diubah dari {...} ke ${...}.
   • Misalnya: "text": "Hello {name}" menjadi "text": "Hello ${name}"
2. API JavaScript tidak lagi berisi EvaluationContext objek. Cukup teruskan data Anda ke fungsi expand. Silakan lihat halaman SDK untuk detail selengkapnya.
3. API .NET didesain ulang agar lebih cocok dengan API JavaScript. Silakan di bawah ini untuk detail lengkapnya.

JavaScript

Pustaka templat kartu adaptif tersedia di npm dan melalui CDN. Lihat tautan paket untuk dokumentasi lengkap.

npm

npm install adaptivecards-templating

CDN

<script src="https://unpkg.com/adaptivecards-templating/dist/adaptivecards-templating.min.js"></script>

Penggunaan

Sampel di bawah ini mengasumsikan Anda juga telah menginstal pustaka kartu adaptif untuk merender kartu.

Jika Anda tidak berencana untuk merender kartu, Anda bisa menghapus kode parse dan render.

import * as ACData from "adaptivecards-templating";
import * as AdaptiveCards from "adaptivecards";
 
// Define a template payload
var templatePayload = {
    "type": "AdaptiveCard",
    "version": "1.0",
    "body": [
        {
            "type": "TextBlock",
            "text": "Hello ${name}!"
        }
    ]
};
 
// Create a Template instance from the template payload
var template = new ACData.Template(templatePayload);
 
// Expand the template with your `$root` data object.
// This binds it to the data and produces the final Adaptive Card payload
var cardPayload = template.expand({
   $root: {
      name: "Matt Hidinger"
   }
});
 
// OPTIONAL: Render the card (requires that the adaptivecards library be loaded)
var adaptiveCard = new AdaptiveCards.AdaptiveCard();
adaptiveCard.parse(cardPayload);
document.getElementById('exampleDiv').appendChild(adaptiveCard.render());

.NET

dotnet add package AdaptiveCards.Templating

Penggunaan

// Import the library 
using AdaptiveCards.Templating;

var templateJson = @"
{
    ""type"": ""AdaptiveCard"",
    ""version"": ""1.2"",
    ""body"": [
        {
            ""type"": ""TextBlock"",
            ""text"": ""Hello ${name}!""
        }
    ]
}";

// Create a Template instance from the template payload
AdaptiveCardTemplate template = new AdaptiveCardTemplate(templateJson);

// You can use any serializable object as your data
var myData = new
{
    Name = "Matt Hidinger"
};

// "Expand" the template - this generates the final Adaptive Card payload
string cardJson = template.Expand(myData);

Fungsi Kustom

Fungsi kustom dapat ditambahkan ke Pustaka Ekspresi Adaptif selain fungsi bawaan.

Dalam contoh di bawah ini, fungsi kustom stringFormat ditambahkan, dan funtion digunakan untuk memformat string.

string jsonTemplate = @"{
    ""type"": ""AdaptiveCard"",
    ""version"": ""1.0"",
    ""body"": [{
        ""type"": ""TextBlock"",
        ""text"": ""${stringFormat(strings.myName, person.firstName, person.lastName)}""
    }]
}";

string jsonData = @"{
    ""strings"": {
        ""myName"": ""My name is {0} {1}""
    },
    ""person"": {
        ""firstName"": ""Andrew"",
        ""lastName"": ""Leader""
    }
}";

AdaptiveCardTemplate template = new AdaptiveCardTemplate(jsonTemplate);

var context = new EvaluationContext
{
    Root = jsonData
};

// a custom function is added
AdaptiveExpressions.Expression.Functions.Add("stringFormat", (args) =>
{
    string formattedString = "";

    // argument is packed in sequential order as defined in the template
    // For example, suppose we have "${stringFormat(strings.myName, person.firstName, person.lastName)}"
    // args will have following entries
    // args[0]: strings.myName
    // args[1]: person.firstName
    // args[2]: strings.lastName
    if (args[0] != null && args[1] != null && args[2] != null) 
    {
        string formatString = args[0];
        string[] stringArguments = {args[1], args[2] };
        formattedString = string.Format(formatString, stringArguments);
    }
    return formattedString;
});

string cardJson = template.Expand(context);

Penyelesaian Masalah

Pertanyaan Mengapa saya menghadapi AdaptiveTemplateException saat memanggil expand()?
A. Jika pesan kesalahan Anda terlihat seperti '<item yang menyebabkan kesalahan>' pada baris, '<nomor> baris' tidak valid untuk pasangan '$data : '".
Pastikan bahwa nilai yang disediakan untuk "$data" adalah json yang valid seperti angka, boolean, objek, dan array, atau mengikuti sintaks yang benar untuk bahasa Templat Adaptif, dan entri ada dalam konteks data pada nomor baris.

Pertanyaan Mengapa saya mengalami ArgumentNullException saat memanggil expand()?
Sebuah. Jika pesan kesalahan Anda terlihat seperti" Periksa apakah konteks data induk diatur, atau masukkan nilai non-null untuk '<item> yang menyinggung' pada baris, '<nomor> baris'".
Ini menunjukkan bahwa tidak ada konteks data untuk pengikatan data yang diminta. Pastikan bahwa konteks data akar diatur; apabila ada, pastikan konteks data apa pun tersedia untuk pengikatan saat ini seperti yang ditunjukkan oleh nomor baris.

Pertanyaan Mengapa tanggal/waktu dalam format RFC 3389 misalnya "2017-02-14T06:08:00Z" saat digunakan dengan templat tidak berfungsi dengan fungsi TIME/DATE?
Sebuah. .NET sdk nuget versi 1.0.0-rc.0 menunjukkan perilaku ini. perilaku ini dikoreksi dalam rilis berikutnya. Perilaku default deserializer json.Net yang mengubah string format tanggal/waktu akan dinonaktifkan untuk rilis berikutnya. Gunakan fungsi formatDateTime() untuk memformat string tanggal/waktu ke RFC 3389 seperti yang terlihat dalam contoh ini, atau Anda dapat melewati fungsi TIME/DATE, dan cukup gunakan formatDateTime(). Untuk informasi selengkapnya tentang formatDateTime(), silakan buka di sini.