Okienko formatowania w wizualizacjach niestandardowych usługi Power BI

Korzystając z interfejsu API w wersji 5.1 lub nowszej, deweloperzy mogą tworzyć wizualizacje za pomocą okienka Format. Deweloperzy mogą definiować karty i ich kategorie dla dowolnej właściwości w wizualizacji niestandardowej, co ułatwia twórcom raportów korzystanie z tych wizualizacji.

Interfejs API używa metody FormattingModel do dostosowywania części okienek formatu i analizy.

Funkcja getFormattingModel zwraca element FormattingModel definiujący wygląd okienka formatowania i analizy wizualizacji.

Oprócz dotychczasowych możliwości model formatowania obsługuje także bieżące funkcje okienka formatowania, właściwości i hierarchie.

Tworzenie wizualizacji obsługującej najnowsze okienko Format

Ogólne kroki dodawania obsługi okienka Format do wizualizacji niestandardowej:

1. Ustaw element apiVersion w pliku pbiviz.json na 5.1 lub nowszy.

2. Zdefiniuj wszystkie objects możliwe do dostosowania w pliku capabilities.json. Te obiekty są następnie przypisywane do właściwości okienka formatowania. Dla każdego obiektu wymagane są następujące właściwości:

   • nazwa obiektu
   • nazwa właściwości
   • typ właściwości

   Wszystkie inne właściwości, w tym DisplayName i description, są teraz opcjonalne.

3. Stwórz wizualizację niestandardową FormattingModel, wykonując jedną z poniższych czynności:

   • Użyj narzędzia formattingmodel. (Zalecane)
   • Bez tego narzędzia korzystaj tylko z interfejsów API.

Zdefiniuj właściwości niestandardowego modelu formatowania wizualizacji i skompiluj go przy użyciu kodu (a nie kodu JSON).

4. Zaimplementuj getFormattingModel API w klasie wizualizacji niestandardowej, który zwraca niestandardowy model formatowania wizualizacji. (Ten interfejs API zastępuje enumerateObjectInstances element używany w poprzednich wersjach).

Przykład implementacji modelu formatowania

• Przykład użycia narzędzia formattingmodel do modelowania formatowania. (Zalecane)
• Formatowanie modelu przy użyciu tylko przykładowych interfejsów API.

Właściwości formatowania mapy

Jeśli masz wizualizację niestandardową utworzoną przy użyciu starszego interfejsu API i chcesz ją zaktualizować za pomocą okienka formatowania lub jeśli tworzysz nową wizualizację niestandardową:

1. Ustaw element apiVersion w pliku pbiviz.json na 5.1 lub nowszy.

2. Dla każdej nazwy obiektu i nazwy właściwości w capabilities.jsonutwórz zgodną właściwość formatowania. Właściwość formatowania powinna zawierać deskryptor zawierający element objectName i propertyName zgodny z nazwą obiektu i nazwą właściwości w capabilities.json.

objects Właściwości w pliku capabilities nadal mają ten sam format i nie trzeba ich zmieniać.

Jeśli na przykład circle obiekt w pliku capabilities.json jest zdefiniowany w następujący sposób:

"objects": {
    "circle": {
        "properties": {
            "circleColor": {
                "type": {
                    "fill": {
                        "solid": {
                            "color": true
                        }
                    }
                }
            },
        }
    }
}

Właściwość formatowania w modelu powinna być typu ColorPicker i wyglądać następująco:

control: {
    type: "ColorPicker",
    properties: {
        descriptor: {
            objectName: "circle",
            propertyName: "circleColor"
        },
        value: {
            value: this.visualSettings.circle.circleColor
        }
    }
}

Jeśli spełniony jest jeden z następujących warunków, występuje błąd:

• Nazwa obiektu lub właściwości w pliku capabilities nie jest zgodna z nazwą obiektu w modelu formatowania
• Typ właściwości w pliku capabilities nie jest zgodny z typem w modelu formatowania

Model formatowania

Model formatowania to miejsce, w którym opisano i dostosujesz wszystkie właściwości okienka formatowania.

Formatowanie składników modelu

W modelu formatowania składniki właściwości są grupowane razem w kategoriach logicznych i podkategorii. Te grupy ułatwiają skanowanie modelu. Istnieją pięć podstawowych składników, od największych do najmniejszych:

• Model formatowania Największy kontener okienka używany do formatowania interfejsu frontalnego okienka. Zawiera listę kart do formatowania.

• Karta formatowania Kontener grupujący właściwości najwyższego poziomu właściwości formatowania. Każda karta składa się z co najmniej jednej grupy formatowania, jak pokazano poniżej.

  

