控制報表交叉分析篩選器

發行項
09/17/2023

使用交叉分析篩選器 API，您可以取得並設定 Power BI 交叉分析篩選器的狀態。此外，您可以在載入報表時使用載入組態來變更交叉分析篩選器狀態。

交叉分析篩選器視覺效果有兩種類型：

現成 - 現成的 Power BI 視覺效果交叉分析篩選器。現成的交叉分析篩選器支援隨附于 Power BI (Desktop 和服務) 的所有 Power BI 視覺效果。
來自 AppSource 和檔案的 Power BI 視覺效果 - 適用于協力廠商 Power BI 視覺效果的交叉分析篩選器、可從 AppSource 取得，或作為 .pbiviz 檔案。來自 AppSource 和檔案之 Power BI 視覺效果的交叉分析篩選器，或是 來自 AppSource 或檔案的簡短視覺效果，是開發人員所建置之 Power BI 視覺效果的交叉分析篩選器。

Slicer 物件

交叉分析篩選器類型有四種：

類別交叉分析篩選器
範圍交叉分析篩選器
相對日期交叉分析篩選器
階層交叉分析篩選器

類別交叉分析篩選器

類別交叉分析篩選器支援下列顯示：

清單
下拉式功能表
值卡

您可以從這些清單中選取單一或多個專案，以據以篩選報表。

若要變更這些交叉分析篩選器類型的選取範圍，您需要建立 IBasicFilter 物件。如需建立基本篩選的詳細資訊，請參閱基本篩選。

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
};

await visual.setSlicerState({
    filters: [basicFilter]
});

如果交叉分析篩選器目標是階層，請提供 IFilterHierarchyTarget 目標。如需詳細資訊，請參閱使用目標來選取要處理的資料欄位。

const basicFilter = {
  $schema: "http://powerbi.com/product/schema#basic",
  target: {
    table: "Store",
    hierarchy: "Country",
    hierarchyLevel: "Code"
  },
  operator: "In",
  values: [456, 943],
  filterType: models.FilterType.BasicFilter
};

await visual.setSlicerState({
    filters: [basicFilter]
});

範圍交叉分析篩選器

範圍交叉分析篩選器支援條件，例如：

介於
之前
After

若要變更範圍交叉分析篩選器的選取範圍，請建立 IAdvancedFilter 物件。如需詳細資訊，請參閱進階篩選。

const advancedFilter = {
  $schema: "http://powerbi.com/product/schema#advanced",
  target: {
    table: "Store",
    column: "Number"
  },
  logicalOperator: "And",
  conditions: [
    {
      operator: "GreaterThanOrEqual",
      value: 30
    },
    {
      operator: "LessThan",
      value: 40
    }
  ],
  filterType: models.FilterType.AdvancedFilter
};

await visual.setSlicerState({
    filters: [advancedFilter]
});

相對日期交叉分析篩選器

相對日期交叉分析篩選器支援條件，例如：

上週
過去五年

若要變更相對日期交叉分析篩選器的選取範圍，請建立 IRelativeDateFilter 物件。如需詳細資訊，請參閱相對日期和時間篩選物件。

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

await visual.setSlicerState({
    filters: [relativeDateFilter]
});

相對時間交叉分析篩選器

相對時間交叉分析篩選器支援條件，例如：

過去五分鐘
此小時

若要變更相對時間交叉分析篩選器的選取範圍，請建立 IRelativeTimeFilter 物件。如需詳細資訊，請參閱相對日期和時間篩選。

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

await visual.setSlicerState({
    filters: [relativeTimeFilter]
});

階層交叉分析篩選器

階層交叉分析篩選器可讓您從多個相關欄位進行篩選。

顯示階層交叉分析篩選器範例的螢幕擷取畫面。它會顯示層級年份、季和月份。

SDK 2.21 版支援階層交叉分析篩選器。使用 setSlicerState API 設定階層交叉分析篩選器中的選取範圍，或使用 getSlicerState API取得目前的階層選取專案。

瞭解如何將欄位新增至階層交叉分析篩選器。

階層篩選

描述 IHierarchyFilter 交叉分析篩選器階層。使用此篩選準則的 getSlicerState 和 setSlicerState 方法。

