埋め込み分析アプリのレポートビジュアルメニューコマンドを変更する

[アーティクル]
07/16/2024

Power BI のビジュアルには、アプリユーザーが自分のデータを表示する方法を変更できるメニューがあります。たとえば、コンテキスト メニューを使用すると、データポイントをビジュアルに含めたり、ビジュアルから除外したりすることができます。 オプション メニューを使用すると、ビジュアルに含まれるデータをスプレッドシートにエクスポートできます。

ビジュアルまたはビジュアル内の特定のデータポイントを右クリックして、コンテキストメニューを開きます。

ビジュアルの右上隅にある省略記号を選択して、オプション メニューを開きます。

手記

ビジュアルのビジュアルヘッダーが非表示の場合、省略記号は表示されません。

この API では、これらのメニューを拡張して、ユーザーのコマンドを追加し、アプリのエクスペリエンスを強化する方法を提供します。アクションを非表示または無効にすることで、メニューをさらにカスタマイズできます。たとえば、オプションメニューの Spotlight 組み込みコマンドを非表示にすることができます。

extensions を使用してメニューを変更してコマンドを追加し、commands 組み込みコマンドの表示方法を変更します。

レポートの読み込み (埋め込み構成) に対して機能するように API を構成することも、レポート updateSettings メソッドを呼び出して、レポートの読み込み後に追加されたアイテムを更新することもできます。詳細については、「レポート設定の構成」および「ビジュアルヘッダーの表示/非表示をする」を参照してください。

新しいメニュー設定は、レポート内のすべてのビジュアルに適用されます。特定のビジュアルに設定を適用するには、セレクターを使用します。

コマンド定義を作成するには、次のパラメーターを使用します。

名 - コマンド名。
タイトル - コマンドのタイトル。これは、visualContextMenu と visualOptionsMenu内にオーバーライドがない場合に、既定として使用されます。
アイコン(省略可能) - アイコンとして表示する画像。アイコンは オプションメニューでサポート のみです。
拡張 - コマンドを拡張するメニューを定義します。コマンドは、ビジュアルコンテキストメニュー、ビジュアルオプションメニュー、またはその両方に追加できます。メニューのタイトルやアイコンの場所など、各メニューのプロパティをカスタマイズすることもできます。

レポート設定に渡される拡張オブジェクトのコマンド配列にコマンド定義を追加します。 Commands は拡張機能内の ICommandExtension の配列であり、IExtensions型です。

let embedConfig = {
    ...
    settings: {
        extensions: {
            commands: [...]
        }
    }
};

新しいコマンドの commandTriggered イベントも処理する必要があります。このイベントは、特に commandNameに対してトリガーされます。

report.on("commandTriggered", function(event) {
    let commandName = event.detail.command;
    ...
    if (commandName === "command name") {
        // Handler code
    }
});

イベントの処理の詳細については、「イベントを処理する方法」を参照してください。

アイコンは省略可能です。使用する場合は、Base 64 に変換する必要があります。有効な Base 64 アイコンの例については、次のコードを参照してください。

"data:image/png;base64,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"

次のコードは、メニューコマンド拡張機能を追加するための完全なコード例です。

// Get models. Models contain enums that can be used.
let models = window['powerbi-client'].models;

let embedConfiguration = {
    type: 'report',
    id: '5dac7a4a-4452-46b3-99f6-a25915e0fe55',
    embedUrl: 'https://app.powerbi.com/reportEmbed',
    tokenType: models.TokenType.Aad,
    accessToken: 'e4...rf',
    settings: {
        ...
        extensions: {
            commands: [{
                name: "command name",
                title: "command title",
                icon: "data:image/png;base64,iVBORw0KGgoAAAANSUhEU...AAABJRU5ErkJggg==",
                extend: {
                    visualContextMenu: {
                        title: "context menu title",
                    },
                    visualOptionsMenu: {
                        title: "options menu title",
                    }
                }
            }]
        }
    }
};

...

// Embed the report and display it within the div container.
let report = powerbi.embed(embedContainer, embedConfiguration);

// Report.on will add an event handler to commandTriggered event which prints to console window.
report.on("commandTriggered", function (command) {
    console.log(command);
});

既定では、メニューの下部にコマンドが追加されます。グループ化されていないコマンドの場合は、menuLocation プロパティを使用して、メニューの上部または下部にコマンドを配置するかどうかを選択できます。

手記

メニューの上部に複数の拡張機能を追加すると、最後に追加された拡張機能が上部に表示されます。

たとえば、次のコードでは、メニューの上部にあるオプションメニューコマンド拡張機能と、メニューの下部にあるコンテキストメニューコマンドを設定できます。

extensions: {
    commands: [{
       name: "command name",
       title: "command title",
       icon: "data:image/png;base64,iVBORw0KGgoAAAANSUhEU...AAABJRU5ErkJggg==",
       extend:
       {
           visualContextMenu: {
               title: "context menu title",
               menuLocation: models.MenuLocation.Bottom
           },
           visualOptionsMenu: {
               title: "options menu title",
               menuLocation: models.MenuLocation.Top
           }
       }
    }]
}

