Power BI 视觉对象中的视觉对象筛选器 API

项目
03/23/2023

通过视觉对象筛选器 API，可在 Power BI 视觉对象中筛选数据。筛选器 API 与其他选择数据的方式之间的主要区别在于它对报表中其他视觉对象产生影响的方式。当筛选器应用于视觉对象时，尽管其他视觉对象支持突出显示，但筛选后的数据仅将在所有视觉对象中可见。

若要对此视觉对象启用筛选，capabilities.json 文件应在 general 部分中包含 filter 对象。

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

注意

powerbi-models 包提供了视觉对象筛选器 API 接口。此包还包含用于创建筛选器实例的类。
```
npm install powerbi-models --save
```
如果使用的是早期版本的工具（早于 3.x.x），则需在视觉对象包中包含 powerbi-models。有关详细信息，请参阅简短指南将高级筛选器 API 添加到自定义视觉对象。若要了解正在使用的版本，请检查 pbiviz.json 文件中的 apiVersion。

所有筛选器均使用 IFilter 接口，如下面的代码所示：

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

其中 target 是数据源中的表列。

有三种筛选器 API：

基本筛选器 API
高级筛选器 API
元组（多列）筛选器 API

基本筛选器 API

基本筛选器接口如以下代码所示：

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

其中：

operator 是包含值“In”、“NotIn”和“All”的枚举。
values 是条件值。

基本筛选器示例

下面的示例返回 col1 等于值 1、2 或 3 的所有行。

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

上述示例的 SQL 等效项是：

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

要创建筛选器，可以使用 powerbi-models 中的 BasicFilter 类。

如果使用的是较旧版本的工具，则应使用 window['powerbi-models'] 在窗口对象中获取模型实例，如以下代码所示：

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);

该视觉对象通过对主机接口 IVisualHost（提供给构造函数方法中的视觉对象）调用 applyJsonFilter() 方法来调用筛选器。

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

高级筛选器 API

高级筛选器 API 支持基于多条件（例如“LessThan”、“Contains”、“Is”和“IsBlank”等）的跨视觉对象数据点的复杂选择和筛选查询。

视觉对象 API 版本 1.7.0 中引入了此筛选器。

与基本 API 不同，在高级筛选器 API 中：

target 需要 table 和 column 名称（基本 API 只有 column）。
运算符为 And 和 Or（而不是 In）。
筛选器使用条件（less than、greater than 等），而不是接口的值：

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

operator 参数的条件运算符为“None”、“LessThan”、“LessThanOrEqual”、“GreaterThan”、“GreaterThanOrEqual”、“Contains”、“DoesNotContain”、“StartsWith”、“DoesNotStartWith”、“Is”、“IsNot”、“IsBlank”和“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);

SQL 等效项为：

SELECT * FROM table WHERE col1 < 0;

有关使用高级筛选器 API 的完整示例代码，请参阅 Sampleslicer 视觉对象存储库。

元组筛选器 API（多列筛选器）

视觉对象 API 2.3.0 中引入了元组筛选器 API。它类似于基本筛选器 API，但它允许为多个列和表定义条件。

筛选器接口如以下代码所示：

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

其中

target 是由含有表名的列构成的数组：
```
declare type ITupleFilterTarget = IFilterTarget[];
```
筛选器可以处理来自不同表的列。
$schema 为 https://powerbi.com/product/schema#tuple 。
filterType 为 FilterType.Tuple。
仅允许在“In”运算符中使用 operator。
values 是由值元组构成的数组。每个元组表示一个允许的目标列值组合。

declare type TupleValueType = ITupleElementValue[];

interface ITupleElementValue {
    value: PrimitiveValueType
}

完整示例：

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);

重要

列名和条件值的顺序非常重要。

上述代码的 SQL 等效项是：

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

从数据视图还原 JSON 筛选器

从 API 版本 2.2.0 开始，可从 VisualUpdateOptions 还原 JSON 筛选器，如以下代码所示：

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

切换书签时，Power BI 调用视觉对象的 update 方法，且视觉对象获取对应的 filter 对象。有关详细信息，请参阅添加对 Power BI 视觉对象的书签支持。

示例 JSON 筛选器

一些示例 JSON 筛选器代码如下图所示：

Screenshot of sample JSON filter code showing values in an array.

清除 JSON 筛选器

若要重置或清除筛选器，请将 null 值传递给筛选器 API。

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

后续步骤

使用 Power BI 视觉对象选择为视觉添加交互性

通过