Freigeben über

Verbessern der Benutzerfreundlichkeit mit Lesezeichen

  • Artikel

Mit Berichtsmarken in Power BI können Sie den aktuellen Zustand einer eingebetteten Berichtsseite erfassen, einschließlich aller Filter und des Zustands der visuellen Elemente. Wenn Sie den Bericht zu einem späteren Zeitpunkt öffnen, können Sie die Textmarke auswählen, um den Bericht in den gespeicherten Zustand wiederherzustellen. Entwickler können die Benutzererfahrung mithilfe der Power BI-Client-APIs steuern, um Lesezeichen zu erfassen und anzuwenden.

Eine gespeicherte Textmarke kann entweder eine Textmarke sein, die als Teil eines Berichts gespeichert wurde, oder eine Textmarke, die als Echtzeitstatus eines Berichts erfasst wurde. Wenn Sie beim Laden eines Berichts eine gespeicherte Textmarke anwenden, können Sie das zu verwendende Lesezeichen angeben, indem Sie entweder den Namen der Textmarke oder den zugehörigen Zustand angeben. Wenn Sie eine Textmarke anhand des Namens angeben, muss Ihr Bericht eine gespeicherte Textmarke mit demselben Namen enthalten.

In diesem Artikel werden die verschiedenen API-Einstellungen erläutert, die Sie zum Einbetten von Berichten benötigen, die Lesezeichen unterstützen.

Anmerkung

In Berichten, die Sie für Ihre Organisationeinbetten, erstellen Verbraucher persönliche Lesezeichen, indem Sie den Status des Berichts erfassen und schnell zu diesem Zustand zurückkehren, indem Sie die Textmarke auswählen. Weitere Informationen finden Sie unter persönliche Lesezeichen.

Informationen zum Erstellen einer ähnlichen Benutzeroberfläche in Berichte, die Sie für Ihre Kundeneinbetten, finden Sie in der Darstellung der Berichtsansicht zur Erfassung im Power BI Embedded Analytics-Playground.

Weitere Informationen zur Verwendung von Lesezeichen in Power BI finden Sie unter Erstellen von Lesezeichen in Power BI Desktop.

Informationen zum Verwenden von persönlichen Lesezeichen beim Einbetten von Power BI finden Sie unter persönliche Lesezeichen.

Verwenden von Berichtsmarken

In den folgenden Abschnitten wird gezeigt, wie Sie die Power BI-Client-APIs verwenden, um mit Berichtsmarken zu arbeiten.

Verwalten der Textmarken eines Berichts

Verwenden Sie zum Verwalten der Textmarken eines Berichts die bookmarksManager Eigenschaft einer eingebetteten Berichtsinstanz .

Die BookmarksManager Klasse weist die folgenden Methoden auf:

  • getBookmarks – Gibt eine Liste der gespeicherten Lesezeichen zurück, die dem Bericht zugeordnet sind.

  • apply – Wendet sich mit dem Namen einer zuvor gespeicherten Textmarke auf den Bericht an.

  • capture – Erfasst und gibt eine Base64-Serialisierungszeichenfolge zurück, die den aktuellen Status des Berichts darstellt.

  • applyState Wendet einen zuvor erfassten Base64-Serialisierungsstatus einer Textmarke auf den Bericht an.

  • play – Steuert den Präsentationsmodus der Bildschirmpräsentation für die Textmarken des Berichts.

Zugreifen auf eine Berichtsmarke

Um auf eine einzelne Textmarke zuzugreifen, verwenden Sie die getBookmarks-Methode, um auf eine Liste von ReportBookmark Objekten zuzugreifen. Die ReportBookmark Klasse weist die folgenden Eigenschaften auf:

  • name – Der eindeutige Bezeichner der Berichtsmarke.

  • displayName – Der Anzeigename der Berichtsmarke, die im Bereich Lesezeichen angezeigt wird.

  • state – Eine Base64-Serialisierung des Zustands der Berichtsmarke. Sie können sie speichern und auf einen Bericht mit der bookmarksManager.applyState-Methode anwenden.

  • children – Eine Liste mit ReportBookmark Objekten, die eine Berichtsmarkengruppe darstellen, sofern vorhanden.

Verwenden der Berichtsmarken-APIs

In einem eingebetteten Bericht können Entwickler:

Abrufen einer Liste gespeicherter Berichtsmarken

Um die Liste der gespeicherten Lesezeichen abzurufen, die einem Bericht zugeordnet sind, rufen Sie die getBookmarks-Methode des BookmarksManager Objekt auf, das von der bookmarksManager-Eigenschaft des Berichts zurückgegeben wird.

Die getBookmarks-Methode ist wie folgt definiert:

getBookmarks(): Promise<models.IReportBookmark[]>

Zum Beispiel:

let bookmarks = await report.bookmarksManager.getBookmarks();

Anwenden einer gespeicherten Textmarke anhand des Namens beim Laden des Berichts oder während einer Sitzung

Um eine zuvor gespeicherte Textmarke mithilfe des Lesezeichennamens auf einen Bericht anzuwenden, rufen Sie die apply Methode des BookmarksManager- objekts auf, das von der bookmarksManager Eigenschaft eines Berichts zurückgegeben wird.

Weitere Informationen finden Sie unter Konfigurieren von Berichtseinstellungen.

Die apply-Methode ist wie folgt definiert:

apply(bookmarkName: string): Promise<void>

Zum Beispiel:

await report.bookmarksManager.apply("Bookmark1234");

