Power BI ビジュアルのオブジェクトとプロパティ

[アーティクル]
03/23/2023

オブジェクトでは、ビジュアルに関連付けられているカスタマイズ可能なプロパティが記述されています。オブジェクトは複数のプロパティを持つことができ、各プロパティにはプロパティの内容を示す型が関連付けられています。この記事では、オブジェクトとプロパティの型について説明します。

myCustomObject は、dataView 内のオブジェクトを参照するために使用される内部名です。

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

表示名と説明

Note

表示名と説明は、API バージョン 5.1 以降では非推奨とされます。現在、表示名と説明は、capabilities.json ファイルではなく書式設定モデルに追加されます。

displayName は、プロパティウィンドウに表示される名前です。 description は、ツールヒントとしてユーザーに表示される、書式設定プロパティの説明です。

Properties

properties は、開発者によって定義されるプロパティのマップです。

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

注意

show は、スイッチを使用してオブジェクトを切り替えることができる特殊なプロパティです。

例:

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

プロパティの型

プロパティには、ValueTypeDescriptor と StructuralTypeDescriptor の 2 つの型があります。

値型記述子

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 プロパティには注意する必要があります。前者は、カラーピッカーです。後者は、グラデーションの置換規則であり、規則の条件が満たされると "fill プロパティ" visually を置き換えます。

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 のバージョンに応じて、次のいずれかの方法を使います。

getFormattingModel API メソッド
enumerateObjectInstances API メソッド - 非推奨

Note

getFormattingModel API メソッドは、API バージョン 5.1 以降でサポートされています。使用しているバージョンを確認するには、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 のどこにバインドされるかを決定します。 4 つの異なるオプションがあります。

例

上の myCustomCard の例は、1 つのプロパティ myCustomProperty を持つオブジェクトに対して、書式設定モデルの書式設定プロパティがどのようなものかを示しています。このプロパティオブジェクトは "静的に" dataViews[index].metadata.objects にバインドされます。記述子のセレクターは、選択するセレクターの種類に応じて変更できます。

Note

enumerateObjectInstances メソッドは、API バージョン 5.1 から非推奨になりました。新しい API では getFormattingModel に置き換えられました。

オブジェクトを効果的に使用するには、カスタムビジュアルに enumerateObjectInstances という関数が必要です。この関数では、プロパティウィンドウにオブジェクトを追加し、dataView 内でのオブジェクトのバインド先を決定します。

一般的なセットアップは次のようになります。

public enumerateObjectInstances(options: EnumerateVisualObjectInstancesOptions): VisualObjectInstanceEnumeration {
    let objectName: string = options.objectName;
    let objectEnumeration: VisualObjectInstance[] = [];

    switch( objectName ) {
        case 'myCustomObject':
            objectEnumeration.push({
                objectName: objectName,
                properties: { ... },
                selector: { ... }
            });
            break;
    };

    return objectEnumeration;
}

enumerateObjectInstances プロパティ

enumerateObjectInstances のプロパティには、機能で定義したプロパティを反映します。例については、この記事の末尾を参照してください。

enumerateObjectInstances の例

次の例では、1 つのプロパティ fill を持つ customColor オブジェクトに対する 1 つの objectEnumeration がどのようなものになるかを示します。次に示すように、このオブジェクトを dataViews[index].metadata.objects に静的にバインドします。

objectEnumeration.push({
    objectName: "customColor",
    displayName: "Custom Color",
    properties: {
        fill: {
            solid: {
                color: dataPoint.color
            }
        }
    },
    selector: null
});

オブジェクトセレクターの種類

enumerateObjectInstances のセレクターでは、dataView 内でのオブジェクトのバインド先を決定します。 4 つの異なるオプションがあります。

static
columns
selector
スコープ ID

static

このオブジェクトは、ここで示すようにメタデータ dataviews[index].metadata.objects にバインドされます。

selector: null

列

このオブジェクトは、一致する QueryName を持つ列にバインドされます。

selector: {
    metadata: 'QueryName'
}

セレクター

このオブジェクトは、作成した selectionID の対象である要素にバインドされます。この例では、いくつかのデータポイントに対して selectionID を作成してあり、それらをループ処理するものとします。

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

スコープ ID

このオブジェクトは、グループの共通部分の特定の値にバインドされます。たとえば、カテゴリ ["Jan", "Feb", "March", ...] と系列 ["Small", "Medium", "Large"] がある場合に、Feb と Large に一致する値の共通部分にあるオブジェクトを取得したいものとします。これを実現するには、両方の列の DataViewScopeIdentity を取得し、それらを変数 identities にプッシュして、セレクターで次の構文を使用します。

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

次のステップ

パフォーマンスに関するヒント

Share via

Power BI ビジュアルのオブジェクトとプロパティ

表示名と説明

Properties

プロパティの型

値型記述子

構造型記述子

グラデーションプロパティ

書式設定ウィンドウ

書式設定モデルに反映される機能オブジェクト

書式設定プロパティセレクター

例

enumerateObjectInstances プロパティ

enumerateObjectInstances の例

オブジェクトセレクターの種類

static

列

セレクター

スコープ ID

次のステップ

フィードバック

フィードバック

その他のリソース

Share via

Power BI ビジュアルのオブジェクトとプロパティ

表示名と説明

Properties

プロパティの型

値型記述子

構造型記述子

グラデーション プロパティ

書式設定ウィンドウ

書式設定モデルに反映される機能オブジェクト

書式設定プロパティ セレクター

例

オブジェクト セレクターの種類

static

列

セレクター

スコープ ID

次のステップ

フィードバック

フィードバック

その他のリソース

グラデーションプロパティ

書式設定プロパティセレクター

オブジェクトセレクターの種類