Compartir a través de

Configuración de las opciones del informe

  • Artículo

Con las API de cliente de Power BI, puede insertar análisis de Power BI en la aplicación. Cuando se usa esta biblioteca del lado cliente para insertar un informe de Power BI, se proporciona a la API información sobre ese informe.

Puede usar un objeto de configuración para almacenar información sobre el informe de Power BI. Al insertar el informe, se pasa ese objeto a la API.

Además de proporcionar a la API acceso al informe, también puede usar el objeto de configuración para personalizar la apariencia y el comportamiento del informe. Por ejemplo, puede ajustar la visibilidad del filtro, el acceso de navegación y la configuración de ubicación en el objeto de configuración.

En las secciones siguientes se explica cómo insertar y configurar contenido de Power BI.

Proporcionar información de configuración

La interfaz IReportLoadConfiguration muestra las propiedades que un objeto de configuración puede proporcionar a las API de cliente de Power BI sobre un informe:

interface IReportLoadConfiguration {
    embedUrl: string;
    accessToken: string;
    id: string;
    groupId?: string;
    settings?: ISettings;
    bookmark?: IApplyBookmarkRequest;
    pageName?: string;
    filters?: ReportLevelFilters[];
    slicers?: ISlicer[];
    theme?: IReportTheme;
    contrastMode?: ContrastMode;
    datasetBinding?: IDatasetBinding;
    permissions?: Permissions;
    viewMode?: ViewMode;
    tokenType?: TokenType;
}

Consulte Insertar un informe para obtener una explicación de los parámetros necesarios de esta interfaz y para ver ejemplos de código que muestran cómo insertar un informe.

Personalizar la configuración

En las secciones siguientes se describe cómo puede usar la propiedad settings para ajustar la apariencia y el comportamiento del informe de Power BI insertado. Para actualizar la configuración del informe cuando el informe ya esté cargado, use el método report.updateSettings. Para obtener más información, consulte Actualizar la configuración del informe en tiempo de ejecución.

Paneles

Controle la apariencia de todos los paneles del informe de Power BI con una sola propiedad panes, como se muestra en el código siguiente:

let embedConfig = {
    ...
    settings: {
        panes: {
            bookmarks: {
                visible: true
            },
            fields: {
                expanded: false
            },
            filters: {
                expanded: false,
                visible: true
            },
            pageNavigation: {
                visible: false
            },
            selection: {
                visible: true
            },
            syncSlicers: {
                visible: true
            },
            visualizations: {
                expanded: false
            }
        }
    }
};

En la tabla siguiente, puede ver qué valores admite cada propiedad panes:

Propiedad Visible Ampliado
bookmarks ✔ ❌
fields ✔ ✔
filters ✔ ✔
pageNavigation ✔ ❌
selection ✔ ❌
syncSlicers ✔ ❌
visualizations ✔ ✔

Panel filtro

De forma predeterminada, el panel de filtro está visible. Si desea ocultar este panel, use la propiedad filterPaneEnabled, como se muestra en el código siguiente:

let embedConfig = {
    ...
    settings: {
        filterPaneEnabled: false
    }
};

Nota

La propiedad paneles reemplaza la propiedad filterPaneEnabled. Para mantener la compatibilidad con versiones anteriores, la propiedad filterPaneEnabled sigue existiendo. Sin embargo, debe evitar usar estas dos propiedades juntas.

Panel de navegación de página

De forma predeterminada, las flechas de navegación de página están visibles en los informes incrustados. Para ocultar estas flechas, use la propiedad navContentPaneEnabled, como se muestra en el código siguiente:

let embedConfig = {
    ...
    settings: {
        navContentPaneEnabled: false
    }
};

Nota

La propiedad paneles reemplaza la propiedad navContentPaneEnabled. Para mantener la compatibilidad con versiones anteriores, la propiedad navContentPaneEnabled sigue existiendo. Sin embargo, debe evitar usar estas dos propiedades juntas.

El panel de navegación de página aparece en la parte inferior del informe, para usar el nuevo panel de páginas verticales, puede establecer la propiedad position:

let embedConfig = {
    ...
    settings: {
        panes:{
            pageNavigation: {
                visible: true,
                position: PagesPosition.Left
            }
        }    
    }
};

Nota

No se puede cambiar la posición del panel de navegación de página mediante updateSettings.

Bares

Establezca la visibilidad de la barra de acciones y la barra de estado mediante la propiedad bars.

Barra de acciones

El código siguiente hace que la barra de acciones sea visible:

let embedConfig = {
    ...
    settings: {
        bars: {
            actionBar: {
                visible: true
            }
        }
    }
};

Como alternativa, en el modo de vista, también es posible usar el parámetro url de actionBarEnabled:

let embedConfig = {
   ...
   embedUrl: embedUrl + "&actionBarEnabled=true"
};

Nota

En el modo de vista, la barra de acciones solo se admite para la inserción de para su organización escenario.

Para la barra de acciones en modo de vista, se recomienda habilitar UserState.ReadWrite.All permiso para la aplicación de Azure AD. Este permiso es necesario para permitir que los usuarios finales agreguen el informe a sus favoritos y para habilitar marcadores personales y filtros persistentes.

Barra de estado

La barra de estado contiene el controlador de zoom del lienzo, que proporciona la capacidad de acercar el lienzo.

El código siguiente hace que la barra de estado sea visible:

let embedConfig = {
    ...
    settings: {
        bars: {
            statusBar: {
                visible: true
            }
        }
    }
};

Configuración regional

Use la propiedad localeSettings para especificar el idioma y el formato del informe incrustado:

La propiedad language de localeSettings consta de dos partes de dos letras cada una, separadas por un guión:

  • idioma define el idioma que Usa Power BI para la localización. Algunos ejemplos de idiomas incluyen en (inglés), es (español) y tr (turco).
  • configuración regional define el formato de texto que Power BI usa para fechas, moneda y otro contenido relacionado. Algunos ejemplos de configuraciones regionales incluyen us (inglés), ES (España) y TR (Türkiye).

Consulte idiomas admitidos para obtener una lista de los idiomas y regiones disponibles.

El código siguiente asigna valores específicos a estos localeSettings:

let embedConfig = {
    ...
    settings: {
        localeSettings: {
            language: "en-us"
        }
    }
};

Nota

No se puede cambiar la configuración regional después de cargar el informe. Para cambiar la configuración regional del informe, restablezca el iframe llamando a powerbi.reset(element)y, a continuación, vuelva a insertar el informe.

Fondo transparente

De forma predeterminada, el fondo del contenido incrustado es blanco con márgenes grises. Si lo prefiere, puede proporcionar al contenido incrustado un fondo transparente. A continuación, puede aplicar el estilo que desea al elemento html div que contiene el contenido incrustado. A continuación, el estilo del elemento div se vuelve visible.

Use este código para que el fondo del contenido incrustado sea transparente:

let embedConfig = {
    ...
    settings: {
        background: models.BackgroundType.Transparent
    }
};

Puede controlar el comportamiento de un hipervínculo en una tabla o objetos visuales de matriz de fábrica. De forma predeterminada, el hipervínculo abre una nueva ventana.

Los modos de comportamiento disponibles:

enum HyperlinkClickBehavior {
    Navigate,
    NavigateAndRaiseEvent,
    RaiseEvent
}
  • Navigate: la dirección URL se carga en un nuevo contexto de exploración.
  • NavigateAndRaiseEvent: la dirección URL se carga en un nuevo contexto de exploración y genera un evento de dataHyperlinkClicked.
  • RaiseEvent: impide el comportamiento predeterminado de la dirección URL y genera dataHyperlinkClicked evento.

Use este código para cambiar el comportamiento de los vínculos para generar un evento:

let embedConfig = {
    ...
    settings: {
        hyperlinkClickBehavior: HyperlinkClickBehavior.RaiseEvent
    }
};

Un evento de dataHyperlinkClicked se desencadena cuando se hace clic en un hipervínculo en una tabla o objetos visuales de matriz predefinidos y el comportamiento es NavigateAndRaiseEvent o RaiseEvent.

report.on('dataHyperlinkClicked', () => {
    ...
});

Para obtener más información sobre el control de eventos, vea Cómo controlar eventos.

Eventos representados visualmente

Puede escuchar un evento para cada objeto visual representado. De forma predeterminada, los eventos representados visualmente están deshabilitados.

Use este código para desencadenar los eventos visualRendered:

let embedConfig = {
    ...
    settings: {
        visualRenderedEvents: true
    }
};

Un evento visualRendered se desencadena cuando se representa un objeto visual y el visualRenderedEvents está habilitado en la configuración del informe.

report.on('visualRendered', () => {
    ...
});

Para obtener más información sobre el control de eventos, vea Cómo controlar eventos.

Nota

Dado que los objetos visuales se pueden representar debido a las interacciones del usuario, se recomienda activar este evento solo cuando sea necesario.

Mensajes de error

