Definir configurações de relatório

Artigo
09/17/2023

Usando as APIs de Cliente do Power BI, você pode inserir a análise do Power BI em seu aplicativo. Ao usar essa biblioteca do lado do cliente para inserir um relatório do Power BI, você fornece à API informações sobre esse relatório.

Você pode usar um objeto de configuração para armazenar informações sobre seu relatório do Power BI. Ao inserir o relatório, você passa esse objeto para a API.

Além de fornecer à API acesso ao relatório, você também pode usar o objeto de configuração para personalizar a aparência e o comportamento do relatório. Por exemplo, você pode ajustar a visibilidade do filtro, o acesso de navegação e as configurações de localização no objeto de configuração.

As seções a seguir explicam como inserir e configurar o conteúdo do Power BI.

Fornecer informações de configuração

A interface IReportLoadConfiguration exibe propriedades que um objeto de configuração pode fornecer às APIs do Cliente do Power BI sobre um relatório:

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 Inserir um relatório para obter uma explicação dos parâmetros necessários dessa interface e para obter exemplos de código mostrando como inserir um relatório.

Personalizar configurações

As seções a seguir descrevem como você pode usar a settings propriedade para ajustar a aparência e o comportamento do relatório do Power BI inserido. Para atualizar as configurações de relatório quando o relatório já estiver carregado, use o report.updateSettings método . Para obter mais informações, consulte Atualizar configurações de relatório em runtime.

Painéis

Controle a aparência de todos os painéis no relatório do Power BI com uma única panes propriedade, conforme mostrado no código a seguir:

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

Na tabela a seguir, você pode ver quais valores cada panes propriedade dá suporte:

Propriedade	Visible	Expanded
`bookmarks`	✔	❌
`fields`	✔	✔
`filters`	✔	✔
`pageNavigation`	✔	❌
`selection`	✔	❌
`syncSlicers`	✔	❌
`visualizations`	✔	✔

Painel Filtro

Por padrão, o painel de filtro fica visível. Se você quiser ocultar esse painel, use a filterPaneEnabled propriedade , conforme mostrado no código a seguir:

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

Observação

A propriedade panes substitui a filterPaneEnabled propriedade . Para manter a compatibilidade com versões anteriores, a filterPaneEnabled propriedade ainda existe. No entanto, você deve evitar usar essas duas propriedades juntas.

Por padrão, as setas de navegação de página ficam visíveis em relatórios inseridos. Para ocultar essas setas, use a navContentPaneEnabled propriedade , conforme mostrado no seguinte código:

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

Observação

A propriedade panes substitui a navContentPaneEnabled propriedade . Para manter a compatibilidade com versões anteriores, a navContentPaneEnabled propriedade ainda existe. No entanto, você deve evitar usar essas duas propriedades juntas.

O painel de navegação da página aparece na parte inferior do relatório para usar o novo painel de páginas verticais que você pode definir a position propriedade:

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

Observação

Não é possível alterar a posição do painel de navegação da página usando updateSettings.

Barras

Defina a visibilidade da barra de ações e da barra de status usando a bars propriedade .

Barra de ação

O código a seguir torna a barra de ações visível:

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

Como alternativa, no modo de exibição, também é possível usar o actionBarEnabled parâmetro url:

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

Observação

No modo de exibição, a barra de ações só tem suporte para o cenário de inserção para sua organização .

Para a barra de ações no modo de exibição, é recomendável habilitar UserState.ReadWrite.All a permissão para seu aplicativo Azure AD. Essa permissão é necessária para permitir que os usuários finais adicionem o relatório aos seus favoritos e para habilitar indicadores pessoais e filtros persistentes.

Barra de Status

A barra de status contém o controlador de zoom de tela, que fornece a capacidade de ampliar a tela.

O código a seguir torna a barra de status visível:

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

Configurações de localidade

Use a localeSettings propriedade para especificar o idioma e a formatação do relatório inserido:

A language propriedade em consiste em localeSettings duas partes de duas letras cada, separadas por um hífen:

O idioma define o idioma que o Power BI usa para localização. Exemplos de idiomas incluem en (inglês), es (espanhol) e tr (turco).
localidade define a formatação de texto que o Power BI usa para datas, moeda e outros conteúdos relacionados. Exemplos de localidades incluem EUA (inglês), ES (Espanha) e TR (Türkiye).

Confira Idiomas com suporte para obter uma lista de idiomas e regiões disponíveis.

O código a seguir atribui valores específicos a estes localeSettings:

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

Observação

As configurações de localidade não podem ser alteradas depois que o relatório é carregado. Para alterar as configurações de localidade do relatório, redefina o iframe chamando powerbi.reset(element)e insira o relatório novamente.

Plano de fundo transparente

Por padrão, a tela de fundo do conteúdo inserido é branca com margens cinzas. Se preferir, você pode dar ao conteúdo inserido uma tela de fundo transparente. Em seguida, você pode aplicar o estilo desejado ao elemento HTML div que contém o conteúdo inserido. O div estilo do elemento se torna visível.

