控制報表篩選

當您內嵌 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-models 程式庫的一部分。

基本篩選

基本篩選 具有具有一或多個值的單一運算子。

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 - 前 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 時，filters 引數必須是 undefined 。 對於任何其他作業，必須定義它。

篩選層級

更新和取得篩選可以在三個層級完成。 不同層級上的篩選是獨立的，而且更新某個層級上的篩選，將不會變更另一個層級。 例如，移除頁面篩選，並不會從報表中的其他頁面移除它。

篩選的支援層級如下：

• 報表 - 篩選會套用至報表中的所有頁面。
• Page - 篩選會套用至目前的報表頁面。
• 視覺效果 - 篩選準則會套用至特定視覺效果。

注意

只有視覺層級篩選支援 ITopNFilter 篩選類型。

報表層級篩選

若要取得或更新套用至報表中所有頁面的篩選，請在報表物件上呼叫相關的 API。 例如：

取得報表篩選

取得套用至所有頁面的篩選準則。

let reportFilters = await report.getFilters();

將新的篩選新增至報表篩選

為所有頁面新增新的篩選，以及現有的篩選。

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

移除報表篩選

移除套用至所有頁面的篩選準則。

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

頁面層級篩選

若要取得或更新頁面層級篩選，請執行下列動作：

1. 取得目標頁面的頁面物件。 如需詳細資訊，請參閱 取得頁面和視覺效果。
2. 在頁面物件上，呼叫相關的 API。

取得頁面篩選

取得套用至特定頁面的篩選。

let reportFilters = await page.getFilters();

取代所有頁面篩選

以一組新的篩選取代套用至特定頁面的所有現有篩選。

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

移除頁面篩選

移除套用至特定頁面的篩選準則。

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

視覺效果層級篩選

若要取得或更新視覺效果層級篩選，請執行下列動作：

1. 取得目標視覺效果的視覺物件。 如需詳細資訊，請參閱 取得頁面和視覺效果。
2. 在視覺物件上，呼叫相關的 API。

取得視覺效果篩選

取得套用至特定視覺效果的篩選。

let reportFilters = await visual.getFilters();

以相同的目標取代視覺效果篩選

取代特定視覺效果的篩選。 如果篩選存在與指定篩選相同的目標資料欄位，則會由指定的篩選準則取代。 已新增不符合任何現有篩選準則的指定篩選。

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

移除視覺效果篩選

移除套用至特定視覺效果的篩選。

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

限制

• 建置 進階篩選 條件時，有兩個以上的條件可能會導致未定義的行為。

• IncludeExclude 不支援 和 Tuple 篩選類型。

• 不支援 Tuple 和階層篩選目標。

下一步

• 進行報告設定
• 控制報表交叉分析篩選器
• 個人化報表配置