Kontrolowanie filtrów raportów

Podczas osadzania raportu usługi Power BI można stosować filtry automatycznie podczas fazy ładowania lub dynamicznie zmieniać filtry po załadowaniu raportu. Możesz na przykład utworzyć własne niestandardowe okienko filtru i automatycznie zastosować te filtry do raportów, aby wyświetlić szczegółowe informacje użytkownika. Możesz również utworzyć przycisk, który umożliwia użytkownikowi stosowanie filtrów do raportu osadzonego.

Obsługiwane są następujące typy filtrów:

• Basic - IBasicFilter
• Advanced - IAdvancedFilter
• pierwszych N - ITopNFilter
• data względna - IRelativeDateFilter
• - IRelativeTimeFilter czasu względnego

Atrybuty obiektu filtru

Wszystkie typy filtrów dziedziczą interfejs IFilter. Atrybuty wymienione poniżej są istotne dla wszystkich typów filtrów.

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

Schemat

Atrybut $schema definiuje typ filtru. Dostępnych jest pięć schematów, po jednym dla każdego typu filtru:

• Basic - https://powerbi.com/product/schema#basic
• Advanced - https://powerbi.com/product/schema#advanced
• data względna - https://powerbi.com/product/schema#relativeDate
• - https://powerbi.com/product/schema#relativeTime czasu względnego
• pierwszych N - https://powerbi.com/product/schema#topN

Ustawienia wyświetlania

Atrybut displaySettings definiuje sposób wyświetlania filtru w okienku filtrów.

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

• isLockedInViewMode — zablokowany filtr jest stosowany i wyświetlany w okienku filtru. Nie można zmienić wartości filtru w trybie widoku . Ustaw go na wartość true, aby zablokować filtr.

• isHiddenInViewMode — ukryty filtr jest stosowany do raportu, ale nie jest wyświetlany w okienku filtru w trybie widoku . Ustaw go na wartość true, aby ukryć filtr.

• displayName — filtr można wyświetlić w okienku filtru z spersonalizowaną nazwą. Użyj tego atrybutu, aby ustawić spersonalizowaną nazwę filtru. Gdy wartość jest niezdefiniowana lub ma wartość null, zostanie wyświetlona domyślna nazwa filtru (zazwyczaj nazwa filtrowanego pola danych).

Typ filtru

Atrybut filterType definiuje typ filtru. Użyj następującego wyliczenia zdefiniowanego w bibliotece modeli:

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

Cel

Atrybut target definiuje element docelowy filtru. Aby uzyskać więcej informacji, zobacz Use targets to select which data field to select which data to act on.

Dodatkowe atrybuty według typu filtru

Każdy typ filtru ma własny interfejs z innym zestawem atrybutów. Interfejsy filtrów są częścią biblioteki powerbi-models.

Filtr podstawowy

filtru podstawowego ma jeden operator z co najmniej jedną wartością.

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

• operator — w przypadku podstawowego filtru operator może być jednym z następujących elementów:

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

• values — tablica wartości filtru, wszystkie wartości muszą być tego samego typu.

• requireSingleSelection — określa, czy można wybrać wiele wartości w filtrze. Jeśli ustawiono wartość true, można wybrać tylko jedną wartość.

Na przykład:

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
}

Filtr zaawansowany

filtr zaawansowany ma jeden operator logiczny i jeden lub dwa warunki, które mają własny operator i wartość.

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

• logicalOperator — operator logiczny może być jednym z następujących elementów:

  type AdvancedFilterLogicalOperators = "And" | "Or";
  

• conditions — tablica warunków filtru zaawansowanego, każdy warunek ma operator i value.

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

  Dostępne operatory warunku to:

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

Na przykład:

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
}

Nuta

Jeśli tworzysz AdvancedFilter tylko z jednym warunkiem, ustaw logicalOperator na "And". Operator logiczny jest ignorowany podczas analizowania przez usługę Power BI, ponieważ istnieje tylko jeden warunek, a gdy filtr jest serializowany, domyślny operator logiczny jest "And". Dzięki temu filtry zwracane podczas wywoływania getFilterssą zgodne z tymi ustawionymi przy użyciu setFilters.

Filtr pierwszych N

filtru Top N ma jeden operator, licznik elementów dla ilości elementów do wyświetlenia i kolejność według celu.

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

• operator — operator filtru Top N może być jednym z następujących elementów:

  type TopNFilterOperators = "Top" | "Bottom";
  

• itemCount — ilość elementów do wyświetlenia.

• orderBy — docelowe pole danych do sortowania według. Aby uzyskać więcej informacji, zobacz Use targets to select which data field to select which data to act on.

Na przykład:

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
};

Filtry daty względnej i czasu względnego

Filtr daty względnej i filtr czasu względnego dziedziczą z interfejsu IRelativeDateTimeFilter:

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

• operator — operator filtrów daty i godziny względnej może być jednym z następujących elementów:

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

• timeUnitsCount — ilość jednostek czasu.

• timeUnitType — definiuje jednostkę czasu używania filtru.

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

  W poniższej tabeli wymieniono czasy jednostek obsługiwane przez filtry daty względnej i czasu względnego.

  Jednostka czasu	Data względna	Czas względny
  Dni	✔	✖
  Tygodni	✔	✖
  CalendarWeeks	✔	✖
  Miesiące	✔	✖
  Miesiąc kalendarzowy	✔	✖
  Lata	✔	✖
  Rok kalendarzowy	✔	✖
  Protokół	✖	✔
  Godzin	✖	✔

• includeToday — akceptuje wartość logiczną określającą, czy uwzględnić bieżący dzień w filtrze.

  interface IRelativeDateFilter extends IRelativeDateTimeFilter {
  includeToday: boolean;
  }
  

  Nuta

  includeToday jest obsługiwana tylko przez filtr dat względnych .

Przykład filtru dat względnych:

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
};

Przykład filtru czasu względnego:

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
};

Interfejsy API filtrów

Użyj następujących metod, aby pobrać i zaktualizować filtry zastosowane do raportu:

• Pobieranie filtrów - getFilters
• Filtry aktualizacji- updateFilters.

Pobieranie filtrów

Użyj getFilters, aby pobrać wszystkie filtry dla jednego z następujących obiektów:

• Sprawozdanie
• Strona
• Wizualny

getFilters(): Promise<IFilter[]>

Aktualizowanie filtrów

Użyj updateFilters do dodawania, zastępowania lub usuwania filtrów w obiekcie (raport, strona lub wizualizacja). Odbiera operację i opcjonalną tablicę filtrów.

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

Operacja filtrowania

Podczas wywoływania updateFilters należy przekazać operację filtrowania , którą chcesz wstępnie utworzyć. Dostępne operacje to:

• RemoveAll — usuwa wszystkie filtry na poziomie filtru.
• ReplaceAll — zastępuje wszystkie istniejące filtry na poziomie filtru podanymi filtrami.
• Add — dodaje podane filtry na poziomie filtru (oprócz istniejących filtrów).
• Replace — zastępuje istniejący filtr danym filtrem tylko wtedy, gdy oba filtry mają zastosowanie do tego samego pola danych. Jeśli istnieje dany filtr, który nie zastępuje istniejącego filtru, zostanie dodany.

Nuta

Podczas wywoływania interfejsu API za pomocą RemoveAllargument filtrów musi być undefined. W przypadku innych operacji należy go zdefiniować.

Poziomy filtrów

Aktualizowanie i pobieranie filtrów można wykonywać na trzech poziomach. Filtry na różnych poziomach są niezależne, a aktualizowanie filtrów na jednym poziomie nie spowoduje zmiany innego. Na przykład usunięcie filtru strony nie powoduje usunięcia go z innych stron w raporcie.

Obsługiwane poziomy filtrów to:

• raport — filtry są stosowane do wszystkich stron w raporcie.
• strona — filtry są stosowane do bieżącej strony raportu.
• Visual — filtry są stosowane do określonej wizualizacji.

Nuta

Tylko filtry na poziomie wizualizacji obsługują typ filtru ITopNFilter.

Filtry na poziomie raportu

Aby uzyskać lub zaktualizować filtry, które mają zastosowanie do wszystkich stron w raporcie, wywołaj odpowiedni interfejs API w obiekcie raportu. Na przykład:

Pobieranie filtrów raportu

Pobieranie filtrów zastosowanych do wszystkich stron.

let reportFilters = await report.getFilters();

Dodawanie nowych filtrów do filtrów raportu

Dodawanie nowych filtrów obok istniejących filtrów dla wszystkich stron.

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

Usuwanie filtrów raportu

Usuń filtry zastosowane do wszystkich stron.

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

Filtry na poziomie strony

Aby uzyskać lub zaktualizować filtry na poziomie strony, wykonaj następujące czynności:

1. Pobierz obiekt strony dla strony docelowej. Aby uzyskać więcej informacji, zobacz Pobieranie stron i wizualizacji.
2. W obiekcie strony wywołaj odpowiedni interfejs API.

Pobieranie filtrów strony

Pobieranie filtrów zastosowanych do określonej strony.

let reportFilters = await page.getFilters();

Zamień wszystkie filtry stron

Zastąpienie wszystkich istniejących filtrów zastosowanych do określonej strony nowym zestawem filtrów.

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

Usuwanie filtrów strony

Usuwanie filtrów zastosowanych do określonej strony.

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

Filtry na poziomie wizualizacji

Aby uzyskać lub zaktualizować filtry na poziomie wizualizacji, wykonaj następujące czynności:

1. Pobierz obiekt wizualizacji dla wizualizacji docelowej. Aby uzyskać więcej informacji, zobacz Pobieranie stron i wizualizacji.
2. W obiekcie wizualizacji wywołaj odpowiedni interfejs API.

Pobieranie filtrów wizualizacji

Pobieranie filtrów zastosowanych do określonej wizualizacji.

let reportFilters = await visual.getFilters();

Zastępowanie filtrów wizualizacji tym samym elementem docelowym

Zamienianie filtrów określonej wizualizacji. Jeśli filtr istnieje z tym samym polem danych docelowych co dany filtr, zostanie zastąpiony przez dany filtr. Podane filtry, które nie pasują do żadnego istniejącego filtru, są dodawane.

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

Usuwanie filtrów wizualizacji

Usuwanie filtrów zastosowanych do określonej wizualizacji.

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

Zagadnienia i ograniczenia

• Posiadanie więcej niż dwóch warunków podczas tworzenia filtru zaawansowanego może spowodować niezdefiniowane zachowanie.

• typy filtrów IncludeExclude i Tuple nie są obsługiwane.

• Obiekty docelowe filtru krotki i hierarchii nie są obsługiwane.

Powiązana zawartość

• Konfigurowanie ustawień raportu
• fragmentatory raportów kontroli
• personalizowanie układu raportu