Erfassen und Abrufen einer aktuellen Ansicht als Lesezeichenobjekt

Um den aktuellen Status eines Berichts als Base64-Zeichenfolge zu erfassen, rufen Sie die capture-Methode eines BookmarksManager--Objekts auf. Die capture-Methode gibt ein IReportBookmark-Objekt zurück, das eine Textmarke darstellt, die nicht in einem bestimmten Bericht gespeichert ist. Verwenden Sie die IReportBookmark.state-Eigenschaft, um die base64-Zeichenfolge zurückzugeben, die den Textmarkenzustand identifiziert, den Sie später während der Ladezeit oder Laufzeit auf einen Bericht anwenden können.

Die capture-Methode ist wie folgt definiert:

capture(options?:ICaptureBookmarkOptions): Promise<models.IReportBookmark>

Zum Beispiel:

let capturedBookmark = await report.bookmarksManager.capture();

Textmarkenoptionen erfassen

Sie können auch ein ICaptureBookmarkOptions-Objekt an die capture-Methode übergeben.

interface ICaptureBookmarkOptions {
    allPages?: boolean;
    personalizeVisuals?: boolean;
}
  • allPages – Standardmäßig speichert der erfasste Textmarkenstatus nur den aktuellen Seitenzustand. Rufen Sie zum Erfassen des Zustands aller Seiten capture Methode auf, wobei allPages Option auf truefestgelegt ist.
  • personalizeVisuals – Um den aktuellen Zustand mit personalisierten visuellenzu erfassen, rufen Sie die capture-Methode auf, wobei die option personalizeVisuals auf truefestgelegt ist.

Der folgende Code erfasst beispielsweise den Zustand aller Seiten, einschließlich der personalisierten visuellen Elemente:

let capturedBookmark = await report.bookmarksManager.capture({
    allPages: true,
    personalizeVisuals: true
});

Anwenden eines erfassten Textmarkenstatus beim Laden des Berichts oder während einer Sitzung

Um einen zuvor erfassten Textmarkenstatus auf einen Bericht anzuwenden, verwenden Sie die applyState Methode eines BookmarksManager--Objekts.

Weitere Informationen finden Sie unter Konfigurieren von Berichtseinstellungen.

Die applyState-Methode ist wie folgt definiert:

applyState(state: string): Promise<void>

Zum Beispiel:

await report.bookmarksManager.applyState(capturedBookmark.state);

Ausführen zusätzlicher Logik, wenn eine Berichtsmarke angewendet wird

Um festzustellen, wann eine Berichtsmarke angewendet wurde, lauschen Sie auf das bookmarkApplied Ereignis, indem Sie die on Methode des Berichts-Objekts aufrufen.

Zum Beispiel:

report.on("bookmarkApplied", (event) => {
    console.log(event.detail.name);
});

Anzeigen oder Ausblenden des Bereichs "Lesezeichen"

Um den Bereich "Power BI Lesezeichen" ein- oder auszublenden, aktualisieren Sie die panes Eigenschaft der Berichtseinstellungen.

Anzeigen des Bereichs "Lesezeichen"

let embedConfig = {
    ...
    panes: {
        bookmarks: {
            visible: true
        }
    }
};

Ausblenden des Bereichs "Lesezeichen"

let embedConfig = {
    ...
    panes: {
        bookmarks: {
            visible: false
        }
    }
};

Informationen zum Aktualisieren von Berichtseinstellungen finden Sie unter Konfigurieren von Berichtseinstellungen.

Eingabe- oder Beenden des Textmarken-Bildschirmpräsentationsmodus

Rufen Sie zum Steuern des Präsentationsmodus für die Textmarken eines Berichts die play Methode eines BookmarksManager--Objekts auf. Weitere Informationen finden Sie unter Lesezeichen als Bildschirmpräsentation.

Die play-Methode ist wie folgt definiert:

play(playMode: models.BookmarksPlayMode): Promise<void>

Anmerkung

Stellen Sie vor dem Eingeben des Bildschirmpräsentationsmodus für Textmarken sicher, dass mindestens eine Textmarke im Bericht mit getBookmarks-APIvorhanden ist.

Bildschirmpräsentationsmodus eingeben

await report.bookmarksManager.play(models.BookmarksPlayMode.Presentation);

Bildschirmpräsentationsmodus beenden

await report.bookmarksManager.play(models.BookmarksPlayMode.Off);

Überlegungen und Einschränkungen

  • Wenn Sie die Lesezeichen-API verwenden, können bestimmte Änderungen am Bericht einen Fehler oder ein unerwartetes Ergebnis verursachen. Ein Beispiel hierfür ist das Entfernen von Berichtsfiltern aus dem Bericht. Um Fehler zu vermeiden, müssen die entsprechenden Filterkarten vorhanden sein. Statt die Filter zu entfernen, legen Sie deren Werte auf Allfest. Wenn Sie nicht wissen, welche Filter gelöscht oder geändert wurden, erstellen Sie die Textmarke erneut, nachdem Sie die Änderungen auf den Bericht angewendet haben.

  • Filter wie beim Laden von Filtern, die von der Einbettungssitzung erstellt oder von den Updatefiltern hinzugefügt werden, fügen Vorganghinzu, werden im Textmarkenstatus erfasst, werden aber nur in der aktuellen Sitzung angewendet. Um diese Einschränkung zu umgehen, sollte der Filter im Bericht mit dem All-Wert gespeichert und in der Einbettungssitzung mithilfe der Aktualisierungsfilteraktualisierungsvorganggeändert werden.

Verwandte Inhalte