Power BI ビジュアルのオブジェクトとプロパティ
オブジェクトでは、ビジュアルに関連付けられているカスタマイズ可能なプロパティが記述されています。 オブジェクトは複数のプロパティを持つことができ、各プロパティにはプロパティの内容を示す型が関連付けられています。 この記事では、オブジェクトとプロパティの型について説明します。
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 のバージョンに応じて、次のいずれかの方法を使います。
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 にバインドされます。
記述子のセレクターは、選択するセレクターの種類に応じて変更できます。
オブジェクト セレクターの種類
enumerateObjectInstances のセレクターでは、dataView 内でのオブジェクトのバインド先を決定します。 4 つの異なるオプションがあります。
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
}