サブメニューでコマンドをグループ化する

サブメニューを作成して、次のパラメーターを使用してコマンドをグループ化できます。

名 - グループ名。これはグループの一意識別子です。
タイトル - メニューに表示するタイトル。
menuLocation(省略可能) - グループをメニューの上部または下部に配置するかどうかを選択します。

グループ定義は、IMenuGroupExtensionの配列である groups 配列に拡張オブジェクト内に追加する必要があります。

メニューの場所の値を使用する場合、Top グループの最初のコマンドを追加するときに、メニューの上部にグループが配置されます。使用されていない場合、または Bottom 値を使用している場合、グループの最初のコマンドを追加するときに、メニューの下部にグループが追加されます。

グループ配列で定義されたグループにコマンドを追加するには、groupName プロパティをコマンドに追加します。

次のコードは、2 つのコマンドを含むサブメニューをオプションメニューに追加する方法の完全なコード例です。

extensions: {
    commands: [
        {
            name: "Command 1",
            title: "Command 1",
            extend: {
                visualOptionsMenu: {
                    groupName: "group-unique-identifier"
                }
            }
        },
        {
            name: "Command 2",
            title: "Command 2",
            extend: {
                visualOptionsMenu: {
                    groupName: "group-unique-identifier"
                }
            }
        }
    ],
    groups: [{
        name: "group-unique-identifier",
        title: "Group title",
        menuLocation: models.MenuLocation.Top
    }]
}

組み込みコマンドの表示には、3 つの表示モードがあります。

有効 - ビジュアルで使用できる場合は、コマンドが表示されます。
無効 - ビジュアルで使用できるが淡色表示されている場合は、コマンドが表示されます (ユーザーはコマンドを選択できません)。
非表示 - コマンドは表示されません。

現在使用できる組み込みコマンドは次のとおりです。

コピー - 値、選択、またはビジュアルをコピーします。コンテキストメニューでのみ使用できます (ビジュアルは編集モードでのみ使用できます)。
ドリル - ドリルモードのを使用します。コンテキストメニューでのみ使用できます。
ドリルスルー - ドリルスルー機能を使用します。コンテキストメニューでのみ使用できます。
expandCollapse の - 選択範囲、レベル全体、階層全体を展開または折りたたみます。コンテキストメニューでのみ使用できます。
exportData - 視覚化の作成に使用されたデータをエクスポートします。オプションメニューでのみ使用できます。
includeExclude - データポイントを含めるまたは除外する。コンテキストメニューでのみ使用できます。
removeVisual の - ビジュアルを削除します。編集モードのオプションメニューでのみ使用できます。
検索 - スライサーの検索オプションを切り替えます。編集モードでのみ使用できます。
data - 視覚化の作成に使用されたデータを表示します (テーブルとして表示とも呼ばれます)。
並べ替え - 選択したデータフィールドで値の並べ替え順序を並べ替え、選択します。オプションメニューでのみ使用できます。
スポットライト - ビジュアルにスポットライトを当てます。オプションメニューでのみ使用できます。
insightsAnalysis - ビジュアルに関する分析情報を表示します。オプションメニューでのみ使用できます。
addComment - ビジュアルにコメントを追加します。オプションメニューでのみ使用できます。
groupVisualContainers - 編集モードのコンテキストメニューでのみ使用できます。
の概要 - 視覚化の概要を表示します。コンテキストメニューでのみ使用できます。
clearSelection - コンテキストメニューでのみ使用できます。

組み込みコマンドの表示をカスタマイズするには、埋め込み構成設定でコマンドオブジェクトを定義して渡します。コマンドは、ICommandsSettingsの配列です。

let embedConfig = {
    ...
    settings: {
        commands: [...]
    }
};

次のコードは、組み込みコマンドを追加するための完全なコード例です。

// The new settings that you want to apply to the report.
const newSettings = {
    commands: [
        {
            spotlight: {
                displayOption: models.CommandDisplayOption.Hidden,
            },
            drill: {
                displayOption: models.CommandDisplayOption.Disabled,
            }
        }
    ]
};

// Update the settings by passing in the new settings you have configured.
await report.updateSettings(newSettings);

次の方法で共有

レポートビジュアルのメニューコマンドを変更する

メニューコマンドを変更する方法

メニューコマンドの拡張

メニュー項目の場所を設定する

サブメニューでコマンドをグループ化する

メニューコマンドをカスタマイズする

その他のリソース

次の方法で共有

レポート ビジュアルのメニュー コマンドを変更する

メニュー コマンドを変更する方法

メニュー コマンドの拡張

メニュー項目の場所を設定する

サブメニューでコマンドをグループ化する

メニュー コマンドをカスタマイズする

関連コンテンツ

その他のリソース

レポートビジュアルのメニューコマンドを変更する

メニューコマンドを変更する方法

メニューコマンドの拡張

メニューコマンドをカスタマイズする