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

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

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

ヒント

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

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

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

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

最新の [書式] ウィンドウをサポートするビジュアルを作成する

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

  1. apiVersion ファイルの を 5.1 以降に設定します。

  2. objects ファイル内のすべてのカスタマイズ可能な を定義します。 これらのオブジェクトは 書式設定ウィンドウのプロパティに マッピングされます。 各オブジェクトには、次のプロパティが必要です。

    • オブジェクト名
    • プロパティ名
    • プロパティの種類

    DisplayName や descriptionなど、他のすべてのプロパティは省略可能になりました。

  3. 次のいずれかを実行して、カスタム ビジュアル FormattingModel をビルドします。

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

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

書式設定モデルの実装例

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

古い API で作成されたカスタム ビジュアルがあり、それを書式設定ウィンドウで更新する場合、または新しいカスタム ビジュアルを作成する場合:

  1. apiVersion ファイルの を 5.1 以降に設定します。

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

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

たとえば、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 プロパティ
ブール値 ブール トグルスイッチ
数値
  • 数値
  • 整数
    		•
  • NumUpDown
  • スライダー
    		•
    列挙リスト enumeration:[]
  • アイテムドロップダウン
  • アイテムフラグ選択
  • オートドロップダウン
  • 自動フラグ選択
    • * 下記の注意事項を参照してください
    色 幅に合わせて調整 ColorPicker
    勾配 フィルルール GradientBar: プロパティ値は、次で構成される文字列である必要があります。 minValue[,midValue],maxValue
    テキスト テキスト
  • TextInput
  • テキストエリア
    		•

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

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

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

    • 列挙項目の一覧を含め、書式設定クラスで次のプロパティを宣言します。

      • ItemDropdown
      • ItemFlagsSelection

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

      • AutoDropdown
      • 自動フラグ選択

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

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

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

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

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

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

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

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

    • マージンパディング マージンパディング は、ビジュアル内でテキストの整列を決定します。 これは、次のプロパティで構成されます。

      • 左
      • 右
      • 上
      • 下

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

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

    GitHub リソース

    関連コンテンツ

    その他の質問 Power BI コミュニティでご質問ください。

    • Last updated on