Uyarlamalı Kartlar Tasarımcısı kullanarak pencere öğesi şablonu oluşturun.

Bir Uyarlamalı Kart pencere öğesi için kullanıcı arabirimini ve etkileşimleri, Uyarlamalı Kartlar JSON şablonu ve isteğe bağlı olarak ayrı bir JSON veri yükü kullanarak tanımlayın. Bu makalede, veri bağlama ve koşullu düzen içeren bir counting widget şablonu adım adım açıklanır. Windows pencere öğeleri url'den HTML de görüntüleyebilir; bu içerik biçimi için bkz. Web pencere öğesi sağlayıcıları.

Sayım aracı

Bu makaledeki örnek, bir tamsayı değeri görüntüleyen ve kullanıcının pencere öğesinin kullanıcı arabirimindeki bir düğmeye tıklayarak değeri artırmasına olanak tanıyan basit bir sayma pencere öğesidir. Bu örnek şablon, kullanıcı arabirimini veri bağlamını temel alarak otomatik olarak güncelleştirmek için veri bağlamayı kullanır.

Uygulamaların pencere öğesi şablonunu ve/veya verilerini oluşturup güncelleştirmek ve bunları pencere öğesi konağına geçirmek için bir pencere öğesi sağlayıcısı uygulaması gerekir. Win32 uygulamasında pencere öğesi sağlayıcısı uygulama makalesi, aşağıdaki adımlarda oluşturacağımız sayım pencere öğesi için pencere öğesi sağlayıcısını uygulamaya yönelik adım adım yönergeler sağlar.

Uyarlamalı Kartlar Tasarımcısı

Uyarlamalı Kartlar Tasarımcısı, kart JSON'unu düzenlemek ve düzenini ve veri bağlamasını önizlemek için kullanılan çevrimiçi bir araçtır. Şablon üzerinde çalışmak için Tasarımcı'nı açın.

Important

Tasarımcı kendi renderer ve konak seçeneklerini kullanır. Sunduğu özelliklerin Widgets Panosu tarafından desteklendiğini veya Windows'a özgü $host değerler sağladığını varsaymayın. Bu kılavuz bir ana bilgisayar hazır ayarına veya ana bilgisayar veri düzenleyicisine bağlı değildir. Desteklenen her boyut ve tema için son şablonu bir Windows widget sağlayıcısında test edin.

Aşağıdaki görüntüler geçerli Tasarımcı arabirimini değil kartın düzenini gösterir.

Boş bir kartla başlayın

Card payload düzenleyicisi, kartın JSON tanımını içerir. İçeriğini şu boş kartla değiştirin:

{
    "type": "AdaptiveCard",
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.6",
    "body": []
}

Örnek veri düzenleyicisi isteğe bağlı bir JSON veri bağlamı içerir. Bu verileri şablona bağlama hakkında bilgi için bkz. Uyarlamalı Kartlar Template Language.

Windows pencere öğesi ana bilgisayarı özellikleri

Bileşenler Panosu çalışma zamanında ana bilgisayar özellikleri sağlar. Bunlara, ${$host.widgetSize} aracılığıyla şablon ifadelerinde, örneğin $host başvurun. Bu özellikler sağlayıcınızın veri yükünden ayrıdır; örnek verilere widgetSize alanını eklemek $host.widgetSize ayarını yapmaz.

Mülkiyet Değer Açıklama
host.widgetSize "küçük", "orta" veya "büyük" Sabitlenmiş pencere öğesinin boyutu.
host.hostTheme "açık" veya "koyu" Araçlar Panosu'nun görüntülendiği cihazdaki mevcut tema.
host.isSettingsPayload doğru veya yanlış Bu değer doğru olduğunda, kullanıcı pencere öğesi bağlam menüsündeki Pencere öğesini özelleştir düğmesine tıklamıştır. Özelleştirme ayarları kullanıcı arabirimi öğelerini görüntülemek için bu özellik değerini kullanabilirsiniz. Bu, pencere öğesi sağlayıcısı uygulamasında JSON yükünü değiştirmek için IWidgetProvider2.OnCustomizationRequested kullanmanın alternatif bir yöntemidir. Daha fazla bilgi için bkz. Widget özelleştirmesinin uygulanması.
host.isHeaderSupported doğru veya yanlış Bu değer true olduğunda üst bilgi özelleştirmesi desteklenir. Daha fazla bilgi için bkz. isHeaderSupported.
host.isHeader doğru veya yanlış Bu değer doğru olduğunda, sunucu özellikle pencere öğesi üst bilgisinin işlenmesi için bir yük talep eder.
host.isWebSupported doğru veya yanlış Bu değer false olduğunda, sunucu şu anda bir pencere öğesinin web içeriğini yüklemeyi desteklemez. Bu durumda, web pencere öğeleri pencere öğesi sağlayıcısı tarafından sağlanan geri dönüş JSON yükünü görüntüler, ancak bu değer içeriği daha fazla özelleştirmek için kullanılabilir. Daha fazla bilgi için bkz . Web pencere öğesi sağlayıcıları
host.isUserContextAuthenticated doğru veya yanlış Bu değer false olduğunda, desteklenen tek eylem Action.OpenUrl'dir. IsUserContextAuthenticated değeri, etkileşim sınırlamaları göz önünde bulundurularak pencere öğesi içeriğini uygun şekilde ayarlamak için kullanılabilir.

