Compartir a través de

Mejora de la experiencia de los usuarios con marcadores

  • Artículo

Los marcadores de informe de Power BI permiten capturar el estado actual de una página de informe incrustada, incluidos todos los filtros y el estado de sus objetos visuales. Al abrir el informe más adelante, puede seleccionar un marcador para restaurar el informe al estado guardado. Los desarrolladores pueden controlar la experiencia del usuario mediante las API de cliente de Power BI para capturar y aplicar marcadores.

Un marcador guardado puede ser un marcador que se guardó como parte de un informe o un marcador que se capturó como un estado en tiempo real de un informe. Si aplica un marcador guardado al cargar un informe, puede especificar el marcador que se usará proporcionando el nombre del marcador o su estado. Si proporciona un marcador por nombre, el informe debe contener un marcador guardado con ese mismo nombre.

En este artículo se explican las distintas configuraciones de API que deberá insertar informes que admitan marcadores.

Nota

En los informes que insertó para la organización, los consumidores de informes crean marcadores personales capturando el estado del informe y volviendo rápidamente a ese estado seleccionando el marcador. Consulte marcadores personales para obtener más información.

Para obtener información sobre cómo crear una experiencia similar en los informes que insertó para los clientes, consulte el visualización de la vista de informes de captura en el área de juegos de análisis insertados de Power BI.

Para obtener más información sobre el uso de marcadores en Power BI, consulte Creación de marcadores en Power BI Desktop.

Para obtener información sobre el uso de marcadores personales al insertar Power BI, consulte Marcadores personales.

Uso de marcadores de informe

En las secciones siguientes se muestra cómo usar las API de cliente de Power BI para trabajar con marcadores de informe.

Administrar los marcadores de un informe

Para administrar los marcadores de un informe, use la propiedad bookmarksManager de una instancia de informe insertada .

La clase BookmarksManager tiene los métodos siguientes:

  • getBookmarks: devuelve una lista de marcadores guardados asociados al informe.

  • apply: se aplica por nombre a un marcador guardado anteriormente en el informe.

  • capture: captura y devuelve una cadena de serialización base64, que representa el estado actual del informe.

  • applyState Aplica un estado de serialización base64 capturado previamente de un marcador al informe.

  • play: controla el modo de presentación con diapositivas para los marcadores del informe.

Acceso a un marcador de informe

Para acceder a un marcador individual, use el método getBookmarks para acceder a una lista de objetos ReportBookmark. La clase ReportBookmark tiene las siguientes propiedades:

  • name: identificador único del marcador del informe.

  • displayName: el nombre para mostrar del marcador del informe, que aparece en el panel de Marcadores.

  • state: serialización base64 del estado del marcador de informe. Puede guardarlo y aplicarlo a un informe con el método bookmarksManager.applyState.

  • children: lista de objetos ReportBookmark que representan un grupo de marcadores de informe, si existe.

Uso de las API de marcadores de informe

En un informe insertado, los desarrolladores pueden:

Obtener una lista de marcadores de informe guardados

Para obtener la lista de marcadores guardados asociados a un informe, llame al método getBookmarks del objeto BookmarksManager devuelto por la propiedad bookmarksManager del informe.

El método getBookmarks se define de la siguiente manera:

getBookmarks(): Promise<models.IReportBookmark[]>

Por ejemplo:

let bookmarks = await report.bookmarksManager.getBookmarks();

Aplicar un marcador guardado por nombre en la carga del informe o durante una sesión

Para aplicar un marcador guardado previamente a un informe mediante su nombre de marcador, llame al método apply del objeto BookmarksManager devuelto por la propiedad bookmarksManager de un informe.

Para obtener más información, consulte Configuración de las opciones de informe.

El método apply se define de la siguiente manera:

apply(bookmarkName: string): Promise<void>

Por ejemplo:

await report.bookmarksManager.apply("Bookmark1234");

Capturar y obtener una vista actual como un objeto de marcador

