Belirtim: Uyarlamalı Kart İşleyici

Aşağıdaki belirtim, herhangi bir yerel kullanıcı arabirimi platformunda Uyarlamalı Kart işleyicisinin nasıl uygulandığını açıklar.

Önemli

Bu içerik devam eden bir çalışmadır ve bazı ayrıntılar eksik olabilir. Sorularınız veya geri bildirimleriniz varsa lütfen bize bildirin .

JSON Ayrıştırma

Hata koşulları

1. Ayrıştırıcının geçerli JSON içeriği olup olmadığını denetlemesi GEREKIR
2. Ayrıştırıcı şemaya göre doğrulamaLIDIR (gerekli özellikler vb.)
3. Yukarıdaki hatalar konak uygulamasına bildirilmelidir (özel durum veya eşdeğer)

Bilinmeyen türler

1. Bilinmeyen "türler" ile karşılaşılırsa sonuçtan ÇıKARILMASI GEREKİr
2. Yükte yapılan değişiklikler (yukarıdaki gibi) konak uygulamasına uyarı olarak bildirilmelidir

Bilinmeyen özellikler

1. Ayrıştırıcı, öğelere ekstra özellikler eklemelidir

Dikkat edilmesi gereken ek noktalar

1. özellik speakSSML işaretlemesi içerebilir ve konak uygulamaya belirtildiği gibi döndürülmelidir

Ana Makine Yapılandırmasını Ayrıştırma

1. YAPILACAKLAR

Sürüm oluşturma

1. bir işleyici şemanın belirli bir sürümünü uygulamalidir .
2. Oluşturucu, AdaptiveCard özelliğine version geçerli şema sürümünü temel alan bir varsayılan değer vermelidir
3. Bir işleyici, bir AdaptiveCard içinde desteklenen sürümden daha yüksek bir version özelliği ile karşılaşırsa, bunun yerine fallbackText'ü döndürmelidir.

Renderlama

Bir AdaptiveCard, body ve actions'den oluşur. body, bir işleyicinin sırayla numaralandıracağı ve işleyeceği CardElement koleksiyonudur.

