Aggiungere il supporto per i segnalibri per oggetti visivi di Power BIAdd bookmark support for Power BI visuals

  • 4 minuti per la lettura

Con i segnalibri dei report di Power BI, è possibile acquisire una visualizzazione configurata di una pagina del report, lo stato di selezione e lo stato di filtro dell'oggetto visivo.With Power BI report bookmarks, you can capture a configured view of a report page, the selection state, and the filtering state of the visual. Tuttavia è necessaria un'azione aggiuntiva sul lato degli oggetti visivi di Power BI, per supportare i segnalibri e rispondere correttamente alle modifiche.But it requires additional action from the Power BI visuals side to support the bookmark and react correctly to changes.

Per altre informazioni sui segnalibri, vedere Usare i segnalibri per condividere informazioni dettagliate e creare storie in Power BI.For more information about bookmarks, see Use bookmarks to share insights and build stories in Power BI.

Supporto per segnalibri del report nell'oggetto visivoReport bookmarks support in your visual

Se l'oggetto visivo interagisce con altri oggetti visivi, seleziona punti dati o filtra altri oggetti visivi, è necessario ripristinare lo stato dalle proprietà.If your visual interacts with other visuals, selects data points, or filters other visuals, you need to restore the state from properties.

Aggiungere il supporto per i segnalibri del reportAdd report bookmarks support

  1. Installare (o aggiornare) l'utilità necessaria, powerbi-visuals-utils-interactivityutils versione 3.0.0 o successiva.Install (or update) the required utility, powerbi-visuals-utils-interactivityutils version 3.0.0 or later. Contiene classi aggiuntive da modificare con lo stato selezione o filtro.It contains additional classes to manipulate with the state selection or filter. È necessaria per gli oggetti visivi di filtro e per qualsiasi oggetto visivo che usa InteractivityService.It's required for filter visuals and any visual that uses InteractivityService.

  2. Aggiornare l'API per oggetti visivi alla versione 1.11.0 per usare registerOnSelectCallback in un'istanza di SelectionManager.Update the visual API to version 1.11.0 to use registerOnSelectCallback in an instance of SelectionManager. È necessaria per gli oggetti visivi non di filtro che usano SelectionManager semplice anziché InteractivityService.It's required for non-filter visuals that use the plain SelectionManager rather than InteractivityService.

Interazione degli oggetti visivi di Power BI con Power BI nei segnalibri del reportHow Power BI visuals interact with Power BI in report bookmarks

Si consideri lo scenario seguente: si vogliono creare diversi segnalibri nella pagina del report, con uno stato di selezione diverso in ogni segnalibro.Let's consider the following scenario: you want to create several bookmarks on the report page, with a different selection state in each bookmark.

In primo luogo, si seleziona un punto dati nell'oggetto visivo.First, you select a data point in your visual. L'oggetto visivo interagisce con Power BI e altri oggetti visivi passando le selezioni all'host.The visual interacts with Power BI and other visuals by passing selections to the host. Si seleziona quindi Aggiungi nel riquadro Segnalibro e Power BI salva le selezioni correnti per il nuovo segnalibro.You then select Add in the Bookmark pane, and Power BI saves the current selections for the new bookmark.

Questo si verifica ripetutamente quando si modifica la selezione e si aggiungono nuovi segnalibri.It happens repeatedly as you change the selection and add new bookmarks. Dopo aver creato i segnalibri, è possibile spostarsi tra di essi.After you create the bookmarks, you can switch between them.

Quando si seleziona un segnalibro, Power BI ripristina lo stato di selezione o di filtro salvato e lo passa agli oggetti visivi.When you select a bookmark, Power BI restores the saved filter or selection state and passes it to the visuals. Gli altri oggetti visivi vengono evidenziati o filtrati in base allo stato archiviato nel segnalibro.Other visuals are highlighted or filtered according to the state that's stored in the bookmark. L'host Power BI è responsabile delle azioni.The Power BI host is responsible for the actions. L'oggetto visivo è responsabile di far riflettere correttamente il nuovo stato di selezione, ad esempio per la modifica dei colori dei punti dati di cui è stato eseguito il rendering.Your visual is responsible for correctly reflecting the new selection state (for example, for changing the colors of rendered data points).

Il nuovo stato di selezione viene comunicato all'oggetto visivo tramite il metodo update.The new selection state is communicated to the visual through the update method. L'argomento options contiene una proprietà speciale, options.jsonFilters.The options argument contains a special property, options.jsonFilters. La proprietà JSONFilter può contenere Advanced Filter e Tuple Filter.Its JSONFilter property can contain Advanced Filter and Tuple Filter.

L'oggetto visivo deve ripristinare i valori di filtro per visualizzare lo stato corrispondente dell'oggetto visivo per il segnalibro selezionato.The visual should restore the filter values to display the corresponding state of the visual for the selected bookmark. In alternativa, se l'oggetto visivo usa solo selezioni, è possibile usare la chiamata della funzione di callback speciale registrata come metodo registerOnSelectCallback di ISelectionManager.Or, if the visual uses selections only, you can use the special callback function call that's registered as the registerOnSelectCallback method of ISelectionManager.

Oggetti visivi con selezioneVisuals with Selection