Sayma pencere öğesi, düğmesi için dört TextBlock öğesi ve bir Action.Execute eylemi kullanır.

TextBlock öğeleri ekleme

Tasarımcı'nın öğe paletinden dört TextBlock öğesi ekleyin veya bunları doğrudan kart JSON'una ekleyin. Koşullu düzen uygulanmadan önce, kartta aşağıda gösterildiği gibi dört satırlık metin bulunur.

Üzerinde çalışılan uyarlamalı bir kart. Yeni TextBlock metnini içeren dört satırlık bir widget gösterir. Dört metin satırı, widget'ın alt kenarını taşır.

Koşullu düzen uygulama

Card payload düzenleyicisinde body dizisini aşağıdaki parçayla değiştirin:

"body": [
    {
        "type": "TextBlock",
        "text": "You have clicked the button ${count} times"
    },
    {
        "type": "TextBlock",
        "text": "Rendering only if medium",
        "$when": "${$host.widgetSize==\"medium\"}"
    },
    {
        "type": "TextBlock",
        "text": "Rendering only if small",
        "$when": "${$host.widgetSize==\"small\"}"
    },
    {
        "type": "TextBlock",
        "text": "Rendering only if large",
        "$when": "${$host.widgetSize==\"large\"}"
    }
]

Uyarlamalı Kartlar Şablon Dili'nde $when özelliği, ilişkili değer true olarak değerlendirildiğinde içeren öğenin görüntüleneceğini belirtir. Değer false olarak değerlendirilirse, içeren öğe görüntülenmez. Örneğimizdeki gövde öğesinde, özelliğin değerine bağlı olarak üç TextBlock öğesinden biri gösterilir ve diğer ikisi gizlenir $host.widgetSize . Uyarlamalı Kartlar'da desteklenen koşullu ifadeler hakkında daha fazla bilgi için bkz. $when ile Koşullu Yerleşim.

Şablon ifadelerini değerlendirmeden, kart dört metin bloğunun tümünü gösterir:

Oluşturulmakta olan bir uyarlanabilir kart. Önceki adımda gösterilen JSON yükünde belirtilen metni içeren dört satırlık bir widget gösterir. Öğeleri koşullu olarak gizlemek yerine, tüm öğeler görünür ve kartın alt kenarını aşmaktadır.

Bileşenler Panosu şablonu, $host.widgetSize"small" olarak ayarlanmışken değerlendirdiğinde, sayıyla birlikte yalnızca küçük boyutlu metin bloğu görüntülenir:

Uyarlamalı bir kart hazırlanıyor. JSON yükünde belirtilen metni içeren iki satırlı bir widget gösterilir. Yalnızca küçük boyut için TextBlock işlenmiştir.

Şablonu sağlayıcınızla tümleştirdikten sonra Bileşenler Panosu'nda sabitlenmiş bileşeni yeniden boyutlandırın ve eşleşen metin bloğunun görüntülenip görüntülenmediğini denetleyin. widget provider manifestinde test etmek istediğiniz her boyutu bildirin. Windows ana bilgisayar verileri olmayan genel bir Tasarımcı önizlemesi bu koşulları doğrulayamaz.

Veri bağlamına bağla

Örnek, ilk count içinde ${count} tarafından başvuruda bulunulan adlı bir veri özelliği kullanır. Çalışma zamanında sağlayıcı veri yükünü widget ana bilgisayarına gönderir. Tasarım zamanında Örnek veri düzenleyicisine aşağıdaki JSON değerini girin ve Tasarımcı'nın önizlemesinin sayaç bağlamasını denetlemesini sağlayın. Bu örnek veriler ayrı Windows konak özelliklerini sağlamaz.

{"count": "2"}

