Funzionalità e proprietà degli oggetti visivi di Power BICapabilities and properties of Power BI visuals

Le funzionalità si usano per fornire all'host informazioni sull'oggetto visivo.You use capabilities to provide information to the host about your visual. Tutte le proprietà nel modello capabilities sono optional.All properties on the capabilities model are optional.

Gli oggetti radice delle funzionalità di un oggetto visivo sono dataRoles, dataViewMappings e così via.The root objects of a visual's capabilities are dataRoles, dataViewMappings, and so on.

{
    "dataRoles": [ ... ],
    "dataViewMappings": [ ... ],
    "objects":  { ... },
    "supportsHighlight": true|false,
    "advancedEditModeSupport": 0|1|2,
    "sorting": { ... }
}

Definire i campi dati previsti dall'oggetto visivo: dataRolesDefine the data fields that your visual expects: dataRoles

Per definire i campi che possono essere associati ai dati, si usa dataRoles.To define fields that can be bound to data, you use dataRoles. dataRoles usa una matrice di oggetti DataViewRole, che definisce tutte le proprietà obbligatorie.dataRoles takes an array of DataViewRole objects, which defines all the required properties.

ProprietàProperties

  • name: nome interno di questo campo dati (deve essere univoco).name: The internal name of this data field (must be unique).
  • kind: tipo di campo:kind: The kind of field:
    • Grouping: valori discreti usati per il raggruppamento dei campi delle misure.Grouping: Discrete values that are used to group measure fields.
    • Measure: valori dei dati numerici.Measure: Numeric data values.
    • GroupingOrMeasure: valori che possono essere usati come raggruppamento o misura.GroupingOrMeasure: Values that can be used as either a grouping or a measure.
  • displayName: nome visualizzato dall'utente nel riquadro Proprietà.displayName: The name displayed to the user in the Properties pane.
  • description: breve descrizione del campo (proprietà facoltativa).description: A short description of the field (optional).
  • requiredTypes: tipo di dati richiesto per questo ruolo dati.requiredTypes: The required type of data for this data role. I valori che non corrispondono sono impostati su null (proprietà facoltativa).Values that don't match are set to null (optional).
  • preferredTypes: tipo di dati preferito per questo ruolo dati (proprietà facoltativa).preferredTypes: The preferred type of data for this data role (optional).

Tipi di dati validi in requiredTypes e preferredTypesValid data types in requiredTypes and preferredTypes

  • bool: valore booleanobool: A boolean value
  • integer: valore intero (numero intero)integer: An integer (whole number) value
  • numeric: valore numericonumeric: A numeric value
  • text: valore di testotext: A text value
  • geography: dati geograficigeography: A geographic data

EsempioExample

"dataRoles": [
    {
        "displayName": "My Category Data",
        "name": "myCategory",
        "kind": "Grouping",
        "requiredTypes": [
            {
                "text": true
            },
            {
                "numeric": true
            },
            {
                "integer": true
            }
        ],
        "preferredTypes": [
            {
                "text": true
            }
        ]
    },
    {
        "displayName": "My Measure Data",
        "name": "myMeasure",
        "kind": "Measure",
        "requiredTypes": [
            {
                "integer": true
            },
            {
                "numeric": true
            }
        ],
        "preferredTypes": [
            {
                "integer": true
            }
        ]
    },
    {
        "displayNameKey": "Visual_Location",
        "name": "Locations",
        "kind": "Measure",
        "displayName": "Locations",
        "requiredTypes": [
            {
                "geography": {
                    "address": true
                }
            },
            {
                "geography": {
                    "city": true
                }
            },
            {
                "geography": {
                    "continent": true
                }
            },
            {
                "geography": {
                    "country": true
                }
            },
            {
                "geography": {
                    "county": true
                }
            },
            {
                "geography": {
                    "place": true
                }
            },
            {
                "geography": {
                    "postalCode": true
                }
            },
            {
                "geography": {
                    "region": true
                }
            },
            {
                "geography": {
                    "stateOrProvince": true
                }
            }
        ]
    }
]

