チュートリアル:Power BI ビジュアルへの書式設定オプションの追加Tutorial: Adding formatting options to a Power BI visual

このチュートリアルでは、ビジュアルに共通プロパティを追加する方法について説明します。In this tutorial, we go through how to add common properties to the visual.

このチュートリアルで学習する内容は次のとおりです。In this tutorial, you learn how to:

  • ビジュアルのプロパティを追加する。Add visual properties.
  • ビジュアルをパッケージ化する。Package the visual.
  • カスタム ビジュアルを Power BI Desktop レポートにインポートする。Import the custom visual to a Power BI Desktop report.

書式設定オプションの追加Adding formatting options

  1. Power BI書式ページを選択します。In Power BI, select the Format page.

    次のメッセージが表示されます - "このビジュアルに対して書式設定オプションは使用できません"。You should see a message that reads - Formatting options are unavailable for this visual.

    書式設定ペイントブラシ

  2. Visual Studio Code で、capabilities.json ファイルを開きます。In Visual Studio Code, open the capabilities.json file.

  3. dataViewMappings 配列の前に、objects を追加します (8 行目の後)。Before the dataViewMappings array, add objects (after line 8).

    "objects": {},
    

    オブジェクトの追加

  4. capabilities.json ファイルを保存します。Save the capabilities.json file.

  5. Power BI で、書式設定オプションをもう一度確認します。In Power BI, review the formatting options again.

    注意

    書式設定オプションが変化していない場合は、 [Reload Custom Visual](カスタム ビジュアルの再読み込み) を選択します。If you do not see the formatting options change then select Reload Custom Visual.

    書式設定オプションを表示する

  6. [タイトル] オプションを "オフ" に設定します。Set the Title option to Off. ビジュアルの左上隅にメジャー名が表示されなくなったことを確認します。Notice that the visual no longer displays the measure name at the top-left corner.

    タイル オプションをオフにする

    名前なしのタイル

カスタム書式設定オプションの追加Adding custom formatting options

