Adicionar suporte a indicadores a visuais em relatórios do Power BI
Com indicadores 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 exibição salva de maneira rápida e fácil sempre que quiser. O indicador salva toda a configuração, incluindo seleções e filtros.
Para obter mais informações sobre indicadores, confira Usar indicadores para compartilhar informações e criar histórias no Power BI.
Visuais compatíveis com indicadores
Um visual do Power BI compatível com indicadores 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 no indicador nas propriedades filterState do visual.
Observação
A criação de um visual compatível com indicadores requer:
- Powerbi-visuals-utils-interactivityutils versão 3.0.0 ou posterior para visuais de filtro e outros visuais que usem
InteractivityService. - API de visual versão 1.11.0 ou posterior para visuais sem filtro que usem
SelectionManagerem vez deInteractivityService. - Para descobrir qual versão você está usando, verifique
apiVersionno 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 host. 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, emISelectionManager. - Se o visual usar filtros para selecionar dados, redefina os valores de filtro para os valores correspondentes do indicador selecionado.
Visuais com seleção
Se o visual interage com outros visuais usando a Seleção, você pode adicionar suporte a indicadores de uma de duas maneiras:
- Por meio de InteractivityService para gerenciar seleções (use o
applySelectionFromFilter). Esse é o método preferencial e mais fácil. - Por meio de SelectionManager, se o visual não usar InteractivityService.
Usar InteractivityService para restaurar seleções de indicador
Se o visual usar InteractivityService, você não precisará de nenhuma outra ação para dar suporte aos indicadores em seu visual.
Quando você seleciona um indicador, o utilitário manipula automaticamente o estado de seleção do visual.
Usar SelectionManager para restaurar seleções de indicador
Se você não estiver usando InteractivityService, poderá salvar e fazer recall de seleções de indicador usando o método ISelectionManager.registerOnSelectCallback da seguinte forma:
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 indicador.
Visuais com um filtro
Para dar suporte a indicadores em visuais que têm 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 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 deverá 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 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).
Importante
No cenário de indicadores 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 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 indicadores.
A propriedade filterState salva um aspecto de filtro como uma propriedade. O visual pode armazenar valores filterState diferentes em indicadores.
Para salvar um valor da propriedade como um estado de filtro, defina a propriedade de objeto como "filterState": true no arquivo capabilities.json.