Partager via


Ajouter la prise en charge des signets aux visuels dans les rapports Power BI

Avec les signets de rapport Power BI, vous pouvez capturer et enregistrer une vue configurée d’une page de rapport. Vous pouvez ensuite revenir à la vue enregistrée rapidement et facilement chaque fois que vous le souhaitez. Le signet enregistre l’ensemble de la configuration, dont les sélections et les filtres.

Pour plus d'informations sur les signets, consultez Utiliser des signets pour partager des insights et créer des récits dans Power BI.

Visuels prenant en charge les signets

Un visuel Power BI qui prend en charge les signets doit être en mesure d’enregistrer et de fournir les informations correctes, si nécessaire. Si votre visuel interagit avec d’autres visuels, qu’il sélectionne des points de données ou qu’il filtre d’autres visuels, vous devez enregistrer l’état marqué d’un signet dans les propriétés filterState du visuel.

Notes

La création d’un visuel qui prend en charge les signets nécessite les éléments suivants :

  • API visuelle version 1.11.0 ou ultérieure pour les visuels non filtrés qui utilisent SelectionManager.
  • API visuelle version 2.6.0 ou ultérieure pour les visuels de filtre.
  • Pour savoir quelle version vous utilisez, consultez le apiVersion fichier pbiviz.json .

Interaction des visuels Power BI avec Power BI dans les signets de rapport

Supposons que vous voulez créer plusieurs signets sur une page de rapport, avec des points de données différents sélectionnés pour chaque signet.

Tout d’abord, sélectionnez un ou plusieurs points de données dans votre visuel. Le visuel passe vos sélections à l’hôte. Sélectionnez ensuite Ajouter dans le volet Signet. Power BI enregistre les sélections actuelles pour le nouveau signet.

Effectuez cette opération plusieurs fois pour créer de nouveaux signets. Une fois que vous avez créé les signets, vous pouvez basculer entre eux.

Chaque fois que vous sélectionnez un signet, Power BI restaure l’état de sélection ou de filtre enregistré, puis le passe aux visuels. Les visuels du rapport sont mis en évidence ou filtrés en fonction de l’état stocké dans le signet. Pour restaurer l’état correct, votre visuel doit passer l’état de sélection approprié à l’hôte (par exemple, les couleurs des points de données rendus).

Le nouvel état de sélection (ou filtre) est communiqué par le biais de la propriété options.jsonFilters dans la méthode update. jsonFilters peut avoir la valeur Advanced Filter ou Tuple Filter.

  • Si votre visuel contient des points de données sélectionnés, réinitialisez la sélection sur celle du signet sélectionné à l’aide de la fonction de rappel, registerOnSelectCallback, dans ISelectionManager.
  • Si votre visuel utilise des filtres pour sélectionner des données, réinitialisez les valeurs de filtre sur les valeurs correspondantes du signet sélectionné.

Visuels avec une sélection

Remarque

InteractivityService a été déconseillé.

Si votre visuel interagit avec d’autres visuels à l’aide de Selection, vous pouvez ajouter des signets de deux façons :

Utiliser InteractivityService pour restaurer des sélections de signets - déconseillé

Si votre visuel utilise InteractivityService, vous n’avez pas besoin d’autres actions pour prendre en charge les signets dans votre visuel.

Quand vous sélectionnez un signet, l’utilitaire gère automatiquement l’état de sélection du visuel.

Utiliser SelectionManager pour restaurer les sélections de signets

Vous pouvez enregistrer et rappeler les sélections de signet à l’aide de la ISelectionManager.registerOnSelectCallback méthode comme suit :

Quand vous sélectionnez un signet, Power BI appelle la méthode callback du visuel avec les sélections correspondantes.

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

Supposons que vous avez créé un point de données dans la méthode visualTransform de votre visuel.

datapoints ressemble à ceci :

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

Vous avez maintenant visualDataPoints comme points de données et le tableau ids qui est passé à la fonction callback.

À ce stade, le visuel doit comparer le tableau ISelectionId[] avec les sélections indiquées dans votre tableau visualDataPoints, puis marquer les points de données correspondants comme étant sélectionnés.

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

Une fois les points de données mis à jour, ils doivent refléter l’état de sélection actuel stocké dans l’objet filter. Ensuite, quand les points de données sont affichés, l’état de sélection du visuel personnalisé correspond à l’état du signet.

Visuels avec un filtre

Supposons que le visuel crée un filtre de données par plage de dates. startDate et endDate définissent les dates de début et de fin de la plage.

Le visuel crée un filtre avancé et appelle la méthode hôte applyJsonFilter pour filtrer les données selon les conditions appropriées.

La cible est la table utilisée pour le filtrage.

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

Chaque fois que vous sélectionnez un signet, le visuel personnalisé reçoit un appel update.

Dans la méthode update, le visuel vérifie le filtre dans l’objet :

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

Si l’objet filter n’est pas Null, le visuel restaure les conditions de filtre à partir de l’objet :

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
}

Après cela, le visuel change d’état interne pour qu’il corresponde aux conditions actuelles. L’état interne inclut les points de données et les objets de visualisation (lignes, rectangles, etc.).

Le visuel Timeline Slicer change le sélecteur de plage pour refléter les plages de données correspondantes.

Enregistrer l’état de filtre du visuel

Outre l’enregistrement des conditions du filtre pour le signet, vous pouvez également enregistrer d’autres aspects du filtre.

Par exemple, Timeline Slicer stocke les valeurs de la propriété Granularity comme un état de filtre. Il permet à la précision de la chronologie (jours, mois, années, etc.) de changer à mesure que vous changez les signets.

La propriété filterState enregistre un aspect de filtre en tant que propriété. Le visuel peut stocker différentes valeurs filterState dans les signets.

Pour enregistrer une valeur de propriété comme un état de filtre, définissez la propriété de l’objet sur "filterState": true dans le fichier capabilities.json.