1. Her bir öğe, üst öğesinin genişliğine kadar uzanmalıdır (HTML'deki gibi düşünün display: block).
2. bir işleyici karşılaştığı bilinmeyen öğe türlerini yoksaymaLI ve yükün geri kalanını işlemeye devam etmelidir.

Text, TextBlock ve RichTextBlock

1. TextBlock, wrap özelliği true olmadığı sürece, tek bir satırda bulunmalı.
2. Metin bloğu, fazlalık metni üç nokta (...) ile kırpmalıdır

Markdown

1. Uyarlamalı Kartlar, Markdown'ın bir alt kümesini destekler ve TextBlock içinde desteklenmelidir.
2. RichTextBlock Markdown'ı DESTEKLEMEZ ve kullanıma sunulan özellikler kullanılarak stillendirilmelidir.
3. Tam markdown gereksinimlerini görün

Biçimlendirme işlevleri

1. TextBlockher işleyicide desteklenmesi GEREKENTARİh/SAAT biçimlendirme işlevlerine izin verir.
2. TÜM HATALAR , ham dizeyi kartta görüntülemeLIDIR. Dostane bir mesaj denenmedi. (Amaç, geliştiricinin bir sorun olduğunu hemen fark etmelerini sağlamaktır)

Resimler

1. Oluşturucu, konak uygulamalarının tüm HTTP görüntülerinin indirildiğini ve kartın "tamamen işlendiğini" bilmelerine izin vermelidir
2. BIR işleyici HTTP görüntülerini indirirken Konak Yapılandırma maxImageSize parametresini incelemeLIDIR
3. bir çizici ZORUNDADIR.png ve .jpeg desteklemelidir
4. Bir işleyici görüntüleri desteklemeLIDIR.gif

Gelişmiş Düzen Davranışı

İşleyici, bu belgede belirtilen özniteliklere göre kart öğelerini işlerken aşağıdaki davranışlara dikkat etmelidir .

İşleyici, kart öğelerinin ve alt öğelerinin kenar boşluğu, doldurma, yükseklik ve genişlik gibi çeşitli faktörleri dikkate alarak Kısıtlamaları yönetmelidir.

Genişlik

1. İzin verilen değerler - auto, stretch ve pixels açısından sabit değerler weight
2. auto genişliğin genişletilmesi için yeterli alan sağlar (en az genişletmeyi destekler)
3. stretch kalan genişliği kaplar (maksimum genişletmeyi destekler)

Aşağıdaki senaryolarda kısıtlamaların sütunlar için farklı genişlik birleşimleriyle nasıl etkilendiği açıklanmaktadır

auto ile stretch karşılaştırması

1. auto ve stretch genişliğinde sütunlar.

• Genişliğe sahip auto ilk sütun içeriği görüntülemek için yeterli alan alır ve genişlikli ikinci sütun stretch tüm alanı kaplar.

2. Yalnızca stretch genişliği olan sütunlar

• Yalnızca esnetme genişliğine sahip sütunlar, eşit olarak bölündikten sonra kalan boşlukları kaplar.

3. auto,stretch ve auto

birinci ve üçüncü sütun genişliği, önce öğeleri yeterince barındıracak şekilde ayarlanır ve esnetilmiş genişliğe sahip ikinci sütun kalan alanı kaplar.

4. auto genişlik sütunları ile öğelerin gösterim sırası

• auto içeren sütunlar, içeriğin işlenmesi için geniş alan sağlayacak şekilde kendilerini konumlandırır.
• Görüntü görünümleri söz konusu olduğunda, resimler kalan genişliğe uyacak şekilde küçültülecektir.
• Not: Görüntüler yalnızca stretch ve auto görüntü boyutu için küçültülür, ancak piksel cinsinden sabit genişlik ve yükseklik için küçültülmez.

weights ile pixels karşılaştırması

1. weight ve pixel genişliği kombinasyonuna sahip sütunlar

• Yukarıdaki kart, aşağıdaki genişlik yapılandırmasına sahip üç sütuna sahiptir :
• Column1: Weight 50, Column2: 100px, Column3: Weight 50
• Sütun 2'nin genişliği, pixel value tarafından belirlenir.
• Sütun 1 ve 3'ün genişliği weights ve hesaplanan weight ratio öğesine göre ayarlanır.

2. weight, pixel width ve auto özniteliklerine sahip sütunlar

• Yukarıdaki kart aşağıdaki genişlik yapılandırmasına sahip dört sütuna sahiptir :
• Column1: Weight 50, Column2: 100px, Column3: Weight 50 ve Column4: auto
• Not: Görüntü görünümü, kalan alana uyacak şekilde auto genişlik sütununu küçültür.

width özniteliğine sahip öğeleri görüntülemenin öncelik sırası

px > weight > auto > stretch

Yükseklik

İzin verilen değerler - auto ve stretch

Aşağıdaki senaryolarda kısıtlamaların kart öğeleri için farklı yükseklik bileşimlerinden nasıl etkilendiği açıklanmaktadır

1. Kart sabit yükseklikte olmadığında öğeler serbestçe dikey olarak genişletilir

• Her iki sütun da auto ve stretch değerlerinden bağımsız olarak yeterince dikey genişleyebilir.
• Bu, wrap metin bloğunun özelliğinin devre dışı bırakıldığı durumu ifade eder.

2. Aşağıdaki kartta wrap metin bloğu için özelliği etkinleştirilmiştir.

Aralık ve Ayırıcı

1. spacing Her öğedeki özelliği CURRENT öğesi ile ÖNCESİ arasındaki boşluk miktarını etkiler.
2. BoşlukLAR YALNIZCA önünde bir öğe olduğunda uygulanmalıdır. (Örneğin, bir dizideki ilk öğeye uygulanmaz)
3. İşleyici, geçerli öğeye uygulanan sabit listesi değeri için aralıktan hostConfig kullanılacak alan miktarını aramalıdır.
4. öğesinin separator değeri truevarsa, geçerli öğe ile ondan önceki öğe arasında görünür bir çizgi çizilmelidir .
5. Ayrım çizgisi mutlakacontainer.style.default.foregroundColor kullanılarak çizilmelidir.
6. Öğenin dizideki ilk öğe olmaması durumunda bir ayırıcı YALNıZCA çizilmelidir.
7. Aralık - İzin verilen değerler none, small, default, medium, , extra largelargevepadding

• Aralık özniteliği, bu öğeyle önceki öğe arasına boşluk ekler.

• Aralık özniteliği, görünüm kapsayıcısında ilk öğe olduğunda herhangi bir etkiye sahip değildir.

• Okla işaretlenen öğeler, eşdüzey öğeleri arasındaki ilk öğelerdir, bu nedenle aralığın hiçbir etkisi yoktur.

2. Ayırıcı - Olası değerler (açık/kapalı anahtar)

• Öğenin en üstüne ayrım çizgisi çizer.

3. Aralık ve Seperator bileşimi

• Aralık ve seperatör bileşiminin kısıtlamaları aşağıda gösterilmiştir.

• Toplam aralık uzaklığı, sağlanan değerlere göre korunur.
• Ayırıcı, aralıklı mesafenin yarı yolunda eklenir.

[Not. Ayırıcının aralık alanına yerleştirildiği uzaklığı onaylamanız gerekir. Ortadaki gibi görünüyor]

Kapsayıcı Stilleri

• Sütunlar ve sütun kümesi gibi kapsayıcılar için stil ipuçları sağlar
• İzin verilen değerler none, default, emphasis, good, , warningattentionveaccent
• Bu önceden tanımlanmış stil seçenekleri, kapsayıcı içindeki öğeler ve arka plan rengi için doldurma sağlar

1. A Kartı, stil seçeneği olmayan sütunları ve sütun kümesini gösterir
2. B Kartı, Dikkat stiline sahip sütun kümesini gösterir. Sütun kümesi kapsayıcısının içindeki doldurmaya ve arka plan rengindeki değişikliğe dikkat edin.
3. C kartı yalnızca stil içeren sütunları gösterir. Öncekine benzer şekilde, sütun doldurma ve arka plan değişikliği içerir.
4. D kartı, hem sütunları hem de sütun kümesini stil seçenekleriyle gösterir.

[Not. Doldurma miktarının nasıl belirlendiğini denetlemem gerekiyor. Konak tarafından belirlenir mi? ]

Kanamak

• Bu özellik, sütunlar ve sütun kümesi gibi kapsayıcının üst öğesine nüfuz etmesini sağlar.
• Olası değerler on ve off.

1. Kart A, normal stil ile sütunları ve sütun kümesini gösterir.
2. B kartı kenar taşması seçeneğine sahip ilk sütunu gösterir. İçerik sınırlarını aşarak üst öğeye geçer.

Görüntü Boyutu

Size özniteliği

• İzin verilen değerler - auto, stretch, small, medium, large
• auto : Gerekirse resimlerin ölçeği sığacak şekilde azaltılır, ancak alanı dolduracak şekilde artırılmaz.
• stretch : Gerektiğinde sığacak şekilde hem aşağı hem de yukarı ölçekleyen görüntü.
• small, medium ve large: Görüntü, genişliğin konak tarafından belirlendiği sabit bir genişlikte gösterilir.

1. auto ile stretch karşılaştırması

2. Sütun genişliği ve Görüntü Boyutu bileşimi

• Genel olarak, genişliğinde stretch sütunlar, görüntülerin stretch boyutuyla serbestçe büyüyebilmesini sağlar.
• auto genişliğindeki sütunlar, görüntünün boyutu ne olursa olsun, görüntünün yer kaplayacağı alanı tam olarak belirler.
• Sütun genişliği, bu düzenlemedeki görüntü boyutunun belirlenmesinde daha önceliklidir.

Görüntü Width (in pixels) özniteliği

• Bu, görüntünün istenen ekran genişliğini sağlar.
• size özelliği, bir değer belirtildiğinde geçersiz kılınır

• auto genişliğine sahip sütun, bu düzenlemede görüntü içeriği için yer sağlamak açısından stretch'den daha öncelikli olacaktır.

Sütun Genişliği (ağırlık ve piksel) ve Görüntü boyutu (otomatik ve esnetme) Bileşimi

• auto boyutuna sahip görüntüler, weight ve pixel genişliği sütun kısıtlamaları içinde genişleme (veya küçültme) için yeterli alan kaplar.
• Boyutu olan stretch görüntüler, sütun weight ve pixel genişlik kısıtlamaları içinde kalan alanı dolduracak şekilde genişletilebilir.

Gelişmiş Düzen Özeti

• Sütun genişliği, görüntünün boyutunun belirlenmesinde resim boyutundan (otomatik, esnetme, en az genişlik vb.) daha önceliklidir.
• İçeriğini yeterince görüntülemek için alınan sütun genişliğinin önceliği - px>weight>auto>stretch
• size görüntüsü (otomatik, esnetme), width ve height piksel cinsinden sağlandığında yoksayılır.
• Görüntü stretch boyutu özniteliği, yalnızca kalan alan olduğunda ve sütun otomatikauto ayarlanmamışsa görüntüyü büyütür.
• Bir görüntü, sütundaki kullanılabilir alan içinde en boy oranını koruduğu sınıra kadar uzanır. Buna karşılık, yükseklik serbestçe genişler.
• Spacing özniteliği, eşdüzey öğe arasındaki ilk veya tek öğe olduğunda hiçbir etkisi olmaz.

Eylemler

1. HostConfig supportsInteractivity ise false, çizici herhangi bir eylemi İŞLEMEMELİDİR.
2. actions özelliği, kartın alt kısmında yer alan bir eylem çubuğunda genellikle düğme olarak gösterilmelidir.
3. Bir düğmeye dokunulduğunda, ana uygulamanın olayı işlemesi kesinlikle sağlanmalıdır.
4. Olay, eylemle ilişkili tüm özellikleri geçirmeLI
5. Olayın yürütülen AdaptiveCard ile birlikte geçmesi GEREKİR.

Eylem	Davranış
Action.OpenUrl	Görüntülemek için dış URL'yi açma
Action.ShowCard	Kullanıcıya bir alt kart gösterilmesini istemektedir.
İşlem.Gönder	Giriş öğelerinin tamamının bir nesnede toplanarak size, konak uygulama tarafından tanımlanan bir yöntemle gönderilmesini isteyin.
Action.Execute	(v1.4'te kullanıma sunulmuştur) Daha sonra "evrensel eylem işlem hattı" aracılığıyla size gönderilen bir nesnede toplanacak tüm giriş öğelerini isteyin

Action.OpenUrl

1. Action.OpenUrlYerel platform mekanizmasını kullanarak URL'yi açmalı
2. Bu mümkün değilse, URL'nin açılmasını sağlamak için konak uygulamasına bir olay tetiklemek zorundadır. Bu olay, varsayılan davranışın konak uygulama tarafından geçersiz kılınmasına izin vermelidir. Örneğin, URL'yi kendi uygulamaları içinde açmalarına izin verin.

Action.ShowCard

1. Action.ShowCardhostConfig ayarına bağlı olarak bir şekilde desteklenmeli. İki mod vardır: satır içi ve açılır pencere. Satır içi kartlar, kart görünürlüğünü otomatik olarak değiştirmeLIDIR . Açılan modda, kartın bir şekilde gösterilmesi için konak uygulamasına bir olay tetiklenmeli .

Aksiyon.Gönder

• Action.Submit öğesi giriş alanlarını toplar, isteğe bağlı veri alanıyla birleştirilir ve istemciye bir olay gönderir.
• ACL işleyicisinin 1.x ve 2.x sürümü arasında öğe davranışında önemli bir fark vardır.

Adaptif Kartlar'daki "Gönderme Eylemi", bir HTML formu gönderimi gibi davranır; ancak HTML genellikle bir HTTP gönderisini tetiklerken, "gönderme" işleminin ne anlama geldiğini belirlemek konak uygulamasına bırakılır.

1. Bu bir olay tetiklediğinde kullanıcı çağrılan eyleme dokunur.
2. data özelliği geri çağırma yüküne dahil edilmelidir.
3. için Action.Submit, işleyici kart üzerindeki tüm girişleri toplamalı ve değerlerini almalıdır .

• 1.x Renderer - Girişler, hiyerarşideki giriş alanının bulunduğu konumdan bağımsız olarak tüm alanlardan toplanır.
• 2.x Renderer - Girişler, ana kapsayıcıda bulunan alanlardan veya Action.Submit öğesinin yanındaki kardeş alanlardan toplanır.

Action.Execute (Ayrıntılar daha sonra sunulacak)

Action.Execute, sürüm 1.4'te kullanıma sunulmuştur. SDK'lar için daha sonraki bir tarihte uygulama kılavuzu sağlayacağız. Bu konu hakkında sorularınız varsa lütfen ulaşın.

selectAction

1. Sunucu Yapılandırması supportedInteractivity bir falseselectAction dokunmatik hedef olarak işLENMEMELİDİR.
2. Image, ColumnSetve Column kullanıcı tarafından çağrıldığında yürütülmesi gereken bir selectAction özellik (örneğin, öğesine dokunarak) sunar.

Girişler

1. HostConfig supportsInteractivity bir işleyiciyse false hiçbir girişi İşlememesi GEREKİR.
2. Girişler mümkün olan en yüksek doğrulukta işlenmelidir. Örneğin, bir Input.Date ideal olarak kullanıcıya bir tarih seçici sunmalıdır, ancak bu kullanıcı arabirimi yığınınızda mümkün değilse, işleyici standart bir metin kutusunu işlemeye geri dönmek zorundadır.
3. Bir çizici GÖSTERMELİplaceholderText mümkünse
4. Giriş değeri bağlaması düzgün bir şekilde kaçış noktası oluşturulmalıdır
5. v1.3'ten önce, bir işlemcinin girdinin doğrulamasını yapması gerekmez. Uyarlamalı Kart kullanıcılarının kendi uçlarında alınan verileri doğrulamayı planlamaları gerekir.
6. Giriş Etiketleri ve Doğrulama , Uyarlamalı Kartlar Şemasının v1.3'lerinde kullanıma sunulmuştur. İlişkili etiketin, doğrulama ipuçlarının ve hata iletilerinin işlenmesinde dikkatli olunmalıdır.

Stil Oluşturma, Özelleştirme ve Genişletilebilirlik API'leri

Her SDK, genel stili denetlemek ve şemayı uygun gördükleri şekilde genişletmek için Uygulamaları Barındırmak için belirli bir esneklik düzeyi sağlamalıdır.

Konak Yapılandırması

• TODO: Varsayılanlar ne olmalıdır? Herkes paylaşsın mı? İkili dosyalara ortak bir hostConfig.json dosyası eklemeli miyiz?

HostConfig , Uyarlamalı Kart oluşturucus un kullanıcı arabirimini nasıl oluşturduğunu belirten paylaşılan bir yapılandırma nesnesidir.

Bu, platformdan bağımsız olan özelliklerin farklı platformlarda ve cihazlarda işleyiciler arasında paylaşılmasını sağlar. Ayrıca, kartın belirli bir ortam için sahip olacağı görünüm ve his hakkında fikir veren araçlar oluşturulmasına da olanak tanır.

1. Renderer'lar konak uygulamaları için Konak Yapılandırması parametresini kullanıma sunmalı
2. Tüm öğeler, ilgili Konak Yapılandırması ayarlarına göre stillendirilmelidir

Yerel platform stillendirmesi

1. Her öğe türü, oluşturulan kullanıcı arabirimi öğesiyle yerel bir platform stili eklemeLIDIR . Örneğin, HTML'de öğe türlerine bir CSS sınıfı ekledik ve XAML'de belirli bir Stil atıyoruz.

Genişletilebilirlik

1. Render motoru, ana bilgisayar uygulamalarının varsayılan öğe işleyicilerini geçersiz kılmasına izin vermelidir. Örneğin, işlemeyi kendi mantığıyla değiştirin TextBlock .
2. Bir render MUTLAKA konak uygulamalarının özel öğe türlerini kaydetmesine izin vermelidir. Örneğin, özel Rating bir öğe için destek ekleme
3. oluşturucu, konak uygulamalarının varsayılan öğe desteğini kaldırmasına izin vermelidir . Örneğin, desteklenmesini istemiyorsanız Action.Submit öğesini kaldırın.

Etkinlikler

1. Bir öğenin görünürlüğü değiştiğinde gösterici bir olayı tetiklemelidir ve konak uygulamanın kartı konumuna kaydırmasına izin vermelidir.