Ändern von Menübefehlen für ein Berichtsvisual in einer eingebetteten Power BI-Analyseanwendung

Artikel
01/18/2024

Visuals in Power BI verfügen über Menüs, mit denen Ihre App-Benutzer die Art und Weise ändern können, wie sie ihre Daten sehen. Mithilfe des Kontextmenüs können beispielsweise Datenpunkte in ein Visual eingeschlossen oder ausgeschlossen werden. Das Menü Optionen kann verwendet werden, um die in einem Visual enthaltenen Daten in ein Arbeitsblatt zu exportieren.

Öffnen Sie das Kontextmenü, indem Sie mit der rechten Maustaste auf ein Visual oder einen bestimmten Datenpunkt in einem Visual klicken.

Öffnen Sie das Menü Optionen , indem Sie die Auslassungspunkte in der oberen rechten Ecke des Visuals auswählen.

Hinweis

Wenn der visuelle Header für ein Visual ausgeblendet ist, wird die Auslassungspunkte nicht angezeigt.

Diese API bietet eine Möglichkeit, diese Menüs zu erweitern, sodass Sie Befehle für Ihre Benutzer hinzufügen und die App-Benutzeroberfläche verbessern können. Sie können die Menüs weiter anpassen, indem Sie Aktionen ausblenden oder deaktivieren. Sie können beispielsweise den integrierten Spotlight-Befehl für das Optionsmenü ausblenden.

Ändern Sie die Menüs, extensions indem Sie Befehle hinzufügen und commands die Anzeige der integrierten Befehle ändern.

Sie können die API so konfigurieren, dass die Berichtslast ausgeführt wird (Einbettungskonfiguration), oder Sie können die Berichtsmethode updateSettings aufrufen, um die hinzugefügten Elemente nach dem Laden eines Berichts zu aktualisieren. Weitere Informationen finden Sie unter Konfigurieren von Berichtseinstellungen und Ausblenden oder Anzeigen von visuellen Headern .

Die neuen Menüeinstellungen werden auf alle Visuals im Bericht angewendet. Um eine Einstellung auf ein bestimmtes Visual anzuwenden, verwenden Sie Selektoren.

Verwenden Sie die folgenden Parameter, um eine Befehlsdefinition zu erstellen:

name : Der Befehlsname.
title : Der Titel für den Befehl. Dies wird standardmäßig verwendet, wenn in und visualOptionsMenukeine Überschreibung visualContextMenu vorhanden ist.
icon(optional): Das Bild, das Als Symbol angezeigt werden soll. Symbole werden nur im Optionsmenü unterstützt.
extend : Definieren Sie das Menü, das der Befehl erweitert. Sie können den Befehl dem visuellen Kontextmenü, dem Menü mit den visuellen Optionen oder beidem hinzufügen. Es ist auch möglich, die Eigenschaften in jedem Menü anzupassen, z. B. den Menütitel oder die Symbolposition.

Fügen Sie die Befehlsdefinition dem Befehlsarray im Erweiterungsobjekt hinzu, das an die Berichtseinstellungen übergeben wird. Befehle sind ein Array von ICommandExtension innerhalb von Erweiterungen, das vom Typ IExtensions ist.

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

Sie sollten auch das Ereignis für den commandTriggered neuen Befehl behandeln. Dieses Ereignis wird speziell für commandNameausgelöst.

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

Weitere Informationen zum Behandeln von Ereignissen finden Sie unter Behandeln von Ereignissen.

Symbole sind optional. Wenn Sie eine verwenden, muss sie in Base 64 konvertiert werden. Im folgenden Code finden Sie ein Beispiel für ein gültiges Base 64-Symbol.

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

Der folgende Code ist ein vollständiges Codebeispiel zum Hinzufügen einer Menübefehlserweiterung.

// 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);
});

Befehle werden standardmäßig am unteren Rand des Menüs hinzugefügt. Bei nicht gruppierten Befehlen können Sie die menuLocation -Eigenschaft verwenden, um auszuwählen, ob ein Befehl oben oder unten im Menü platziert wird.

Hinweis

Wenn Sie am oberen Rand des Menüs mehr als eine Erweiterung hinzufügen, befindet sich die zuletzt hinzugefügte Erweiterung ganz oben.

