Compartilhar via

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

Com marcadores de relatório do Power BI, você pode capturar e salvar uma visualização configurada de uma página de relatório. Em seguida, você pode voltar para a exibição salva de maneira 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, confira Usar marcadores para compartilhar informações e criar histórias no Power BI.

Visuais compatíveis com indicadores

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

Observação

A criação de um visual que suporte marcadores requer:

  • Visual API versão 1.11.0 ou posterior para visuais sem filtro que usam SelectionManager.
  • Visual API versão 2.6.0 ou posterior para visuais de filtro.
  • Para descobrir qual versão você está usando, verifique apiVersion no arquivo pbiviz.json.

Como os visuais do Power BI interagem com o Power BI em indicadores de relatório

Vamos considerar que você deseja criar vários indicadores em uma página de relatório, com pontos de dados diferentes selecionados em cada indicador.

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

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

Quando você seleciona um indicador, o Power BI restaura o estado de seleção ou o filtro salvo e passa para os visuais. Os visuais no relatório são realçados ou filtrados de acordo com o estado armazenado no indicador. Para restaurar o estado correto, seu 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 por meio da propriedade options.jsonFilters no método update. O jsonFilters pode ser Advanced Filter ou Tuple Filter.

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

Visuais com seleção

Observação

O uso de InteractivityService foi preterido.

Se o visual interage com outros visuais usando a Seleção, você pode adicionar suporte a favoritos de duas formas:

Use InteractivityService para restaurar seleções de marcadores - obsoleto

Se o seu visual usar InteractivityService, você não precisará de nenhuma outra ação para dar suporte aos marcadores em seu visual.

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

Usar SelectionManager para restaurar seleções de marcador

Você pode salvar e recuperar seleções de favoritos usando o ISelectionManager.registerOnSelectCallback método da seguinte maneira:

Quando você seleciona um indicador, o Power BI chama o método callback 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 visual.

O datapoints tem esta aparência:

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 matriz ids passados para a função callback.

Neste ponto, o visual deve comparar a matriz de ISelectionId[] com as seleções em sua matriz visualDataPoints e, em seguida, marcar os pontos de dados correspondentes conforme 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 estado de seleção atual armazenado no objeto filter. Em seguida, quando os pontos de dados são renderizados, o estado de seleção do visual personalizado corresponde ao estado do marcador.

Visuais com um filtro

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 de término do intervalo.

O visual cria um filtro avançado e chama o método de host applyJsonFilter 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 indicador, o visual personalizado recebe uma chamada update.

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

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

Se o objeto filter não for nulo, o visual restaura as condições de filtro a partir 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 altera o próprio estado interno para refletir as condições atuais. O estado interno inclui os pontos de dados e os objetos de visualização (linhas, retângulos e assim por diante).

O visual da Segmentação 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 indicador, você também pode salvar outros aspectos do filtro.

Por exemplo, a Segmentação de Linha do Tempo armazena os valores de propriedade Granularity como um estado de filtro. Ele permite que a granularidade da linha do tempo (dias, meses, anos, etc.) mude conforme você altera os marcadores.

A propriedade filterState salva um elemento de filtro como uma propriedade. O visual pode armazenar diversos valores filterState em marcadores.

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

Conteúdo relacionado