カスタム プロパティを追加して、円の色や境界線の幅を設定することができます。You can add custom properties to enable configuring the color of the circle, and also the border width.

  1. PowerShell で、カスタム ビジュアルを停止します。In PowerShell, stop the custom visual.

  2. Visual Studio Code で、capabilities.json ファイルにある objects というラベルのオブジェクトに次の JSON フラグメントを挿入します。In Visual Studio Code, in the capabilities.json file, insert the following JSON fragment into the object labeled objects.

        {
            "circle": {
                "displayName": "Circle",
                "properties": {
                    "circleColor": {
                        "displayName": "Color",
                        "description": "The fill color of the circle.",
                        "type": {
                            "fill": {
                                "solid": {
                                    "color": true
                                }
                            }
                        }
                    },
                    "circleThickness": {
                        "displayName": "Thickness",
                        "description": "The circle thickness.",
                        "type": {
                            "numeric": true
                        }
                    }
                }
            }
        }
    

    この JSON フラグメントには circle という名前のグループが記述されています。これは、circleColor と circleThickness という 2 つのオプションで構成されています。The JSON fragment describes a group named circle, which consists of two options named circleColor and circleThickness.

    円の太さに関するコード

  3. capabilities.json ファイルを保存します。Save the capabilities.json file.

  4. src フォルダーの内部からエクスプローラー ウィンドウに入り、settings.ts を選択します。In the Explorer pane, from inside the src folder, and then select settings.ts. このファイルには、スターターのビジュアルに関する設定が記述されていますThis file represents the settings for the starter visual.

  5. settings.ts ファイルで、2 つのクラスを次のコードに置き換えます。In the settings.ts file, replace the two classes with the following code.

    export class CircleSettings {
        public circleColor: string = "white";
        public circleThickness: number = 2;
    }
    export class VisualSettings extends DataViewObjectsParser {
        public circle: CircleSettings = new CircleSettings();
    }
    

    モジュール クラス

    このモジュールでは、2 つのクラスが定義されます。This module defines the two classes. CircleSettings クラスでは、capabilities.json ファイル内で定義されるオブジェクト (circleColorcircleThickness) の名前と一致する 2 つのプロパティが定義されます。また規定値も設定されています。The CircleSettings class defines two properties with names that match the objects defined in the capabilities.json file (circleColor and circleThickness) and also sets default values. VisualSettings クラスでは DataViewObjectParser クラスが継承され、circle という名前のプロパティが追加されます。これは capabilities.json ファイル内で定義されるオブジェクトと一致しており、CircleSettings のインスタンスを返します。The VisualSettings class inherits the DataViewObjectParser class and adds a property named circle, which matches the object defined in the capabilities.json file, and returns an instance of CircleSettings.

  6. settings.ts ファイルを保存します。Save the settings.ts file.

  7. visual.ts ファイルを開きます。Open the visual.ts file.

  8. visual.ts ファイルで、In the visual.ts file,

    VisualSettingsVisualObjectInstanceEnumerationEnumerateVisualObjectInstancesOptions をインポートします。import VisualSettings, VisualObjectInstanceEnumeration and EnumerateVisualObjectInstancesOptions:

    import { VisualSettings } from "./settings";
    import VisualObjectInstanceEnumeration = powerbi.VisualObjectInstanceEnumeration;
    import EnumerateVisualObjectInstancesOptions = powerbi.EnumerateVisualObjectInstancesOptions;
    

    Visual クラスに次のプロパティを追加します。and in the Visual class add the following property:

    private visualSettings: VisualSettings;
    

    このプロパティには VisualSettings オブジェクトへの参照が格納され、ビジュアルの設定が記述されます。This property stores a reference to the VisualSettings object, describing the visual settings.

    ビジュアル クラスを追加する

  9. Visual クラスで、update メソッドの前に次のメソッドを追加します。In the Visual class, add the following method before the update method. このメソッドは、書式設定オプションを設定するために使用されます。This method is used to populate the formatting options.

    public enumerateObjectInstances(options: EnumerateVisualObjectInstancesOptions): VisualObjectInstanceEnumeration {
        const settings: VisualSettings = this.visualSettings || <VisualSettings>VisualSettings.getDefault();
        return VisualSettings.enumerateObjectInstances(settings, options);
    }
    

    このメソッドは、書式設定オプションを設定するために使用されます。This method is used to populate the formatting options.

    ビジュアル設定オブジェクト

  10. update メソッドの radius 変数の宣言の後に、次のコードを追加します。In the update method, after the declaration of the radius variable, add the following code.

    this.visualSettings = VisualSettings.parse<VisualSettings>(dataView);
    
    this.visualSettings.circle.circleThickness = Math.max(0, this.visualSettings.circle.circleThickness);
    this.visualSettings.circle.circleThickness = Math.min(10, this.visualSettings.circle.circleThickness);
    

    このコードは書式設定オプションを取得します。This code retrieves the format options. ここでは circleThickness プロパティに渡される値が調整されます。負の値は 0 に変換され、10 より大きい値は 10 に変換されます。It adjusts any value passed into the circleThickness property, converting it to 0 if negative, or 10 if it's a value greater than 10.

    Radius 変数

  11. circle の要素で、fill の style に渡される値を次の式に変更します。For the circle element, modify the value passed to the fill style to the following expression.

    this.visualSettings.circle.circleColor
    

    circle の要素の fill

  12. circle の要素で、stroke-width の style に渡される値を次の式に変更します。For the circle element, modify the value passed to the stroke-width style to the following expression.

    this.visualSettings.circle.circleThickness
    

    Circle の Stroke-width

  13. visual.ts ファイルを保存します。Save the visual.ts file.

  14. PowerShell で、ビジュアルを開始します。In PowerShell, start the visual.

    pbiviz start
    
  15. Power BI のビジュアルの上に表示されるツールバーで、 [自動再読み込みの切り替え] を選択します。In Power BI, in the toolbar floating above the visual, select Toggle Auto Reload.

  16. ビジュアルの書式オプションで、 [Circle] を展開します。In the visual format options, expand Circle.

    Circle の書式

    [色] オプションと [太さ] オプションを変更します。Modify the color and thickness option.

    [太さ] オプションの値を、0 より小さい値や 10 より大きい値に変更します。Modify the thickness option to a value less than zero, and a value higher than 10. すると、ビジュアルによって許容する最小値または最大値に値が更新されることを確認してください。Then notice the visual updates the value to a tolerable minimum or maximum.

カスタム ビジュアルのパッケージ化Packaging the custom visual

