Adaptive Card Extension – wskazówki i porady dla programistów

Jeśli jesteś programistą i korzystasz z Viva Connections, być może wiesz, że istnieje dedykowany typ komponentów SPFx do tej platformy – Adaptive Card Extension, czyli ACE. ACE sprawdzi się świetnie w wielu scenariuszach – od przedstawiania szczegółów lotu albo zamówienia, po wyświetlanie galerii obrazów. Na stronie Microsoft możesz znaleźć podstawowy samouczek dotyczący ich tworzenia.

Nawet jeśli jesteś prawdziwym fanem Microsoft i krok po kroku prześledzisz jego tutorial, możesz mieć pytania na temat ACE. W artykule rozwiejemy te wątpliwości i stworzymy najlepsze rozszerzenie SPFx w życiu! Zaczynajmy 😉

Jak mogę stworzyć projekt Adaptive Card Extension? Nie widzę takiej opcji w moim Yeoman!

Hej, zachowaj spokój! Upewnij się, że Twój generator SharePoint w Yeoman jest zaktualizowany. Na chwilę obecną najlepiej, aby Twój SPFx był co najmniej w wersji 1.18. Jeśli nie wiesz, jak sprawdzić swoją wersję, możesz skorzystać z postu Waldka.

Przy okazji warto rzucić okiem na tabelę kompatybilności, aby upewnić się, że Twoje pakiety Node.js, TypeScript i React również mają odpowiednią wersję.  

Temat adaptive cards wydaje się być bardzo skomplikowany. Od czego mam zacząć?

Zainspiruj się projektami Microsoft lub spójrz na przykłady dostarczone przez PnP. Gdy znajdziesz coś interesującego, dostosuj rozwiązanie w projektancie.

Pamiętaj – nie musisz kopiować swojego szablonu do projektanta za każdym razem, gdy chcesz go zaktualizować! Do niewielkich zmian i szybkiego podglądu świetnie sprawdzi się rozszerzenie Microsoft „Adaptive Card Previewer”. Zainstaluj je w swoim Visual Studio Code.

I pamiętaj – jak w przypadku wielu umiejętności, trening czyni mistrza!

Ikona rozszerzenia nie jest wyświetlana. Czy źle coś ustawiam?

Po pierwsze, zajrzyj do poradnika Microsoft – znajdziesz tam informację, że ikonę należy ustawić w manifeście rozwiązania. Sugeruję skonfigurowanie dwóch właściwości ikon:

• „officeFabricIconFontName” – aby Twoje rozwiązanie miało ładnie wyglądający obrazek w przyborniku edytora,
• „iconProperty” (zgodnie z sugestią Microsoft) – do wyświetlenia ikony na pasku Twojego adaptive card.

Po drugie, upewnij się, że wykorzystujesz prawidłową ikonografię. Jak zawsze, dla właściwości „officeFabricIconFontName” możesz użyć ikon Fluent UI. W przypadku obrazka na pasku adaptive card, obługiwane są tylko wybrane wartości.

Użytkownik powiedział, że mój ACE jest trudny do przeglądania, a obrazy mają dziwne tło! W mojej aplikacji wszystko wygląda świetnie!

Pamiętaj, że użytkownicy mają możliwość zmiany motywów swoich aplikacji. W rezultacie Twój piękny adaptive card może wyglądać inaczej dla różnych odbiorców.

Motyw użytkownika możesz sprawdzić w funkcji onInit swojego rozwiązania:

this.context.sdks?.microsoftTeams?.teamsJs.app.getContext().then((context) => {
    this.setState({
      theme: context.app.appInfo.theme
    });
  });

Ważne! Upewnij się, że używasz SPFx co najmniej w wersji 1.18 – w przeciwnym razie w kontekście może brakować właściwości „sdks”. Teraz możesz wyrenderować swoją kartę zgodnie z aktualnym motywem, o której dowiesz się więcej ze strony Microsoftu.

Chcę pokazać dynamiczną zawartość na moim adaptive card. Jak mogę wyświetlić elementy listy SharePoint? Czy istnieje sposób, aby przekazać je do szablonu?

Oczywiście, że tak! Po pierwsze, odwołaj się do swoich danych w klasie z „quick view” – na przykład przekaż wartości ze stanu adaptive card:

public get data(): IQuickViewData {
  return {
    items: this.state.items
  };
}

Dzięki temu potem możesz wyświetlić elementy listy w widoku swojej karty. Pamiętaj, że kontener nadrzędny powinien mieć ustawioną właściwość „$data”:

{
  "type": "AdaptiveCard",
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "version": "1.5",
  "body": [
    {
      "type": "Container",
      "$data": "${items}",
      "items": [
        {
          "type": "TextBlock",
          "text": "${title}",
        },
        …
      ]
    }
}

W efekcie na karcie zostaną wyświetlone wszystkie pozycje z listy! Podobnie jak w przypadku właściwości „data”, właściwości elementu są identyfikowane za pomocą znaku dolara, na przykład „${title}”.

Wygląda na to, że adaptive card nie pozwala na używanie ikon w swoim schemacie. Naprawdę chcę używać ikony Fluent UI na mojej karcie. Co powinienem zrobić?

Zamiast tego użyj obrazu! Odwołaj się do adresu URL zdjęcia:

{
      "type": "Image",
      "url": "https://adaptivecards.io/content/cats/1.png",
      "altText": "Cat"
    }

lub alternatywnie przekonwertuj ikonę na format base64:

{
      "type": "Image",
      "url": "data:image/png;base64,iVBORw0KGgoAAAA…",
      "altText": "Cat"
    }

Możesz poszukać w Internecie konwerterów obrazów lub wypróbować to sprytne rozwiązanie CodePen.

Podsumowanie

Mam nadzieję, że odpowiedziałam na najczęściej pojawiające się pytania i dzięki temu łatwiej odnajdziesz się w świecie Adaptive Card Extension. Chętnie dowiem się, jakie są Twoje porady i obserwacje na temat pracy z tym narzędziem 😊