Use este código para tornar a tela de fundo do conteúdo inserido transparente:

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

Comportamento de clique de hiperlink

Você pode controlar o comportamento de um hiperlink em uma tabela ou visuais prontos para uso de matriz. Por padrão, o hiperlink abrirá uma nova janela.

Os modos de comportamento disponíveis estão listados abaixo:

enum HyperlinkClickBehavior {
    Navigate,
    NavigateAndRaiseEvent,
    RaiseEvent
}

Navigate - A URL será carregada em um novo contexto de navegação.
NavigateAndRaiseEvent - A URL será carregada em um novo contexto de navegação e gerará um dataHyperlinkClicked evento.
RaiseEvent – Impede o comportamento padrão do clique de URL e aciona dataHyperlinkClicked o evento.

Use este código para alterar o comportamento dos links para gerar um evento:

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

Um dataHyperlinkClicked evento é acionado quando um hiperlink é clicado em uma tabela pronta para uso ou visuais de matriz e o comportamento é NavigateAndRaiseEvent ou RaiseEvent.

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

Para obter mais informações sobre como lidar com eventos, consulte Como lidar com eventos.

Eventos renderizados visualmente

Você pode ouvir um evento para cada visual renderizado. Por padrão, os eventos renderizados do visual são desabilitados.

Use este código para tornar os visualRendered eventos disparados:

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

Um visualRendered evento é acionado quando um visual é renderizado e o visualRenderedEvents está habilitado nas configurações do relatório.

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

Para obter mais informações sobre como lidar com eventos, consulte Como lidar com eventos.

Observação

Como os visuais podem ser renderizados devido a interações do usuário, é recomendável ativar esse evento somente quando necessário.

Mensagens de erro

Se você quiser exibir mensagens de erro personalizadas em relatórios inseridos, use a hideErrors propriedade para ocultar as mensagens de erro padrão inseridas no Power BI. Em seguida, o código pode lidar com eventos de erro de uma maneira que atenda ao design do aplicativo. Consulte Substituir mensagens de erro padrão para obter mais informações sobre como substituir erros padrão.

Use este código para ocultar mensagens de erro padrão:

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

Personalizar opções

As seções a seguir descrevem como você pode usar propriedades adicionais para personalizar ainda mais a aparência e o comportamento do relatório do Power BI inserido.

Página padrão

Você pode controlar qual página do relatório inserido aparece inicialmente. Por padrão, a página inicial é a página que você modificou mais recentemente, que foi a página ativa na última vez que você salvou o relatório. Você pode substituir esse comportamento usando a pageName propriedade e fornecendo-a com o nome da página que deseja exibir. No entanto, se nenhuma página com esse nome existir no Power BI, a solicitação para abri-la falhará.

O código a seguir mostra como configurar seu aplicativo para exibir uma página específica:

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

Em filtros de carga

Você pode controlar os filtros que seu aplicativo aplica a um relatório inserido. Por padrão, o relatório usa inicialmente os filtros que você salvou no relatório. No entanto, você terá duas opções se quiser ajustar os filtros:

Configure filtros adicionais para usar junto com os filtros salvos. O código a seguir mostra como usar a filters propriedade para acrescentar filtros adicionais:
```
let embedConfig = {
    ...
    filters: [...]
};
```
Substitua os filtros salvos por um novo conjunto. O setFilters método fornece uma maneira de alterar dinamicamente os filtros de um relatório. Se você usar esse método durante a inserção em fases, poderá substituir os filtros que o relatório aplica inicialmente. Para obter mais informações sobre como construir filtros e usar o setFilters método , consulte Controlar filtros de relatório.

Em segmentações de carga

Você pode controlar o estado das segmentações de dados que seu aplicativo aplica a um relatório inserido. Por padrão, a API usa as segmentações que você salvou no relatório. No entanto, você pode usar a slicers propriedade para modificar o estado das segmentações de dados existentes, como demonstra o código a seguir:

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

Consulte Controlar segmentações de relatório para obter mais informações sobre como modificar o estado de uma segmentação de dados.

No indicador de carga

Usando a bookmark propriedade , você pode aplicar um indicador a um relatório inserido. Consulte Indicadores para obter mais informações sobre como usar indicadores para capturar a exibição atualmente configurada de páginas de relatório.

Você pode especificar o indicador a ser usado fornecendo o nome do indicador ou o estado. Se você fornecer o nome do indicador, o relatório do Power BI precisará conter um indicador salvo com esse nome.

A bookmark propriedade é do tipo IApplyBookmarkRequest. O código a seguir mostra a definição desse tipo:

type IApplyBookmarkRequest = IApplyBookmarkStateRequest | IApplyBookmarkByNameRequest;

interface IApplyBookmarkStateRequest {
    state: string;
}

interface IApplyBookmarkByNameRequest {
    name: string;
}

Este código mostra como especificar um indicador por nome:

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

Este código mostra como especificar um indicador por estado:

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

Temas e modo de alto contraste