interface IHierarchyFilter extends IFilter {
    target: (IFilterTarget | IFilterKeyTarget)[];
    hierarchyData: IHierarchyFilterNode[];
}

hierarchyData - 階層樹狀結構中選取和未選取的專案，其中每個 IHierarchyFilterNode 專案都代表單一值選取範圍。
```
interface IHierarchyFilterNode {
    value?: PrimitiveValueType;
    keyValues?: PrimitiveValueType[];
    children?: IHierarchyFilterNode[];
    operator?: HierarchyFilterNodeOperators;
}
```
- value必須設定或 keyValues
- children – 與目前選取範圍相關的節點子系列表
- operator – 樹狀結構中單一物件的運算子。運算子可以是下列其中一項：
type HierarchyFilterNodeOperators = "Selected" | "NotSelected" | "Inherited";
- Selected – 明確選取值。
- NotSelected – 明確未選取值。
- Inherited – 值選取是根據階層中的父值，如果它是根值，則為預設值。
operator 是選擇性的。如果未設定任何運算子，則預設值為 Inherited 。

階層交叉分析篩選器範例

下列範例說明搭配階層交叉分析篩選器使用 setSlicerState API 的不同案例。

選取不同層級上的值。例如，選取 [第 1 季] 和 [2013 年第 2 季] 和 [第 1 季] 和 [2014 年第 2 季]。

const filter = {
  "$schema": http://powerbi.com/product/schema#hierarchy,
  "target": [
      {
          "table": "Dates",
          "hierarchy": "Date Hierarchy",
          "hierarchyLevel": "Year"
      },
      {
          "table": "Dates",
          "hierarchy": "Date Hierarchy",
          "hierarchyLevel": "Quarter"
      }
  ],
  "filterType": 9,
  "hierarchyData": [
      {
          "operator": "Inherited",
          "value": 2013,
          "children": [
              {
                  "operator": "Selected",
                  "value": "Qtr 1"
              },
              {
                  "operator": "Selected",
                  "value": "Qtr 2"
              }
          ]
      },
      {
          "operator": "Inherited",
          "value": 2014,
          "children": [
              {
                  "operator": "Selected",
                  "value": "Qtr 1"
              },
              {
                  "operator": "Selected",
                  "value": "Qtr 2"
              }
          ]
      }
  ]
};

await slicer.setSlicerState({ filters: [filter] });

此螢幕擷取畫面顯示階層交叉分析篩選器的範例，其中 2013 年和 2014 年選取了第一季和兩季。

選取不同層級上的值，但有例外狀況。例如，選取不含 'Qtr 1' 的 2014。

const filter = {
  "$schema": http://powerbi.com/product/schema#hierarchy,
  "target": [
      {
          "table": "Dates",
          "hierarchy": "Date Hierarchy",
          "hierarchyLevel": "Year"
      },
      {
          "table": "Dates",
          "hierarchy": "Date Hierarchy",
          "hierarchyLevel": "Quarter"
      }
  ],
  "filterType": 9,
  "hierarchyData": [
      {
          "operator": "Selected",
          "value": 2014,
          "children": [
              {
                  "operator": "NotSelected",
                  "value": "Qtr 1"
              }
          ]
      }
  ]
};

await slicer.setSlicerState({ filters: [filter] });

顯示階層交叉分析篩選器範例的螢幕擷取畫面，其中選取不同層級的值，但有例外狀況。它選取了 2014 年，但 Q 1 除外。

從 NotSelected 運算子開始，選取特定值 以外的 所有專案。例如，選取 'Qtr 1' 以外的所有專案 2008 和 2009。

const filter = {
  "$schema": http://powerbi.com/product/schema#hierarchy,
  "target": [
      {
          "table": "Dates",
          "column": "Year"
      },
      {
          "table": "Dates",
          "column": "Quarter"
      }
  ],
  "filterType": 9,
  "hierarchyData": [
      {
          "operator": "NotSelected",
          "value": 2009
      },
      {
          "operator": "Inherited",
          "value": 2008,
          "children": [
              {
                  "operator": "NotSelected",
                  "value": "Q1"
              }
          ]
      }
  ]
}

await slicer.setSlicerState({ filters: [filter] });

顯示階層交叉分析篩選器範例的螢幕擷取畫面，其中選取指定值以外的所有專案。已選取 2010 年到 2014 年。選取 2008 而未選取 Q 1，而且完全未選取 2009。

