Rozhraní API filtrů vizuálů ve vizuálech Power BIThe Visual Filters API in Power BI visuals

Rozhraní API filtrů vizuálů umožňuje filtrování dat ve vizuálech Power BI.The Visual Filters API allows you to filter data in Power BI visuals. Od jiných výběrů se liší zejména tím, že jiné vizuály se budou filtrovat jakýmkoli způsobem, bez ohledu na podporu zvýraznění jiného vizuálu.The main difference from other selections is that other visuals will be filtered in any way, despite highlight support by other visual.

Pokud chcete u vizuálu povolit filtrování, měl by vizuál obsahovat objekt filter v sekci general kódu 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
                    }
                }
            }
        }
    }

Rozhraní API filtrů vizuálů jsou dostupná v balíčku powerbi-models.Visual Filters API interfaces are available in the powerbi-models package. Balíček dále obsahuje třídy pro vytváření instancí filtrů.The package also contains classes to create filter instances.

npm install powerbi-models --save

Pokud používáte starší verzi nástrojů (starší než 3.x.x), měli byste do balíčku vizuálů zahrnout powerbi-models.If you use an older (earlier than 3.x.x) version of the tools, you should include powerbi-models in the visuals package. Další informace najdete ve stručné příručce Přidání rozhraní API rozšířeného filtru do vlastního vizuálu.For more information, see the short guide, Add the Advanced Filter API to the custom visual.

Všechny filtry rozšiřují rozhraní IFilter, jak je znázorněno v následujícím kódu:All filters extend the IFilter interface, as shown in the following code:

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

Kde:Where:

  • target je sloupec tabulky ve zdroji dat.target is the table column on the data source.

Rozhraní API základního filtruThe Basic Filter API

Rozhraní základního filtru je zobrazeno v následujícím kódu:Basic filter interface is shown in the following code:

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

Kde:Where:

  • operator je výčet s hodnotami In, NotIn a All.operator is an enumeration with the values In, NotIn, and All.
  • values jsou hodnoty pro podmínku.values are values for the condition.

Příklad základního filtru:Example of a basic filter:

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

Tento filtr znamená „chci všechny řádky, kde col1 se rovná hodnotě 1, 2 nebo 3“.The filter means, "Give me all rows where col1 equals the value 1, 2, or 3."

Ekvivalent SQL je zde:The SQL equivalent is:

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

Pokud chcete vytvořit filtr, můžete použít třídu BasicFilter v powerbi-models.To create a filter, you can use the BasicFilter class in powerbi-models.

Pokud používáte starší verzi tohoto nástroje, měli byste získat instanci modelů v objektu window pomocí window['powerbi-models'], jak je znázorněno v následujícím kódu: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);

Tento vizuál vyvolává filtr pomocí metody applyJsonFilter() v rozhraní hostitele IVisualHost, které je vizuálu poskytnuto v konstruktoru.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);

Rozhraní API rozšířeného filtruThe Advanced Filter API

Rozhraní API rozšířeného filtru umožňuje komplexní výběr datových bodů a filtrovací dotazy napříč vizuály na základě více kritérií, mezi která patří LessThan, Contains, Is, IsBlank atd.).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).

Filtr byl představen v rozhraní API vizuálů 1.7.0.The filter was introduced in Visuals API 1.7.0.

Rozhraní API rozšířeného filtru dále vyžaduje target s table a názvem column.The Advanced Filter API also requires target with a table and column name. Operátory rozhraní API rozšířeného filtru ale jsou And a Or.But the Advanced Filter API operators are And and Or.

Filtr navíc s tímto rozhraním používá podmínky místo hodnot:Additionally, the filter uses conditions instead of values with the interface:

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

Operátory podmínky pro parametr operator jsou None, LessThan, LessThanOrEqual, GreaterThan, GreaterThanOrEqual, Contains, DoesNotContain, StartsWith, DoesNotStartWith, Is, IsNot, IsBlank a 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);

Ekvivalent SQL je zde:The SQL equivalent is:

SELECT * FROM table WHERE col1 < 0;

Úplný vzorový kód pro použití rozhraní API rozšířeného filtru najdete v úložišti vizuálu Sampleslicer.For the complete sample code for using the Advanced Filter API, go to the Sampleslicer visual repository.

Rozhraní API filtru řazené kolekce členů (filtr s více sloupci)The Tuple Filter API (multi-column filter)

Rozhraní API filtru řazené kolekce členů bylo představeno v rozhraní API vizuálů 2.3.0.The Tuple Filter API was introduced in Visuals API 2.3.0. Podobá se rozhraní API základního filtru, umožňuje ale definovat podmínky pro několik sloupců a tabulek.It is similar to the Basic Filter API, but it allows you to define conditions for several columns and tables.

Rozhraní tohoto filtru je zobrazeno v následujícím kódu:The filter interface is shown in the following code:

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

Kde:Where:

  • target je pole sloupců s názvy tabulek:target is an array of columns with table names:

    declare type ITupleFilterTarget = IFilterTarget[];
    

    Filtr dokáže adresovat sloupce z různých tabulek.The filter can address columns from various tables.

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

  • filterType je FilterType.Tuple.filterType is FilterType.Tuple.

  • operator lze použít jen v operátoru In.operator allows use only in the In operator.

  • values je pole řazených kolekcí členů hodnot, přičemž každá řazená kolekce členů představuje jednu povolenou kombinaci cílových hodnot sloupců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
}

Kompletní příklad: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);

Důležité

Na pořadí názvů sloupců a hodnot podmínek záleží.The order of the column names and condition values is sensitive.

Ekvivalent SQL je zde:The SQL equivalent is:

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

Obnovení filtru JSON ze zobrazení datRestore the JSON filter from the data view

Počínaje rozhraním API verze 2.2.0 můžete filtr JSON obnovit z VisualUpdateOptions, jak ukazuje následující kód: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[];
}

Při přepínání záložek volá Power BI metodu update vizuálu a vizuál získá odpovídající objekt filter.When you switch, bookmarks, Power BI calls the update method of the visual, and the visual gets a corresponding filter object. Další informace najdete v článku Přidání podpory záložek pro vizuály Power BI.For more information, see Add bookmark support for Power BI visuals.

Ukázkový filtr JSONSample JSON filter

Ukázkový kód filtru JSON je zobrazený na následujícím obrázku:Some sample JSON filter code is shown in the following image:

Kód filtru JSON

Vymazání filtru JSONClear the JSON filter

Rozhraní API filtrů přijímá hodnotu null filtru jako obnovení nebo vymazání.The Filter API accepts the null value of the filter as reset or clear.

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