共用方式為

Power BI 視覺效果中的視覺效果篩選 API

  • 發行項

視覺效果篩選 API 可讓您篩選 Power BI 視覺效果中的資料。 篩選 API 與其他選取資料方式的主要差異在於它如何影響報表中的其他視覺效果。 當篩選套用至視覺效果時，儘管其他視覺效果支援反白顯示，但所有視覺效果中只會顯示篩選的資料。

若要啟用視覺效果的篩選， capabilities.json 檔案應該包含 filter 區段中的物件 general 。

"objects": {
        "general": {
            "displayName": "General",
            "displayNameKey": "formattingGeneral",
            "properties": {
                "filter": {
                    "type": {
                        "filter": true
                    }
                }
            }
        }
    }

注意

  • Powerbi-models 套件中 提供視覺化篩選 API 介面。 此套件也包含用來建立篩選實例的類別。

    npm install powerbi-models --save

  • 如果您使用舊版（早于 3.x.x） 版的工具， powerbi-models 請在視覺效果套件中包含 。 如需詳細資訊，請參閱簡短指南： 將進階篩選 API 新增至自訂視覺效果 。 若要找出您所使用的版本，請檢查 apiVersion pbiviz.json 檔案中的 。

所有篩選都會使用 IFilter 介面 ，如下列程式碼所示：

export interface IFilter {
        $schema: string;
        target: IFilterTarget;
}

其中 target 是資料來源中的資料表資料行。

有三個篩選 API：

基本篩選 API

基本篩選介面會顯示在下列程式碼中：

export interface IBasicFilter extends IFilter {
    operator: BasicFilterOperators;
    values: (string | number | boolean)[];
}

其中：

  • operator是具有 In 、 NotIn 和 All 值的 列舉。
  • values 是條件的值。

基本篩選準則的範例

下列範例會傳回等於值 1、2 或 3 的所有資料列 col1 。

let basicFilter = {
    target: {
        column: "Col1"
    },
    operator: "In",
    values: [1,2,3]
}

上述範例的 SQL 對等專案如下：

SELECT * FROM table WHERE col1 IN ( 1 , 2 , 3 )

若要建立篩選，您可以在 中使用 powerbi-models BasicFilter 類別。

如果您使用舊版的工具，您應該使用 window['powerbi-models'] 取得視窗物件中的模型實例，如下列程式碼所示：

let categories: DataViewCategoricalColumn = this.dataView.categorical.categories[0];

let target: IFilterColumnTarget = {
    table: categories.source.queryName.substr(0, categories.source.queryName.indexOf('.')),
    column: categories.source.displayName
};

let values = [ 1, 2, 3 ];

let filter: IBasicFilter = new window['powerbi-models'].BasicFilter(target, "In", values);

視覺效果會藉由在主介面上呼叫 applyJsonFilter() 方法來叫用篩選， IVisualHost 這個方法會提供給建構函式方法中的視覺效果。

IVisualHost.applyJsonFilter(filter, "general", "filter", FilterAction.merge);

進階篩選 API

進 階篩選 API 可讓您根據多個準則進行複雜的跨視覺資料點選取和篩選查詢，例如 LessThan 、 Contains 、 Is、Is、 IsBlank 等等。

此篩選是在 Visuals API 1.7.0 版中引進的。

與 基本 API 相反，在進階篩選 API 中 ：

  • target需要 和 columntable 名稱 （ 基本 API 剛有 column ）。
  • 運算子為 And 和 Or （與 In 相反 ）。
  • 篩選準則會使用條件（ 小於 、 大於 etc.），而不是使用 介面的值：
interface IAdvancedFilterCondition {
    value: (string | number | boolean);
    operator: AdvancedFilterConditionOperators;
}

參數的條件 operator 運算子包括： None 、 LessThan、LessThanOrEqual、 GreaterThan 、 GreaterThanOrEqual 、 Contains 、 DoesNotContain 、 StartsWith、DoesNotStartWith 、 Is 、 IsNot 、 IsBlank 和 「IsNotBlank」

let categories: DataViewCategoricalColumn = this.dataView.categorical.categories[0];

