API dei filtri degli oggetti visivi negli oggetti visivi di Power BIThe Visual Filters API in Power BI visuals

L'API dei filtri visivi consente di filtrare i dati negli oggetti visivi di Power BI.The Visual Filters API allows you to filter data in Power BI visuals. La differenza principale rispetto alle altre selezioni consiste nel fatto che gli altri oggetti visivi verranno filtrati in qualsiasi modo, indipendentemente dal supporto dell'evidenziazione in tali oggetti visivi.The main difference from other selections is that other visuals will be filtered in any way, despite highlight support by other visual.

Per abilitare il filtro per l'oggetto visivo, questo deve contenere l'oggetto filter nella sezione general del codice di capabilities.json.To enable filtering for the visual, it should contain a filter object in the general section of capabilities.json code.

"objects": {
        "general": {
            "displayName": "General",
            "displayNameKey": "formattingGeneral",
            "properties": {
                "filter": {
                    "type": {
                        "filter": true
                    }
                }
            }
        }
    }

Le interfacce API per i filtri degli oggetti visivi sono disponibili nel pacchetto powerbi-models.Visual Filters API interfaces are available in the powerbi-models package. Il pacchetto contiene anche classi per la creazione di istanze di filtro.The package also contains classes to create filter instances.

npm install powerbi-models --save

Se si usa una versione meno recente degli strumenti (precedente a 3.x.x), è necessario includere powerbi-models nel pacchetto degli oggetti visivi.If you use an older (earlier than 3.x.x) version of the tools, you should include powerbi-models in the visuals package. Per altre informazioni, vedere la guida Aggiungere l'API del filtro avanzato all'oggetto visivo personalizzato.For more information, see the short guide, Add the Advanced Filter API to the custom visual.

Tutti i filtri estendono l'interfaccia IFilter, come illustrato nel codice seguente:All filters extend the IFilter interface, as shown in the following code:

export interface IFilter {
    $schema: string;
    target: IFilterTarget;
}

Dove:Where:

  • target è la colonna della tabella nell'origine dati.target is the table column on the data source.

API del filtro di baseThe Basic Filter API

L'interfaccia del filtro di base è illustrata nel codice seguente:Basic filter interface is shown in the following code:

export interface IBasicFilter extends IFilter {
    operator: BasicFilterOperators;
    values: (string | number | boolean)[];
}

Dove:Where:

  • operator è un'enumerazione con i valori In, NotIn e All.operator is an enumeration with the values In, NotIn, and All.
  • values sono i valori per la condizione.values are values for the condition.

Esempio di filtro di base:Example of a basic filter:

let basicFilter = {
    target: {
        column: "Col1"
    },
    operator: "In",
    values: [1,2,3]
}

Il filtro indica di fornire tutte le righe in cui col1 è uguale al valore 1, 2 o 3.The filter means, "Give me all rows where col1 equals the value 1, 2, or 3."

L'equivalente SQL è il seguente:The SQL equivalent is:

SELECT * FROM table WHERE col1 IN ( 1 , 2 , 3 )

Per creare un filtro, è possibile usare la classe BasicFilter in powerbi-models.To create a filter, you can use the BasicFilter class in powerbi-models.

Se si usa una versione precedente dello strumento, è necessario ottenere un'istanza dei modelli nell'oggetto finestra usando window['powerbi-models'], come illustrato nel codice seguente:If you use an older version of the tool, you should get an instance of models in the window object by using window['powerbi-models'], as shown in the following code:

let categories: DataViewCategoricalColumn = this.dataView.categorical.categories[0];

let target: IFilterColumnTarget = {
    table: categories.source.queryName.substr(0, categories.source.queryName.indexOf('.')),
    column: categories.source.displayName
};

let values = [ 1, 2, 3 ];

let filter: IBasicFilter = new window['powerbi-models'].BasicFilter(target, "In", values);

L'oggetto visivo richiama il filtro usando il metodo applyJsonFilter() nell'interfaccia host, IVisualHost, che viene fornita all'oggetto visivo nel costruttore.The visual invokes the filter by using the applyJsonFilter() method on the host interface, IVisualHost, which is provided to the visual in the constructor.

visualHost.applyJsonFilter(filter, "general", "filter", FilterAction.merge);

API del filtro avanzatoThe Advanced Filter API

L'API del filtro avanzato permette query complesse di selezione e filtro di punti dati tra oggetti visivi in base a più criteri, tra cui LessThan, Contains, Is, IsBlank e così via.The Advanced Filter API enables complex cross-visual data-point selection and filtering queries that are based on multiple criteria, such as LessThan, Contains, Is, IsBlank, and so on).

Il filtro è stato introdotto nell'API degli oggetti visivi 1.7.0.The filter was introduced in Visuals API 1.7.0.

Anche l'API del filtro avanzato richiede target con i nomi table e column.The Advanced Filter API also requires target with a table and column name. Tuttavia, gli operatori dell'API del filtro avanzato sono And e Or.But the Advanced Filter API operators are And and Or.

Inoltre, il filtro usa condizioni invece di valori con l'interfaccia:Additionally, the filter uses conditions instead of values with the interface:

interface IAdvancedFilterCondition {
    value: (string | number | boolean);
    operator: AdvancedFilterConditionOperators;
}

Gli operatori di condizione per il parametro operator sono None, LessThan, LessThanOrEqual, GreaterThan, GreaterThanOrEqual, Contains, DoesNotContain, StartsWith, DoesNotStartWith, Is, IsNot, IsBlank e "IsNotBlank"`Condition operators for the operator parameter are None, LessThan, LessThanOrEqual, GreaterThan, GreaterThanOrEqual, Contains, DoesNotContain, StartsWith, DoesNotStartWith, Is, IsNot, IsBlank, and "IsNotBlank"`

