Freigeben über

Steuerelementberichtfilter

  • Artikel

Wenn Sie einen Power BI-Bericht einbetten, können Sie Filter anwenden, während der Ladephase automatisch angewendet werden, oder Sie können Filter dynamisch ändern, nachdem der Bericht geladen wurde. Sie können z. B. einen eigenen benutzerdefinierten Filterbereich erstellen und diese Filter automatisch auf Berichte anwenden, um den benutzerspezifischen Einblicken anzuzeigen. Sie können auch eine Schaltfläche erstellen, mit der der Benutzer Filter auf den eingebetteten Bericht anwenden kann.

Die folgenden Filtertypen werden unterstützt:

Die Filterobjektattribute

Alle Filtertypen erben die IFilter Schnittstelle. Die unten aufgeführten Attribute sind für alle Filtertypen relevant.

interface IFilter {
    $schema: string;
    target: IFilterGeneralTarget;
    filterType: FilterType;
    displaySettings?: IFilterDisplaySettings;
}

Schema

Das attribut $schema definiert den Typ des Filters. Es stehen fünf Schemas zur Verfügung, eine für jeden Filtertyp:

  • Basic- - https://powerbi.com/product/schema#basic
  • Advanced - https://powerbi.com/product/schema#advanced
  • relatives Datum - https://powerbi.com/product/schema#relativeDate
  • relative Zeit - https://powerbi.com/product/schema#relativeTime
  • Top N- - https://powerbi.com/product/schema#topN

Anzeigeeinstellungen

Das attribut displaySettings definiert, wie der Filter im Filterbereich angezeigt wird.

interface IFilterDisplaySettings {
    isLockedInViewMode?: boolean;
    isHiddenInViewMode?: boolean;
    displayName?: string;
}

  • isLockedInViewMode – Ein gesperrter Filter wird im Filterbereich angewendet und angezeigt. Der Filterwert kann im Ansichtsmodusnicht geändert werden. Legen Sie ihn auf true fest, um den Filter zu sperren.

  • isHiddenInViewMode – Ein ausgeblendeter Filter wird auf den Bericht angewendet, aber nicht im Filterbereich im Ansichtsmodusangezeigt. Legen Sie ihn auf true fest, um den Filter auszublenden.

  • displayName – Ein Filter kann im Filterbereich mit einem personalisierten Namen angezeigt werden. Verwenden Sie dieses Attribut, um einen personalisierten Namen für Ihren Filter festzulegen. Wenn der Wert nicht definiert oder null ist, wird der Standardname des Filters angezeigt (in der Regel der Name des gefilterten Datenfelds).

Filtertyp

Das attribut filterType definiert den Typ des Filters. Verwenden Sie die folgende Enumeration, die in der Modellbibliothek definiert ist:

enum FilterType {
    Advanced = 0,
    Basic = 1,
    Unknown = 2,
    IncludeExclude = 3,
    RelativeDate = 4,
    TopN = 5,
    Tuple = 6,
    RelativeTime = 7,
}

Ziel

Das attribut target definiert das Ziel des Filters. Weitere Informationen finden Sie unter Verwenden von Zielen, um auszuwählen, welches Datenfeld aufreagieren soll.

Zusätzliche Attribute nach Filtertyp

Jeder Filtertyp verfügt über eine eigene Schnittstelle mit einem anderen Satz von Attributen. Die Filterschnittstellen sind Teil der powerbi-Modelle Bibliothek.

Standardfilter

Standardfilter- verfügt über einen einzelnen Operator mit einem oder mehreren Werten.

interface IBasicFilter extends IFilter {
    operator: BasicFilterOperators;
    values: (string | number | boolean)[];
    requireSingleSelection?: boolean;
}

  • operator – Für grundlegende Filter kann der Operator eine der folgenden Sein:

    type BasicFilterOperators = "In" | "NotIn" | "All"

  • values – Ein Array von Werten für den Filter, alle Werte müssen denselben Typ aufweisen.

  • requireSingleSelection – Definiert, ob mehrere Werte für den Filter ausgewählt werden können. Wenn sie auf truefestgelegt ist, kann nur ein einzelner Wert ausgewählt werden.

