Controles de filtros de informe

Al insertar un informe de Power BI, puede aplicar filtros automáticamente durante la fase de carga, o puede cambiar los filtros dinámicamente después de cargar el informe. Por ejemplo, puede crear su propio panel de filtro personalizado y aplicar automáticamente esos filtros a los informes para mostrar la información específica del usuario. También puede crear un botón que permita al usuario aplicar filtros al informe insertado.

Se admiten los siguientes tipos de filtro:

• básico - IBasicFilter
• Advanced - IAdvancedFilter
• N principales - ITopNFilter
• fecha relativa - IRelativeDateFilter
• tiempo relativo - IRelativeTimeFilter

Atributos de objeto de filtro

Todos los tipos de filtro heredan la interfaz IFilter. Los atributos que se enumeran a continuación son pertinentes para todos los tipos de filtro.

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

Esquema

El atributo $schema define el tipo de filtro. Hay cinco esquemas disponibles, uno para cada tipo de filtro:

• básico - https://powerbi.com/product/schema#basic
• Advanced - https://powerbi.com/product/schema#advanced
• fecha relativa - https://powerbi.com/product/schema#relativeDate
• tiempo relativo - https://powerbi.com/product/schema#relativeTime
• N principales - https://powerbi.com/product/schema#topN

Configuración de visualización

El atributo displaySettings define la forma en que se muestra el filtro en el panel filtros.

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

• isLockedInViewMode: se aplica un filtro bloqueado y se muestra en el panel de filtros. No se puede cambiar el valor del filtro en modo de vista. Establézcalo en true para bloquear el filtro.

• isHiddenInViewMode: se aplica un filtro oculto al informe, pero no se muestra en el panel de filtro en modo de vista. Establézcalo en true para ocultar el filtro.

• displayName: se puede mostrar un filtro en el panel de filtros con un nombre personalizado. Use este atributo para establecer un nombre personalizado para el filtro. Cuando el valor es indefinido o null, se mostrará el nombre predeterminado del filtro (normalmente el nombre del campo de datos filtrado).

Tipo de filtro

El atributo filterType define el tipo del filtro. Use la enumeración siguiente, definida en la biblioteca de modelos:

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

Blanco

El atributo target define el destino del filtro. Para obtener más información, consulte Usar destinos para seleccionar el campo de datos que se va a actuar en.

Atributos adicionales por tipo de filtro

Cada tipo de filtro tiene su propia interfaz con un conjunto diferente de atributos. Las interfaces de filtro forman parte de la biblioteca powerbi-models.

Filtro básico

filtro Básico tiene un único operador con uno o varios valores.

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

• operator: para el filtro básico, el operador puede ser uno de los siguientes:

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

• values: matriz de valores para el filtro, todos los valores deben ser del mismo tipo.

• requireSingleSelection: define si es posible seleccionar varios valores en el filtro. Si se establece en true, solo se puede seleccionar un solo valor.

Por ejemplo:

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
}

Filtro avanzado

filtro avanzado tiene un único operador lógico y una o dos condiciones que tienen su propio operador y valor.

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

• logicalOperator: el operador lógico puede ser uno de los siguientes:

  type AdvancedFilterLogicalOperators = "And" | "Or";
  

• conditions: matriz de condiciones para el filtro avanzado, cada condición tiene un operator y un value.

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

  Los operadores disponibles para una condición son:

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

Por ejemplo:

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
}

Nota

Si va a crear un AdvancedFilter con una sola condición, establezca el logicalOperator en "And". Power BI omite el operador lógico al analizarlo porque solo hay una condición y, cuando el filtro se serializa, el operador lógico predeterminado es "And". Esto garantiza que los filtros devueltos al llamar a getFilters, coincidan con los establecidos mediante setFilters.

Filtro N superior

filtro N superior tiene un único operador, contador de elementos para la cantidad de elementos que se van a mostrar y ordenar por destino.

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

• operator: el operador del filtro Top N puede ser uno de los siguientes:

  type TopNFilterOperators = "Top" | "Bottom";
  

• itemCount: cantidad de elementos que se van a mostrar.

• orderBy: campo de datos de destino por el que se va a ordenar. Para obtener más información, consulte Usar destinos para seleccionar el campo de datos que se va a actuar en.

Por ejemplo:

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

Filtros de fecha relativa y hora relativa

El filtro de fecha relativa y el filtro de tiempo relativo heredan de la interfaz de IRelativeDateTimeFilter:

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

• operator: el operador para los filtros de fecha y hora relativos puede ser uno de los siguientes:

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

• timeUnitsCount: la cantidad de unidades de tiempo.