Se l'oggetto visivo interagisce con altri oggetti visivi usando Selection, è possibile aggiungere i segnalibri in uno dei due modi seguenti:If your visual interacts with other visuals by using Selection, you can add bookmarks in either of two ways:

  • Se l'oggetto visivo non ha già usato InteractivityService, è possibile usare il metodo FilterManager.restoreSelectionIds.If the visual hasn't already used InteractivityService, you can use the FilterManager.restoreSelectionIds method.

  • Se l'oggetto visivo usa già InteractivityService per gestire le selezioni, è consigliabile usare il metodo applySelectionFromFilter nell'istanza di InteractivityService.If the visual already uses InteractivityService to manage selections, you should use the applySelectionFromFilter method in the instance of InteractivityService.

Usare ISelectionManager.registerOnSelectCallbackUse ISelectionManager.registerOnSelectCallback

Quando si seleziona un segnalibro, Power BI chiama il metodo callback dell'oggetto visivo con le selezioni corrispondenti.When you select a bookmark, Power BI calls the callback method of the visual with the corresponding selections.

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

Si supponga di avere un punto dati nell'oggetto visivo creato nel metodo visualTransform.Let's assume that you have a data point in your visual that was created in the visualTransform method.

datapoints ha un aspetto simile al seguente:And datapoints looks like:

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.You now have visualDataPoints as your data points and the ids array passed to the callback function.

A questo punto, l'oggetto visivo deve confrontare la matrice ISelectionId[] con le selezioni nella matrice visualDataPoints e contrassegnare i punti dati corrispondenti come selezionati.At this point, the visual should compare the ISelectionId[] array with the selections in your visualDataPoints array and mark the corresponding data points as selected.

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.After you update the data points, they'll reflect the current selection state that's stored in the filter object. Quando viene eseguito il rendering dei punti dati, lo stato di selezione dell'oggetto visivo personalizzato corrisponderà allo stato del segnalibro.Then, when the data points are rendered, the custom visual's selection state will match the state of the bookmark.

Usare InteractivityService per le selezioni dei controlli nell'oggetto visivoUse InteractivityService for control selections in the visual

Se l'oggetto visivo usa InteractivityService, non è necessario eseguire altre azioni per supportare i segnalibri al suo interno.If your visual uses InteractivityService, you don't need any additional actions to support the bookmarks in your visual.

Quando si selezionano i segnalibri, l'utilità gestisce lo stato di selezione dell'oggetto visivo.When you select bookmarks, the utility handles the visual's selection state.

Oggetti visivi con un filtroVisuals with a filter

Si supponga che l'oggetto visivo crei un filtro di dati in base all'intervallo di date.Let's assume that the visual creates a filter of data by date range. startDate ed endDate sono le date di inizio e di fine dell'intervallo.You have startDate and endDate as the start and end dates of the range.

L'oggetto visivo crea un filtro avanzato e chiama il metodo host applyJsonFilter per filtrare i dati in base alle condizioni pertinenti.The visual creates an advanced filter and calls the host method applyJsonFilter to filter data by the relevant conditions.

La destinazione è la tabella usata per il filtro.The target is the table that's used for filtering.

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.Each time you select a bookmark, the custom visual gets an update call.

L'oggetto visivo personalizzato deve controllare il filtro nell'oggetto:The custom visual should check the filter in the object:

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

Se l'oggetto filter non è null, l'oggetto visivo deve ripristinare le condizioni di filtro dall'oggetto:If the filter object isn't null, the visual should restore the filter conditions from the object:

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
}

A questo punto, l'oggetto visivo deve modificare lo stato interno per riflettere le condizioni correnti.After that, the visual should change its internal state to reflect the current conditions. Lo stato interno include i punti dati e gli oggetti di visualizzazione (linee, rettangoli e così via).The internal state includes the data points and visualization objects (lines, rectangles, and so on).

Importante

Nello scenario dei segnalibri del report, l'oggetto visivo non deve chiamare applyJsonFilter per filtrare gli altri oggetti visivi,In the report bookmarks scenario, the visual shouldn't call applyJsonFilter to filter the other visuals. che verranno già filtrati da Power BI.They will already be filtered by Power BI.

L'oggetto visivo del filtro dei dati della sequenza temporale imposta il selettore di intervallo sugli intervalli di dati corrispondenti.The Timeline Slicer visual changes the range selector to the corresponding data ranges.

Per altre informazioni, vedere il repository di Timeline Slicer.For more information, see the Timeline Slicer repository.

Filtrare lo stato per salvare le proprietà dell'oggetto visivo nei segnalibriFilter the state to save visual properties in bookmarks

La proprietà filterState crea una proprietà di una parte del filtro.The filterState property makes a property of a part of filtering. L'oggetto visivo può archiviare svariati valori nei segnalibri.The visual can store a variety of values in bookmarks.

Per salvare il valore della proprietà come stato del filtro, contrassegnare la proprietà dell'oggetto come "filterState": true nel file capabilities.json.To save the property value as a filter state, mark the object property as "filterState": true in the capabilities.json file.

Il filtro dei dati della sequenza temporale, ad esempio, archivia i valori della proprietà Granularity in un filtro.For example, the Timeline Slicer stores the Granularity property values in a filter. Consente la modifica della granularità corrente quando si modificano i segnalibri.It allows the current granularity to change as you change the bookmarks.

Per altre informazioni, vedere il repository di Timeline Slicer.For more information, see the Timeline Slicer repository.