カスタム ビジュアル プロジェクトのプロパティ値を入力し、アイコン ファイルを更新したら、カスタム ビジュアルをパッケージ化します。Enter property values for the custom visual project, update the icon file, and then package the custom visual.

  1. PowerShell で、カスタム ビジュアルを停止します。In PowerShell, stop the custom visual.

  2. Visual Studio Codepbiviz.json ファイルを開きます。Open the pbiviz.json file in Visual Studio Code.

  3. visual オブジェクトで、displayName プロパティを Circle Card に変更します。In the visual object, modify the displayName property to Circle Card.

    [視覚化] ウィンドウでアイコンにカーソルを合わせると、表示名が表示されます。In the Visualizations pane, hovering over the icon reveals the display name.

    表示名のビジュアル

  4. description プロパティに次のテキストを入力します。For the description property, enter the following text.

    円の内側に書式設定された測定値を表示しますDisplays a formatted measure value inside a circle

  5. ビジュアルの supportUrlgitHubUrl を設定します。Fill supportUrl and gitHubUrl for the visual.

    例: Example:

    {
        "supportUrl": "https://community.powerbi.com",
        "gitHubUrl": "https://github.com/microsoft/PowerBI-visuals-circlecard"
    }
    
  6. author オブジェクトに詳細を入力します。Enter your details in the author object.

  7. pbiviz.json ファイルを保存します。Save the pbiviz.json file.

  8. assets オブジェクトのドキュメントでアイコンへのパスが定義されていることに注意してください。In the assets object, notice that the document defines a path to an icon. このアイコンは、 [視覚化] ウィンドウに表示されるイメージです。The icon is the image that appears in the Visualizations pane. これは "20 × 20 ピクセル" の PNG ファイルにする必要があります。It must be a PNG file, 20 pixels by 20 pixels.

  9. エクスプローラーで icon.png ファイルをコピーして貼り付け、assets フォルダーにある既定のファイルを置き換えます。In Windows Explorer, copy the icon.png file, and then paste it to replace the default file located at assets folder.

  10. Visual Studio Code のエクスプローラー ウィンドウで assets フォルダーを展開し、icon.png ファイルを選択します。In Visual Studio Code, in the Explorer pane, expand the assets folder, and then select the icon.png file.

  11. アイコンを確認します。Review the icon.

    視覚化ウィンドウのイメージ

  12. Visual Studio Code で、すべてのファイルが保存されていることを確認します。In Visual Studio Code, ensure that all files are saved.

  13. カスタム ビジュアルをパッケージ化するには、PowerShell で次のコマンドを入力します。To package the custom visual, in PowerShell, enter the following command.

    pbiviz package
    

    dist フォルダー

パッケージがプロジェクトの dist フォルダーに出力されました。Now the package is output to the dist folder of the project. パッケージには、カスタム ビジュアルを Power BI サービスまたは Power BI Desktop レポートにインポートするために必要なものがすべて含まれています。The package contains everything required to import the custom visual into either the Power BI service or a Power BI Desktop report. これでカスタム ビジュアルのパッケージ化が完了し、使用する準備が整いました。You have now packaged the custom visual, and it is now ready for use.

カスタム ビジュアルのインポートImporting the custom visual

Power BI Desktop レポートを開き、カスタム ビジュアル Circle Card をインポートできるようになりました。Now you can open the Power BI Desktop report, and import the Circle Card custom visual.

  1. Power BI Desktop を開き、任意の "サンプルのデータセット" を使用して新しいレポートを作成します。Open Power BI Desktop, create a new report with any sample dataset

  2. [視覚化] ウィンドウで省略記号を選択し、ファイルから [インポート] を選択します。In the Visualizations pane, select the ellipsis, and then select Import from File.

    デスクトップにカスタム ビジュアルを追加する

  3. インポート ウィンドウで、 [インポート] を選択します。In the import window, select Import.

  4. 開いたウィンドウで、プロジェクトのディレクトリの dist フォルダーに移動します。In the Open window, navigate to the dist folder in your project directory.

  5. circleCard.pbiviz ファイルを選択して、 [開く] を選択します。Select the circleCard.pbiviz file, and then select Open.

  6. ビジュアルが正常にインポートされたら、 [OK] を選択します。When the visual has successfully imported, select OK.

  7. ビジュアルが [視覚化] ウィンドウに追加されたことを確認します。Verify that the visual has been added to the Visualizations pane.

    PBI Desktop 視覚化ウィンドウのビュー

  8. Circle Card にカーソルを合わせると、ツールヒントが表示されることに注目してください。Hover over the Circle Card icon, and notice the tooltip that appears.

デバッグDebugging

カスタム ビジュアルのデバッグに関するヒントについては、デバッグ ガイドを参照してください。For tips about debugging your custom visual, see the debugging guide.

次の手順Next steps

他のユーザーが使用できるように新しく開発したビジュアルをリストすることはできますが、その場合、AppSource に送信する必要があります。You can list your newly developed visual for others to use by submitting it to the AppSource. このプロセスの詳細については、「Power BI ビジュアルを AppSource に発行する」を参照してください。For more information on this process reference Publish Power BI visuals to AppSource.