Přidání podpory záložek pro vizuály Power BIAdd bookmark support for Power BI visuals

Pomocí záložek sestavy Power BI můžete zachytit nakonfigurované zobrazení stránky sestavy, stav výběru a stav filtrování vizuálu.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. Podpora záložek a správné reakce na změny ale vyžadují další akci ze strany vizuálů Power BI.But it requires additional action from the Power BI visuals side to support the bookmark and react correctly to changes.

Další informace o záložkách najdete v tématu Použití záložek ke sdílení přehledů a sestavení příběhů v Power BI.For more information about bookmarks, see Use bookmarks to share insights and build stories in Power BI.

Podpora záložek sestavy ve vizuáluReport bookmarks support in your visual

Pokud vizuál komunikuje s jinými vizuály, vybírá datové body nebo filtruje jiné vizuály, je nutné obnovit stav z vlastností.If your visual interacts with other visuals, selects data points, or filters other visuals, you need to restore the state from properties.

Přidání podpory záložek sestavyAdd report bookmarks support

  1. Nainstalujte (nebo aktualizujte) požadovaný nástroj powerbi-visuals-utils-interactivityutils verze 3.0.0 nebo novější.Install (or update) the required utility, powerbi-visuals-utils-interactivityutils version 3.0.0 or later. Tento nástroj obsahuje další třídy pro manipulaci s výběrem stavu nebo filtrem.It contains additional classes to manipulate with the state selection or filter. Vyžaduje se u vizuálů s filtrem a u všech vizuálů, které používají objekt InteractivityService.It's required for filter visuals and any visual that uses InteractivityService.

  2. Aktualizujte rozhraní API vizuálů na verzi 1.11.0, aby se používala metoda registerOnSelectCallback v instanci objektu SelectionManager.Update the visual API to version 1.11.0 to use registerOnSelectCallback in an instance of SelectionManager. Vyžaduje se to u vizuálů bez filtru, které používají prostý objekt SelectionManager, nikoli objekt InteractivityService.It's required for non-filter visuals that use the plain SelectionManager rather than InteractivityService.

Interakce vizuálů Power BI s Power BI v záložkách sestavyHow Power BI visuals interact with Power BI in report bookmarks

Předpokládejme následující scénář: Chcete na stránce sestavy vytvořit několik záložek, přičemž v každé záložce má být jiný stav výběru.Let's consider the following scenario: you want to create several bookmarks on the report page, with a different selection state in each bookmark.

Nejprve vyberete datový bod ve vizuálu.First, you select a data point in your visual. Vizuál komunikuje s Power BI a dalšími vizuály tak, že předá výběry hostiteli.The visual interacts with Power BI and other visuals by passing selections to the host. Pak v podokně Záložka vyberete Přidat a Power BI uloží aktuální výběry pro novou záložku.You then select Add in the Bookmark pane, and Power BI saves the current selections for the new bookmark.

K tomu dojde opakovaně, když změníte výběr a přidáte nové záložky.It happens repeatedly as you change the selection and add new bookmarks. Po vytvoření záložek můžete mezi nimi přepínat.After you create the bookmarks, you can switch between them.

Když vyberete záložku, Power BI obnoví uložený filtr nebo stav výběru a předá ho vizuálům.When you select a bookmark, Power BI restores the saved filter or selection state and passes it to the visuals. Ostatní vizuály se zvýrazní nebo vyfiltrují podle stavu uloženého v záložce.Other visuals are highlighted or filtered according to the state that's stored in the bookmark. Za akce zodpovídá hostitel Power BI.The Power BI host is responsible for the actions. Příslušný vizuál zodpovídá za správné vyjádření nového stavu výběru (například za změnu barev vykreslovaných datových bodů).Your visual is responsible for correctly reflecting the new selection state (for example, for changing the colors of rendered data points).

Nový stav výběru se předá do vizuálu prostřednictvím metody update.The new selection state is communicated to the visual through the update method. Argument options obsahuje speciální vlastnost options.jsonFilters.The options argument contains a special property, options.jsonFilters. Tato vlastnost JSONFilter může obsahovat Advanced Filter a Tuple Filter.Its JSONFilter property can contain Advanced Filter and Tuple Filter.

Vizuál by měl obnovit hodnoty filtru na zobrazení odpovídající stavu vizuálu pro vybranou záložku.The visual should restore the filter values to display the corresponding state of the visual for the selected bookmark. Pokud daný vizuál používá jenom výběry, můžete také volat speciální funkci zpětného volání, která je registrována jako metoda registerOnSelectCallback objektu 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.

Vizuály s výběremVisuals with Selection

