Power BI カスタムビジュアルの [書式] ウィンドウ

[アーティクル]
01/24/2025

API バージョン 5.1 以降では、開発者は、新しい Power 形式ウィンドウを使用するビジュアルを作成できます。開発者は、カスタムビジュアル内の任意のプロパティのカードとそのカテゴリを定義できるため、レポート作成者はこれらのビジュアルを簡単に使用できます。

新しい API では、FormattingModel メソッドを使用して、書式設定ウィンドウと分析ウィンドウの一部をカスタマイズします。

ヒント

getFormattingModel メソッドは、以前のバージョンの API で enumerateObjectInstances メソッドを置き換えます。

getFormattingModel は、ビジュアルの書式設定と分析ウィンドウの外観を定義する FormattingModel を返します。

すべての古い書式設定ウィンドウ機能に加えて、新しい書式設定モデルでは、新しい書式設定ウィンドウ機能、新しいプロパティ、新しい階層がサポートされます。

新しい書式設定ウィンドウのスクリーンショット。

新しい書式ペインをサポートするビジュアルを作成する

新しい書式ペインのサポートをカスタムビジュアルに追加する一般的な手順:

pbiviz.json ファイルの apiVersion を 5.1 以降に設定します。
capabilities.json ファイル内のすべてのカスタマイズ可能な objects を定義します。これらのオブジェクトは書式設定ウィンドウのプロパティにマッピングされます。各オブジェクトには、次のプロパティが必要です。
- オブジェクト名
- プロパティ名
- プロパティの種類
DisplayName や descriptionなど、他のすべてのプロパティは省略可能になりました。
次のいずれかを実行して、カスタムビジュアル FormattingModel をビルドします。
- のフォーマッティングモデルユーティリティを使用します。 (推奨)
- このユーティリティがない場合は、API のみを使用します。

カスタムビジュアル書式設定モデルのプロパティを定義し、(JSON ではなく) コードを使用してビルドします。

カスタムビジュアル書式設定モデルを返すカスタムビジュアルクラスに getFormattingModel API を実装します。 (この API は、以前のバージョンで使用されていた enumerateObjectInstances を置き換えます)。

書式設定モデルの実装例

formattingmodel util を使用したモデルの書式設定例です。 (推奨)
API のみを使用して モデルを書式設定する例。

マップの書式設定プロパティ

古い API を使用してカスタムビジュアルを作成し、新しいフォーマットウィンドウに移行する場合、または新しいカスタムビジュアルを作成する場合:

pbiviz.json ファイルの apiVersion を 5.1 以降に設定します。
capabilities.json内のオブジェクト名とプロパティ名ごとに、一致する書式設定プロパティを作成します。書式設定プロパティには、capabilities.jsonのオブジェクト名とプロパティ名と一致する objectName と propertyName を含む記述子が必要です。

機能ファイルの objects プロパティの形式は同じであり、変更する必要はありません。

たとえば、capabilities.json ファイル内の circle オブジェクトが次のように定義されている場合は、次のようになります。

"objects": {
    "circle": {
        "properties": {
            "circleColor": {
                "type": {
                    "fill": {
                        "solid": {
                            "color": true
                        }
                    }
                }
            },
        }
    }
}

モデルの書式設定プロパティは ColorPicker 型で、次のようになります。

control: {
    type: "ColorPicker",
    properties: {
        descriptor: {
            objectName: "circle",
            propertyName: "circleColor"
        },
        value: {
            value: this.visualSettings.circle.circleColor
        }
    }
}

次のいずれかの条件に該当する場合は、エラーが発生します。

機能ファイル内のオブジェクトまたはプロパティ名が、書式設定モデルの名前と一致しません
機能ファイルのプロパティ型が書式設定モデルの型と一致しない

書式設定モデル

書式設定モデルでは、書式設定ウィンドウのすべてのプロパティを記述してカスタマイズします。

モデルコンポーネントの書式設定

新しい書式設定モデルでは、プロパティコンポーネントは論理カテゴリとサブカテゴリにグループ化されます。これらのグループにより、モデルのスキャンが容易になります。最大から最小の 5 つの基本的なコンポーネントがあります。

書式設定モデル ウィンドウの前面インターフェイスの書式設定に使用される最大のペインコンテナーです。これには、書式設定カードの一覧が含まれています。
書式設定カード 書式設定プロパティの最上位のプロパティグループ化コンテナーです。各カードは、次に示すように、1 つ以上の書式設定グループで構成されます。
書式設定グループ
コンテナーをグループ化するセカンダリレベルのプロパティ。書式設定グループは、スライスを書式設定するためのグループ化コンテナーとして表示されます。
書式設定コンテナー
コンテナーをグループ化するセカンダリレベルのプロパティ。書式設定コンテナーは、スライスの書式設定を個別のコンテナー項目にグループ化し、ドロップダウンリストを使用して切り替えることができます。
書式設定スライス
プロパティコンテナー。スライスには次の 2 種類があります。
- 単純スライス: 個別のプロパティコンテナー
- 複合スライス: 複数の関連するプロパティコンテナーを 1 つの書式設定スライスにグループ化する
次の図は、さまざまな種類のスライスを示しています。 "Font" は、フォントファミリ、サイズ、太字、斜体、下線の切り替えで構成される複合スライスです。 "Color"、"display units"、およびその他のスライスは、それぞれ 1 つのコンポーネントを持つ単純なスライスです。

