控制報表篩選
當您內嵌 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
取得下列其中一個物件的所有篩選:
- 報告
- 頁面
- 視覺效果
getFilters(): Promise<IFilter[]>
更新篩選器
使用 updateFilters
在報表、頁面或視覺效果) (物件上新增、取代或移除篩選。 接收作業和選擇性篩選陣列。
updateFilters(operation: models.FiltersOperations, filters?: models.IFilter[]): Promise<IHttpPostMessageResponse<void>>
篩選作業
呼叫 updateFilters
時,您必須傳遞您想要預先設定的 篩選作業 。 可用的作業如下:
RemoveAll
- 移除篩選層級上的所有篩選。ReplaceAll
- 以指定的篩選取代篩選層級上的所有現有篩選。Add
- 除了現有的篩選) 之外,在篩選層級上新增指定的篩選 (。Replace
- 只有在這兩個篩選都套用至相同的資料欄位時,才以指定的篩選來取代現有的篩選。 如果有一個未取代現有篩選的指定篩選,則會新增它。
注意
使用 RemoveAll
呼叫 API 時,filters 引數必須是 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
篩選類型。不支援 Tuple 和階層篩選目標。