控制报表筛选器

项目
09/17/2023

嵌入 Power BI 报表时，可以在加载阶段自动应用筛选器，也可以在加载报表后动态更改筛选器。例如，可以创建自己的自定义筛选器窗格，并自动将这些筛选器应用于报表，以显示用户特定的见解。还可以创建一个按钮，允许用户将筛选器应用于嵌入报表。

支持以下筛选器类型：

基本 - IBasicFilter
先进 - IAdvancedFilter
前 N 个 - ITopNFilter
相对日期 - IRelativeDateFilter
相对时间 - IRelativeTimeFilter

筛选器对象属性

所有筛选器类型都继承接口 IFilter 。下面列出的属性与所有筛选器类型相关。

interface IFilter {
    $schema: string;
    target: IFilterGeneralTarget;
    filterType: FilterType;
    displaySettings?: IFilterDisplaySettings;
}

架构

该 $schema 属性定义筛选器的类型。有五种架构可用，每个筛选器类型有一个架构：

基本 - http://powerbi.com/product/schema#basic
先进 - http://powerbi.com/product/schema#advanced
相对日期 - http://powerbi.com/product/schema#relativeDate
相对时间 - http://powerbi.com/product/schema#relativeTime
前 N 个 - http://powerbi.com/product/schema#topN

显示设置

该 displaySettings 属性定义筛选器在筛选器窗格中显示的方式。

interface IFilterDisplaySettings {
    isLockedInViewMode?: boolean;
    isHiddenInViewMode?: boolean;
    displayName?: string;
}

isLockedInViewMode - 在筛选器窗格中应用并显示锁定的筛选器。不能在 视图模式下更改筛选器值。将其设置为 true 以锁定筛选器。
isHiddenInViewMode - 隐藏的筛选器应用于报表，但不显示在 视图模式下的筛选器窗格中。将其设置为 true 以隐藏筛选器。
displayName - 筛选器可以显示在具有个性化名称的筛选器窗格中。使用此属性可为筛选器设置个性化名称。当值未定义或为 null 时，筛选器的默认名称将显示 (通常) 筛选数据字段的名称。

筛选器类型

该 filterType 属性定义筛选器的类型。使用以下在模型库中定义的枚举：

enum FilterType {
    Advanced = 0,
    Basic = 1,
    Unknown = 2,
    IncludeExclude = 3,
    RelativeDate = 4,
    TopN = 5,
    Tuple = 6,
    RelativeTime = 7,
}

目标

该 target 属性定义筛选器的目标。有关详细信息，请参阅使用目标选择要对其执行操作的数据字段。

按筛选器类型排序的其他属性

每个筛选器类型都有其自己的接口，其中包含一组不同的属性。筛选器接口是 powerbi 模型库的一部分。

基本筛选器

基本筛选器具有具有一个或多个值的单个运算符。

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

operator - 对于基本筛选器，运算符可以是下列选项之一：
```
type BasicFilterOperators = "In" | "NotIn" | "All"
```
values - 筛选器的值数组，所有值都需要具有相同的类型。
requireSingleSelection - 定义是否可以在筛选器上选择多个值。如果设置为 true，则只能选择单个值。

例如：

const basicFilter = {
  $schema: "http://powerbi.com/product/schema#basic",
  target: {
    table: "Store",
    column: "Count"
  },
  operator: "In",
  values: [1, 2, 3, 4],
  filterType: models.FilterType.BasicFilter,
  requireSingleSelection: true
}

高级筛选器

高级筛选器具有单个逻辑运算符和一个或两个具有其自己的运算符和值的条件。

interface IAdvancedFilter extends IFilter {
    logicalOperator: AdvancedFilterLogicalOperators;
    conditions: IAdvancedFilterCondition[];
}

logicalOperator - 逻辑运算符可以是下列运算符之一：
```
type AdvancedFilterLogicalOperators = "And" | "Or";
```

conditions - 高级筛选器的条件数组，每个条件都有一 operator 个和一个 value。

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

条件的可用运算符包括：