{"count": "2"} örnek veri olduğunda, şablon genişletme ilk ${count} içinde öğesini 2 ile değiştirir. Önizlemeyi etkinleştirdikten sonra Tasarımcı'da bu bağlantıyı denetleyin. Yukarıda açıklandığı gibi Widgets Panosu'nda ayrı $host.widgetSize koşulları kontrol edin.

Bir uyarlanabilir kart üzerinde çalışılıyor. Metnin ilk satırı artık veri yükünden gelen 2 değerini içermektedir.

Düğme ekle

Sonraki adım pencere öğesimize bir düğme eklemektir. Widget ana bilgisayarında, kullanıcı düğmeye tıkladığında ana bilgisayar pencere öğesi sağlayıcısına bir istekte bulunur. Bu örnekte pencere öğesi sağlayıcısı sayım değerini artırır ve güncelleştirilmiş bir veri yükü döndürür. Bu işlem bir pencere öğesi sağlayıcısı gerektirdiğinden, bu davranışı Uyarlamalı Kartlar Tasarımcısı'nda görüntüleyemezsiniz, ancak kullanıcı arabiriminizdeki düğmenizin düzenini ayarlamak için tasarımcıyı kullanmaya devam edebilirsiniz.

Uyarlamalı Kartlar ile etkileşimli öğeler action öğeleriyle tanımlanır. Aşağıdaki JSON bloğunu doğrudan kart yükü düzenleyicisindeki gövde öğesinin arkasına ekleyin. Gövde öğesinin kapatma köşeli ayracından (]) sonra virgül eklediğinizden emin olun; aksi takdirde tasarımcı biçimlendirme hatası bildirecektir.

,
"actions": [                                                      
    {                                                               
        "type": "Action.Execute",                               
        "title": "Increment",                                   
        "verb": "inc"                                           
    }                                                               
]

type özelliği, pencere öğesi konağının sağlayıcınızın OnActionInvoked geri çağırmasına ilettiği Action.Execute öğesini seçer. Bunun yerine URL gezintisi için Action.OpenUrl kullanın; Action.OpenUrl bu sağlayıcı geri çağırmasını tetiklemez. Başlık düğme metnini sağlar ve verb, sağlayıcının işlediği uygulama tanımlı işlemdir. $host.isUserContextAuthenticated false olduğunda Action.Execute etkileşimleri sunmayın; yalnızca Action.OpenUrl desteklenir.

Son uyarlamalı kart. İki metin çizgisinin ardından Artım metnini içeren mavi bir düğme görüntülenir.

Tamamlanmış pencere öğesi şablonu

Aşağıdaki kod listesi, sayma pencere öğesi etkileşimi için son şablonu gösterir. Action.Execute düğmesi, kimliği doğrulanmış bir kullanıcı bağlamı gerektirir. Bunu sağlayıcınızda Widgets Panosu'nda doğrulayın; Tasarımcı, sağlayıcınızın increment işleyicisini çalıştırmaz.

{
    "type": "AdaptiveCard",
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.6",
    "body": [
    {
      "type": "TextBlock",
      "text": "You have clicked the button ${count} times"
    },
    {
      "type": "TextBlock",
       "text": "Rendering Only if Small",
      "$when": "${$host.widgetSize==\"small\"}"
    },
    {
      "type": "TextBlock",
      "text": "Rendering Only if Medium",
      "$when": "${$host.widgetSize==\"medium\"}"
    },
    {
      "type": "TextBlock",
      "text": "Rendering Only if Large",
      "$when": "${$host.widgetSize==\"large\"}"
    }
    ],
   "actions": [
    {
      "type": "Action.Execute",
      "title": "Increment",
      "verb": "inc"
    }
  ]
}

Konfigürasyon yükü örneği

Aşağıdaki kod listesinde, kullanıcı Pencere öğesini özelleştir düğmesine tıkladığında farklı içeriği görüntülemek için host.isSettingsPayload özelliğini kullanan basit bir JSON yükü örneği gösterilmektedir.

{
    "type": "AdaptiveCard",
    "body": [
    {
        "type": "Container",
        "items":[
            {
                "type": "TextBlock",
                "text": "Content payload",
                "$when": "${!$host.isSettingsPayload}"
            }
        ]
    },
    {
        "type": "Container",
        "items":[
            {
                "type": "TextBlock",
                "text": "Settings payload",
                "$when": "${$host.isSettingsPayload}"
            }
        ]
    }
],
"actions": [
    {
        "type": "Action.Execute",
        "title": "Increment",
        "verb": "inc",
        "$when": "${!$host.isSettingsPayload}"
    },
    {
        "type": "Action.Execute",
        "title": "Update Setting",
        "verb": "setting",
        "$when": "${$host.isSettingsPayload}"
    }
],
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.6"
}
  • Son güncelleştirme: