Condividi tramite

Aggiungere il supporto dei segnalibri agli oggetti visivi nei report di Power BI

  • Articolo

Con i segnalibri del report di Power BI è possibile acquisire e salvare una visualizzazione configurata di una pagina del report. Si può quindi tornare alla visualizzazione salvata in modo rapido e semplice ogni volta che lo si desidera. Il segnalibro salva l'intera configurazione, incluse le selezioni e i filtri.

Per altre informazioni sui segnalibri, vedere Usare i segnalibri per condividere informazioni dettagliate e creare storie in Power BI.

Oggetti visivi che supportano i segnalibri

Un oggetto visivo di Power BI che supporta i segnalibri deve essere in grado di salvare e fornire le informazioni corrette, quando necessario. Se l'oggetto visivo interagisce con altri oggetti visivi, seleziona i punti dati o filtra altri oggetti visivi, è necessario salvare lo stato con segnalibro nelle proprietà filterState dell'oggetto visivo.

Nota

La creazione di un oggetto visivo che supporta i segnalibri richiede:

  • API per gli oggetti visivi versione 1.11.0 o successive per gli oggetti visivi non di filtro che usano SelectionManager.
  • API per gli oggetti visivi versione 2.6.0 o successive per gli oggetti visivi di filtro.
  • Per scoprire quale versione si sta usando, archiviare apiVersion nel file pbiviz.json.

Interazione degli oggetti visivi di Power BI con Power BI nei segnalibri del report

Si supponga di voler creare diversi segnalibri in una pagina del report, in cui ogni segnalibro abbia diversi punti di dati selezionati.

Selezionare prima di tutto uno o più punti dati nell'oggetto visivo. L'oggetto visivo passa le selezioni all'host. Selezionare quindi Aggiungi nel riquadro Segnalibro. Power BI salva le selezioni correnti per il nuovo segnalibro.

Per creare nuovi segnalibri, eseguire questa operazione più volte. Dopo aver creato i segnalibri, è possibile spostarsi tra di essi.

Ogni volta che si seleziona un segnalibro, Power BI ripristina lo stato di selezione o di filtro salvato e lo passa agli oggetti visivi. Gli oggetti visivi nel report vengono evidenziati o filtrati in base allo stato archiviato nel segnalibro. Per ripristinare lo stato corretto, l'oggetto visivo deve passare lo stato di selezione giusto all'host, ad esempio i colori dei punti dati di cui è stato eseguito il rendering.

Il nuovo stato di selezione (o filtro) viene comunicato tramite la proprietà options.jsonFilters nel metodo update. jsonFilters può essere Advanced Filter o Tuple Filter.

  • Se l'oggetto visivo contiene punti dati selezionati, reimpostare la selezione su quella del segnalibro scelto usando la funzione di richiamata, registerOnSelectCallback, in ISelectionManager.
  • Se l'oggetto visivo usa filtri per selezionare i dati, reimpostare i valori del filtro sui valori corrispondenti del segnalibro scelto.

Oggetti visivi con selezione

Nota

InteractivityService è stato deprecato.

Se l'oggetto visivo interagisce con altri oggetti visivi usando Selezione, è possibile aggiungere il supporto dei segnalibri in uno dei due modi seguenti:

Usare InteractivityService per ripristinare le selezioni dei segnalibri - Deprecato

Se l'oggetto visivo usa InteractivityService, non sono necessarie ulteriori azioni per supportare i segnalibri nell'oggetto visivo.

Quando si seleziona un segnalibro, l'utilità gestisce automaticamente lo stato di selezione dell'oggetto visivo.

Usare SelectionManager per ripristinare le selezioni dei segnalibri

È possibile salvare e richiamare le selezioni dei segnalibri usando il metodo ISelectionManager.registerOnSelectCallback, come indicato di seguito:

Quando si seleziona un segnalibro, Power BI chiama il metodo callback dell'oggetto visivo con le selezioni corrispondenti.

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

Si supponga di aver creato un punto dati nel metodo visualTransform dell'oggetto visivo.

datapoints è simile al seguente:

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
});

Sono ora presenti visualDataPoints come punti dati e la matrice ids passata alla funzione callback.

A questo punto, l'oggetto visivo deve confrontare la matrice ISelectionId[] con le selezioni nella matrice visualDataPoints e quindi contrassegnare i punti dati corrispondenti come selezionati.

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

Una volta aggiornati, i punti dati riflettono lo stato di selezione corrente archiviato nell'oggetto filter. Quando viene eseguito il rendering dei punti dati, lo stato di selezione dell'oggetto visivo personalizzato corrisponde allo stato del segnalibro.

Oggetti visivi con un filtro

Si supponga che l'oggetto visivo crei un filtro di dati in base all'intervallo di date. startDate ed endDate sono le date di inizio e di fine dell'intervallo.

L'oggetto visivo crea un filtro avanzato e chiama il metodo host applyJsonFilter per filtrare i dati in base alle condizioni pertinenti.

La destinazione è la tabella usata per il filtro.

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
);

Ogni volta che si seleziona un segnalibro, l'oggetto visivo riceve una chiamata update.

Nel metodo update l'oggetto visivo controlla il filtro nell'oggetto:

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

Se l'oggetto filter non è null, l'oggetto visivo ripristina le condizioni di filtro dall'oggetto:

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
}

Successivamente, l'oggetto visivo modifica lo stato interno in modo che corrisponda alle condizioni correnti. Lo stato interno include i punti dati e gli oggetti di visualizzazione (linee, rettangoli e così via).

L'oggetto visivo del filtro dei dati della sequenza temporale imposta il selettore di intervallo sugli intervalli di dati corrispondenti.

Salvare lo stato del filtro dell'oggetto visivo

Oltre a salvare le condizioni del filtro per il segnalibro, è anche possibile salvare altri aspetti del filtro.

Il filtro dei dati della sequenza temporale, ad esempio, archivia i valori della proprietà Granularity come stato di filtro. Consente di modificare la granularità della sequenza temporale (giorni, mesi, anni e così via) quando si cambiano i segnalibri.

La proprietà filterState salva un aspetto del filtro come proprietà. L'oggetto visivo può archiviare vari valori filterState nei segnalibri.

Per salvare un valore della proprietà come stato del filtro, impostare la proprietà dell'oggetto come "filterState": true nel file capabilities.json.

Contenuto correlato