Objecten en eigenschappen van Power BI-visuals

  • Artikel

Objecten beschrijven aanpasbare eigenschappen die zijn gekoppeld aan een visual. Een object kan meerdere eigenschappen hebben en elke eigenschap heeft een gekoppeld type dat beschrijft wat de eigenschap is. Dit artikel bevat informatie over objecten en eigenschapstypen.

myCustomObject is de interne naam die wordt gebruikt om naar het object binnen dataViewte verwijzen.

"objects": {
    "myCustomObject": {
        "properties": { ... }
    }
}

Schermnaam en -beschrijving

Notitie

Weergavenaam en beschrijving zijn afgeschaft uit API-versie 5.1+. De weergavenaam en beschrijving worden nu toegevoegd in het opmaakmodel in plaats van het capabilities.json-bestand .

displayName is de naam die wordt weergegeven in het eigenschappenvenster. description is een beschrijving van de opmaakeigenschap die als knopinfo voor de gebruiker wordt weergegeven.

Eigenschappen

properties is een kaart met eigenschappen die zijn gedefinieerd door de ontwikkelaar.

"properties": {
    "myFirstProperty": {
        "type": ValueTypeDescriptor | StructuralTypeDescriptor
    }
}

Notitie

show is een speciale eigenschap waarmee een schakeloptie het object kan in- of uitschakelen.

Voorbeeld:

"properties": {
    "show": {
        "type": {"bool": true}
    }
}

Eigenschapstypen

Er zijn twee eigenschapstypen: ValueTypeDescriptor en StructuralTypeDescriptor.

Waardetypedescriptor

ValueTypeDescriptor typen zijn voornamelijk primitief en worden gewoonlijk gebruikt als een statisch object.

Hier volgen enkele algemene ValueTypeDescriptor elementen:

export interface ValueTypeDescriptor {
    text?: boolean;
    numeric?: boolean;
    integer?: boolean;
    bool?: boolean;
}

Structuurtypedescriptor

StructuralTypeDescriptor typen worden meestal gebruikt voor gegevensgebonden objecten. Het meest voorkomende StructuralTypeDescriptor type is opvulling.

export interface StructuralTypeDescriptor {
    fill?: FillTypeDescriptor;
}

Kleurovergangseigenschap

De eigenschap kleurovergang is een eigenschap die niet kan worden ingesteld als een standaardeigenschap. In plaats daarvan moet u een regel instellen voor de vervanging van de eigenschap kleurkiezer (opvultype ).

Een voorbeeld wordt weergegeven in de volgende code:

"properties": {
    "showAllDataPoints": {
        "type": {
            "bool": true
        }
    },
    "fill": {
        "type": {
            "fill": {
                "solid": {
                    "color": true
                }
            }
        }
    },
    "fillRule": {
        "type": {
            "fillRule": {}
        },
        "rule": {
            "inputRole": "Gradient",
            "output": {
                "property": "fill",
                    "selector": [
                        "Category"
                    ]
            }
        }
    }
}

Let op de eigenschappen fill en fillRule . De eerste is de kleurkiezer en de tweede is de vervangingsregel voor de kleurovergang die de opvuleigenschap vervangt, visuallywanneer aan de voorwaarden van de regel wordt voldaan.

Deze koppeling tussen de vuleigenschap en de vervangingsregel wordt ingesteld in de>"rule""output" sectie van de eigenschap fillRule.

"Rule">"InputRole" met eigenschap wordt ingesteld welke gegevensrol de regel (voorwaarde) activeert. Als de gegevensrol "Gradient" in dit voorbeeld gegevens bevat, wordt de regel toegepast voor de "fill" eigenschap.

Een voorbeeld van de gegevensrol die de vulregel activeert (the last item) wordt weergegeven in de volgende code:

{
    "dataRoles": [
            {
                "name": "Category",
                "kind": "Grouping",
                "displayName": "Details",
                "displayNameKey": "Role_DisplayName_Details"
            },
            {
                "name": "Series",
                "kind": "Grouping",
                "displayName": "Legend",
                "displayNameKey": "Role_DisplayName_Legend"
            },
            {
                "name": "Gradient",
                "kind": "Measure",
                "displayName": "Color saturation",
                "displayNameKey": "Role_DisplayName_Gradient"
            }
    ]
}

