Dostosowywanie okienka formatowania w wizualizacjach niestandardowych usługi Power BI

Począwszy od interfejsu API w wersji 5.1, deweloperzy mogą tworzyć wizualizacje korzystające z nowego okienka Formatu zasilania. 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.

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

Napiwek

Metoda getFormattingModel zastępuje metodę we wcześniejszych wersjach interfejsu enumerateObjectInstances API.

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

Oprócz wszystkich starych możliwości okienka formatowania nowy model formatowania obsługuje nowe funkcje okienka formatowania, nowe właściwości i nowe hierarchie.

Aby przeprowadzić uaktualnienie do wersji 5.1 lub nowszej interfejsu API, ustaw apiVersion plik pbiviz.jsonna 5.1 lub nowszy i wykonaj jedną z następujących czynności:

• Użyj narzędzia formatowaniamodel. (Zalecane)
• Bez tego narzędzia użyj tylko interfejsów API zgodnie z następującą metodą.

Tworzenie wizualizacji obsługującej nowe okienko formatowania

Aby utworzyć wizualizację niestandardową korzystającą z nowego okienka formatowania:

1. Zdefiniuj wszystkie możliwe do objects dostosowania w pliku capabilities.json .
   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.

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

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

Mapowanie właściwości formatowania

Jeśli masz wizualizację niestandardową utworzoną przy użyciu starszego interfejsu API i chcesz przeprowadzić migrację do nowego okienka formatowania lub jeśli tworzysz nową wizualizację niestandardową:

1. Ustaw w apiVersionpliku 5.1 pbiviz.json wartość lub nowszą.

2. Dla każdej nazwy obiektu i nazwy właściwości w pliku capabilities.json utwó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 pliku 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, zostanie wyświetlony 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 nowym 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 formatowania.

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

  

• Grupa formatowania
  Kontener grupowania właściwości na poziomie pomocniczym. Grupa formatowania jest wyświetlana jako kontener grupowania na potrzeby formatowania wycinków.

  

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

  • Prosty fragment: pojedynczy kontener 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 wycinki z jednym składnikiem.

  

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 pliku capabilities.json i ich pasujące klasy typów we właściwościach nowoczesnego modelu formatowania:

Typ	Typ wartości możliwości	Właściwość formatowania
Wartość logiczna	Bool	Przełącznik przełącznika
Liczba	numeryczne Liczba całkowita	NumUpDown Suwak
Lista wyliczeń	wyliczenie:[]	ItemDropdown ItemFlagsSelection Automatyczne tło AutoFlagsSelection * Zobacz notatkę poniżej
Kolor	Wypełnienie	ColorPicker
Gradientu	FillRule	GradientBar: wartość właściwości powinna być ciągiem składającym się z: minValue[,midValue],maxValue
Text	Text	TextInput Textarea

Możliwości formatowania obiektów

Typ	Typ wartości możliwości	Właściwość formatowania
Font size	FontSize	NumUpDown
Rodzina czcionek	Fontfamily	FontPicker
Wyrównanie linii	Wyrównanie	Grupa wyrównania
Jednostki wyświetlania etykiety	LabelDisplayUnits	AutodropDown

^* Właściwość formatowania listy wyliczania różni się w modelu formatowania i w pliku capabilities.

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

  • ItemDropdown
  • ItemFlagsSelection

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

  • Automatyczne tło
  • AutoFlagWybieranie

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

Formatowanie wycinka złożonego to wycinka formatowania, która zawiera wiele powiązanych właściwości.

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:

  Właściwości	Typ możliwości	Typ formatowania
  Rodzina czcionek	Formatowanie: { fontFamily}	FontPicker
  Rozmiar czcionki	Formatowanie: {fontSize}	NumUpDown
  Pogrubienie	Bool	Przełącznik przełącznika
  Kursywa	Bool	Przełącznik przełącznika
  Podkreślenie	Bool	Przełącznik przełącznika

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

  • Left
  • Right
  • Góra
  • Dół

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

  Właściwości	Typ możliwości	Typ formatowania
  Left	Liczbowe	NumUpDown
  Right	Liczbowe	NumUpDown
  Góra	Liczbowe	NumUpDown
  Dół	Liczbowe	NumUpDown