Mit dem folgenden Code können Sie beispielsweise die Optionsmenübefehlserweiterung oben im Menü und den Kontextmenübefehl am unteren Rand des Menüs festlegen.

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
           }
       }
    }]
}

Gruppieren von Befehlen in einem Untermenü

Sie können ein Untermenü erstellen, um Befehle mit den folgenden Parametern zu gruppieren:

name : Der Gruppenname. Dies ist der eindeutige Bezeichner der Gruppe.
title : Der Titel, der im Menü angezeigt werden soll.
menuLocation(optional): Wählen Sie aus, ob die Gruppe oben oder unten im Menü platziert wird.

Die Gruppendefinition sollte dem Gruppenarray( ein Array von IMenuGroupExtension) innerhalb des Erweiterungsobjekts hinzugefügt werden.

Wenn Sie sich für die Verwendung eines Menüspeicherortwerts entscheiden, Top wird die Gruppe zum Zeitpunkt des Hinzufügens des ersten Befehls der Gruppe oben im Menü platziert. Wenn sie nicht verwendet wird oder den Bottom Wert verwendet, wird die Gruppe zum Zeitpunkt des Hinzufügens des ersten Befehls der Gruppe am unteren Rand des Menüs hinzugefügt.

Um einer Gruppe, die im Gruppenarray definiert wurde, einen Befehl hinzuzufügen, fügen Sie dem Befehl die groupName -Eigenschaft hinzu.

Der folgende Code ist ein vollständiges Codebeispiel zum Hinzufügen eines Untermenüs zum Optionsmenü mit zwei Befehlen darin.

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
    }]
}

Die Anzeige integrierter Befehle verfügt über drei Anzeigemodi.

Aktiviert : Der Befehl wird angezeigt, wenn er für das Visual verfügbar ist.
Deaktiviert : Der Befehl wird angezeigt, wenn er für das Visual verfügbar ist, aber abgeblendet ist (der Benutzer kann den Befehl nicht auswählen).
Ausgeblendet : Der Befehl wird nicht angezeigt.

Die derzeit verfügbaren integrierten Befehle sind:

copy : Kopieren von Wert, Auswahl oder Visual. Nur im Kontextmenü verfügbar (Visual ist nur im Bearbeitungsmodus verfügbar).
drill : Verwenden Sie den Drillmodus. Nur im Kontextmenü verfügbar.
Drillthrough : Verwenden Sie das Drillthroughfeature . Nur im Kontextmenü verfügbar.
expandCollapse : Erweitern oder reduzieren Sie die Auswahl, die gesamte Ebene oder die gesamte Hierarchie. Nur im Kontextmenü verfügbar.
exportData : Exportieren Sie die Daten, die zum Erstellen einer Visualisierung verwendet wurden. Nur im Optionsmenü verfügbar.
includeExclude: Datenpunkte einschließen oder ausschließen. Nur im Kontextmenü verfügbar.
removeVisual: Löschen Sie das Visual. Nur im Menü Optionen im Bearbeitungsmodus verfügbar.
search : Schalten Sie die Suchoption für einen Slicer um. Nur im Bearbeitungsmodus verfügbar.
seeData – Zeigt die Daten an, die zum Erstellen einer Visualisierung verwendet wurden (auch als Tabelle anzeigen bezeichnet).
sortieren : Sortieren Und wählen Sie die Sortierreihenfolge der Werte nach einem ausgewählten Datenfeld aus. Nur im Optionsmenü verfügbar.
Spotlight : Hervorheben eines Visuals. Nur im Optionsmenü verfügbar.
insightsAnalysis : Zeigt Erkenntnisse zum Visual an. Nur im Optionsmenü verfügbar.
addComment: Fügen Sie dem Visual einen Kommentar hinzu. Nur im Optionsmenü verfügbar.
groupVisualContainers : Nur im Kontextmenü im Bearbeitungsmodus verfügbar.
summari : Zeigt eine Zusammenfassung der Visualisierung an. Nur im Kontextmenü verfügbar.
clearSelection : Nur im Kontextmenü verfügbar.

Um die anzeige der integrierten Befehle anzupassen, definieren Und übergeben Sie ein Befehlsobjekt in den Einbettungskonfigurationseinstellungen. Befehle sind ein Array von ICommandsSettings.

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

Der folgende Code ist ein vollständiges Codebeispiel zum Hinzufügen integrierter Befehle.

// 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);

Menübefehle für ein Berichtsvisual ändern