Verbessern der Benutzerfreundlichkeit mit Lesezeichen

  • Artikel

Mit Berichtslesezeichen in Power BI können Sie den aktuellen Zustand einer eingebetteten Berichtsseite erfassen, einschließlich aller Filter und des Zustands ihrer Visuals. Wenn Sie den Bericht zu einem späteren Zeitpunkt öffnen, können Sie das Lesezeichen auswählen, um den Bericht in den gespeicherten Zustand wiederherzustellen. Entwickler können die Benutzeroberfläche steuern, indem sie die Power BI-Client-APIs verwenden, um Lesezeichen zu erfassen und anzuwenden.

Ein gespeichertes Lesezeichen kann entweder ein Lesezeichen sein, das als Teil eines Berichts gespeichert wurde, oder ein Lesezeichen, das als Echtzeitzustand eines Berichts erfasst wurde. Wenn Sie beim Laden eines Berichts ein gespeichertes Lesezeichen anwenden, können Sie das zu verwendende Lesezeichen angeben, indem Sie entweder den Namen oder den Status des Lesezeichens angeben. Wenn Sie ein Lesezeichen anhand des Namens angeben, muss ihr Bericht ein gespeichertes Lesezeichen 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.

Hinweis

In Berichten, die Sie für Ihre Organisation einbetten, erstellen Berichtsconsumer persönliche Lesezeichen, indem sie den Status des Berichts erfassen und schnell zu diesem Zustand zurückkehren, indem Sie das Lesezeichen auswählen. Weitere Informationen finden Sie unter Persönliche Lesezeichen .

Informationen zum Erstellen einer ähnlichen Benutzeroberfläche in Berichten, die Sie für Ihre Kunden einbetten, finden Sie im Showcase der Erfassungsberichtsansicht 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 zur Verwendung von persönlichen Lesezeichen beim Einbetten von Power BI finden Sie unter Persönliche Lesezeichen.

Verwenden von Berichtslesezeichen

In den folgenden Abschnitten wird gezeigt, wie Sie die Power BI-Client-APIs zum Arbeiten mit Berichtslesezeichen verwenden.

Verwalten der Lesezeichen eines Berichts

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

Die BookmarksManager-Klasse verfügt über die folgenden Methoden:

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

  • apply – Wendet ein zuvor gespeichertes Lesezeichen namens auf den Bericht an.

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

  • applyState Wendet einen zuvor erfassten Base64-Serialisierungszustand eines Lesezeichens auf den Bericht an.

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

Zugreifen auf ein Berichtslesezeichen

Um auf ein einzelnes Lesezeichen zuzugreifen, verwenden Sie die getBookmarks -Methode, um auf eine Liste von ReportBookmark Objekten zuzugreifen. Die ReportBookmark -Klasse verfügt über die folgenden Eigenschaften:

  • name : Der eindeutige Bezeichner des Berichtslesezeichens.

  • displayName – Der Anzeigename des Berichtslesezeichens , das im Bereich Lesezeichen angezeigt wird.

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

  • children – Eine Liste von ReportBookmark Objekten, die eine Berichtslesezeichengruppe darstellen, sofern vorhanden.

Verwenden der ApIs für Berichtslesezeichen

In einem eingebetteten Bericht können Entwickler:

Abrufen einer Liste mit gespeicherten Berichtslesezeichen

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

Die getBookmarks -Methode ist wie folgt definiert:

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

Zum Beispiel:

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

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

Um ein zuvor gespeichertes Lesezeichen mithilfe des Lesezeichennamens auf einen Bericht anzuwenden, rufen Sie die apply Methode des BookmarksManager-Objekts auf, das von der -Eigenschaft eines Berichts bookmarksManager 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 Zustand 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 ein Lesezeichen darstellt, das nicht in einem bestimmten Bericht gespeichert ist. Verwenden Sie die IReportBookmark.state -Eigenschaft, um die base64-Zeichenfolge zurückzugeben, die den Lesezeichenzustand identifiziert, den Sie später während der Ladezeit oder der 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();

Optionen für Das Erfassen von Lesezeichen

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

interface ICaptureBookmarkOptions {
    allPages?: boolean;
    personalizeVisuals?: boolean;
}
  • allPages – Standardmäßig speichert der erfasste Lesezeichenzustand nur den aktuellen Seitenzustand. Um den Zustand aller Seiten zu erfassen, rufen Sie capture die -Methode auf, wobei allPages die Option auf truefestgelegt ist.
  • personalizeVisuals – Um den aktuellen Zustand mit personalisierten Visuals zu erfassen, rufen Sie die capture -Methode auf, wobei die personalizeVisuals Option auf truefestgelegt ist.

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

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

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

Um einen zuvor erfassten Lesezeichenzustand 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 ein Berichtslesezeichen angewendet wird

Um zu bestimmen, wann ein Berichtslesezeichen angewendet wurde, lauschen Sie auf das bookmarkApplied Ereignis, indem Sie die on -Methode des Berichtsobjekts aufrufen.

Zum Beispiel:

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

Ein- oder Ausblenden des Bereichs "Lesezeichen"

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

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.

Wechseln oder Beenden des Bildschirmpräsentationsmodus für Lesezeichen

Um den Präsentationsmodus der Bildschirmpräsentation für die Lesezeichen eines Berichts zu steuern, rufen Sie 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>

Hinweis

Bevor Sie in den Bildschirmpräsentationsmodus für Lesezeichen wechseln, stellen Sie sicher, dass mindestens ein Lesezeichen im Bericht mit der getBookmarks-API vorhanden ist.

In den Präsentationsmodus für Bildschirmpräsentationen wechseln

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

Beenden des Präsentationsmodus für Bildschirmpräsentationen

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

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. Anstatt die Filter zu entfernen, legen Sie deren Werte auf fest All. Wenn Sie nicht wissen, welche Filter gelöscht oder geändert wurden, erfassen Sie das Lesezeichen erneut, nachdem Sie die Änderungen auf den Bericht angewendet haben.

  • Filter, z. B . auf Lastfilter, die von der Einbettungssitzung erstellt oder durch den Vorgang zum Hinzufügen von Updatefiltern hinzugefügt wurden, werden im Lesezeichenzustand erfasst, 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 des Updatefilteraktualisierungsvorgangs geändert werden.

Nächste Schritte