type AdvancedFilterConditionOperators = "None" | "LessThan" | "LessThanOrEqual" | 
"GreaterThan" | "GreaterThanOrEqual" | "Contains" | "DoesNotContain" | "StartsWith" | 
"DoesNotStartWith" | "Is" | "IsNot" | "IsBlank" | "IsNotBlank";

例如：

const advancedFilter = {
  $schema: "http://powerbi.com/product/schema#advanced",
  target: {
    table: "Store",
    column: "Name"
  },
  logicalOperator: "Or",
  conditions: [
    {
      operator: "Contains",
      value: "Wash"
    },
    {
      operator: "Contains",
      value: "Park"
    }
  ],
  filterType: models.FilterType.AdvancedFilter
}

注意

如果只创建一个 AdvancedFilter 条件，请 logicalOperator 设置为 "And"。当由 Power BI 分析时，逻辑运算符将被忽略，因为只有一个条件，并且当筛选器序列化为默认逻辑运算符 "And"时。这可确保调用 getFilters时返回的筛选器与使用的 setFilters筛选器匹配。

前 N 个筛选器

前 N 个筛选器具有单个运算符、要显示的项数的项计数器以及按目标排序。

interface ITopNFilter extends IFilter {
    operator: TopNFilterOperators;
    itemCount: number;
    orderBy: ITarget;
}

operator - Top N 筛选器的运算符可以是下列值之一：
```
type TopNFilterOperators = "Top" | "Bottom";
```
itemCount - 要显示的项目量。
orderBy - 要排序的目标数据字段。有关详细信息，请参阅使用目标选择要对其执行操作的数据字段。

例如：

const topNFilter = {
  $schema: "http://powerbi.com/product/schema#topN",
  target: {
    table: "Store",
    column: "name"
  },
  operator: "Top",
  itemCount: 5,
  orderBy: {
      table: "Product",
      measure: "Count of Product"
   },
  filterType: models.FilterType.TopN
};

相对日期和时间筛选器

相对日期筛选器和相对时间筛选器都继承自IRelativeDateTimeFilter接口：

interface IRelativeDateTimeFilter extends IFilter {
    operator: RelativeDateOperators;
    timeUnitsCount: number;
    timeUnitType: RelativeDateFilterTimeUnit;
}

operator - 相对日期和时间筛选器的运算符可以是下列值之一：

enum RelativeDateOperators {
    InLast = 0,
    InThis = 1,
    InNext = 2,
}

timeUnitsCount - 时间单位量。

timeUnitType - 定义筛选器正在使用的时间单位。

enum RelativeDateFilterTimeUnit {
    Days = 0,
    Weeks = 1,
    CalendarWeeks = 2,
    Months = 3,
    CalendarMonths = 4,
    Years = 5,
    CalendarYears = 6,
    Minutes = 7,
    Hours = 8
}

下表列出了相对日期和相对时间筛选器支持的单位时间。

时间单位	相对日期	相对时间
天	✔	✖
周	✔	✖
CalendarWeeks	✔	✖
数月	✔	✖
CalendarMonths	✔	✖
年	✔	✖
CalendarYears	✔	✖
分钟数	✖	✔
小时	✖	✔

includeToday - 接受一个布尔值，该值指定是否在筛选器中包含当前日期。
```
interface IRelativeDateFilter extends IRelativeDateTimeFilter {
includeToday: boolean;
}
```
注意

includeToday 仅受相对日期筛选器支持。

相对日期筛选器示例：

const relativeDateFilter = {
  $schema: "http://powerbi.com/product/schema#relativeDate",
  target: {
    table: "Sales",
    column: "OrderDate"
  },
  operator: models.RelativeDateOperators.InLast,
  timeUnitsCount: 30,
  timeUnitType: RelativeDateFilterTimeUnit.Days,
  includeToday: true,
  filterType: models.FilterType.RelativeDate
};

相对时间筛选器示例：

const relativeTimeFilter = {
  $schema: "http://powerbi.com/product/schema#relativeTime",
  target: {
    table: "Sales",
    column: "OrderDate"
  },
  operator: models.RelativeDateOperators.InLast,
  timeUnitsCount: 12,
  timeUnitType: models.RelativeDateFilterTimeUnit.Hours,
  filterType: models.FilterType.RelativeTime
};