• timeUnitType: define la unidad de tiempo que usa el filtro.

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

  En la tabla siguiente se enumeran las horas de unidad admitidas por los filtros de fecha relativa y hora relativa.

  Unidad de tiempo	Fecha relativa	Hora relativa
  Días	✔	✖
  Semanas	✔	✖
  CalendarWeeks	✔	✖
  Meses	✔	✖
  CalendarMonths	✔	✖
  Años	✔	✖
  CalendarYears	✔	✖
  Acta	✖	✔
  Horas	✖	✔

• includeToday: acepta un valor booleano que especifica si se debe incluir el día actual en el filtro.

  interface IRelativeDateFilter extends IRelativeDateTimeFilter {
  includeToday: boolean;
  }
  

  Nota

  includeToday solo es compatible con el filtro de fecha relativa .

Ejemplo de filtro de fecha relativa:

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

Ejemplo de filtro de tiempo relativo:

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

API de filtros

Use los métodos siguientes para obtener y actualizar los filtros aplicados a un informe:

• Obtener filtros - getFilters
• Actualizar filtros- updateFilters.

Obtener filtros

Use getFilters para obtener todos los filtros de uno de los objetos siguientes:

• Informe
• Página
• Visual

getFilters(): Promise<IFilter[]>

Actualizar filtros

Use updateFilters para agregar, reemplazar o quitar filtros en el objeto (informe, página o objeto visual). Recibe una operación y una matriz de filtros opcionales.

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

Operación de filtros

Al llamar a updateFilters debe pasar la operación de filtro de desea preformular. Las operaciones disponibles son:

• RemoveAll: quita todos los filtros en el nivel de filtro.
• ReplaceAll: reemplaza todos los filtros existentes en el nivel de filtro por los filtros especificados.
• Add: agrega los filtros especificados en el nivel de filtro (además de los filtros existentes).
• Replace: reemplaza un filtro existente por un filtro determinado solo si ambos filtros se aplican al mismo campo de datos. Si hay un filtro determinado que no reemplaza un filtro existente, se agregará.

Nota

Al llamar a la API con RemoveAll, el argumento filters debe ser undefined. Para cualquier otra operación, debe definirse.

Niveles de filtros

La actualización y obtención de los filtros se puede realizar en tres niveles. Los filtros en un nivel diferente son independientes y la actualización de filtros en un nivel no cambiará otro. Por ejemplo, quitar un filtro de página, no lo quita de otras páginas del informe.

Los niveles admitidos para los filtros son:

• informe: los filtros se aplican a todas las páginas del informe.
• Página: los filtros se aplican a la página del informe actual.
• Visual: los filtros se aplican a un objeto visual específico.

Nota

Solo los filtros de nivel visual admiten el tipo de filtro ITopNFilter.

Filtros de nivel de informe

Para obtener o actualizar los filtros que se aplican a todas las páginas del informe, llame a la API pertinente en el objeto de informe. Por ejemplo:

Obtención de los filtros de informe

Obtener los filtros aplicados a todas las páginas.

let reportFilters = await report.getFilters();

Adición de nuevos filtros a los filtros de informe

Agregar nuevos filtros, junto con los filtros existentes, para todas las páginas.

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

Quitar los filtros de informe

Quite los filtros aplicados a todas las páginas.

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

Filtros de nivel de página

Para obtener o actualizar filtros de nivel de página, haga lo siguiente:

1. Obtiene el objeto de página de la página de destino. Para obtener más información, vea Obtener páginas y objetos visuales.
2. En el objeto de página, llame a la API correspondiente.

Obtener los filtros de página

Obtener los filtros aplicados a una página específica.

let reportFilters = await page.getFilters();

Reemplazar todos los filtros de página

Reemplazar todos los filtros existentes aplicados a una página específica, con un nuevo conjunto de filtros.

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

Quitar los filtros de página

Quitar los filtros aplicados a una página específica.

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

Filtros de nivel visual

Para obtener o actualizar filtros de nivel visual, haga lo siguiente:

1. Obtenga el objeto visual del objeto visual de destino. Para obtener más información, vea Obtener páginas y objetos visuales.
2. En el objeto visual, llame a la API correspondiente.

Obtención de los filtros visuales

Obtener los filtros aplicados a un objeto visual específico.

let reportFilters = await visual.getFilters();

Reemplazar filtros visuales por el mismo destino

Reemplazar los filtros de un objeto visual específico. Si existe un filtro con el mismo campo de datos de destino que un filtro determinado, se reemplaza por el filtro especificado. Se agregan filtros dados que no coinciden con ningún filtro existente.

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

Quitar los filtros visuales

Quitar los filtros aplicados a un objeto visual específico.

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

Consideraciones y limitaciones

• Tener más de dos condiciones al crear una filtro avanzado puede provocar un comportamiento indefinido.

• no se admiten los tipos de filtro IncludeExclude y Tuple.

• No se admiten destinos de filtro de tupla y jerarquía.

Contenido relacionado

• Configuración de las opciones de informe
• segmentaciones de informes de control
• Personalizar un diseño de informe