Share via

Aprimorar a experiência dos usuários com indicadores

  • Artigo

Os indicadores de relatório no Power BI permitem capturar o estado atual de uma página de relatório inserida, incluindo todos os filtros e o estado de seus visuais. Ao abrir o relatório posteriormente, você pode selecionar um indicador para restaurar o relatório para o estado salvo. Os desenvolvedores podem controlar a experiência do usuário usando as APIs de Cliente do Power BI para capturar e aplicar indicadores.

Um indicador salvo pode ser um indicador que foi salvo como parte de um relatório ou um indicador que foi capturado como um estado em tempo real de um relatório. Se você aplicar um indicador salvo ao carregar um relatório, poderá especificar o indicador a ser usado fornecendo o nome do indicador ou seu estado. Se você fornecer um indicador por nome, seu relatório precisará conter um indicador salvo com esse mesmo nome.

Este artigo explica as diferentes configurações de API necessárias para inserir relatórios que dão suporte a indicadores.

Observação

Nos relatórios inseridos para sua organização, os consumidores de relatório criam indicadores pessoais capturando o estado do relatório e retornando rapidamente a esse estado selecionando o indicador. Confira Indicadores pessoais para obter mais informações.

Para obter informações sobre como criar uma experiência semelhante em relatórios que você inseriu para seus clientes, consulte a demonstração de exibição de relatório de captura no playground de análise integrada do Power BI.

Para obter mais informações sobre como usar indicadores no Power BI, consulte Criar indicadores no Power BI Desktop.

Para obter informações sobre como usar indicadores pessoais ao inserir o Power BI, consulte Indicadores pessoais.

Como usar indicadores de relatório

As seções a seguir mostram como usar as APIs de Cliente do Power BI para trabalhar com indicadores de relatório.

Gerenciar indicadores de um relatório

Para gerenciar os indicadores de um relatório, use a bookmarksManager propriedade de uma instância de relatório inserida.

A classe BookmarksManager tem os seguintes métodos:

  • getBookmarks – Retorna uma lista de indicadores salvos associados ao relatório.

  • apply – Aplica-se pelo nome de um indicador salvo anteriormente ao relatório.

  • capture – Captura e retorna uma cadeia de caracteres de serialização base64, que representa o estado atual do relatório.

  • applyState Aplica um estado de serialização base64 capturado anteriormente de um indicador ao relatório.

  • play – Controla o modo de apresentação de apresentação de slides para os indicadores do relatório.

Acessar um indicador de relatório

Para acessar um indicador individual, use o getBookmarks método para acessar uma lista de ReportBookmark objetos. A ReportBookmark classe tem as seguintes propriedades:

  • name - O identificador exclusivo do indicador de relatório.

  • displayName - O nome de exibição do indicador de relatório, que aparece no painel Indicadores .

  • state - Uma serialização base64 do estado do indicador de relatório. Você pode salvá-lo e aplicá-lo a um relatório com o bookmarksManager.applyState método .

  • children - Uma lista de ReportBookmark objetos que representam um grupo de indicadores de relatório, se existir.

Usar as APIs de indicadores de relatório

Em um relatório inserido, os desenvolvedores podem:

Obter uma lista de indicadores de relatório salvos

Para obter a lista de indicadores salvos associados a um relatório, chame o getBookmarks método do objeto BookmarksManager retornado pela propriedade do bookmarksManager relatório.

O getBookmarks método é definido da seguinte maneira:

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

Por exemplo:

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

Aplicar um indicador salvo por nome no carregamento do relatório ou durante uma sessão

Para aplicar um indicador salvo anteriormente a um relatório usando seu nome de indicador, chame o apply método do objeto BookmarksManager retornado pela propriedade de bookmarksManager um relatório.

Para obter mais informações, consulte Definir configurações de relatório.

O apply método é definido da seguinte maneira:

apply(bookmarkName: string): Promise<void>

Por exemplo:

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

Capturar e obter uma exibição atual como um objeto de indicador

Para capturar o estado atual de um relatório como uma cadeia de caracteres base64, chame o capture método de um objeto BookmarksManager . O capture método retorna um IReportBookmark objeto , que representa um indicador que não é salvo em um relatório específico. Use a IReportBookmark.state propriedade para retornar a cadeia de caracteres base64 que identifica o estado do indicador, que você pode aplicar posteriormente a um relatório durante o tempo de carregamento ou o tempo de execução.

O capture método é definido da seguinte maneira:

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

Por exemplo:

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

Opções de captura de indicador

Você também pode passar um ICaptureBookmarkOptions objeto para o capture método .

interface ICaptureBookmarkOptions {
    allPages?: boolean;
    personalizeVisuals?: boolean;
}
  • allPages - Por padrão, o estado do indicador capturado salvará apenas o estado da página atual. Para capturar o estado de todas as páginas, chame capture o método com allPages a trueopção definida como .
  • personalizeVisuals – Para capturar o estado atual com visuais personalizados, chame o capture método com a opção personalizeVisuals definida truecomo .

Por exemplo, o código a seguir captura o estado de todas as páginas, incluindo os visuais personalizados:

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

Aplicar um estado de indicador capturado na carga do relatório ou durante uma sessão

Para aplicar um estado de indicador capturado anteriormente a um relatório, use o applyState método de um objeto BookmarksManager .

Para obter mais informações, consulte Definir configurações de relatório.

O applyState método é definido da seguinte maneira:

applyState(state: string): Promise<void>

Por exemplo:

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

Executar lógica adicional quando um indicador de relatório é aplicado

Para determinar quando um indicador de relatório foi aplicado, ouça o bookmarkApplied evento chamando o on método do objeto de relatório .

Por exemplo:

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

Mostrar ou ocultar o painel Indicadores

Para mostrar ou ocultar o painel Indicadores do Power BI, atualize a panes propriedade das configurações do relatório.

Mostrar o painel Indicadores

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

Ocultar o painel Indicadores

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

Para obter informações sobre como atualizar as configurações de relatório, consulte Definir configurações de relatório.

Entrar ou sair do modo de apresentação de slides de indicadores

Para controlar o modo de apresentação de apresentação de slides para os indicadores de um relatório, chame o play método de um objeto BookmarksManager . Para obter mais informações, consulte Indicadores como uma apresentação de slides.

O play método é definido da seguinte maneira:

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

Observação

Antes de entrar no modo de apresentação de slides de indicadores, verifique se há pelo menos um indicador no relatório com a API getBookmarks.

Insira o modo de apresentação de apresentação de slides

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

Sair do modo de apresentação de apresentação de apresentação de slides

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

Limitações

  • Quando você usa a API de indicadores, determinadas alterações no relatório podem causar um erro ou um resultado inesperado. Um exemplo disso é remover filtros de relatório do relatório. Para evitar erros, os cartões de filtro correspondentes devem estar presentes. Em vez de remover os filtros, defina seus valores como All. Se você não souber quais filtros foram excluídos ou alterados, recapture o indicador depois de aplicar as alterações ao relatório.

  • Filtros como em filtros de carga criados pela sessão de inserção ou adicionados pela operação de adição de filtros de atualização são capturados no estado do indicador, mas serão aplicados somente na sessão atual. Para superar essa limitação, o filtro deve ser salvo no relatório com o All valor e modificado na sessão de inserção usando a operação de atualização de filtros de atualização.

Próximas etapas