let categories: DataViewCategoricalColumn = this.dataView.categorical.categories[0];

let target: IFilterColumnTarget = {
    table: categories.source.queryName.substr(0, categories.source.queryName.indexOf('.')), // table
    column: categories.source.displayName // col1
};

let conditions: IAdvancedFilterCondition[] = [];

conditions.push({
    operator: "LessThan",
    value: 0
});

let filter: IAdvancedFilter = new window['powerbi-models'].AdvancedFilter(target, "And", conditions);

// invoke the filter
visualHost.applyJsonFilter(filter, "general", "filter", FilterAction.merge);

L'equivalente SQL è il seguente:The SQL equivalent is:

SELECT * FROM table WHERE col1 < 0;

Per il codice di esempio completo per l'uso dell'API del filtro avanzato, vedere il repository dell'oggetto visivo Sampleslicer.For the complete sample code for using the Advanced Filter API, go to the Sampleslicer visual repository.

API del filtro di tuple (filtro multicolonna)The Tuple Filter API (multi-column filter)

L'API del filtro di tuple è stata introdotta nell'API degli oggetti visivi 2.3.0.The Tuple Filter API was introduced in Visuals API 2.3.0. È simile all'API del filtro di base, ma permette di definire condizioni per diverse colonne e tabelle.It is similar to the Basic Filter API, but it allows you to define conditions for several columns and tables.

L'interfaccia del filtro è illustrata nel codice seguente:The filter interface is shown in the following code:

interface ITupleFilter extends IFilter {
    $schema: string;
    filterType: FilterType;
    operator: TupleFilterOperators;
    target: ITupleFilterTarget;
    values: TupleValueType[];
}

Dove:Where:

  • target è una matrice di colonne con nomi di tabella:target is an array of columns with table names:

    declare type ITupleFilterTarget = IFilterTarget[];
    

    Il filtro può riguardare colonne di varie tabelle.The filter can address columns from various tables.

  • $schema è https://powerbi.com/product/schema#tuple.$schema is https://powerbi.com/product/schema#tuple.

  • filterType è FilterType.Tuple.filterType is FilterType.Tuple.

  • operator consente l'uso solo nell'operatore In.operator allows use only in the In operator.

  • values è una matrice di tuple di valori e ogni tupla rappresenta una combinazione consentita dei valori della colonna di destinazione.values is an array of value tuples, and each tuple represents one permitted combination of the target column values.

declare type TupleValueType = ITupleElementValue[];

interface ITupleElementValue {
    value: PrimitiveValueType
}

Esempio completo:Complete example:

let target: ITupleFilterTarget = [
    {
        table: "DataTable",
        column: "Team"
    },
    {
        table: "DataTable",
        column: "Value"
    }
];

let values = [
    [
        // the first column combination value (or the column tuple/vector value) that the filter will pass through
        {
            value: "Team1" // the value for the `Team` column of the `DataTable` table
        },
        {
            value: 5 // the value for the `Value` column of the `DataTable` table
        }
    ],
    [
        // the second column combination value (or the column tuple/vector value) that the filter will pass through
        {
            value: "Team2" // the value for `Team` column of `DataTable` table
        },
        {
            value: 6 // the value for `Value` column of `DataTable` table
        }
    ]
];

let filter: ITupleFilter = {
    $schema: "https://powerbi.com/product/schema#tuple",
    filterType: FilterType.Tuple,
    operator: "In",
    target: target,
    values: values
}

// invoke the filter
visualHost.applyJsonFilter(filter, "general", "filter", FilterAction.merge);

Importante

L'ordine dei nomi di colonna e dei valori della condizione è importante.The order of the column names and condition values is sensitive.

L'equivalente SQL è il seguente:The SQL equivalent is:

SELECT * FROM DataTable WHERE ( Team = "Team1" AND Value = 5 ) OR ( Team = "Team2" AND Value = 6 );

Ripristinare il filtro JSON dalla vista datiRestore the JSON filter from the data view

A partire dall'API versione 2.2.0, è possibile ripristinare il filtro JSON da VisualUpdateOptions, come illustrato nel codice seguente:Starting with API version 2.2.0, you can restore the JSON filter from VisualUpdateOptions, as shown in the following code:

export interface VisualUpdateOptions extends extensibility.VisualUpdateOptions {
    viewport: IViewport;
    dataViews: DataView[];
    type: VisualUpdateType;
    viewMode?: ViewMode;
    editMode?: EditMode;
    operationKind?: VisualDataChangeOperationKind;
    jsonFilters?: IFilter[];
}

Quando si passa da un segnalibro all'altro, Power BI chiama il metodo update dell'oggetto visivo e l'oggetto visivo ottiene l'oggetto filter corrispondente.When you switch, bookmarks, Power BI calls the update method of the visual, and the visual gets a corresponding filter object. Per altre informazioni, vedere Aggiungere il supporto dei segnalibri per gli oggetti visivi di Power BI.For more information, see Add bookmark support for Power BI visuals.

Filtro JSON di esempioSample JSON filter

Nell'immagine seguente è illustrato il codice del filtro JSON di esempio:Some sample JSON filter code is shown in the following image:

Codice del filtro JSON

Cancellare il filtro JSONClear the JSON filter

L'API del filtro accetta il valore null del filtro come reimpostazione o cancellazione.The Filter API accepts the null value of the filter as reset or clear.

// invoke the filter
visualHost.applyJsonFilter(null, "general", "filter", FilterAction.merge);