控制報表篩選

當您內嵌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模型 連結庫 的一部分。

基本篩選

Basic 篩選 具有一或多個值的單一運算符。

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 - 前 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>>

篩選作業

呼叫 時，您需要傳遞您想要預先格式化 篩選作業。 可用的作業如下：

• RemoveAll - 移除篩選層級上的所有篩選。
• ReplaceAll - 以指定的篩選取代篩選層級上的所有現有篩選。
• Add - 在篩選層級上新增指定的篩選（除了現有的篩選之外）。
• Replace - 只有當這兩個篩選都套用至相同的數據欄位時，才會將現有的篩選取代為指定的篩選。 如果有未取代現有篩選條件的指定篩選，則會新增它。

注意

使用 RemoveAll呼叫 API 時，篩選自變數必須 undefined。 若為任何其他作業，則必須定義它。

篩選層級

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

篩選的支援層級如下：

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

注意

只有視覺層級篩選支援 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 和階層篩選目標。

相關內容

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