Pokud vizuál komunikuje s jinými vizuály pomocí výběru, můžete přidat záložky jedním ze dvou způsobů:If your visual interacts with other visuals by using Selection, you can add bookmarks in either of two ways:

  • Pokud vizuál ještě nepoužívá objekt InteractivityService, můžete použít metodu FilterManager.restoreSelectionIds.If the visual hasn't already used InteractivityService, you can use the FilterManager.restoreSelectionIds method.

  • Pokud vizuál už ke správě výběrů používá objekt InteractivityService, měli byste použít metodu applySelectionFromFilter v instanci objektu InteractivityService.If the visual already uses InteractivityService to manage selections, you should use the applySelectionFromFilter method in the instance of InteractivityService.

Použití ISelectionManager.registerOnSelectCallbackUse ISelectionManager.registerOnSelectCallback

Když uživatel vybere záložku, Power BI zavolá metodu callback daného vizuálu s odpovídajícími výběry.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
    });
);

Předpokládejme, že máte ve vizuálu datový bod, který byl vytvořen v metodě visualTransform.Let's assume that you have a data point in your visual that was created in the visualTransform method.

A datapoints vypadá takto: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
});

Jako datové body teď máte visualDataPoints a do funkce callback se předává pole ids.You now have visualDataPoints as your data points and the ids array passed to the callback function.

V tomto okamžiku by měl vizuál porovnat pole ISelectionId[] s výběry v poli visualDataPoints a označit odpovídající datové body jako vybrané.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;
                }
            });
        });
    });
);

Po aktualizaci těchto datových bodů se to odrazí v aktuálním stavu výběru, který je uložený v objektu filter.After you update the data points, they'll reflect the current selection state that's stored in the filter object. Při vykreslování datových bodů pak bude stav výběru vlastního vizuálu odpovídat stavu záložky.Then, when the data points are rendered, the custom visual's selection state will match the state of the bookmark.

Použití objektu InteractivityService k řízení výběrů ve vizuáluUse InteractivityService for control selections in the visual

Pokud vizuál používá objekt InteractivityService, nejsou k podpoře záložek v tomto vizuálu potřeba žádné další akce.If your visual uses InteractivityService, you don't need any additional actions to support the bookmarks in your visual.

Když vyberete záložky, nástroj zpracuje stav výběru daného vizuálu.When you select bookmarks, the utility handles the visual's selection state.

Vizuály s filtremVisuals with a filter

Předpokládejme, že vizuál vytvoří filtr dat podle rozsahu kalendářních dat.Let's assume that the visual creates a filter of data by date range. Jako počáteční a koncové datum rozsahu máte startDate aendDate.You have startDate and endDate as the start and end dates of the range.

K filtrování dat podle příslušných podmínek vizuál vytvoří rozšířený filtr a provede volání metody applyJsonFilter hostitele.The visual creates an advanced filter and calls the host method applyJsonFilter to filter data by the relevant conditions.

Cílem je tabulka, která se používá k filtrování.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
);

Pokaždé, když vyberete záložku, vlastní vizuál provede volání update.Each time you select a bookmark, the custom visual gets an update call.

Vlastní vizuál by měl kontrolovat filtr v příslušném objektu:The custom visual should check the filter in the object:

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

Pokud objekt filter není null, měl by vizuál obnovit podmínky filtru z příslušného objektu: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
}

Potom by měl vizuál změnit svůj vnitřní stav tak, aby odrážel aktuální podmínky.After that, the visual should change its internal state to reflect the current conditions. Vnitřní stav zahrnuje datové body a objekty vizualizace (čáry, obdélníky atd.).The internal state includes the data points and visualization objects (lines, rectangles, and so on).

Důležité

Ve scénáři se záložkami sestavy by vizuál neměl volat applyJsonFilter za účelem filtrování jiných vizuálů.In the report bookmarks scenario, the visual shouldn't call applyJsonFilter to filter the other visuals. Ty už budou vyfiltrovány pomocí Power BI.They will already be filtered by Power BI.

Vizuál Timeline Slicer (Průřez časové osy) změní selektor rozsahu tak, aby odpovídal rozsahům kalendářních dat.The Timeline Slicer visual changes the range selector to the corresponding data ranges.

Další informace najdete v úložišti pro Timeline Slicer.For more information, see the Timeline Slicer repository.

Filtrování stavu pro uložení vlastností vizuálu do záložekFilter the state to save visual properties in bookmarks

Vlastnost filterState vytváří vlastnost ze součásti filtru.The filterState property makes a property of a part of filtering. Vizuál může do záložek ukládat různé hodnoty.The visual can store a variety of values in bookmarks.

Pokud chcete hodnotu vlastnosti uložit jako stav filtru, označte vlastnost objektu v souboru capabilities.json jako "filterState": true.To save the property value as a filter state, mark the object property as "filterState": true in the capabilities.json file.

Například Timeline Slicer ukládá do filtru hodnoty vlastnosti Granularity.For example, the Timeline Slicer stores the Granularity property values in a filter. Umožňuje změnou záložek změnit aktuální úroveň podrobností.It allows the current granularity to change as you change the bookmarks.

Další informace najdete v úložišti pro Timeline Slicer.For more information, see the Timeline Slicer repository.