Przykład: formatowanie karty danych

W tym przykładzie pokazano, jak utworzyć niestandardowy model formatowania wizualizacji z jedną kartą.
Karta ma dwie grupy:

• Grupa formantów czcionek z jedną właściwością złożoną
  • Kontrolka czcionki
• Grupa projektów danych z dwiema prostymi właściwościami
  • Kolor czcionki
  • Wyrównanie linii

Najpierw dodaj obiekty do pliku możliwości:

"objects": {
        "dataCard": {
            "properties": {
                "displayUnitsProperty": {
                    "type":
                    {
                        "formatting": {
                            "labelDisplayUnits": true
                        }
                    }
                },
                "fontSize": { 
                    "type": {
                        "formatting": {
                            "fontSize": true
                        }
                    }
                },
                "fontFamily": {
                    "type": {
                        "formatting": {
                            "fontFamily": true
                        }
                    }
                },
                "fontBold": {
                    "type": {
                        "bool": true
                    }
                },
                "fontUnderline": {
                    "type": {
                        "bool": true
                    }
                },
                "fontItalic": {
                    "type": {
                        "bool": true
                    }
                },
                "fontColor": {
                    "type": {
                        "fill": {
                            "solid": {
                                "color": true
                            }
                        }
                    }
                },
                "lineAlignment": {
                    "type": {
                        "formatting": {
                            "alignment": true
                        }
                    }
                }
            }
        }
    }

Następnie utwórz getFormattingModel

    public getFormattingModel(): powerbi.visuals.FormattingModel {
        // Building data card, We are going to add two formatting groups "Font Control Group" and "Data Design Group"
        let dataCard: powerbi.visuals.FormattingCard = {
            description: "Data Card Description",
            displayName: "Data Card",
            uid: "dataCard_uid",
            groups: []
        }

        // Building formatting group "Font Control Group"
        // Notice that "descriptor" objectName and propertyName should match capabilities object and property names
        let group1_dataFont: powerbi.visuals.FormattingGroup = {
            displayName: "Font Control Group",
            uid: "dataCard_fontControl_group_uid",
            slices: [
                {
                    uid: "dataCard_fontControl_displayUnits_uid",
                    displayName:"display units",
                    control: {
                        type: powerbi.visuals.FormattingComponent.Dropdown,
                        properties: {
                            descriptor: {
                                objectName: "dataCard",
                                propertyName:"displayUnitsProperty"
                            },
                            value: 0
                        }
                    }
                },
                // FontControl slice is composite slice, It means it contain multiple properties inside it
                {
                    uid: "data_font_control_slice_uid",
                    displayName: "Font",
                    control: {
                        type: powerbi.visuals.FormattingComponent.FontControl,
                        properties: {
                            fontFamily: {
                                descriptor: {
                                    objectName: "dataCard",
                                    propertyName: "fontFamily"
                                },
                                value: "wf_standard-font, helvetica, arial, sans-serif"
                            },
                            fontSize: {
                                descriptor: {
                                    objectName: "dataCard",
                                    propertyName: "fontSize"
                                },
                                value: 16
                            },
                            bold: {
                                descriptor: {
                                    objectName: "dataCard",
                                    propertyName: "fontBold"
                                },
                                value: false
                            },
                            italic: {
                                descriptor: {
                                    objectName: "dataCard",
                                    propertyName: "fontItalic"
                                },
                                value: false
                            },
                            underline: {
                                descriptor: {
                                    objectName: "dataCard",
                                    propertyName: "fontUnderline"
                                },
                                value: false
                            }
                        }
                    }
                }
            ],
        };
        // Building formatting group "Font Control Group"
        // Notice that "descriptor" objectName and propertyName should match capabilities object and property names
        let group2_dataDesign: powerbi.visuals.FormattingGroup = {
            displayName: "Data Design Group",
            uid: "dataCard_dataDesign_group_uid",
            slices: [
                // Adding ColorPicker simple slice for font color
                {
                    displayName: "Font Color",
                    uid: "dataCard_dataDesign_fontColor_slice",
                    control: {
                        type: powerbi.visuals.FormattingComponent.ColorPicker,
                        properties: {
                            descriptor:
                            {
                                objectName: "dataCard",
                                propertyName: "fontColor"
                            },
                            value: { value: "#01B8AA" }
                        }
                    }
                },
                // Adding AlignmentGroup simple slice for line alignment
                {
                    displayName: "Line Alignment",
                    uid: "dataCard_dataDesign_lineAlignment_slice",
                    control: {
                        type: powerbi.visuals.FormattingComponent.AlignmentGroup,
                        properties: {
                            descriptor:
                            {
                                objectName: "dataCard",
                                propertyName: "lineAlignment"
                            },
                            mode: powerbi.visuals.AlignmentGroupMode.Horizonal,
                            value: "right"
                        }
                    }
                },
            ]
        };

        // Add formatting groups to data card
        dataCard.groups.push(group1_dataFont);
        dataCard.groups.push(group2_dataDesign);

        // Build and return formatting model with data card
        const formattingModel: powerbi.visuals.FormattingModel = { cards: [dataCard] };
        return formattingModel;
    }