• Grupa formatowania
  Kontener grupujący właściwości na drugorzędnym poziomie. Grupa formatowania jest wyświetlana jako kontener grupowania na potrzeby formatowania wycinków.

  

• Formatowanie kontenera
  Kontener grupujący właściwości na drugorzędnym poziomie. Kontener formatowania grupuje wycinki formatowania w oddzielne elementy kontenera i umożliwia przełączanie się między nimi za pomocą listy rozwijanej.

  

• Fragment formatowania
  Kontener właściwości. Istnieją dwa typy wycinków:

  • Prosty wycinek: kontener pojedynczej właściwości
  • Fragment złożony: wiele powiązanych kontenerów właściwości pogrupowanych w jeden wycinek formatowania

  Na poniższej ilustracji przedstawiono różne typy wycinków. "Czcionka" to fragment złożony składający się z rodziny czcionek, rozmiaru i pogrubienia, kursywy i przełączników podkreślenia. "Kolor", "jednostki wyświetlania" i inne wycinki to proste elementy z jednym komponentem.

  

Właściwości formatowania okienka wizualizacji

Każda właściwość w modelu formatowania powinna być zgodna z typem obiektu w pliku capabilities.json.

W poniższej tabeli przedstawiono typy właściwości formatowania w plikucapabilities.json i ich pasujące klasy typów we właściwościach nowoczesnego modelu formatowania:

Możliwości formatowania obiektów

^* Właściwość formatowania listy wyliczeniowej różni się w modelu formatowania i w pliku możliwości.

• Zadeklaruj następujące właściwości w klasie ustawień formatowania, w tym listę elementów wyliczenia:

  • Lista rozwijana elementów
  • ItemFlagsSelection

• Zadeklaruj następujące właściwości w klasie ustawień formatowania bez listy elementów wyliczenia. Zadeklaruj listę elementów wyliczenia w capabilities.json pod odpowiednim obiektem. (Te typy są takie same jak w poprzednich wersjach interfejsu API):

  • Automatyczne menu rozwijane
  • AutoFlagWybieranie

Właściwości wycinka złożonego

Wycinek formatowania złożonego to fragment formatowania, który zawiera wiele powiązanych właściwości razem.

Na razie mamy dwa typy wycinków złożonych:

• FontControl
  Spowoduje to zachowanie wszystkich właściwości powiązanych z czcionką. Składa się z następujących właściwości:

  • Rodzina czcionek
  • Rozmiar czcionki
  • Pogrubienie [opcjonalnie]
  • Kursywa [opcjonalnie]
  • Podkreślnie [opcjonalne]

  

  Każda z tych właściwości powinna mieć odpowiedni obiekt w pliku capabilities:

  Majątek	Typ możliwości	Typ formatowania
  Rodzina czcionek	Formatowanie: { fontFamily}	FontPicker
  Rozmiar czcionki	Formatowanie: {fontSize}	NumUpDown
  Pogrubiona	bool	Przełącznik
  Italik	bool	Przełącznik
  Podkreślenie	bool	Przełącznik

• MarginPadding Wypełnienie marginesu określa wyrównanie tekstu w wizualizacji. Składa się z następujących właściwości:

  • Lewo
  • Prawo
  • Do góry
  • Dno

  Każda z tych właściwości powinna mieć odpowiedni obiekt w pliku capabilities:

  Majątek	Typ możliwości	Typ formatowania
  Lewo	Liczbowy	NumUpDown
  Prawo	Liczbowy	NumUpDown
  Do góry	Liczbowy	NumUpDown
  Dno	Liczbowy	NumUpDown

Zasoby usługi GitHub

• Wszystkie interfejsy modelu formatowania są dostępne w GitHub - microsoft/powerbi-visuals-api: interfejs API wizualizacji niestandardowych usługi Power BI w pliku "formatting-model-api.d.ts".

• Zalecamy używanie najnowszych narzędzi modelu formatowania w witrynie GitHub — microsoft/powerbi-visuals-utils-formattingmodel: narzędzia pomocnika modelu formatowania wizualizacji usługi Power BI

• Przykład wizualizacji niestandardowej SampleBarChart, który korzysta z interfejsu API w wersji 5.1.0 i implementuje getFormattingModel przy wykorzystaniu najnowszych narzędzi modelu formatowania, można znaleźć na GitHub — microsoft/PowerBI-visuals-sampleBarChart: Wykres słupkowy wizualizacji niestandardowej na potrzeby samouczka.

Treści powiązane

Więcej pytań? Zapytaj Społeczność usługi Power BI.