控制报表筛选器

项目
07/09/2024

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

支持以下筛选器类型：

基本 - IBasicFilter
高级 - IAdvancedFilter
前 N - ITopNFilter
相对日期 - IRelativeDateFilter
相对时间 - IRelativeTimeFilter

筛选器对象属性

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

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

图式

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

基本 - https://powerbi.com/product/schema#basic
高级 - https://powerbi.com/product/schema#advanced
相对日期 - https://powerbi.com/product/schema#relativeDate
相对时间 - https://powerbi.com/product/schema#relativeTime
前 N - https://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: "https://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: "https://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: "https://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: "https://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: "https://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。对于任何其他操作，必须定义它。

筛选器级别

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

筛选器支持级别为：

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

注意

只有视觉对象级别筛选器支持 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 筛选器类型。
不支持元组和层次结构筛选器目标。

通过

控制报表筛选器

筛选器对象属性

图式

显示设置

筛选器类型

目标

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

基本筛选器

高级筛选器

前 N 个筛选器

相对日期和相对时间筛选器

筛选器 API

获取筛选器

更新筛选器

筛选器操作

筛选器级别

报表级别筛选器

获取报表筛选器

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

删除报表筛选器

页面级别筛选器

获取页面筛选器

替换所有页面筛选器

删除页面筛选器

视觉对象级别筛选器

获取视觉对象筛选器

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

删除视觉对象筛选器

注意事项和限制

其他资源

通过

控制报表筛选器

筛选器对象属性

图式

显示设置

筛选器类型

目标

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

基本筛选器

高级筛选器

前 N 个筛选器

相对日期和相对时间筛选器

筛选器 API

获取筛选器

更新筛选器

筛选器操作

筛选器级别

报表级别筛选器

获取报表筛选器

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

删除报表筛选器

页面级别筛选器

获取页面筛选器

替换所有页面筛选器

删除页面筛选器

视觉对象级别筛选器

获取视觉对象筛选器

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

删除视觉对象筛选器

注意事项和限制

相关内容

其他资源