Zum Beispiel:

const basicFilter = {
  $schema: "https://powerbi.com/product/schema#basic",
  target: {
    table: "Store",
    column: "Count"
  },
  operator: "In",
  values: [1, 2, 3, 4],
  filterType: models.FilterType.BasicFilter,
  requireSingleSelection: true
}

Erweiterter Filter

Erweiterter Filter verfügt über einen einzelnen logischen Operator und eine oder zwei Bedingungen, die über einen eigenen Operator und einen eigenen Wert verfügen.

interface IAdvancedFilter extends IFilter {
    logicalOperator: AdvancedFilterLogicalOperators;
    conditions: IAdvancedFilterCondition[];
}

  • logicalOperator : Der logische Operator kann einer der folgenden Sein:

    type AdvancedFilterLogicalOperators = "And" | "Or";

  • conditions - Ein Array von Bedingungen für den erweiterten Filter verfügt jede Bedingung über eine operator und eine value.

    interface IAdvancedFilterCondition {
    value?: (string | number | boolean | Date);
    operator: AdvancedFilterConditionOperators;
}

    Die verfügbaren Operatoren für eine Bedingung sind:

    type AdvancedFilterConditionOperators = "None" | "LessThan" | "LessThanOrEqual" | 
"GreaterThan" | "GreaterThanOrEqual" | "Contains" | "DoesNotContain" | "StartsWith" | 
"DoesNotStartWith" | "Is" | "IsNot" | "IsBlank" | "IsNotBlank";

Zum Beispiel:

const advancedFilter = {
  $schema: "https://powerbi.com/product/schema#advanced",
  target: {
    table: "Store",
    column: "Name"
  },
  logicalOperator: "Or",
  conditions: [
    {
      operator: "Contains",
      value: "Wash"
    },
    {
      operator: "Contains",
      value: "Park"
    }
  ],
  filterType: models.FilterType.AdvancedFilter
}

Anmerkung

Wenn Sie eine AdvancedFilter nur mit einer einzigen Bedingung erstellen, legen Sie die logicalOperator auf "And"fest. Der logische Operator wird ignoriert, wenn er von Power BI analysiert wird, da es nur eine Bedingung gibt, und wenn der Filter serialisiert wird, wird der logische Standardoperator "And". Dadurch wird sichergestellt, dass die beim Aufrufen von getFilterszurückgegebenen Filter mit den mit setFiltersfestgelegten übereinstimmen.

Top N-Filter

Top N-Filter verfügt über einen einzelnen Operator, einen Elementzähler für die Anzahl der anzuzeigenden Elemente und die Reihenfolge nach Ziel.

interface ITopNFilter extends IFilter {
    operator: TopNFilterOperators;
    itemCount: number;
    orderBy: ITarget;
}

  • operator – Der Operator für top N-Filter kann eine der folgenden Sein:

    type TopNFilterOperators = "Top" | "Bottom";

  • itemCount – Die Anzuzeigende Menge der Anzuzeigenden Elemente.

  • orderBy - Das Zieldatenfeld, nach dem sortiert werden soll. Weitere Informationen finden Sie unter Verwenden von Zielen, um auszuwählen, welches Datenfeld aufreagieren soll.

Zum Beispiel:

const topNFilter = {
  $schema: "https://powerbi.com/product/schema#topN",
  target: {
    table: "Store",
    column: "name"
  },
  operator: "Top",
  itemCount: 5,
  orderBy: {
      table: "Product",
      measure: "Count of Product"
   },
  filterType: models.FilterType.TopN
};

Relative Datums- und relative Zeitfilter

Der relative Datumsfilter und der relative Zeitfilter beide von der schnittstelle IRelativeDateTimeFilter erben:

interface IRelativeDateTimeFilter extends IFilter {
    operator: RelativeDateOperators;
    timeUnitsCount: number;
    timeUnitType: RelativeDateFilterTimeUnit;
}

  • operator – Der Operator für relative Datums- und Uhrzeitfilter kann eine der folgenden Sein:

    enum RelativeDateOperators {
    InLast = 0,
    InThis = 1,
    InNext = 2,
}

  • timeUnitsCount – Die Zeiteinheiten.

  • timeUnitType – Definiert die Zeiteinheit, die der Filter verwendet.

    enum RelativeDateFilterTimeUnit {
    Days = 0,
    Weeks = 1,
    CalendarWeeks = 2,
    Months = 3,
    CalendarMonths = 4,
    Years = 5,
    CalendarYears = 6,
    Minutes = 7,
    Hours = 8
}

    In der folgenden Tabelle sind die Einheitenzeiten aufgeführt, die von den relativen Datums- und relativen Zeitfiltern unterstützt werden.

    Zeiteinheit Relatives Datum Relative Zeit
    Tage ✔ ✖
    Wochen ✔ ✖
    Kalenderwochen ✔ ✖
    Monate ✔ ✖
    CalendarMonths ✔ ✖
    Jahre ✔ ✖
    CalendarYears ✔ ✖
    Protokoll ✖ ✔
    Stunden ✖ ✔

  • includeToday – Akzeptiert einen booleschen Wert, der angibt, ob der aktuelle Tag in den Filter eingeschlossen werden soll.

    interface IRelativeDateFilter extends IRelativeDateTimeFilter {
includeToday: boolean;
}

    Anmerkung

    includeToday wird nur vom relativen Datumsfilterunterstützt.

Beispiel für einen relativen Datumsfilter:

const relativeDateFilter = {
  $schema: "https://powerbi.com/product/schema#relativeDate",
  target: {
    table: "Sales",
    column: "OrderDate"
  },
  operator: models.RelativeDateOperators.InLast,
  timeUnitsCount: 30,
  timeUnitType: RelativeDateFilterTimeUnit.Days,
  includeToday: true,
  filterType: models.FilterType.RelativeDate
};

Beispiel für einen relativen Zeitfilter:

const relativeTimeFilter = {
  $schema: "https://powerbi.com/product/schema#relativeTime",
  target: {
    table: "Sales",
    column: "OrderDate"
  },
  operator: models.RelativeDateOperators.InLast,
  timeUnitsCount: 12,
  timeUnitType: models.RelativeDateFilterTimeUnit.Hours,
  filterType: models.FilterType.RelativeTime
};

Filter-APIs

Verwenden Sie die folgenden Methoden, um die auf einen Bericht angewendeten Filter abzurufen und zu aktualisieren:

Abrufen von Filtern

Verwenden Sie getFilters, um alle Filter für eines der folgenden Objekte abzurufen:

  • Bericht
  • Seite
  • Visuell
getFilters(): Promise<IFilter[]>

Aktualisieren von Filtern

Verwenden Sie updateFilters, um Filter für das Objekt (Bericht, Seite oder visuelle Elemente) hinzuzufügen, zu ersetzen oder zu entfernen. Empfängt einen Vorgang und ein optionales Filterarray.

updateFilters(operation: models.FiltersOperations, filters?: models.IFilter[]): Promise<IHttpPostMessageResponse<void>>

Filtervorgang

Beim Aufrufen von updateFilters müssen Sie den Filtervorgang übergeben, sie vorformieren möchten. Die verfügbaren Vorgänge sind:

  • RemoveAll – Entfernt alle Filter auf der Filterebene.
  • ReplaceAll – Ersetzt alle vorhandenen Filter auf der Filterebene durch die angegebenen Filter.
  • Add – Fügt die angegebenen Filter auf der Filterebene hinzu (zusätzlich zu den vorhandenen Filtern).
  • Replace – Ersetzt einen vorhandenen Filter nur dann durch einen bestimmten Filter, wenn beide Filter auf dasselbe Datenfeld angewendet werden. Wenn ein bestimmter Filter vorhanden ist, der keinen vorhandenen Filter ersetzt, wird er hinzugefügt.

Anmerkung

Beim Aufrufen der API mit RemoveAllmuss das Filterargument undefinedwerden. Für alle anderen Vorgänge muss sie definiert werden.

Filterebenen

