Partilhar via

Adicionar suporte a marcadores a elementos visuais em relatórios do Power BI

  • Artigo

Com os marcadores de relatório do Power BI, você pode capturar e salvar uma exibição configurada de uma página de relatório. Em seguida, você pode voltar para a visualização salva de forma rápida e fácil sempre que quiser. O marcador salva toda a configuração, incluindo seleções e filtros.

Para obter mais informações sobre marcadores, consulte Usar marcadores para compartilhar informações e criar histórias no Power BI.

Elementos visuais que suportam marcadores

Um visual do Power BI que ofereça suporte a marcadores deve ser capaz de salvar e fornecer as informações corretas quando necessário. Se o visual interage com outros elementos visuais, seleciona pontos de dados ou filtra outros elementos visuais, você precisa salvar o estado marcado nas propriedades filterState do visual.

Nota

Criar um visual que suporte marcadores requer:

  • Powerbi-visuals-utils-interactivityutils versão 3.0.0 ou posterior para visuais de filtro e qualquer visual que use InteractivityService.
  • Visual API versão 1.11.0 ou posterior para visuais sem filtro que usam SelectionManager em vez de InteractivityService.
  • Para saber qual versão você está usando, verifique a apiVersion no arquivo pbiviz.json .

Como os visuais do Power BI interagem com o Power BI nos marcadores de relatório

Digamos que você queira criar vários marcadores em uma página de relatório com cada marcador com diferentes pontos de dados selecionados.

Primeiro, selecione um ou mais pontos de dados no seu visual. O visual passa suas seleções para o anfitrião. Em seguida, selecione Adicionar no painel Favorito. O Power BI salva as seleções atuais para o novo indicador.

Faça isso várias vezes para criar novos favoritos. Depois de criar os favoritos, você pode alternar entre eles.

Sempre que seleciona um marcador, o Power BI restaura o filtro guardado ou o estado de seleção e passa-o para os elementos visuais. Os elementos visuais no relatório são realçados ou filtrados de acordo com o estado armazenado no marcador. Para restaurar o estado correto, o visual deve passar o estado de seleção correto para o host (por exemplo, as cores dos pontos de dados renderizados).

O novo estado de seleção (ou filtro) é comunicado através da options.jsonFilters propriedade no update método. O jsonFilters pode ser qualquer um Advanced Filter ou Tuple Filter.

  • Se o visual contiver pontos de dados selecionados, redefina a seleção para a do marcador selecionado usando a função de retorno de chamada, registerOnSelectCallback, em ISelectionManager.
  • Se o visual usar filtros para selecionar dados, redefina os valores do filtro para os valores correspondentes do marcador selecionado.

Elementos visuais com seleção

Se o visual interagir com outros elementos visuais usando a Seleção, você poderá adicionar suporte a favoritos de uma das duas maneiras:

  • Através do InteractivityService para gerenciar seleções, use o applySelectionFromFilter. Este é o método mais fácil e preferido.
  • Através do SelectionManager, se o seu visual não usar o InteractivityService.

Use InteractivityService para restaurar seleções de favoritos

Se o seu visual usa o InteractivityService, você não precisa de nenhuma outra ação para dar suporte aos marcadores no seu visual.

Quando você seleciona um marcador, o utilitário manipula automaticamente o estado de seleção do visual.

Use o SelectionManager para restaurar seleções de favoritos

Se você não estiver usando InteractivityServiceo , poderá salvar e recuperar seleções de favoritos usando o método da ISelectionManager.registerOnSelectCallback seguinte maneira:

Quando você seleciona um indicador, o Power BI chama o callback método do visual com as seleções correspondentes.

this.selectionManager.registerOnSelectCallback(
    (ids: ISelectionId[]) => {
        //called when a selection was set by Power BI
    });
);

Vamos supor que você criou um ponto de dados no método visualTransform do seu visual.

A datapoints aparência é esta:

visualDataPoints.push({
    category: categorical.categories[0].values[i],
    color: getCategoricalObjectValue<Fill>(categorical.categories[0], i, 'colorSelector', 'fill', defaultColor).solid.color,
    selectionId: host.createSelectionIdBuilder()
        .withCategory(categorical.categories[0], i)
        .createSelectionId(),
    selected: false
});

Agora você tem visualDataPoints como seus pontos de dados e a ids matriz passada para a callback função.

Neste ponto, o visual deve comparar a ISelectionId[] matriz com as seleções em sua visualDataPoints matriz e, em seguida, marcar os pontos de dados correspondentes como selecionados.

this.selectionManager.registerOnSelectCallback(
    (ids: ISelectionId[]) => {
        visualDataPoints.forEach(dataPoint => {
            ids.forEach(bookmarkSelection => {
                if (bookmarkSelection.equals(dataPoint.selectionId)) {
                    dataPoint.selected = true;
                }
            });
        });
    });
);

Depois de atualizar os pontos de dados, eles refletirão o filter estado de seleção atual armazenado no objeto. Em seguida, quando os pontos de dados são renderizados, o estado de seleção do visual personalizado corresponde ao estado do indicador.

Elementos visuais com um filtro

Para dar suporte a marcadores em elementos visuais que tenham um filtro, use InteractivityService.

Vamos supor que o visual crie um filtro de dados por intervalo de datas. Você tem startDate e endDate como as datas de início e fim do intervalo.

O visual cria um filtro avançado e chama o método applyJsonFilter host para filtrar dados pelas condições relevantes.

O destino é a tabela usada para filtragem.

import { AdvancedFilter } from "powerbi-models";

const filter: IAdvancedFilter = new AdvancedFilter(
    target,
    "And",
    {
        operator: "GreaterThanOrEqual",
        value: startDate
            ? startDate.toJSON()
            : null
    },
    {
        operator: "LessThanOrEqual",
        value: endDate
            ? endDate.toJSON()
            : null
    });

this.host.applyJsonFilter(
    filter,
    "general",
    "filter",
    (startDate && endDate)
        ? FilterAction.merge
        : FilterAction.remove
);

Cada vez que você seleciona um marcador, o visual personalizado recebe uma update chamada.

No método, o update visual verifica o filtro no objeto:

const filter: IAdvancedFilter = FilterManager.restoreFilter(
    && options.jsonFilters
    && options.jsonFilters[0] as any
) as IAdvancedFilter;

Se o filter objeto não for nulo, o visual restaurará as condições de filtro do objeto:

const jsonFilters: AdvancedFilter = this.options.jsonFilters as AdvancedFilter[];

if (jsonFilters
    && jsonFilters[0]
    && jsonFilters[0].conditions
    && jsonFilters[0].conditions[0]
    && jsonFilters[0].conditions[1]
) {
    const startDate: Date = new Date(`${jsonFilters[0].conditions[0].value}`);
    const endDate: Date = new Date(`${jsonFilters[0].conditions[1].value}`);

    // apply restored conditions
} else {
    // apply default settings
}

Depois disso, o visual muda seu estado interno para corresponder às condições atuais. O estado interno inclui os pontos de dados e objetos de visualização (linhas, retângulos e assim por diante).

Importante

No cenário de marcadores de relatório acima, o visual não deve chamar applyJsonFilter para filtrar os outros elementos visuais. Eles já serão filtrados pelo Power BI.

O visual da segmentação de dados da linha do tempo altera o seletor de intervalo para os intervalos de dados correspondentes.

Salvar o estado do filtro do visual

Além de salvar as condições do filtro para o marcador, você também pode salvar outros aspetos do filtro.

Por exemplo, a segmentação de dados de linha do tempo armazena os valores de Granularity propriedade como um estado de filtro. Ele permite que a granularidade da linha do tempo (dias, meses, anos, etc.) mude à medida que você altera os favoritos.

A filterState propriedade salva um aspeto de filtro como uma propriedade. O visual pode armazenar vários filterState valores em favoritos.

Para salvar um valor de propriedade como um estado de filtro, defina a propriedade object como "filterState": true no arquivo capabilities.json .

Conteúdos relacionados