視覚化ウィンドウの書式設定プロパティ

書式設定モデル内のすべてのプロパティは、capabilities.json ファイル内のオブジェクトの種類と一致する必要があります。

次の表は、capabilities.json ファイル内の書式設定プロパティの型と、最新の書式設定モデルプロパティの対応する型クラスを示しています。

種類	capabilities の値の型	Formatting プロパティ
ブーリアン	ブール	ToggleSwitch
数値	数値整数	NumUpDown スライダー
列挙リスト	enumeration:[]	ItemDropdown ItemFlagsSelection AutoDropdown AutoFlagsSelection ^* 下記の注意事項を参照してください
色	塗りつぶし	ColorPicker
勾配	フィルルール	GradientBar: プロパティ値は、次で構成される文字列である必要があります: `minValue[,midValue],maxValue`
テキスト	テキスト	TextInput TextArea

capabilities の書式設定オブジェクト

種類	capabilities の値の型	Formatting プロパティ
フォントサイズ	フォントサイズ	NumUpDown
フォントファミリ	フォントファミリー	FontPicker（フォント選択ツール）
線の配置	アラインメント	AlignmentGroup
ラベル表示単位	ラベル表示単位	AutoDropDown

^* 列挙リストの書式設定プロパティは、書式設定モデルと機能ファイルで異なります。

列挙項目の一覧を含め、書式設定クラスで次のプロパティを宣言します。
- ItemDropdown
- ItemFlagsSelection
列挙項目の一覧を使用せずに、書式設定クラスで次のプロパティを宣言します。適切なオブジェクトの下の capabilities.json で列挙項目リストを宣言します。 (これらの型は、以前の API バージョンと同じです)。
- AutoDropdown
- 自動フラグ選択

複合スライスのプロパティ

書式設定複合スライスは、複数の関連プロパティをまとめて含む書式設定スライスです。

現時点では、次の 2 つの複合スライスの種類があります。

FontControl
これにより、フォント関連のすべてのプロパティが一緒に保持されます。これは、次のプロパティで構成されます。

フォントファミリ
フォントサイズ
太字 [省略可能]
斜体 [省略可能]
下線 [省略可能]

フォントファミリ、フォントサイズ、太字、斜体、下線オプションを含むフォント複合スライスのスクリーンショット。

これらの各プロパティには、機能ファイル内の対応するオブジェクトが必要です。

財産	機能の種類	書式設定の種類
フォントファミリ	書式設定: { fontFamily}	FontPicker
フォントサイズ	書式設定: {fontSize}	NumUpDown
太字	ブール	トグルスイッチ
イタリック	ブール	トグルスイッチ
アンダーライン	ブール	トグルスイッチ

マージンパディングマージンパディングは、ビジュアル内でテキストの整列を決定します。これは、次のプロパティで構成されます。
- 左
- 右
- 上
- 下
これらの各プロパティには、機能ファイル内の対応するオブジェクトが必要です。

財産機能の種類書式設定の種類

左数値 NumUpDown

右数値 NumUpDown

上数値 NumUpDown

下数値 NumUpDown

財産	機能の種類	書式設定の種類
左	数値	NumUpDown
右	数値	NumUpDown
上	数値	NumUpDown
下	数値	NumUpDown

GitHub リソース

すべての書式設定モデルインターフェイスは、GitHub - microsoft/powerbi-visuals-api: "formatting-model-api.d.ts" の Power BI カスタムビジュアル API にあります
GitHub で新しい書式設定モデルユーティリティを使用することをお勧めします - microsoft/powerbi-visuals-utils-formattingmodel: Power BI ビジュアル書式設定モデルヘルパーユーティリティ
API バージョン 5.1.0 を使用し、新しい書式設定モデルユーティリティを使って getFormattingModel を実装したカスタムビジュアル SampleBarChart の例が、GitHub - microsoft/PowerBI-visuals-sampleBarChart: チュートリアル用の横棒グラフのカスタムビジュアルにあります。

その他の質問 Power BI コミュニティに質問する

次の方法で共有

Power BI カスタムビジュアルの [書式] ウィンドウ

新しい書式ペインをサポートするビジュアルを作成する

書式設定モデルの実装例

マップの書式設定プロパティ