Definir configurações de relatório
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.
Painel de navegação de página
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á umdataHyperlinkClicked
evento.RaiseEvent
– Impede o comportamento padrão do clique de URL e acionadataHyperlinkClicked
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 osetFilters
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 nasetting
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á abars
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 umpermissions
valor doRead,
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 daview,
API não exibirá o conteúdo no modo de edição.
- Configure um nível de permissão com a
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 afilterPaneEnabled
propriedade ounavContentPaneEnabled
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 econtrastMode
, a API usará seucontrastMode
valor com o conteúdo inserido. No entanto, a API ignora atheme
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 apageName
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.