Das Aktualisieren und Abrufen der Filter kann auf drei Ebenen erfolgen. Filter auf unterschiedlicher Ebene sind unabhängig, und das Aktualisieren von Filtern auf einer Ebene ändert sich nicht. Wenn Sie z. B. einen Seitenfilter entfernen, wird er nicht von anderen Seiten im Bericht entfernt.

Die unterstützten Ebenen für Filter sind:

  • Berichts- – Die Filter werden auf alle Seiten im Bericht angewendet.
  • Seite – Die Filter werden auf die aktuelle Berichtsseite angewendet.
  • Visual – Die Filter werden auf ein bestimmtes visuelles Element angewendet.

Anmerkung

Nur Filter auf visueller Ebene unterstützen den ITopNFilter Filtertyp.

Filter auf Berichtsebene

Rufen Sie die relevante API für das Berichtsobjekt auf, um die Filter abzurufen oder zu aktualisieren, die für alle Seiten im Bericht gelten. Zum Beispiel:

Abrufen der Berichtsfilter

Abrufen der Auf alle Seiten angewendeten Filter.

let reportFilters = await report.getFilters();

Hinzufügen neuer Filter zu berichtsfiltern

Hinzufügen neuer Filter neben den vorhandenen Filtern für alle Seiten.

await report.updateFilters(models.FiltersOperations.Add, filtersArray);

Entfernen der Berichtsfilter

Entfernen Sie die Auf alle Seiten angewendeten Filter.

await report.updateFilters(models.FiltersOperations.RemoveAll);

Filter auf Seitenebene

Gehen Sie wie folgt vor, um Filter auf Seitenebene abzurufen oder zu aktualisieren:

  1. Rufen Sie das Seitenobjekt für die Zielseite ab. Weitere Informationen finden Sie unter Abrufen von Seiten und visuellen Elementen.
  2. Rufen Sie im Seitenobjekt die relevante API auf.

Abrufen der Seitenfilter

Abrufen der auf eine bestimmte Seite angewendeten Filter.

let reportFilters = await page.getFilters();

Alle Seitenfilter ersetzen

Ersetzen aller vorhandenen Filter, die auf eine bestimmte Seite angewendet wurden, durch einen neuen Satz von Filtern.

await page.updateFilters(models.FiltersOperations.ReplaceAll, filtersArray);

Entfernen der Seitenfilter

Entfernen der auf eine bestimmte Seite angewendeten Filter.

await page.updateFilters(models.FiltersOperations.RemoveAll);

Filter auf visueller Ebene

Gehen Sie wie folgt vor, um Filter auf visueller Ebene abzurufen oder zu aktualisieren:

  1. Rufen Sie das visuelle Objekt für das visuelle Ziel ab. Weitere Informationen finden Sie unter Abrufen von Seiten und visuellen Elementen.
  2. Rufen Sie im visuellen Objekt die relevante API auf.

Abrufen der visuellen Filter

Abrufen der Filter, die auf ein bestimmtes visuelles Element angewendet werden.

let reportFilters = await visual.getFilters();

Ersetzen visueller Filter durch dasselbe Ziel

Ersetzen der Filter eines bestimmten visuellen Elements. Wenn ein Filter mit demselben Zieldatenfeld wie ein bestimmter Filter vorhanden ist, wird er durch den angegebenen Filter ersetzt. Bestimmte Filter, die keinem vorhandenen Filter entsprechen, werden hinzugefügt.

await visual.updateFilters(models.FiltersOperations.Replace, filtersArray);

Entfernen der visuellen Filter

Entfernen der Filter, die auf ein bestimmtes visuelles Element angewendet wurden.

await visual.updateFilters(models.FiltersOperations.RemoveAll);

Überlegungen und Einschränkungen

  • Wenn beim Erstellen eines erweiterten Filter mehr als zwei Bedingungen auftreten, kann dies zu einem nicht definierten Verhalten führen.

  • IncludeExclude- und Tuple-Filtertypen werden nicht unterstützt.

  • Tupel- und Hierarchiefilterziele werden nicht unterstützt.

Verwandte Inhalte