Usar inserção em fases

A análise e report.render as APIs integradas powerbi.load do Power BI podem melhorar a experiência do usuário final, dando aos desenvolvedores mais flexibilidade para a inserção de relatórios em fases.

Normalmente, você carrega um relatório inserido usando powerbi.embed:

let report = powerbi.embed(embedContainer, embedConfig);

O relatório inserido carrega e renderiza na interface do usuário. Em seguida, o usuário final vê as interações com o relatório renderizado. Por exemplo, se você aplicar um estado de segmentação de dados, o usuário final verá a segmentação entrar em vigor após a renderização do relatório.

Para ocultar essas interações de usuários finais, as powerbi.load APIs e report.render dividem o processo de inserção em fases. A powerbi.load função carrega o relatório para que você possa interagir com os itens antes que os usuários finais vejam os resultados. Em report.render seguida, a função exibe o relatório.

Carregar

A powerbi.load função carrega o relatório, mas não o renderiza, portanto, as interações podem acontecer antes que o usuário final veja os resultados. Por exemplo, você pode usar powerbi.load com report.getPagese, em seguida, especificar qual página mostrar ao usuário final. Ou você pode usar page.getVisualse decidir quais visuais mostrar ou ocultar.

Assim como powerbi.embed, a powerbi.load função requer um elemento HTML e um objeto IEmbedConfiguration .

Quando a carga é concluída, um loaded evento é acionado.

let config = {
    ...
};

// Get a reference to the embedded report HTML element.
let embedContainer = $('#embedContainer')[0];

// Load the report in the container.
let report = powerbi.load(embedContainer, config);

report.on('loaded', function() {
    ...
});

Renderizar

Se você usar powerbi.load, deverá chamar a report.render função na função de loaded manipulador de eventos depois de executar o código. Use report.render para continuar a renderização do relatório e exibir o relatório inserido.

Um rendered evento é acionado quando o relatório termina a renderização.

report.on('loaded', function() {
    report.render();
});

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

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

Exemplo

O exemplo de código a seguir carrega um relatório, define filtros e renderiza o relatório filtrado.

// Build the config object.
let config = {
    type: 'report',
    tokenType: TokenType.Embed,
    accessToken: ...,
    embedUrl: ...,
    id: ...,
    ...
};
 
// Get a reference to the embedded report HTML element.
let embedContainer = $('#embedContainer')[0];

// Load the report in the container.
let report = powerbi.load(embedContainer, config);

...
report.on('loaded', async () => {
    await report.setFilters(filters);
    report.render();
});

Limitações

A inserção em fases pode reduzir a renderização de relatório, portanto, use-a corretamente e somente quando precisar dela.

Você pode chamar as seguintes APIs depois de carregar o relatório e antes de chamar report.render:

Método	Ação
BookmarksManager.getBookmarks, BookmarksManager.apply	Obter e aplicar indicadores. Não há suporte para a captura de indicadores.
Report.updateSettings	Atualizar as configurações do relatório.
Report.applyTheme	Aplique o tema do relatório.
Report.getFilters, Report.setFilters, Report.removeFilters	Obter, definir e remover filtros de relatório.
Report.getPages	Obtenha as páginas de relatório.
Page.setActive	Defina a página de relatório ativa.
Page.getFilters, Page.setFilters, Page.removeFilters	Obter, definir e remover filtros de página.
Page.getVisuals	Obter visuais de página.
Visual.getFilters, Visual.setFilters, Visual.removeFilters	Obter, definir e remover filtros visuais.
Visual.getSlicerState, Visual.setSlicerState	Obter e definir o estado da segmentação visual.

Próximas etapas

Aprimorar a experiência dos usuários com indicadores

Aplicar temas de relatório no Power BI

Controlar filtros de relatório

Controlar segmentações de relatórios

Obter páginas e visuais