Het opmaakvenster aanpassen in aangepaste Power BI-visuals
Vanaf API-versie 5.1 kunnen ontwikkelaars visuals maken die gebruikmaken van het nieuwe deelvenster Power-indeling. Ontwikkelaars kunnen de kaarten en hun categorieën definiëren voor elke eigenschap in hun aangepaste visual, zodat makers van rapporten deze visuals gemakkelijker kunnen gebruiken.
De nieuwe API maakt gebruik van de method FormattingModel om onderdelen van de opmaak- en analysedeelvensters aan te passen.
Tip
De getFormattingModel methode vervangt de enumerateObjectInstances methode in eerdere API-versies.
Hiermee getFormattingModel wordt een FormattingModel resultaat geretourneerd waarmee wordt gedefinieerd hoe het opmaak- en analysedeelvenster van de visual eruitziet.
Naast alle mogelijkheden van het oude opmaakvenster biedt het nieuwe opmaakmodel ondersteuning voor nieuwe mogelijkheden voor opmaakvensters, nieuwe eigenschappen en nieuwe hiërarchieën.
Als u een upgrade wilt uitvoeren naar API-versie 5.1+, stelt u het apiVersion in uw pbiviz.json-bestand in op 5.1 of hoger en voert u een van de volgende handelingen uit:
- Gebruik de opmaakmodel-util. (Aanbevolen)
- Gebruik zonder dit hulpprogramma alleen API's volgens de volgende methode.
Een visual maken die ondersteuning biedt voor het nieuwe opmaakvenster
Een aangepast visueel element maken dat gebruikmaakt van het nieuwe opmaakvenster:
Definieer alle aanpasbare
objectsbestanden in uw capabilities.json-bestand .
De volgende eigenschappen zijn vereist voor elk object:- objectnaam
- eigenschapsnaam
- eigenschapstype
Alle andere eigenschappen, inclusief
DisplayNameendescription, zijn nu optioneel.Bouw het aangepaste visual FormattingModel. Definieer de eigenschappen van uw aangepaste visualopmaakmodel en bouw het met behulp van code (niet JSON).
Implementeer de
getFormattingModelAPI in de aangepaste visualklasse die het aangepaste visuele opmaakmodel retourneert. (Deze API vervangt deenumerateObjectInstancesapi die in eerdere versies is gebruikt).
Eigenschappen van kaartopmaak
Als u een aangepast visueel element hebt gemaakt met een oudere API en u wilt migreren naar het nieuwe opmaakvenster, of als u een nieuwe aangepaste visual maakt:
Stel het
apiVersionbestand pbiviz.json in op5.1of hoger.Maak voor elke objectnaam en eigenschapsnaam in capabilities.json een overeenkomende opmaakeigenschap. De opmaakeigenschap moet een descriptor hebben die een
objectNameenpropertyNamedie overeenkomt met de objectnaam en eigenschapsnaam in capabilities.json.
De objects eigenschappen in het mogelijkhedenbestand hebben nog steeds dezelfde indeling en hoeven niet te worden gewijzigd.
Als het object in uw circlecapabilities.json-bestand bijvoorbeeld als volgt is gedefinieerd:
"objects": {
"circle": {
"properties": {
"circleColor": {
"type": {
"fill": {
"solid": {
"color": true
}
}
}
},
}
}
}
De opmaakeigenschap in uw model moet van het type ColorPicker zijn en er als volgt uitzien:
control: {
type: "ColorPicker",
properties: {
descriptor: {
objectName: "circle",
propertyName: "circleColor"
},
value: {
value: this.visualSettings.circle.circleColor
}
}
}
U krijgt een foutmelding als aan een van de volgende voorwaarden wordt voldaan:
- De naam van het object of de eigenschap in het mogelijkhedenbestand komt niet overeen met de naam in het opmaakmodel
- Het eigenschapstype in het mogelijkhedenbestand komt niet overeen met het type in het opmaakmodel
Opmaakmodel
In het opmaakmodel kunt u alle eigenschappen van het opmaakvenster beschrijven en aanpassen.
Onderdelen van het opmaakmodel
In het nieuwe opmaakmodel worden eigenschapsonderdelen gegroepeerd in logische categorieën en subcategorieën. Met deze groepen is het model eenvoudiger te scannen. Er zijn de vijf basisonderdelen, van groot naar klein:
Opmaakmodel
De grootste deelvenstercontainer die wordt gebruikt voor het opmaken van de frontale interface van het deelvenster. Het bevat een lijst met opmaakkaarten.Opmaakkaart
De eigenschappen op het hoogste niveau die container groeperen voor opmaakeigenschappen. Elke kaart bestaat uit een of meer opmaakgroepen, zoals hier wordt weergegeven.
Opmaakgroep
De eigenschappengroeperingscontainer op secundair niveau. De opmaakgroep wordt weergegeven als een groeperingscontainer voor opmaaksegmenten.
Opmaaksegment
Eigenschapscontainer. Er zijn twee typen segmenten:- Eenvoudig segment: Afzonderlijke eigenschapscontainer
- Samengesteld segment: Meerdere gerelateerde eigenschapscontainers gegroepeerd in één opmaaksegment
In de volgende afbeelding ziet u de verschillende typen segmenten. Lettertype is een samengesteld segment dat bestaat uit lettertypefamilie, grootte en vet, cursief en onderstreepte schakelopties. 'Kleur', 'weergave-eenheden' en de andere segmenten zijn eenvoudige segmenten met elk onderdeel.
Opmaakeigenschappen van visualisatievenster
Elke eigenschap in het opmaakmodel moet overeenkomen met het objecttype in het bestand capabilities.json .
In de volgende tabel ziet u de typen opmaakeigenschappen in capabilities.json-bestand en de bijbehorende typeklasse in de eigenschappen van het moderne opmaakmodel:
| Type | Waardetype mogelijkheden | Opmaakeigenschap |
|---|---|---|
| Boolean | Bool | Wisselknop |
| Aantal | ||
| Opsommingslijst | opsomming:[] | |
| Kleur | Opvullen | Colorpicker |
| Verloop | FillRule | Kleurovergangsbalk: eigenschapswaarde moet een tekenreeks zijn die bestaat uit: minValue[,midValue],maxValue |
| Sms verzenden | Sms verzenden |
Mogelijkheden voor het opmaken van objecten
| Type | Waardetype mogelijkheden | Opmaakeigenschap |
|---|---|---|
| Font size | FontSize | NumUpDown |
| Lettertypefamilie | FontFamily | FontPicker |
| Lijnuitlijning | Uitlijning | AlignmentGroup |
| Weergave-eenheden voor etiketten | LabelDisplayUnits | AutoDropDown |
* De eigenschap opsommingslijstopmaak verschilt in het opmaakmodel en in het mogelijkhedenbestand.
Declareer de volgende eigenschappen in de klasse opmaakinstellingen, inclusief de lijst met opsommingsitems:
- ItemDropdown
- ItemFlagsSelection
Declareer de volgende eigenschappen in de klasse opmaakinstellingen, zonder de lijst met opsommingsitems. Declareer de lijst met opsommingsitems in capabilities.json onder het juiste object. (Deze typen zijn hetzelfde als in de vorige API-versies):
- AutoDropdown
- AutoFlagSelection
Eigenschappen van samengesteld segment
Een samengesteld opmaaksegment is een opmaaksegment dat meerdere gerelateerde eigenschappen bevat.
Voorlopig hebben we twee samengestelde segmenttypen:
FontControl
Hierdoor blijven alle eigenschappen van lettertypes bij elkaar. Het bestaat uit de volgende eigenschappen:- Lettertypefamilie
- Lettergrootte
- Vet [optioneel]
- Cursief [optioneel]
- Onderstrepen [optioneel]
Elk van deze eigenschappen moet een bijbehorend object in het mogelijkhedenbestand hebben:
Eigenschappen Type mogelijkheden Opmaaktype Lettertypefamilie Opmaak: { fontFamily} FontPicker Lettergrootte Opmaak: {fontSize} NumUpDown Vet Bool Wisselknop Cursief Bool Wisselknop Onderstrepen Bool Wisselknop MarginPadding Margin padding bepaalt de uitlijning van de tekst in de visual. Het bestaat uit de volgende eigenschappen:
- Left
- Right
- Boven
- Onder
Elk van deze eigenschappen moet een bijbehorend object in het mogelijkhedenbestand hebben:
Eigenschappen Type mogelijkheden Opmaaktype Left Numeriek NumUpDown Right Numeriek NumUpDown Boven Numeriek NumUpDown Onder Numeriek NumUpDown
Voorbeeld: Een gegevenskaart opmaken
In dit voorbeeld laten we zien hoe u een aangepast visueel opmaakmodel met één kaart kunt maken.
De kaart heeft twee groepen:
- Groep lettertypebesturingselement met één samengestelde eigenschap
- Lettertype besturingselement
- Gegevensontwerpgroep met twee eenvoudige eigenschappen
- Kleur lettertype
- Lijnuitlijning
Voeg eerst objecten toe aan een bestand met mogelijkheden:
"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
}
}
}
}
}
}
Maak vervolgens de 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;
}
Dit is het resulterende deelvenster:
Standaardinstellingen opnieuw instellen
Het nieuwe opmaakvenster bevat de optie om alle standaardwaarden van de opmaakkaarteigenschappen opnieuw in te stellen door te klikken op de knop Standaardinstelling herstellen die wordt weergegeven op de geopende kaart.
Als u deze functie wilt inschakelen, voegt u een lijst met opmaakkaarteigenschappendescriptors toe aan de opmaakkaart revertToDefaultDescriptors.
In het volgende voorbeeld ziet u hoe u de standaardknop Opnieuw instellen toevoegt:
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
]
};
Als u kaarten toevoegt revertToDefaultDescriptors aan opmaakkaarten, kunt u ook alle eigenschappen van opmaakkaarten tegelijk opnieuw instellen door te klikken op de instellingen opnieuw instellen op de standaardknop in de bovenste balk van het opmaakvenster:
Eigenschapkiezer voor opmaak
De optionele selector in de descriptor voor opmaakeigenschappen bepaalt waar elke eigenschap is gebonden in de dataView. Er zijn vier verschillende opties. Meer informatie hierover vindt u in objectkiezertypen.
Lokalisatie
Zie De lokale taal toevoegen aan uw Power BI-visual Met lokalisatiebeheer kunt u onderdelen opmaken die u wilt lokaliseren voor meer informatie over de lokalisatiefunctie en het instellen van een lokalisatieomgeving:
displayName: this.localization.getDisplayName("Font_Color_DisplayNameKey");
description: this.localization.getDisplayName("Font_Color_DescriptionKey");
Het lokaliseren van opmaakmodelhulpmiddelen voor het lokaliseren van opmaakhulpmiddelen.
GitHub-resources
Alle opmaakmodelinterfaces vindt u in GitHub - microsoft/powerbi-visuals-api: Aangepaste Api voor Power BI-visuals in 'format-model-api.d.ts'
We raden u aan de nieuwe hulpmiddelen voor opmaakmodellen te gebruiken op GitHub - microsoft/powerbi-visuals-utils-formatmodel: Power BI-visuals opmaak model helper hulpmiddelen
U vindt een voorbeeld van een aangepaste visual SampleBarChart die gebruikmaakt van API-versie 5.1.0 en implementeert
getFormattingModelmet behulp van de nieuwe opmaakmodelhulpmiddelen op GitHub - microsoft/PowerBI-visuals-sampleBarChart: Staafdiagram Aangepaste visual voor zelfstudie.
Gerelateerde inhoud
Meer vragen? Vraag het Power BI-community
Feedback
Binnenkort beschikbaar: In de loop van 2024 zullen we GitHub-problemen geleidelijk uitfaseren als het feedbackmechanisme voor inhoud en deze vervangen door een nieuw feedbacksysteem. Zie voor meer informatie: https://aka.ms/ContentUserFeedback.
Feedback verzenden en weergeven voor