交叉分析篩選器 API

您可以針對具有類型的視覺效果 slicer 使用下列方法：

取得交叉分析篩選器狀態 - getSlicerState
設定交叉分析篩選器狀態 - setSlicerState

注意

交叉分析篩選器 API 可辨識儲存在報表中的同步交叉分析篩選器組態。這表示如果您使用 API 設定交叉分析篩選器，則相同同步群組中的所有交叉分析篩選器都會受到影響。

取得交叉分析篩選器狀態

若要取得交叉分析篩選器狀態，您需要尋找交叉分析篩選器視覺化實例並呼叫 getSlicerState 。結果的類型為 ISlicerState 。

根據預設，交叉分析篩選器不會套用任何篩選。在這種情況下， getSlicerState 將會以空的篩選陣列傳回 ISlicerState 。

getSlicerState適用于AppSource 或檔案交叉分析篩選器的現成和視覺效果。

let state = await visual.getSlicerState();

設定交叉分析篩選器狀態

若要設定交叉分析篩選器狀態，您需要尋找交叉分析篩選器視覺實例、建立交叉分析篩選器狀態，並使用您建立的交叉分析篩選器狀態呼叫 setSlicerState 。

await visual.setSlicerState(state);

交叉分析篩選器狀態為 ISlicerState 物件。

interface ISlicerState {
    filters: ISlicerFilter[];
    targets?: SlicerTarget[];
}

若要重設交叉分析篩選器，請使用空的篩選陣列呼叫 setSlicerState 。

從 AppSource 或檔案設定視覺效果的交叉分析篩選器

若要 從 AppSource 或檔案 交叉分析篩選器選取範圍設定視覺效果，您需要建立 ISlicerFilter 物件，其可以是下列類型：

IBasicFilter
IAdvancedFilter
IRelativeDateFilter
IRelativeTimeFilter

來自 AppSource 或檔案交叉分析篩選器的不同視覺效果，支援不同類型的篩選。若要判斷修改交叉分析篩選器所需的篩選類型，請呼叫 visual.getSlicerState() 。

如需篩選類型的詳細資訊，請參閱控制報表篩選。

在報表載入時設定交叉分析篩選器

報表載入組態支援變更交叉分析篩選器狀態。這可讓您在報表載入期間變更報表交叉分析篩選器狀態。若要這樣做，請 ISlicer 傳遞陣列。

interface IReportLoadConfiguration {
    ...
    slicers?: ISlicer[];
}

每個 ISlicer 物件都包含選取器和交叉分析篩選器狀態。

interface ISlicer {
    selector: SlicerSelector;
    state: ISlicerState;
}

使用視覺名稱或交叉分析篩選器目標選取器來選取要變更的交叉分析篩選器。如需詳細資訊，請參閱使用選取器來控制哪些視覺效果會受到影響。

注意

如果您傳遞位於相同同步群組中的不同 ISlicer 物件，結果將會非預期。

在負載範例上套用交叉分析篩選器

本節包含使用交叉分析篩選器的兩個負載組態範例。

依名稱設定特定交叉分析篩選器

let slicers = [
  {
    selector: {
      $schema: "http://powerbi.com/product/schema#visualSelector",
      visualName: "d1feb8891635af3b335a"
    },
    state: {
      filters: [advancedFilter]
    }
  }
];

let embedConfig = {
  ...
  slicers: slicers,
};

依交叉分析篩選器目標設定交叉分析篩選器

let target = {
  table: "Store",
  column: "StoreNumber"
};

let slicers = [
  {
    selector: {
      $schema: "http://powerbi.com/product/schema#slicerTargetSelector",
      target: target 
    },
    state: {
      filters: [advancedFilter]
    }
  }
];

let embedConfig = {
  ...
  slicers: slicers,
};

考量與限制

不支援 Tuple 交叉分析篩選器。
SDK 2.21 版支援階層交叉分析篩選器。
現成的交叉分析篩選器僅支援單一篩選。
在不是交叉分析篩選器的視覺效果上呼叫 setSlicerState ，將會傳回拒絕的承諾，錯誤 作業僅適用于交叉分析篩選器。
沒有 API 可變更交叉分析篩選器同步設定。

共用方式為