Para capturar el estado actual de un informe como una cadena base64, llame al método capture de un objeto BookmarksManager. El método capture devuelve un objeto IReportBookmark, que representa un marcador que no se guarda en un informe específico. Use la propiedad IReportBookmark.state para devolver la cadena base64 que identifica el estado del marcador, que se puede aplicar posteriormente a un informe durante el tiempo de carga o el tiempo de ejecución.

El método capture se define de la siguiente manera:

capture(options?:ICaptureBookmarkOptions): Promise<models.IReportBookmark>

Por ejemplo:

let capturedBookmark = await report.bookmarksManager.capture();

Opciones de marcadores de captura

También puede pasar un objeto ICaptureBookmarkOptions al método capture.

interface ICaptureBookmarkOptions {
    allPages?: boolean;
    personalizeVisuals?: boolean;
}
  • allPages: de forma predeterminada, el estado del marcador capturado solo guardará el estado de página actual. Para capturar el estado de todas las páginas, llame al método capture con allPages opción establecida en true.
  • personalizeVisuals: para capturar el estado actual con objetos visuales personalizados, llame al método capture con la opción personalizeVisuals establecida en true.

Por ejemplo, el código siguiente captura el estado de todas las páginas, incluidos los objetos visuales personalizados:

let capturedBookmark = await report.bookmarksManager.capture({
    allPages: true,
    personalizeVisuals: true
});

Aplicación de un estado de marcador capturado en la carga del informe o durante una sesión

Para aplicar un estado de marcador capturado previamente a un informe, use el método applyState de un objeto BookmarksManager.

Para obtener más información, consulte Configuración de las opciones de informe.

El método applyState se define de la siguiente manera:

applyState(state: string): Promise<void>

Por ejemplo:

await report.bookmarksManager.applyState(capturedBookmark.state);

Realizar lógica adicional cuando se aplica un marcador de informe

Para determinar cuándo se ha aplicado un marcador de informe, escuche el evento bookmarkApplied llamando al método on del objeto informe.

Por ejemplo:

report.on("bookmarkApplied", (event) => {
    console.log(event.detail.name);
});

Mostrar u ocultar el panel Marcadores

Para mostrar u ocultar el panel Marcadores de Power BI , actualice la propiedad panes de la configuración del informe.

Mostrar el panel Marcadores

let embedConfig = {
    ...
    panes: {
        bookmarks: {
            visible: true
        }
    }
};

Ocultar el panel Marcadores

let embedConfig = {
    ...
    panes: {
        bookmarks: {
            visible: false
        }
    }
};

Para obtener información sobre cómo actualizar la configuración del informe, consulte Configurar las opciones de informe.

Modo de presentación con diapositivas de marcadores de entrada o salida

Para controlar el modo de presentación de presentación con diapositivas para los marcadores de un informe, llame al método play de un objeto BookmarksManager. Para obtener más información, vea Marcadores como presentación con diapositivas.

El método play se define de la siguiente manera:

play(playMode: models.BookmarksPlayMode): Promise<void>

Nota

Antes de escribir el modo de presentación con diapositivas de marcadores, asegúrese de que haya al menos un marcador en el informe con API getBookmarks.

Escribir el modo de presentación de presentación con diapositivas

await report.bookmarksManager.play(models.BookmarksPlayMode.Presentation);

Salir del modo de presentación con diapositivas

await report.bookmarksManager.play(models.BookmarksPlayMode.Off);

Consideraciones y limitaciones

  • Cuando se usa la API de marcadores, determinados cambios en el informe pueden provocar un error o un resultado inesperado. Un ejemplo de esto es quitar filtros de informe del informe. Para evitar errores, las tarjetas de filtro correspondientes deben estar presentes. En lugar de quitar los filtros, establezca sus valores en All. Si no sabe qué filtros se eliminaron o cambiaron, vuelva a capturar el marcador después de aplicar los cambios en el informe.

  • Los filtros como en los filtros de carga creados por la sesión de inserción o agregados por los filtros de actualización de agregan, se capturan en el estado del marcador, pero solo se aplicarán en la sesión actual. Para superar esta limitación, el filtro debe guardarse en el informe con el valor de All y modificarse en la sesión de inserción mediante la operación de actualización de filtros de actualización de .

Contenido relacionado