Partilhar 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 que você precisará para inserir relatórios que dão suporte a indicadores.

Nota

Em relatórios que você insira para sua organização, informe que os consumidores criam indicadores pessoais capturando o estado do relatório e retornando rapidamente a esse estado selecionando o indicador. Consulte 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 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 propriedade bookmarksManager 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 por nome 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 da apresentação de slides para os indicadores do relatório.

Acessar um indicador de relatório

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

  • name – o identificador exclusivo do indicador de relatório.

  • - 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 método bookmarksManager.applyState.

  • children - Uma lista de objetos ReportBookmark 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 método do objeto BookmarksManager retornado pela propriedade do relatório.

O método getBookmarks é definido da seguinte maneira:

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

Por exemplo:

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

Aplicar um indicador salvo por nome na carga 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 método do objeto BookmarksManager de retornado pela propriedade de um relatório.

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

O método apply é 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 método de um objeto BookmarksManager . O método capture retorna um objeto IReportBookmark, que representa um indicador que não é salvo em um relatório específico. Use a propriedade IReportBookmark.state para retornar a cadeia de caracteres base64 identificando 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 método capture é definido da seguinte maneira:

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

Por exemplo:

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

Opções de indicador de captura

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

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 método com allPages opção definida como true.
  • personalizeVisuals – Para capturar o estado atual com visuais personalizados, chame o método capture com a opção personalizeVisuals definida como true.

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 método applyState de um objeto BookmarksManager.

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

O método applyState é 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 evento bookmarkApplied chamando o método on do relatório objeto.

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 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.

Inserir 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 método play de um objeto BookmarksManager. Para obter mais informações, consulte Indicadores como uma apresentação de slides.

O método play é definido da seguinte maneira:

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

Nota

Antes de inserir o 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 da 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);

Considerações e 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 pelos filtros de atualização adicionam a operaçã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 valor All e modificado na sessão de inserção usando a operação de atualização de filtros de atualização .

Conteúdo relacionado