Steuerelementberichtsschnitte
Mithilfe der Slicer-APIs können Sie den Status eines Power BI-Slicers abrufen und festlegen. Darüber hinaus können Sie die Ladekonfiguration verwenden, um den Slicerstatus beim Laden eines Berichts zu ändern.
Es gibt zwei Arten von Slicervisuals:
Sofort einsatzbereit : Slicer für sofort einsatzbereite Power BI-Visuals. Sofort einsatzbereite Slicer unterstützen alle Power BI-Visuals, die mit Power BI (Desktop und Dienst) ausgeliefert werden.
Power BI-Visuals aus AppSource und Dateien : Slicer für Power BI-Visuals von Drittanbietern, die in AppSource oder als PBIVIZ-Datei verfügbar sind. Slicer für Power BI-Visuals aus AppSource und Dateien, kurz visuals aus AppSource oder Dateien, sind Slicer für Power BI-Visuals, die von Entwicklern erstellt wurden.
Slicerobjekt
Es gibt vier Slicertypen:
Kategorischer Slicer
Kategorische Slicer unterstützen die folgenden Anzeigen:
- Eine Liste
- Dropdownmenü
- Wertkarten
Sie können einzelne oder mehrere Elemente aus diesen Listen auswählen, um den Bericht entsprechend zu filtern.
Um eine Auswahl für diesen Slicertyp zu ändern, müssen Sie ein IBasicFilter Objekt erstellen. Weitere Informationen zum Erstellen eines Basisfilters finden Sie unter Standardfilter.
const basicFilter = {
$schema: "http://powerbi.com/product/schema#basic",
target: {
table: "Store",
column: "Count"
},
operator: "In",
values: [1, 2, 3, 4],
filterType: models.FilterType.BasicFilter
};
await visual.setSlicerState({
filters: [basicFilter]
});
Wenn das Slicerziel eine Hierarchie ist, geben Sie ein Ziel an IFilterHierarchyTarget . Weitere Informationen finden Sie unter Verwenden von Zielen zum Auswählen des Datenfelds, auf das sie reagieren möchten.
const basicFilter = {
$schema: "http://powerbi.com/product/schema#basic",
target: {
table: "Store",
hierarchy: "Country",
hierarchyLevel: "Code"
},
operator: "In",
values: [456, 943],
filterType: models.FilterType.BasicFilter
};
await visual.setSlicerState({
filters: [basicFilter]
});
Bereichsschnitt
Bereichsschnitte unterstützen Bedingungen wie:
- Zwischen
- vor
- Danach
Um eine Auswahl für Bereichsschnitte zu ändern, erstellen Sie ein IAdvancedFilter Objekt. Weitere Informationen finden Sie unter Erweiterter Filter.
const advancedFilter = {
$schema: "http://powerbi.com/product/schema#advanced",
target: {
table: "Store",
column: "Number"
},
logicalOperator: "And",
conditions: [
{
operator: "GreaterThanOrEqual",
value: 30
},
{
operator: "LessThan",
value: 40
}
],
filterType: models.FilterType.AdvancedFilter
};
await visual.setSlicerState({
filters: [advancedFilter]
});
Relativer Datumsschnitt
Relative Datumsschnitte unterstützen Bedingungen wie:
- Letzte Woche:
- Letzte fünf Jahre
Um eine Auswahl für relative Datumsschnitte zu ändern, erstellen Sie ein IRelativeDateFilter Objekt. Weitere Informationen finden Sie unter Filterobjekte für relatives Datum und relative Uhrzeit.
const relativeDateFilter = {
$schema: "http://powerbi.com/product/schema#relativeDate",
target: {
table: "Sales",
column: "OrderDate"
},
operator: models.RelativeDateOperators.InLast,
timeUnitsCount: 30,
timeUnitType: models.RelativeDateFilterTimeUnit.Days,
includeToday: true,
filterType: models.FilterType.RelativeDate
};
await visual.setSlicerState({
filters: [relativeDateFilter]
});
Slicer für relative Zeitbereiche
Relative Zeitslicer unterstützen Bedingungen wie:
- Letzte fünf Minuten
- Diese Stunde
Um eine Auswahl für relative Zeitschnitte zu ändern, erstellen Sie ein IRelativeTimeFilter Objekt. Weitere Informationen finden Sie unter Filter für relatives Datum und relative Zeit.
const relativeTimeFilter = {
$schema: "http://powerbi.com/product/schema#relativeTime",
target: {
table: "Sales",
column: "OrderDate"
},
operator: models.RelativeDateOperators.InLast,
timeUnitsCount: 5,
timeUnitType: models.RelativeDateFilterTimeUnit.Minutes,
filterType: models.FilterType.RelativeTime
};
await visual.setSlicerState({
filters: [relativeTimeFilter]
});
Hierarchieslicer
Mit Hierarchieschnitten können Sie aus mehreren verwandten Feldern filtern.
Der Hierarchie-Slicer wird ab SDK-Version 2.21 unterstützt. Legen Sie Auswahlen im Hierarchieschnitt mit der setSlicerState-API fest , oder rufen Sie die aktuelle Hierarchieauswahl mit der getSlicerState-API ab.
Erfahren Sie mehr über das Hinzufügen von Feldern zu Hierarchieschnitten.
Hierarchiefilter
Der IHierarchyFilter beschreibt die Slicerhierarchie. Verwenden Sie die getSlicerState Methoden und setSlicerState mit diesem Filter.
interface IHierarchyFilter extends IFilter {
target: (IFilterTarget | IFilterKeyTarget)[];
hierarchyData: IHierarchyFilterNode[];
}
hierarchyData– die ausgewählten und nicht ausgewählten Elemente in einer Hierarchiestruktur, in der jedesIHierarchyFilterNodeeine einzelne Wertauswahl darstellt.interface IHierarchyFilterNode { value?: PrimitiveValueType; keyValues?: PrimitiveValueType[]; children?: IHierarchyFilterNode[]; operator?: HierarchyFilterNodeOperators; }- Entweder
valueoderkeyValuesmuss festgelegt werden. children– Liste der untergeordneten Knoten, die für die aktuelle Auswahl relevant sindoperator– Der Operator für einzelne Objekte in der Struktur. Der Operator kann einer der folgenden Sein:
type HierarchyFilterNodeOperators = "Selected" | "NotSelected" | "Inherited";Selected– Wert ist explizit ausgewählt.NotSelected– Wert ist explizit nicht ausgewählt.Inherited– Die Wertauswahl entspricht dem übergeordneten Wert in der Hierarchie oder dem Standardwert, wenn es sich um den Stammwert handelt.
operatorist optional. Wenn kein Operator festgelegt ist, istInheritedder Standardwert .- Entweder
Hierarchieschnittbeispiele
In den folgenden Beispielen werden verschiedene Szenarien für die Verwendung der setSlicerState API mit Hierarchieschnitten beschrieben.
Wählen Sie Werte auf verschiedenen Ebenen aus. Wählen Sie beispielsweise "Qtr 1" und "Qtr 2" in 2013 und "Qtr 1" und "Qtr 2" in 2014 aus.
const filter = { "$schema": http://powerbi.com/product/schema#hierarchy, "target": [ { "table": "Dates", "hierarchy": "Date Hierarchy", "hierarchyLevel": "Year" }, { "table": "Dates", "hierarchy": "Date Hierarchy", "hierarchyLevel": "Quarter" } ], "filterType": 9, "hierarchyData": [ { "operator": "Inherited", "value": 2013, "children": [ { "operator": "Selected", "value": "Qtr 1" }, { "operator": "Selected", "value": "Qtr 2" } ] }, { "operator": "Inherited", "value": 2014, "children": [ { "operator": "Selected", "value": "Qtr 1" }, { "operator": "Selected", "value": "Qtr 2" } ] } ] }; await slicer.setSlicerState({ filters: [filter] });
Wählen Sie Werte auf verschiedenen Ebenen mit Ausnahmen aus. Wählen Sie beispielsweise 2014 ohne "Qtr 1" aus.
const filter = { "$schema": http://powerbi.com/product/schema#hierarchy, "target": [ { "table": "Dates", "hierarchy": "Date Hierarchy", "hierarchyLevel": "Year" }, { "table": "Dates", "hierarchy": "Date Hierarchy", "hierarchyLevel": "Quarter" } ], "filterType": 9, "hierarchyData": [ { "operator": "Selected", "value": 2014, "children": [ { "operator": "NotSelected", "value": "Qtr 1" } ] } ] }; await slicer.setSlicerState({ filters: [filter] });
Beginnen Sie mit dem
NotSelectedOperator, um alles mit Ausnahme bestimmter Werte auszuwählen. Wählen Sie beispielsweise alles mit Ausnahme von "Qtr 1" von 2008 und 2009 aus.const filter = { "$schema": http://powerbi.com/product/schema#hierarchy, "target": [ { "table": "Dates", "column": "Year" }, { "table": "Dates", "column": "Quarter" } ], "filterType": 9, "hierarchyData": [ { "operator": "NotSelected", "value": 2009 }, { "operator": "Inherited", "value": 2008, "children": [ { "operator": "NotSelected", "value": "Q1" } ] } ] } await slicer.setSlicerState({ filters: [filter] });
Slicer-APIs
Sie können die folgenden Methoden für Visuals mit dem slicer Typ verwenden:
- Abrufen des Datenschnittzustands -
getSlicerState - Festlegen des Slicerstatus -
setSlicerState
Hinweis
Die in einem Bericht gespeicherte Konfiguration von Datenschnitten wird von den Slicer-APIs erkannt. Dies bedeutet, dass beim Festlegen eines Datenschnitts mit der API alle Datenschnitte in derselben Synchronisierungsgruppe betroffen sind.
Abrufen des Datenschnittzustands
Um einen Datenschnittstatus zu erhalten, müssen Sie die visuelle Slicerinstanz suchen und aufrufen getSlicerState. Das Ergebnis ist vom Typ ISlicerState.
Standardmäßig werden für den Datenschnitt keine Filter angewendet. In solchen Fällen getSlicerState wird mit einem leeren Array von Filtern zurückgegeben ISlicerState .
getSlicerState funktioniert sowohl für out-of-the-Box- als auch für Visuals aus AppSource- oder Dateienschnitten .
let state = await visual.getSlicerState();
Festlegen des Slicerstatus
Um einen Datenschnittzustand festzulegen, müssen Sie die visuelle Instanz des Slicers suchen , den Datenschnittzustand erstellen und mit dem von Ihnen erstellten Slicerzustand aufrufen setSlicerState .
await visual.setSlicerState(state);
Der Slicerzustand ist ein ISlicerState Objekt.
interface ISlicerState {
filters: ISlicerFilter[];
targets?: SlicerTarget[];
}
Um einen Datenschnitt zurückzusetzen, rufen Sie setSlicerState mit einem leeren Array von Filtern auf.
Festlegen eines Slicers für Visuals aus AppSource oder Dateien
Zum Festlegen eines Visuals aus der AppSource- oder Dateischnittauswahl müssen Sie ein ISlicerFilter Objekt erstellen, das die folgenden Typen aufweisen kann:
IBasicFilterIAdvancedFilterIRelativeDateFilterIRelativeTimeFilter
Verschiedene Visuals aus AppSource oder Dateischnitten unterstützen verschiedene Filtertypen. Um den Filtertyp zu ermitteln, der zum Ändern des Slicers erforderlich ist, rufen Sie auf visual.getSlicerState().
Weitere Informationen zu Filtertypen finden Sie unter Steuern von Berichtsfiltern.
Festlegen von Datenschnitten für die Berichtslast
Die Berichtsladekonfiguration unterstützt das Ändern des Datenschnittzustands. Dadurch können Sie den Status der Berichtsslicer während des Ladens des Berichts ändern. Übergeben Sie dazu ein ISlicer Array.
interface IReportLoadConfiguration {
...
slicers?: ISlicer[];
}
Jedes ISlicer Objekt enthält einen Selektor und einen Datenschnittzustand.
interface ISlicer {
selector: SlicerSelector;
state: ISlicerState;
}
Verwenden Sie einen Visualnamen oder eine Datenschnittzielauswahl , um auszuwählen, welcher Slicer geändert werden soll. Weitere Informationen finden Sie unter Verwenden von Selektoren zum Steuern, welche Visuals verwendet werden.
Hinweis
Wenn Sie verschiedene ISlicer Objekte übergeben, die sich in derselben Synchronisierungsgruppe befinden, wird das Ergebnis unerwartet.
Anwenden von Slicer beim Laden von Beispielen
Dieser Abschnitt enthält zwei Beispiele für die Ladekonfiguration mit Datenschnitten.
Festlegen eines bestimmten Datenschnitts anhand des Namens
let slicers = [ { selector: { $schema: "http://powerbi.com/product/schema#visualSelector", visualName: "d1feb8891635af3b335a" }, state: { filters: [advancedFilter] } } ]; let embedConfig = { ... slicers: slicers, };Festlegen von Datenschnitten nach Slicerziel
let target = { table: "Store", column: "StoreNumber" }; let slicers = [ { selector: { $schema: "http://powerbi.com/product/schema#slicerTargetSelector", target: target }, state: { filters: [advancedFilter] } } ]; let embedConfig = { ... slicers: slicers, };
Überlegungen und Einschränkungen
Tupelslicer werden nicht unterstützt.
Der Hierarchieslicer wird ab SDK-Version 2.21 unterstützt.
Sofort einsatzbereite Slicer unterstützen nur einen einzelnen Filter.
Das Aufrufen
setSlicerStateeines Visuals, bei dem es sich nicht um einen Slicer handelt, gibt eine abgelehnte Zusage mit dem Fehler Operation funktioniert nur für Slicer zurück.Es gibt keine API zum Ändern der Konfiguration der Slicersynchronisierung.