Adición de compatibilidad con marcadores a objetos visuales en informes de Power BI
Con los marcadores de informes de Power BI, puede capturar y guardar una vista configurada de una página del informe. Luego, puede volver a la vista guardada de manera rápida y sencilla siempre que quiera. El marcador guarda toda la configuración, incluidos las selecciones y los filtros.
Para obtener más información sobre los marcadores, consulte Uso de marcadores para compartir información detallada y crear historias en Power BI.
Objetos visuales que admiten marcadores
Un objeto visual de Power BI que admite marcadores debe ser capaz de guardar y proporcionar la información correcta cuando sea necesario. Si el objeto visual interactúa con otros objetos visuales, selecciona puntos de datos o filtra otros objetos visuales, tendrá que guardar el estado marcado en las propiedades filterState del objeto visual.
Nota
Para crear un objeto visual que admita marcadores, se necesita lo siguiente:
- Powerbi-visuals-utils-interactivityutils, versión 3.0.0 o posterior, para filtrar los objetos visuales y cualquier objeto visual que use
InteractivityService. - Visual API 1.11.0 o posterior para objetos visuales sin filtro que usen
SelectionManageren lugar deInteractivityService. - Para averiguar qué versión usa, compruebe
apiVersionen el archivo pbiviz.json.
Interacción de los objetos visuales de Power BI con Power BI en los marcadores de un informe
Imagine que quiere crear varios marcadores en la página de un informe, cada uno con diferentes puntos de datos seleccionados.
En primer lugar, seleccione uno o varios puntos de datos en el objeto visual. El objeto visual pasará las selecciones al host. A continuación, seleccione Agregar en el panel Marcador. Power BI guarda las opciones seleccionadas para el nuevo marcador.
Haga esto varias veces para crear nuevos marcadores. Después de crear los marcadores, puede cambiar entre ellos.
Cada vez que selecciona un marcador, Power BI restaura el estado de selección o filtro guardado y lo pasa a los objetos visuales. Los objetos visuales del informe se resaltan o filtran según el estado almacenado en el marcador. Para restaurar el estado correcto, el objeto visual debe pasar el estado de selección correcto al host (por ejemplo, los colores de los puntos de datos representados).
El nuevo estado de selección (o filtro) se comunica mediante la propiedad options.jsonFilters del método update. jsonFilters puede ser Advanced Filter o Tuple Filter.
- Si el objeto visual contiene puntos de datos seleccionados, restablezca la selección a la del marcador seleccionado mediante la función de devolución de llamada
registerOnSelectCallback, enISelectionManager. - Si el objeto visual usa filtros para seleccionar datos, restablezca los valores de filtro a los valores correspondientes del marcador seleccionado.
Objetos visuales con selecciones
Si el objeto visual interactúa con otros objetos visuales mediante Selection, puede agregar la compatibilidad con el marcador de una de estas dos maneras:
- Mediante InteractivityService, para administrar selecciones, use
applySelectionFromFilter. Este es el método más sencillo y el recomendado. - Mediante SelectionManager, si el objeto visual no usa InteractivityService.
Uso de InteractivityService para restaurar las selecciones de marcadores
Si el objeto visual usa InteractivityService, no necesita ninguna otra acción para admitir los marcadores del objeto visual.
Al seleccionar un marcador, la utilidad controla de forma automática el estado de selección del objeto visual.
Uso de SelectionManager para restaurar las selecciones de marcadores
Si no usa InteractivityService, puede guardar y recuperar las selecciones de marcadores con el método ISelectionManager.registerOnSelectCallback, como se muestra a continuación:
Al seleccionar un marcador, Power BI llama al método callback del objeto visual con las selecciones correspondientes.
this.selectionManager.registerOnSelectCallback(
(ids: ISelectionId[]) => {
//called when a selection was set by Power BI
});
);
Imagine que ha creado un punto de datos en el método visualTransform del objeto visual.
El aspecto de datapoints es similar al siguiente:
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
});
Ahora tiene visualDataPoints como puntos de datos y la matriz ids que ha pasado a la función callback.
En este punto, el objeto visual debe comparar la matriz de ISelectionId[] con la selección de la matriz de visualDataPoints y marcar como seleccionados los puntos de datos que correspondan.
this.selectionManager.registerOnSelectCallback(
(ids: ISelectionId[]) => {
visualDataPoints.forEach(dataPoint => {
ids.forEach(bookmarkSelection => {
if (bookmarkSelection.equals(dataPoint.selectionId)) {
dataPoint.selected = true;
}
});
});
});
);
Tras actualizar los puntos de datos, reflejarán el estado de selección actual almacenado en el objeto filter. Luego, cuando se representen los puntos de datos, el estado de selección del objeto visual personalizado coincidirá con el del marcador.
Objetos visuales con un filtro
Para admitir marcadores en los objetos visuales que tienen un filtro, use InteractivityService.
Supongamos que el objeto visual crea un filtro de datos por intervalo de fechas. Tiene startDate y endDate como las fechas de inicio y finalización del intervalo.
El objeto visual crea un filtro avanzado y llama al método de host applyJsonFilter para filtrar los datos según las condiciones pertinentes.
El destino es la tabla que se usa para filtrar.
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
);
Cada vez que selecciona un marcador, el objeto visual personalizado recibe una llamada de update.
En el método update, el objeto visual comprueba el filtro en el objeto:
const filter: IAdvancedFilter = FilterManager.restoreFilter(
&& options.jsonFilters
&& options.jsonFilters[0] as any
) as IAdvancedFilter;
Si el objeto filter no es NULL, el objeto visual restaura las condiciones de filtro del objeto:
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
}
Después, el objeto visual cambia su estado interno para reflejar las condiciones actuales. El estado interno incluye los puntos de datos y los objetos de visualización (líneas, rectángulos, etc.).
Importante
En el escenario anterior de los marcadores de informe, el objeto visual no tiene que llamar a applyJsonFilter para filtrar los demás objetos visuales. Power BI se encargará de filtrarlos.
El objeto visual Timeline Slicer cambia el selector de intervalo a los intervalos de datos correspondientes.
Guardado del estado de filtro del objeto visual
Además de guardar las condiciones del filtro para el marcador, también puede guardar otros aspectos del filtro.
Por ejemplo, Timeline Slicer almacena los valores de la propiedad Granularity como un estado de filtro. Permite que la granularidad de la escala de tiempo (días, meses, años, etc.) cambie a medida que se cambian los marcadores.
La propiedad filterState guarda un aspecto de filtro como una propiedad. El objeto visual puede almacenar distintos valores filterState en marcadores.
Para guardar el valor de una propiedad como un estado de filtro, establezca la propiedad del objeto como "filterState": true en el archivo capabilities.json.