筛选器 API

使用以下方法获取和更新应用于报表的筛选器：

获取筛选器 - getFilters
更新筛选器- updateFilters。

获取筛选器

用于 getFilters 获取以下对象之一的所有筛选器：

报表
页
可视

getFilters(): Promise<IFilter[]>

更新筛选器

用于 updateFilters 在对象 (报表、页面或视觉对象) 添加、替换或删除筛选器。接收操作和可选筛选器数组。

updateFilters(operation: models.FiltersOperations, filters?: models.IFilter[]): Promise<IHttpPostMessageResponse<void>>

筛选器操作

调用 updateFilters 时，需要传递要预格式化的筛选器操作。可用操作包括：

RemoveAll - 删除筛选器级别上的所有筛选器。
ReplaceAll - 将筛选器级别上的所有现有筛选器替换为给定的筛选器。
Add - 除了现有筛选器) ，还会在筛选器级别 (添加给定筛选器。
Replace - 仅当两个筛选器都应用于同一数据字段时，才将现有筛选器替换为给定筛选器。如果给定的筛选器未替换现有筛选器，则会添加该筛选器。

注意

使用 RemoveAll 调用 API 时，筛选器参数必须是 undefined。对于任何其他操作，必须定义它。

筛选器级别

可以在三个级别更新和获取筛选器。不同级别的筛选器是独立的，并且更新一个级别的筛选器不会更改另一个级别。例如，删除页面筛选器不会将其从报表中的其他页中删除。

筛选器支持级别为：

报表 - 筛选器应用于报表中的所有页面。
Page - 筛选器应用于当前报表页。
视觉对象 - 筛选器应用于特定视觉对象。

注意

只有视觉级别筛选器支持 ITopNFilter 筛选器类型。

报表级别筛选器

若要获取或更新应用于报表中所有页面的筛选器，请对报表对象调用相关的 API。例如：

获取报表筛选器

获取应用于所有页面的筛选器。

let reportFilters = await report.getFilters();

向报表筛选器添加新筛选器

为所有页面添加新筛选器以及现有筛选器。

await report.updateFilters(models.FiltersOperations.Add, filtersArray);

删除报表筛选器

删除应用于所有页面的筛选器。

await report.updateFilters(models.FiltersOperations.RemoveAll);

页级别筛选器

若要获取或更新页面级别筛选器，请执行以下操作：

获取目标页的页面对象。有关详细信息，请参阅获取页面和视觉对象。
在页面对象上，调用相关的 API。

获取页面筛选器

获取应用于特定页面的筛选器。

let reportFilters = await page.getFilters();

替换所有页面筛选器

将应用于特定页面的所有现有筛选器替换为一组新的筛选器。

await page.updateFilters(models.FiltersOperations.ReplaceAll, filtersArray);

删除页面筛选器

删除应用于特定页面的筛选器。

await page.updateFilters(models.FiltersOperations.RemoveAll);

视觉对象级筛选器

若要获取或更新视觉级别筛选器，请执行以下操作：

获取目标视觉对象的视觉对象。有关详细信息，请参阅获取页面和视觉对象。
在视觉对象上，调用相关的 API。

获取视觉对象筛选器

获取应用于特定视觉对象的筛选器。

let reportFilters = await visual.getFilters();

将视觉对象筛选器替换为同一目标

替换特定视觉对象的筛选器。如果存在与给定筛选器相同的目标数据字段的筛选器，则会将其替换为给定筛选器。添加与任何现有筛选器不匹配的给定筛选器。

await visual.updateFilters(models.FiltersOperations.Replace, filtersArray);

删除视觉对象筛选器

删除应用于特定视觉对象的筛选器。

await visual.updateFilters(models.FiltersOperations.RemoveAll);

限制

生成高级筛选器时有两个以上的条件可能会导致未定义的行为。
IncludeExclude 不支持筛选器 Tuple 类型。
不支持元组和层次结构筛选器目标。