I ruoli dei dati precedenti creeranno i campi visualizzati nell'immagine seguente:The preceding data roles would create the fields that are displayed in the following image:

Campi dei ruoli dei dati

Definire il modo in cui si vuole eseguire il mapping dei dati: dataViewMappingsDefine how you want the data mapped: dataViewMappings

Una proprietà DataViewMappings descrive il modo in cui i ruoli dati sono correlati tra loro e permette di specificare i requisiti condizionali per i ruoli.A DataViewMappings property describes how the data roles relate to each other and allows you to specify conditional requirements for the them.

La maggior parte degli oggetti visivi fornisce un solo mapping, ma è possibile fornire più oggetti dataViewMapping.Most visuals provide a single mapping, but you can provide multiple dataViewMappings. Ogni mapping valido genera una visualizzazione dati.Each valid mapping produces a data view.

"dataViewMappings": [
    {
        "conditions": [ ... ],
        "categorical": { ... },
        "table": { ... },
        "single": { ... },
        "matrix": { ... }
    }
]

Per altre informazioni, vedere Mapping di viste dati in oggetti visivi di Power BI.For more information, see Understand data view mapping in Power BI visuals.

Definire le opzioni del riquadro delle proprietà: objectsDefine property pane options: objects

Gli oggetti descrivono proprietà personalizzabili associate all'oggetto visivo.Objects describe customizable properties that are associated with the visual. Ogni oggetto può avere più proprietà e a ogni proprietà è associato un tipo.Each object can have multiple properties, and each property has a type that's associated with it. I tipi indicano che cosa sarà la proprietà.Types refer to what the property will be.

"objects": {
    "myCustomObject": {
        "displayName": "My Object Name",
        "properties": { ... }
    }
}

Per altre informazioni, vedere Oggetti e proprietà.For more information, see Objects and properties of Power BI visuals.

Gestire l'evidenziazione parziale: supportsHighlightHandle partial highlighting: supportsHighlight

Per impostazione predefinita, questo valore è impostato su false, quindi i valori vengono automaticamente filtrati quando un elemento nella pagina viene selezionato.By default, this value is set to false, which means that your values are automatically filtered when something on the page is selected. Questo filtro automatico aggiorna a sua volta l'oggetto visivo in modo da visualizzare solo il valore selezionato.This automatic filtering in turn updates your visual to display only the selected value. Per visualizzare i dati completi, ma evidenziare solo gli elementi selezionati, è necessario impostare supportsHighlight su true nel file capabilities.json.If you want to display the full data but highlight only the selected items, you need to set supportsHighlight to true in your capabilities.json file.

Per altre informazioni,, vedere Evidenziare i punti dati in oggetti visivi di Power BI.For more information, see Highlight data points in Power BI visuals.

Gestire la modalità di modifica avanzata: advancedEditModeSupportHandle advanced edit mode: advancedEditModeSupport

Un oggetto visivo può dichiarare il supporto della modalità di modifica avanzata.A visual can declare its support of advanced edit mode. Per impostazione predefinita, un oggetto visivo non supporta la modalità di modifica avanzata, a meno che non sia specificato diversamente nel file capabilities.json.By default, a visual doesn't support advanced edit mode, unless stated otherwise in the capabilities.json file.

Per altre informazioni, vedere Modalità di modifica avanzata.For more information, see Advanced edit mode in Power BI visuals.

Opzioni di ordinamento dei dati per l'oggetto visivo: sortingData sorting options for visual: sorting

Un oggetto visivo può definire il proprio comportamento di ordinamento tramite le proprie funzionalità.A visual can define its sorting behavior via its capabilities. Per impostazione predefinita, un oggetto visivo non supporta la modifica dell'ordinamento, a meno che non sia specificato diversamente nel file capabilities.json.By default, a visual doesn't support modifying its sorting order, unless stated otherwise in the capabilities.json file.

Per altre informazioni, vedere Opzioni di ordinamento.For more information, see Sorting options for Power BI visuals.