Oto wynikowe okienko:

Resetuj ustawienia domyślnie

Nowe okienko formatu ma możliwość zresetowania wszystkich wartości właściwości karty formatowania domyślnie, klikając przycisk Resetuj do domyślnego , który jest wyświetlany na otwartej karcie.

Aby włączyć tę funkcję, dodaj listę deskryptorów właściwości karty formatowania do formatowania karty revertToDefaultDescriptors. W poniższym przykładzie pokazano, jak dodać przycisk resetuj do domyślnego:

let dataCard: powerbi.visuals.FormattingCard = {
    displayName: "Data Card",
    // ... card parameters and groups list

    revertToDefaultDescriptors: [
        {
            objectName: "dataCard",
            propertyName:"displayUnitsProperty"
        },
        {
            objectName: "dataCard",
            propertyName: "fontFamily"
        },

        // ... the rest of properties descriptors 
    ]
};

Dodanie revertToDefaultDescriptors do kart formatowania umożliwia również zresetowanie wszystkich właściwości kart formatowania jednocześnie, klikając przycisk resetuj wszystkie ustawienia domyślne na górnym pasku okienka formatowania:

Selektor właściwości formatowania

Opcjonalny selektor w deskryptorze właściwości formatowania określa, gdzie każda właściwość jest powiązana w widoku dataView. Istnieją cztery różne opcje. Przeczytaj o nich w typach selektorów obiektów.

Lokalizacja

Aby uzyskać więcej informacji na temat funkcji lokalizacji i konfigurowania środowiska lokalizacji, zobacz Dodawanie języka lokalnego do wizualizacji usługi Power BI Używanie menedżera lokalizacji do formatowania składników, które chcesz lokalizować:

displayName: this.localization.getDisplayName("Font_Color_DisplayNameKey");
description: this.localization.getDisplayName("Font_Color_DescriptionKey");

Aby zlokalizować formatowanie modelu narzędzia formatowania utils lokalizacji narzędzia.

Zasoby usługi GitHub

• Wszystkie interfejsy modelu formatowania można znaleźć w witrynie GitHub — microsoft/powerbi-visuals-api: interfejs API wizualizacji niestandardowych usługi Power BI w obszarze "formatting-model-api.d.ts"

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

• Możesz znaleźć przykład wizualizacji niestandardowej SampleBarChart , która używa interfejsu API w wersji 5.1.0 i implementuje getFormattingModel przy użyciu nowych narzędzi modelu formatowania w witrynie GitHub — microsoft/PowerBI-visuals-sampleBarChart: Wykres słupkowy wizualizacji niestandardowej na potrzeby samouczka.

Powiązana zawartość

Masz więcej pytań? Zapytaj Społeczność usługi Power BI