Opmaakvenster

Als u de eigenschappen in het opmaakvenster wilt aanpassen, gebruikt u een van de volgende methoden, afhankelijk van de API-versie die u gebruikt.

Notitie

De getFormattingModel API-methode wordt ondersteund vanuit API-versies 5.1+. Als u wilt weten welke versie u gebruikt, controleert u het apiVersionbestand pbiviz.json .

Als u objecten effectief wilt gebruiken in API-versie 5.1+, moet u de getFormattingModel methode implementeren.
Met deze methode wordt een opmaakmodel gebouwd en geretourneerd dat volledige eigenschappenvensterhiërarchie van opmaakkaarten, opmaakgroepen bevat, ook opmaakeigenschappen en de bijbehorende waarden bevat.

Mogelijkhedenobjecten die worden weerspiegeld in het opmaakmodel

Elke opmaakeigenschap in het opmaakmodel heeft een bijbehorend object nodig in het bestand capabilities.json . De opmaakeigenschap moet een descriptor bevatten met een objectnaam en eigenschapsnaam die exact overeenkomen met het bijbehorende mogelijkhedenobject (de object- en eigenschapsnamen zijn hoofdlettergevoelig).
Bijvoorbeeld:

Voor de volgende opmaakeigenschap in het opmaakmodel (zie de inhoud van het descriptorobject):

 const myCustomCard: powerbi.visuals.FormattingCard = {
            displayName: "My Custom Object Card",
            uid: "myCustomObjectCard_uid",
            groups: [{
                displayName: undefined,
                uid: "myCustomObjectGroup_uid",
                slices: [
                    {
                        uid: "myCustomProperty_uid",
                        displayName: "My Custom Property",
                        control: {
                            type: powerbi.visuals.FormattingComponent.ColorPicker,
                            properties: {
                                descriptor: {
                                    objectName: "myCustomObject",
                                    propertyName: "myCustomProperty",
                                    selector: null // selector is optional
                                },
                                value: { value: "#000000" }
                            }
                        }
                    }
                ],
            }],
        };

Het bijbehorende object uit de sectie mogelijkheden objects moet het volgende zijn:

    "objects": {
        "myCustomObject": {
            "properties": {
                "myCustomProperty": {
                    "type": {
                         "fill": {
                            "solid": {
                                "color": true
                            }
                        }
                    }
                }
            }
        }
    }

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.

Opmerking

In het bovenstaande myCustomCard voorbeeld ziet u hoe de opmaakeigenschap in het opmaakmodel eruit zou zien voor een object met één eigenschap myCustomProperty. Dit eigenschapsobject is statisch gebonden aan dataViews[index].metadata.objects. Selector in descriptor kan dienovereenkomstig worden gewijzigd in selectortype dat u kiest.

Objectselectorstypen

De selector in enumerateObjectInstances bepaalt waar elk object is gebonden in de dataView. Er zijn vier verschillende opties:

statisch

Dit object is gebonden aan metagegevens dataviews[index].metadata.objects, zoals hier wordt weergegeven.

selector: null

kolommen

Dit object is gebonden aan kolommen met de overeenkomende QueryNamewaarden.

selector: {
    metadata: 'QueryName'
}

Selector

Dit object is gebonden aan het element waarvoor u een selectionID hebt gemaakt. In dit voorbeeld gaan we ervan uit dat we een aantal gegevenspunten hebben gemaakt selectionIDen dat we ze doorlopen.

for (let dataPoint in dataPoints) {
    ...
    selector: dataPoint.selectionID.getSelector()
}

Bereikidentiteit

Dit object is gebonden aan bepaalde waarden op het snijpunt van groepen. Als u bijvoorbeeld categorieën en reeksen ["Jan", "Feb", "March", ...]["Small", "Medium", "Large"]hebt, wilt u mogelijk een object hebben op het snijpunt van waarden die overeenkomen Feb en Large. Om dit te bereiken, kunt u de DataViewScopeIdentity kolommen ophalen, naar een variabele identitiespushen en deze syntaxis gebruiken met de selector.

selector: {
    data: <DataViewScopeIdentity[]>identities
}

Gerelateerde inhoud

Tips voor prestaties