Si desea mostrar mensajes de error personalizados en informes incrustados, use la propiedad hideErrors para ocultar los mensajes de error incrustados predeterminados de Power BI. Después, el código puede controlar los eventos de error de forma que se ajuste al diseño de la aplicación. Consulte Invalidar mensajes de error predeterminados para obtener más información sobre cómo invalidar los errores predeterminados.

Use este código para ocultar los mensajes de error predeterminados:

let embedConfig = {
    ...
    settings: {
        hideErrors: true
    }
};

Personalizar opciones

En las secciones siguientes se describe cómo puede usar más propiedades para personalizar aún más la apariencia y el comportamiento del informe insertado de Power BI.

Página predeterminada

Puede controlar qué página del informe incrustado aparece inicialmente. De forma predeterminada, la página inicial es la página que modificó más recientemente, que fue la página activa la última vez que guardó el informe. Puede invalidar este comportamiento mediante la propiedad pageName y proporcionarlo con el nombre de la página que desea mostrar. Sin embargo, si no existe ninguna página con ese nombre en Power BI, se produce un error en la solicitud para abrirla.

En el código siguiente se muestra cómo configurar la aplicación para mostrar una página específica:

let embedConfig = {
    ...
    pageName: 'ReportSection3'
};

En filtros de carga

Puedes controlar los filtros que la aplicación aplica a un informe incrustado. De forma predeterminada, el informe usa inicialmente los filtros que guardó en el informe. Sin embargo, tiene dos opciones si desea ajustar los filtros:

  • Configure más filtros para usarlos junto con los filtros guardados. En el código siguiente se muestra cómo usar la propiedad filters para anexar más filtros:

    let embedConfig = {
    ...
    filters: [...]
};

  • Reemplace los filtros guardados por un nuevo conjunto. El método setFilters proporciona una manera de cambiar dinámicamente los filtros de un informe. Si usa este método durante la inserción por fases, puede invalidar los filtros que el informe aplica inicialmente. Para obtener más información sobre cómo construir filtros y usar el método setFilters, vea Filtros de informe de control.

En segmentaciones de carga

Puedes controlar el estado de las segmentaciones de datos que la aplicación aplica a un informe incrustado. De forma predeterminada, la API usa las segmentaciones que guardó en el informe. Sin embargo, puede usar la propiedad slicers para modificar el estado de las segmentaciones existentes, como se muestra en el código siguiente:

embedConfig = {
    ...
    slicers: slicerArray,
};

Consulte segmentaciones de informes de control para obtener más información sobre cómo modificar el estado de una segmentación de datos.

Al cargar marcador

Mediante la propiedad bookmark, puede aplicar un marcador a un informe incrustado. Consulte Marcadores para obtener más información sobre el uso de marcadores para capturar la vista configurada actualmente de las páginas de informe.

Puede especificar el marcador que se va a usar proporcionando el nombre del marcador o el estado. Si proporciona el nombre del marcador, el informe de Power BI debe contener un marcador guardado con ese nombre.

La propiedad bookmark es de tipo IApplyBookmarkRequest. El código siguiente muestra la definición de este tipo:

type IApplyBookmarkRequest = IApplyBookmarkStateRequest | IApplyBookmarkByNameRequest;

interface IApplyBookmarkStateRequest {
    state: string;
}

interface IApplyBookmarkByNameRequest {
    name: string;
}

Este código muestra cómo especificar un marcador por nombre:

let embedConfig = {
    ...
    bookmark: {
        name: "Bookmark4f76333c3ea205286501"
    }
};

Este código muestra cómo especificar un marcador por estado:

let embedConfig = {
    ...
    bookmark: {
        state: bookmarkState
    }
};

Temas y modo de contraste alto

Puede controlar el tema y el nivel de contraste que usa el contenido incrustado. De forma predeterminada, cualquier contenido que inserte aparezca con el tema predeterminado y con contraste cero. Puede invalidar este comportamiento configurando un tema específico o un nivel de contraste. Para obtener más información sobre los temas, consulte Aplicar temas de informe.

Los modos de contraste disponibles:

enum ContrastMode {
    None = 0,
    HighContrast1 = 1,
    HighContrast2 = 2,
    HighContrastBlack = 3,
    HighContrastWhite = 4
}

Para configurar un tema específico, use código similar a las líneas siguientes:

let embedConfig = {
    ...
    theme: {themeJson: ...}
};

En el código siguiente se muestra cómo invalidar el nivel de contraste predeterminado, None:

let embedConfig = {
    ...
    contrastMode: models.contrastMode.HighContrast1
};

