Hinzufügen der Unterstützung von Lesezeichen für Power BI-Berichte
Mit Lesezeichen in Power BI-Berichten können Sie eine konfigurierte Ansicht einer Berichtsseite erfassen und speichern. Anschließend können Sie dann jederzeit schnell und einfach zu dieser Ansicht zurück wechseln. Das Lesezeichen speichert die gesamte Konfiguration, einschließlich ausgewählter Optionen und Filter.
Weitere Informationen zu Lesezeichen finden Sie unter Verwenden von Lesezeichen zum Teilen von Erkenntnissen und Erstellen von Präsentationen in Power BI.
Lesezeichen unterstützende Visuals
Power BI-Visuals, die Lesezeichen unterstützen, müssen die richtigen Informationen speichern und bei Bedarf bereitstellen können. Wenn Ihr Visual mit anderen Visuals interagiert, Datenpunkte auswählt oder Filter auf andere Visuals anwendet, müssen Sie den mit einem Lesezeichen gespeicherten Zustand in den filterState-Eigenschaften des Visuals speichern.
Hinweis
Für das Erstellen eines Visuals, das Lesezeichen unterstützt, ist Folgendes erforderlich:
- Version 3.0.0 oder höher von powerbi-visuals-utils-interactivityutils für Filtervisuals und alle Visuals, die
InteractivityServiceverwenden - Version 1.11.0 oder höher der Visual-API bei Visuals ohne Filter, die
SelectionManageranstelle vonInteractivityServiceverwenden. - Um herauszufinden, welche Version Sie verwenden, überprüfen Sie die
apiVersionin der Datei pbiviz.json.
So interagieren Power BI-Visuals mit Power BI im Berichtslesezeichen
Nehmen wir an, Sie möchten mehrere Textmarken auf einer Berichtsseite erstellen, und für jede Textmarke sind verschiedene Datenpunkte ausgewählt.
Wählen Sie zunächst einen oder mehrere Datenpunkte in Ihrem Visual aus. Das Visual übergibt Ihre Auswahl an den Host. Wählen Sie dann die Option Hinzufügen im Bereich „Lesezeichen“ aus. Power BI speichert die aktuelle Auswahl für das neue Lesezeichen.
Wiederholen Sie diesen Vorgang mehrmals, um neue Lesezeichen zu erstellen. Nachdem Sie die Lesezeichen erstellt haben, können Sie zwischen diesen wechseln.
Immer wenn Sie eine Textmarke auswählen, stellt Power BI den gespeicherten Filter- oder Auswahlzustand wieder her und übergibt ihn an die visuellen Elemente. Die Visuals im Bericht werden basierend auf dem im Lesezeichen gespeicherten Zustand hervorgehoben oder gefiltert. Hierzu muss Ihr Visual den richtigen Auswahlzustand an den Host übergeben (z. B. die Farben der gerenderten Datenpunkte).
Der neue Auswahlzustand (oder Filter) wird über die Eigenschaft options.jsonFilters in der update-Methode mitgeteilt. jsonFilters kann entweder Advanced Filter oder Tuple Filter sein.
- Wenn Ihr Visual ausgewählte Datenpunkte enthält, setzen Sie die Auswahl mithilfe der Rückruffunktion
registerOnSelectCallbackinISelectionManagerauf das ausgewählte Lesezeichen zurück. - Wenn Ihr Visual Filter zum Auswählen von Daten verwendet, setzen Sie die Filterwerte auf die entsprechenden Werte für das ausgewählte Lesezeichen zurück.
Visuals mit Auswahl
Wenn das Visual durch eine Auswahl mit anderen Visuals interagiert, gibt es zwei Möglichkeiten, Lesezeichen hinzuzufügen:
- Verwenden Sie
applySelectionFromFilterzum Verwalten der Auswahl mit InteractivityService. Dies ist die einfachere und bevorzugte Methode. - Wenn Ihr Visual InteractivityService nicht nutzt, verwenden Sie SelectionManager.
Verwenden von InteractivityService zum Wiederherstellen der Lesezeichenauswahl
Wenn Ihr Visual InteractivityService verwendet, sind keine weiteren Aktionen Ihrerseits erforderlich, damit die Lesezeichen in Ihrem Visual unterstützt werden.
Wenn Sie ein Lesezeichen auswählen, verarbeitet das Hilfsprogramm automatisch den Auswahlzustand des Visuals.
Verwenden von SelectionManager zum Wiederherstellen der Lesezeichenauswahl
Wenn Sie InteractivityService nicht verwenden, können Sie eine Lesezeichenauswahl mithilfe der ISelectionManager.registerOnSelectCallback-Methode wie folgt speichern und abrufen:
Wenn Sie auf ein Lesezeichen klicken, ruft Power BI die Methode callback des Visuals mit der entsprechenden Auswahl auf.
this.selectionManager.registerOnSelectCallback(
(ids: ISelectionId[]) => {
//called when a selection was set by Power BI
});
);
Angenommen, Sie haben in der visualTransform-Methode Ihres Visuals einen Datenpunkt erstellt.
datapoints sieht wie folgt aus:
visualDataPoints.push({
category: categorical.categories[0].values[i],
color: getCategoricalObjectValue<Fill>(categorical.categories[0], i, 'colorSelector', 'fill', defaultColor).solid.color,
selectionId: host.createSelectionIdBuilder()
.withCategory(categorical.categories[0], i)
.createSelectionId(),
selected: false
});
Sie verfügen jetzt über visualDataPoints als Datenpunkte, und das Array ids wurde an die Funktion callback übergeben.
An diesem Punkt sollte das Visual das Array ISelectionId[] mit der Auswahl im Array visualDataPoints vergleichen und die entsprechenden Datenpunkte dann als ausgewählt markieren.
this.selectionManager.registerOnSelectCallback(
(ids: ISelectionId[]) => {
visualDataPoints.forEach(dataPoint => {
ids.forEach(bookmarkSelection => {
if (bookmarkSelection.equals(dataPoint.selectionId)) {
dataPoint.selected = true;
}
});
});
});
);
Nach dem Aktualisieren der Datenpunkte wird der aktuelle Auswahlzustand angezeigt, der im Objekt filter gespeichert ist. Wenn die Datenpunkte anschließend gerendert werden, entspricht der Auswahlzustand des benutzerdefinierten Visuals dem Zustand des Lesezeichens.
Visuals mit einem Filter
Verwenden Sie InteractivityService, damit Lesezeichen in Visuals unterstützt werden, die über einen Filter verfügen.
Nehmen wir an, dass vom Visual ein Datenfilter nach Datumsbereich erstellt wird. startDate und endDate dienen jeweils als Anfangs- und Enddatum.
Durch das Visual wird ein erweiterter Filter erstellt, und die Hostmethode applyJsonFilter wird aufgerufen, um Daten nach relevanten Bedingungen zu filtern.
Das Ziel ist die Tabelle, die zum Filtern verwendet wird.
import { AdvancedFilter } from "powerbi-models";
const filter: IAdvancedFilter = new AdvancedFilter(
target,
"And",
{
operator: "GreaterThanOrEqual",
value: startDate
? startDate.toJSON()
: null
},
{
operator: "LessThanOrEqual",
value: endDate
? endDate.toJSON()
: null
});
this.host.applyJsonFilter(
filter,
"general",
"filter",
(startDate && endDate)
? FilterAction.merge
: FilterAction.remove
);
Sobald ein Benutzer auf ein Lesezeichen klickt, empfängt das benutzerdefinierte Visual einen update-Aufruf.
In der update-Methode überprüft das Visual den Filter im Objekt:
const filter: IAdvancedFilter = FilterManager.restoreFilter(
&& options.jsonFilters
&& options.jsonFilters[0] as any
) as IAdvancedFilter;
Wenn das filter-Objekt nicht NULL ist, stellt das Visual die Filterbedingungen aus dem Objekt wieder her:
const jsonFilters: AdvancedFilter = this.options.jsonFilters as AdvancedFilter[];
if (jsonFilters
&& jsonFilters[0]
&& jsonFilters[0].conditions
&& jsonFilters[0].conditions[0]
&& jsonFilters[0].conditions[1]
) {
const startDate: Date = new Date(`${jsonFilters[0].conditions[0].value}`);
const endDate: Date = new Date(`${jsonFilters[0].conditions[1].value}`);
// apply restored conditions
} else {
// apply default settings
}
Anschließend ändert das Visual seinen internen Zustand wieder in die aktuellen Bedingungen. Der interne Zustand umfasst die Datenpunkte und Visualisierungsobjekte (Linien, Rechtecke usw.).
Wichtig
Im obigen Szenario mit Berichtslesezeichen sollte das Visual nicht applyJsonFilter aufrufen, um die anderen Visuals zu filtern. Diese werden bereits von Power BI gefiltert.
Das Zeitskalaslicer-Visual ändert die Bereichsauswahl in die entsprechenden Datenbereiche.
Speichern des Filterzustands des Visuals
Neben den Filterbedingungen können Sie für das Lesezeichen auch andere Filteraspekte speichern.
So speichert beispielsweise der Zeitachsendatenschnitt die Werte für die Eigenschaft Granularity als Filterzustand. Dadurch kann sich die Granularität der Zeitskala (Tage, Monate, Jahre usw.) ändern, wenn Sie zwischen Lesezeichen wechseln.
Die Eigenschaft filterState speichert einen Filteraspekt als Eigenschaft. Das Visual kann mehrere filterState-Werte in Lesezeichen speichern.
Wenn Sie einen Eigenschaftswert als Filterzustand speichern möchten, legen Sie die Objekteigenschaft in der Datei capabilities.json als "filterState": true fest.
Nächste Schritte
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für