Você pode controlar o tema e o nível de contraste que o conteúdo inserido usa. Por padrão, qualquer conteúdo que você insira aparece com o tema padrão e sem contraste. Você pode substituir esse comportamento configurando um tema específico ou um nível de contraste. Para obter mais informações sobre temas, consulte Aplicar temas de relatório.

Os modos de contraste disponíveis estão listados abaixo:

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

Use um código semelhante às seguintes linhas para configurar um tema específico:

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

O código a seguir mostra como substituir o nível de contraste padrão, None:

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

Observação

A API não pode aplicar um tema e um nível de contraste ao mesmo tempo. Se você configurar ambas as propriedades, a API usará o nível de contraste especificado, mas ignorará a theme configuração.

Nível de zoom

Para saber mais sobre como ajustar o nível de zoom do relatório marcar o documento de acessibilidade.

Abrir no modo de edição

Por padrão, o relatório que você inseri aparece no modo de exibição. No entanto, você pode substituir esse comportamento para abrir o relatório no modo de edição. Você também pode alternar entre os modos.

Configurar o modo de edição

Para abrir um relatório inserido no modo de edição, use a viewMode propriedade junto com a permissions propriedade .

Você pode atribuir à viewMode propriedade os seguintes valores:

View - Abre o relatório no modo de exibição.
Edit – Abre o relatório no modo de edição.

Você pode atribuir à permissions propriedade estes valores:

Read – Os usuários podem exibir o relatório.
ReadWrite – Os usuários podem exibir, editar e salvar o relatório.
Copy – Os usuários podem salvar uma cópia do relatório usando Salvar como.
Create – Os usuários podem criar um novo relatório.
All – Os usuários podem criar, exibir, editar, salvar e salvar uma cópia do relatório.

Ao configurar o conteúdo para abrir no modo de edição, atribua à permissions propriedade um valor apropriado para edição, como demonstra o código a seguir:

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

Observação

O permissions valor configurado só funcionará se o token de inserção adquirido tiver privilégios suficientes. Para obter mais informações sobre tokens de inserção, consulte Criar o token de inserção.

Alternar entre os modos de edição e exibição

Além de especificar um modo para o conteúdo inserido iniciar, você também pode alternar entre os modos de edição e exibição dinamicamente.

Se o conteúdo estiver no modo de edição e você quiser alternar para o modo de exibição, use este código JavaScript:

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

...

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

Se o conteúdo estiver no modo de exibição e você quiser alternar para o modo de edição, use este código JavaScript:

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

...

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

Considerações e limitações

Considere os seguintes pontos ao configurar o conteúdo inserido:

A posição de navegação da página não pode ser alterada quando a barra de ação está visível. Saiba mais sobre a barra de ações.
Quando você usa a bars propriedade na setting propriedade , conforme descrito em Barras, a API só aplica sua configuração se o conteúdo inserido estiver no modo de edição. Se o conteúdo estiver no modo de exibição, a API ignorará a bars configuração.
Ao usar a viewMode propriedade para exibir o conteúdo no modo de edição, você precisa executar duas etapas adicionais:
- Configure um nível de permissão com a permissions propriedade . Esse nível de permissão precisa dar ao usuário acesso apropriado para modificar o conteúdo. Por exemplo, se você atribuir um permissions valor do Read, usuário não poderá editar o conteúdo.
- Verifique se o token de inserção gerado tem privilégios que dão suporte à edição. Por exemplo, se você adquirir um token com um accessLevel valor da view, API não exibirá o conteúdo no modo de edição.
A propriedade panes substitui as seguintes settings propriedades:
- filterPaneEnabled
- navContentPaneEnabled
Se você usar a panes propriedade para configurar a visibilidade de navegação de página ou filtro, não use a filterPaneEnabled propriedade ou navContentPaneEnabled em seu aplicativo.
A API não pode aplicar um tema e um nível de contraste ao conteúdo inserido ao mesmo tempo. Se você configurar ambas as opções usando as theme propriedades e contrastMode , a API usará seu contrastMode valor com o conteúdo inserido. No entanto, a API ignora a theme configuração.
Se você quiser aplicar um indicador a um relatório inserido, poderá usar a bookmark propriedade . Se você fornecer um nome de indicador com essa propriedade, a API só poderá usar o indicador se houver um com esse nome. Da mesma forma, se você usar a pageName propriedade para especificar uma página de abertura, a API só poderá exibir essa página se houver uma com o nome fornecido. Antes de configurar um nome, considere usar um método acessador, como o método Report getPages, para marcar se existe um componente com esse nome.

Definir configurações de relatório

Fornecer informações de configuração

Personalizar configurações

Painéis

Painel Filtro

Painel de navegação de página

Barras

Barra de ação

Barra de Status

Configurações de localidade

Plano de fundo transparente

Comportamento de clique de hiperlink

Eventos renderizados visualmente

Mensagens de erro

Personalizar opções

Página padrão

Em filtros de carga

Em segmentações de carga

No indicador de carga

Temas e modo de alto contraste

Nível de zoom

Abrir no modo de edição

Configurar o modo de edição

Alternar entre os modos de edição e exibição

Considerações e limitações

Próximas etapas

Recursos adicionais