Oggetti e proprietà degli oggetti visivi di Power BIObjects and properties of Power BI visuals
Gli oggetti descrivono proprietà personalizzabili associate a un oggetto visivo.Objects describe customizable properties that are associated with a visual. Un oggetto può avere più proprietà e a ogni proprietà è associato un tipo che descrive la proprietà.An object can have multiple properties, and each property has an associated type that describes what the property will be. Questo articolo fornisce informazioni sugli oggetti e sui tipi di proprietà.This article provides information about objects and property types.
myCustomObject è il nome interno usato per fare riferimento all'oggetto in dataView e enumerateObjectInstances.myCustomObject is the internal name that's used to reference the object within dataView and enumerateObjectInstances.
"objects": {
"myCustomObject": {
"displayName": "My Object Name",
"properties": { ... }
}
}
Nome visualizzatoDisplay name
displayName è il nome che verrà mostrato nel riquadro delle proprietà.displayName is the name that will be shown in the property pane.
ProprietàProperties
properties è una mappa delle proprietà definite dallo sviluppatore.properties is a map of properties that are defined by the developer.
"properties": {
"myFirstProperty": {
"displayName": "firstPropertyName",
"type": ValueTypeDescriptor | StructuralTypeDescriptor
}
}
Nota
show è una proprietà speciale che abilita un'opzione per attivare o disattivare l'oggetto.show is a special property that enables a switch to toggle the object.
Esempio:Example:
"properties": {
"show": {
"displayName": "My Property Switch",
"type": {"bool": true}
}
}
Tipi di proprietàProperty types
Esistono due tipi di proprietà: ValueTypeDescriptor e StructuralTypeDescriptor.There are two property types: ValueTypeDescriptor and StructuralTypeDescriptor.
Descrittore di tipo valoreValue type descriptor
I tipi ValueTypeDescriptor sono principalmente primitivi e in genere vengono usati come oggetto statico.ValueTypeDescriptor types are mostly primitive and are ordinarily used as a static object.
Ecco alcuni degli elementi ValueTypeDescriptor più comuni:Here are some of the common ValueTypeDescriptor elements:
export interface ValueTypeDescriptor {
text?: boolean;
numeric?: boolean;
integer?: boolean;
bool?: boolean;
}
Descrittore di tipo strutturaleStructural type descriptor
I tipi StructuralTypeDescriptor vengono usati principalmente per oggetti associati a dati.StructuralTypeDescriptor types are mostly used for data-bound objects.
Il tipo StructuralTypeDescriptor più comune è fill.The most common StructuralTypeDescriptor type is fill.
export interface StructuralTypeDescriptor {
fill?: FillTypeDescriptor;
}
Proprietà GradientGradient property
La proprietà Gradient è una proprietà che non può essere impostata come proprietà standard.The gradient property is a property that can't be set as a standard property. È invece necessario impostare una regola per la sostituzione della proprietà di selezione del colore (tipo fill).Instead, you need to set a rule for the substitution of the color picker property (fill type).
Un esempio è illustrato nel codice seguente:An example is shown in the following code:
"properties": {
"showAllDataPoints": {
"displayName": "Show all",
"displayNameKey": "Visual_DataPoint_Show_All",
"type": {
"bool": true
}
},
"fill": {
"displayName": "Fill",
"displayNameKey": "Visual_Fill",
"type": {
"fill": {
"solid": {
"color": true
}
}
}
},
"fillRule": {
"displayName": "Color saturation",
"displayNameKey": "Visual_ColorSaturation",
"type": {
"fillRule": {}
},
"rule": {
"inputRole": "Gradient",
"output": {
"property": "fill",
"selector": [
"Category"
]
}
}
}
}
Prestare attenzione alle proprietà fill e fillRule.Pay attention to the fill and fillRule properties. La prima è il selettore dei colori, mentre la seconda è la regola di sostituzione per la sfumatura che sostituisce la proprietà fill, visually, quando vengono soddisfatte le condizioni della regola.The first is the color picker, and the second is the substitution rule for the gradient that will replace the fill property, visually, when the rule conditions are met.
Questo collegamento tra la proprietà fill e la regola di sostituzione è impostato nella sezione "rule">"output" della proprietà fillRule.This link between the fill property and the substitution rule is set in the "rule">"output" section of the fillRule property.
La proprietà "Rule">"InputRole" imposta il ruolo dati che attiva la regola (condizione)."Rule">"InputRole" property sets which data role triggers the rule (condition). In questo esempio, se il ruolo dati "Gradient" contiene dati, viene applicata la regola per la proprietà "fill".In this example, if data role "Gradient" contains data, the rule is applied for the "fill" property.
Il codice seguente illustra un esempio del ruolo dati che attiva la regola di riempimento (the last item):An example of the data role that triggers the fill rule (the last item) is shown in the following 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"
}
]
}
Metodo enumerateObjectInstancesThe enumerateObjectInstances method
Per usare in modo efficace gli oggetti, è necessaria una funzione nell'oggetto visivo personalizzato denominata enumerateObjectInstances.To use objects effectively, you need a function in your custom visual called enumerateObjectInstances. Questa funzione immette oggetti nel riquadro delle proprietà e determina anche la posizione in cui devono essere associati gli oggetti all'interno di dataView.This function populates the property pane with objects and also determines where your objects should be bound within the dataView.
Di seguito viene mostrato l'aspetto di una configurazione tipica:Here is what a typical setup looks like:
public enumerateObjectInstances(options: EnumerateVisualObjectInstancesOptions): VisualObjectInstanceEnumeration {
let objectName: string = options.objectName;
let objectEnumeration: VisualObjectInstance[] = [];
switch( objectName ) {
case 'myCustomObject':
objectEnumeration.push({
objectName: objectName,
properties: { ... },
selector: { ... }
});
break;
};
return objectEnumeration;
}
ProprietàProperties
Le proprietà in enumerateObjectInstances riflettono le proprietà definite nelle funzionalità.The properties in enumerateObjectInstances reflect the properties that you defined in your capabilities. Un esempio è disponibile alla fine di questo articolo.For an example, go to the end of this article.
Selettore di oggettiObjects selector
Il selettore in enumerateObjectInstances determina la posizione in cui ogni oggetto è associato a dataView.The selector in enumerateObjectInstances determines where each object is bound in the dataView. Sono disponibili quattro opzioni diverse.There are four distinct options.
staticstatic
Questo oggetto viene associato a metadati dataviews[index].metadata.objects, come illustrato di seguito.This object is bound to metadata dataviews[index].metadata.objects, as shown here.
selector: null
colonnecolumns
Questo oggetto viene associato a colonne con QueryName corrispondente.This object is bound to columns with the matching QueryName.
selector: {
metadata: 'QueryName'
}
selectorselector
Questo oggetto viene associato all'elemento per cui è stato creato un oggetto selectionID.This object is bound to the element that you created a selectionID for. In questo esempio si presuppone che siano stati creati selectionID per alcuni punti dati e di eseguire un ciclo tra di essi.In this example, let's assume that we've created selectionIDs for some data points, and that we're looping through them.
for (let dataPoint in dataPoints) {
...
selector: dataPoint.selectionID.getSelector()
}
ScopeIdentityScope identity
Questo oggetto viene associato a valori specifici all'intersezione dei gruppi.This object is bound to particular values at the intersection of groups. Se, ad esempio, sono presenti categorie ["Jan", "Feb", "March", ...] e serie ["Small", "Medium", "Large"], può essere necessario un oggetto all'intersezione dei valori che corrispondono a Feb e Large.For example, if you have categories ["Jan", "Feb", "March", ...] and series ["Small", "Medium", "Large"], you might want to have an object at the intersection of values that match Feb and Large. A questo scopo, è possibile ottenere il valore di DataViewScopeIdentity per entrambe le colonne, eseguirne il push alla variabile identities e usare questa sintassi con il selettore.To accomplish this, you could get the DataViewScopeIdentity of both columns, push them to variable identities, and use this syntax with the selector.
selector: {
data: <DataViewScopeIdentity[]>identities
}
EsempioExample
Nell'esempio seguente viene mostrato l'aspetto di un oggetto objectEnumeration per un oggetto customColor con una proprietà, fill.The following example shows what one objectEnumeration would look like for a customColor object with one property, fill. Questo oggetto deve essere associato in modo statico a dataViews[index].metadata.objects, come illustrato di seguito:We want this object bound statically to dataViews[index].metadata.objects, as shown:
objectEnumeration.push({
objectName: "customColor",
displayName: "Custom Color",
properties: {
fill: {
solid: {
color: dataPoint.color
}
}
},
selector: null
});