共用方式為

Power BI 視覺效果的物件和屬性

  • 發行項

物件會描述與視覺效果相關聯的可自訂屬性。 一個物件可以有多個屬性，且每個屬性都有能描述該屬性將會是什麼的相關聯類型。 此文章提供物件及屬性類型的相關資訊。

myCustomObject 是用來參考 dataView 內之物件的內部名稱。

"objects": {
    "myCustomObject": {
        "properties": { ... }
    }
}

顯示名稱和描述

注意

顯示名稱和描述已在 API 5.1+ 版中淘汰。 顯示名稱和描述現在新增在格式化模型中，而不是 capabilities.json 檔案。

displayName 是將會顯示在 [屬性] 窗格中的名稱。 description 是格式化屬性的描述，會向使用者顯示為工具提示。

屬性

properties 是開發人員所定義的屬性對應。

"properties": {
    "myFirstProperty": {
        "type": ValueTypeDescriptor | StructuralTypeDescriptor
    }
}

注意

show 是啟用參數來切換物件的特殊屬性。

範例：

"properties": {
    "show": {
        "type": {"bool": true}
    }
}

屬性類型

屬性類型有兩種類型：ValueTypeDescriptor 和 StructuralTypeDescriptor。

實值類型描述項

ValueTypeDescriptor 類型大多是基本類型，且通常作為靜態物件使用。

以下是一些常見的 ValueTypeDescriptor元素：

export interface ValueTypeDescriptor {
    text?: boolean;
    numeric?: boolean;
    integer?: boolean;
    bool?: boolean;
}

結構類型描述項

StructuralTypeDescriptor 類型主要用於資料繫結物件。 最常見的 StructuralTypeDescriptor 類型是 fill。

export interface StructuralTypeDescriptor {
    fill?: FillTypeDescriptor;
}

漸層屬性

漸層屬性是無法設定為標準屬性的屬性。 相反地，您必須設定要替代色彩選擇器屬性 (fill 類型) 的規則。

下列程式碼會顯示範例：

"properties": {
    "showAllDataPoints": {
        "type": {
            "bool": true
        }
    },
    "fill": {
        "type": {
            "fill": {
                "solid": {
                    "color": true
                }
            }
        }
    },
    "fillRule": {
        "type": {
            "fillRule": {}
        },
        "rule": {
            "inputRole": "Gradient",
            "output": {
                "property": "fill",
                    "selector": [
                        "Category"
                    ]
            }
        }
    }
}

請注意 fill 和 fillRule 屬性。 第一個是色彩選擇器，而第二個則是漸層的替代規則，其會在符合規則條件時 visually 取代「fill 屬性」。

fill 屬性與替代規則之間的這個連結，是在 fillRule 屬性的 "rule">"output" 區段中設定。

"Rule">"InputRole" 屬性會設定哪一個資料角色會觸發規則 (條件)。 在此範例中，如果資料角色 "Gradient" 包含資料，則會針對 "fill" 屬性套用規則。

您可以在下列程式碼中看到觸發 fill 規則 (the last item) 的資料角色範例：

{
    "dataRoles": [
            {
                "name": "Category",
                "kind": "Grouping",
                "displayName": "Details",
                "displayNameKey": "Role_DisplayName_Details"
            },
            {
                "name": "Series",
                "kind": "Grouping",
                "displayName": "Legend",
                "displayNameKey": "Role_DisplayName_Legend"
            },
            {
                "name": "Gradient",
                "kind": "Measure",
                "displayName": "Color saturation",
                "displayNameKey": "Role_DisplayName_Gradient"
            }
    ]
}

[格式化] 窗格

若要在格式化窗格中自訂屬性，請視您使用的 API 版本而定，使用下列其中一種方法。

注意

API 5.1+ 版支援 getFormattingModel API 方法。 若要了解您正在使用哪個版本，請檢查 pbiviz.json 檔案中的 apiVersion。

若要在 API 5.1+ 版中有效地使用物件，您必須實作 getFormattingModel 方法。
此方法會建置並傳回格式化模型，其中包含格式化卡片、格式化群組的完整屬性窗格階層。此外，也包含格式化屬性及其值。

格式化模型中反映的功能物件

格式化模型中的每個格式化屬性都需要 capabilities.json 檔案中的對應物件。 格式化屬性應包含描述項，其中有與對應功能物件完全相符的物件名稱和屬性名稱 (物件和屬性名稱均區分大小寫)。
例如：

對於格式化模型中的下列格式化屬性 (請參閱描述項物件內容)：

 const myCustomCard: powerbi.visuals.FormattingCard = {
            displayName: "My Custom Object Card",
            uid: "myCustomObjectCard_uid",
            groups: [{
                displayName: undefined,
                uid: "myCustomObjectGroup_uid",
                slices: [
                    {
                        uid: "myCustomProperty_uid",
                        displayName: "My Custom Property",
                        control: {
                            type: powerbi.visuals.FormattingComponent.ColorPicker,
                            properties: {
                                descriptor: {
                                    objectName: "myCustomObject",
                                    propertyName: "myCustomProperty",
                                    selector: null // selector is optional
                                },
                                value: { value: "#000000" }
                            }
                        }
                    }
                ],
            }],
        };

功能 objects 區段中對應的物件應該是：

    "objects": {
        "myCustomObject": {
            "properties": {
                "myCustomProperty": {
                    "type": {
                         "fill": {
                            "solid": {
                                "color": true
                            }
                        }
                    }
                }
            }
        }
    }

格式化屬性選取器

格式化屬性描述項中的選擇性選取器會決定 dataView 中每個屬性繫結的位置。 有四個不同的選項。

範例

上述 myCustomCard 範例顯示對於具有一個屬性 myCustomProperty 的物件，格式化模型中的格式化屬性外觀是什麼樣。 這個屬性物件會以靜態方式繫結至 dataViews[index].metadata.objects。 描述項中的選取器可根據您選擇的選取器類型變更。

物件選取器類型

enumerateObjectInstances 中選取器會決定每個物件在 dataView 中的繫結位置。 有四個不同的選項：

static

此物件會繫結至中繼資料 dataviews[index].metadata.objects，如這裡所示。

selector: null

欄

此物件會繫結到具有相符 QueryName 的資料行。

selector: {
    metadata: 'QueryName'
}

選取器

此物件會繫結至您其建立 selectionID 的元素。 在此範例中，假設我們已針對某些 dataPoints 建立 selectionID，且我們會以迴圈方式執行它們。

for (let dataPoint in dataPoints) {
    ...
    selector: dataPoint.selectionID.getSelector()
}

範圍識別

此物件會繫結到群組交集處的特定值。 例如，如果您有類別 ["Jan", "Feb", "March", ...] 和序列 ["Small", "Medium", "Large"]，您可能想要在符合 Large 和 Feb 的值交集處有一個物件。 為了達到這個目的，您可以取得這兩個資料行的 DataViewScopeIdentity，將它們推送至 identities 變數，並將此語法與選取器搭配使用。

selector: {
    data: <DataViewScopeIdentity[]>identities
}

相關內容

效能祕訣