let target: IFilterColumnTarget = {
    table: categories.source.queryName.substr(0, categories.source.queryName.indexOf('.')), // table
    column: categories.source.displayName // col1
};

let conditions: IAdvancedFilterCondition[] = [];

conditions.push({
    operator: "LessThan",
    value: 0
});

let filter: IAdvancedFilter = new window['powerbi-models'].AdvancedFilter(target, "And", conditions);

// invoke the filter
visualHost.applyJsonFilter(filter, "general", "filter", FilterAction.merge);

SQL 對等專案為：

SELECT * FROM table WHERE col1 < 0;

如需使用進階篩選 API 的完整範例程式碼，請移至 Sampleslicer 視覺化存放庫 。

Tuple 篩選 API （多資料行篩選準則）

Tuple 篩選 API 是在 Visuals API 2.3.0 中引進的。 它類似于 基本篩選 API ，但它可讓您定義數個數據行和資料表的條件。

篩選介面會顯示在下列程式碼中：

interface ITupleFilter extends IFilter {
    $schema: string;
    filterType: FilterType;
    operator: TupleFilterOperators;
    target: ITupleFilterTarget;
    values: TupleValueType[];
}

其中

  • target 是具有資料表名稱的資料行陣列：

    declare type ITupleFilterTarget = IFilterTarget[];

    篩選準則可以處理來自各種資料表的資料行。

  • $schema 為 https://powerbi.com/product/schema#tuple。

  • filterType 為 FilterType.Tuple 。

  • operator只允許在 In 運算子中使用 。

  • values 是值元組的陣列。 每個 Tuple 都代表一個允許的目標資料行值組合。

declare type TupleValueType = ITupleElementValue[];

interface ITupleElementValue {
    value: PrimitiveValueType
}

完整範例：

let target: ITupleFilterTarget = [
    {
        table: "DataTable",
        column: "Team"
    },
    {
        table: "DataTable",
        column: "Value"
    }
];

let values = [
    [
        // the first column combination value (or the column tuple/vector value) that the filter will pass through
        {
            value: "Team1" // the value for the `Team` column of the `DataTable` table
        },
        {
            value: 5 // the value for the `Value` column of the `DataTable` table
        }
    ],
    [
        // the second column combination value (or the column tuple/vector value) that the filter will pass through
        {
            value: "Team2" // the value for `Team` column of `DataTable` table
        },
        {
            value: 6 // the value for `Value` column of `DataTable` table
        }
    ]
];

let filter: ITupleFilter = {
    $schema: "https://powerbi.com/product/schema#tuple",
    filterType: FilterType.Tuple,
    operator: "In",
    target: target,
    values: values
}

// invoke the filter
visualHost.applyJsonFilter(filter, "general", "filter", FilterAction.merge);

重要

資料行名稱和條件值的順序很重要。

上述程式碼的 SQL 對等專案如下：

SELECT * FROM DataTable WHERE ( Team = "Team1" AND Value = 5 ) OR ( Team = "Team2" AND Value = 6 );

從資料檢視還原 JSON 篩選

從 API 2.2.0 版開始，您可以從 VisualUpdateOptions 還原 JSON 篩選 ，如下列程式碼所示：

export interface VisualUpdateOptions extends extensibility.VisualUpdateOptions {
    viewport: IViewport;
    dataViews: DataView[];
    type: VisualUpdateType;
    viewMode?: ViewMode;
    editMode?: EditMode;
    operationKind?: VisualDataChangeOperationKind;
    jsonFilters?: IFilter[];
}

當您切換書簽時，Power BI 會呼叫 update 視覺效果的 方法，而視覺效果會取得對應的 filter 物件。 如需詳細資訊，請參閱 新增 Power BI 視覺效果的 書簽支援。

範例 JSON 篩選準則

下圖顯示一些範例 JSON 篩選程式代碼：

Screenshot of sample JSON filter code showing values in an array.

清除 JSON 篩選準則

若要重設或清除篩選，請將 null 值傳遞至篩選 API。

// invoke the filter
visualHost.applyJsonFilter(null, "general", "filter", FilterAction.merge);

相關內容

使用 Power BI 視覺效果選取專案將互動功能新增至視覺效果