Nota

La API no puede aplicar un tema ni un nivel de contraste al mismo tiempo. Si configura ambas propiedades, la API usa el nivel de contraste que especificó, pero omite la configuración de theme.

Nivel de zoom

Para obtener más información sobre cómo ajustar el nivel de zoom del informe, compruebe el documento de accesibilidad .

Abrir en modo de edición

De forma predeterminada, el informe que insertó aparece en modo de vista. Sin embargo, puede invalidar este comportamiento para abrir el informe en modo de edición. También puede cambiar entre modos.

Configurar el modo de edición

Para abrir un informe incrustado en modo de edición, use la propiedad viewMode junto con la propiedad permissions.

Puede asignar la propiedad viewMode los siguientes valores:

  • View: abre el informe en modo de vista.
  • Edit: abre el informe en modo de edición.

Puede asignar la propiedad permissions estos valores:

  • Read: los usuarios pueden ver el informe.
  • ReadWrite: los usuarios pueden ver, editar y guardar el informe.
  • Copy: los usuarios pueden guardar una copia del informe mediante Guardar como.
  • Create: los usuarios pueden crear un nuevo informe.
  • All: los usuarios pueden crear, ver, editar, guardar y guardar una copia del informe.

Al configurar el contenido para que se abra en modo de edición, asigne la propiedad permissions un valor adecuado para su edición, como se muestra en el código siguiente:

let embedConfig = {
    ...
    permissions: models.Permissions.All
    viewMode: models.ViewMode.Edit
};

Nota

El valor de permissions que configure solo funciona si el token de inserción que adquirió tiene privilegios suficientes. Para obtener más información sobre los tokens de inserción, consulte Creación del token de inserción.

Cambiar entre los modos de edición y vista

Además de especificar un modo para que el contenido incrustado se inicie, también puede cambiar de modo dinámico entre modos de edición y vista.

Si el contenido está en modo de edición y desea cambiar al modo de vista, use este código JavaScript:

// Embed the content.
let embeddedContent = powerbi.embed(container, embedConfiguration);

...

// Switch to view mode.
embeddedContent.switchMode("view");

Si el contenido está en modo de vista y desea cambiar al modo de edición, use este código JavaScript:

// Embed the content.
let embeddedContent = powerbi.embed(container, embedConfiguration);

...

// Switch to edit mode.
embeddedContent.switchMode("edit");

Consideraciones y limitaciones

Tenga en cuenta los siguientes puntos al configurar el contenido incrustado:

  • La navegación de página posición no se puede cambiar cuando la barra de acciones está visible. Obtenga más información sobre la barra de acciones de .

  • Cuando se usa la propiedad bars en la propiedad setting, como se describe en Barras, la API solo aplica la configuración si el contenido incrustado está en modo de edición. Si el contenido está en modo de vista, la API omite la configuración de bars.

  • Al usar la propiedad viewMode para mostrar contenido en modo de edición, debe realizar dos pasos adicionales:

    • Configure un nivel de permiso con la propiedad permissions. Ese nivel de permiso debe proporcionar al usuario el acceso adecuado para modificar el contenido. Por ejemplo, si asigna un valor de permissions de Read, el usuario no podrá editar el contenido.
    • Asegúrese de que el token de inserción que genere tenga privilegios que admitan la edición. Por ejemplo, si adquiere un token con un valor de accessLevel de view, la API no puede mostrar contenido en modo de edición.

  • La propiedad paneles reemplaza las siguientes propiedades de settings:

    • filterPaneEnabled
    • navContentPaneEnabled

    Si usa la propiedad panes para configurar la visibilidad de navegación de páginas o filtros, no use la propiedad filterPaneEnabled ni navContentPaneEnabled en la aplicación.

  • La API no puede aplicar un tema y un nivel de contraste al contenido incrustado al mismo tiempo. Si configura ambas opciones mediante las propiedades theme y contrastMode, la API usa el valor de contrastMode con el contenido incrustado. Sin embargo, la API omite la configuración de theme.

  • Si desea aplicar un marcador a un informe incrustado, puede usar la propiedad bookmark. Si proporciona un nombre de marcador con esa propiedad, la API solo puede usar el marcador si existe con ese nombre. Del mismo modo, si usa la propiedad pageName para especificar una página de apertura, la API solo puede mostrar esa página si existe con el nombre especificado. Antes de configurar un nombre, considere la posibilidad de usar un método de descriptor de acceso, como el método getPages de , para comprobar si existe un componente con ese nombre.

Contenido relacionado