Pridanie interaktivity do vizuálu pomocou výberov vizuálov služby Power BIAdd interactivity into visual by Power BI visuals selections

Služba Power BI podporuje dva spôsoby interakcie medzi vizuálmi, a to výber a filtrovanie.Power BI provides two ways of interaction between visuals - selection and filtering. Ukážka zobrazená nižšie znázorňuje, ako vybrať akúkoľvek položku v jednom vizuáli a oznámiť iným vizuálom v zostave zmenu stavu výberu.The sample below demonstrates how to select any items in one visual and notify other visuals in the report about new selection state.

Objekt Selection zodpovedá rozhraniu:Selection object corresponds to the interface:

export interface ISelectionId {
    equals(other: ISelectionId): boolean;
    includes(other: ISelectionId, ignoreHighlight?: boolean): boolean;
    getKey(): string;
    getSelector(): Selector;
    getSelectorsByColumn(): SelectorsByColumn;
    hasIdentity(): boolean;
}

Použitie funkcie SelectionManager na výber údajových bodovHow to use SelectionManager to select data points

Hostiteľský objekt vizuálu poskytuje metódu na vytvorenie inštancie funkcie Selection Manager.The visual host object provides the method for creating an instance of selection manager. Funkcia Selection Manager zodpovedá za výber, odstránenie výberu, zobrazenie kontextovej ponuky, ukladanie aktuálnych výberov a kontrolu stavu výberu.The selection manager responsible to select, to clear selection, to show the context menu, to store current selections and check selection state. Funkcia Selection Manager používa metódy zodpovedajúce daným akciám.And the selection manager has corresponded methods for those actions.

Vytvorenie inštancie funkcie Selection ManagerCreate an instance of the selection manager

Ak chcete použiť funkciu Selection Manager, musíte vytvoriť inštanciu funkcie Selection Manager.For using the selection manager, you need to create the instance of a selection manager. Zvyčajne vizuály vytvárajú inštanciu funkcie Selection Manager v časti constructor objektu vizuálu.Usually, visuals create a selection manager instance in the constructor of the visual object.

export class Visual implements IVisual {
    private target: HTMLElement;
    private host: IVisualHost;
    private selectionManager: ISelectionManager;
    // ...
    constructor(options: VisualConstructorOptions) {
        this.host = options.host;
        // ...
        this.selectionManager = this.host.createSelectionManager();
    }
    // ...
}

Vytvorenie inštancie nástroja na vytvorenie výberovCreate an instance of the selection builder

Po vytvorení inštancie funkcie Selection Manager je potrebné vytvoriť selections pre jednotlivé údajové body vizuálu.When the selection manager instance is created, you need to create selections for each data point of the visual. Hostiteľský objekt vizuálu poskytne metódu createSelectionIdBuilder na generovanie výberu pre jednotlivé údajové body.The visual host object provides createSelectionIdBuilder method to generate selection for each data point. Táto metóda vráti inštanciu objektu s rozhraním powerbi.visuals.ISelectionIdBuilder:This method return instance of the object with interface powerbi.visuals.ISelectionIdBuilder:

export interface ISelectionIdBuilder {
    withCategory(categoryColumn: DataViewCategoryColumn, index: number): this;
    withSeries(seriesColumn: DataViewValueColumns, valueColumn: DataViewValueColumn | DataViewValueColumnGroup): this;
    withMeasure(measureId: string): this;
    withMatrixNode(matrixNode: DataViewMatrixNode, levels: DataViewHierarchyLevel[]): this;
    withTable(table: DataViewTable, rowIndex: number): this;
    createSelectionId(): ISelectionId;
}

Tento objekt má zodpovedajúce metódy, aby vytvoril selections pre rôzne typy priradení zobrazenia údajov.This object has corresponded methods to create selections for different types of data view mappings.

Poznámka

Metódy withTable a withMatrixNode boli predstavené v rozhraní API verzie 2.5.0 vizuálov služby Power BI.The methods withTable and withMatrixNode were introduced on API 2.5.0 of the Power BI visuals. Ak chcete použiť výbery pre priradenia zobrazení údajov tabuľky alebo matice, musíte aktualizovať verziu rozhrania API na 2.5.0 alebo vyššiu verziu.If you need to use selections for table or matrix data view mappings you need to update API version to 2.5.0 or higher.

Vytvorenie výberov pre priradenia zobrazení kategorických údajovCreate selections for categorical data view mapping

Pozrime sa na to, ako sú vyjadrené výbery v priradeniach zobrazení kategorických údajov pre vzorové množiny údajov:Let's review how selections represent on categorical data view mapping for sample dataset:

VýrobcaManufacturer TypType HodnotaValue
ChryslerChrysler Auto domáceho pôvoduDomestic Car 2888328883
ChryslerChrysler Nákladné auto domáceho pôvoduDomestic Truck 117131117131
ChryslerChrysler Auto vyrobené v zahraničíImport Car 00
ChryslerChrysler Nákladné auto vyrobené v zahraničíImport Truck 63626362
FordFord Auto domáceho pôvoduDomestic Car 5003250032
FordFord Nákladné auto domáceho pôvoduDomestic Truck 122446122446
FordFord Auto vyrobené v zahraničíImport Car 00
FordFord Nákladné auto vyrobené v zahraničíImport Truck 00
GMGM Auto domáceho pôvoduDomestic Car 6542665426
GMGM Nákladné auto domáceho pôvoduDomestic Truck 138122138122
GMGM Auto vyrobené v zahraničíImport Car 197197
GMGM Nákladné auto vyrobené v zahraničíImport Truck 00
HondaHonda Auto domáceho pôvoduDomestic Car 5145051450
HondaHonda Nákladné auto domáceho pôvoduDomestic Truck 4611546115
HondaHonda Auto vyrobené v zahraničíImport Car 29322932
HondaHonda Nákladné auto vyrobené v zahraničíImport Truck 00
NissanNissan Auto domáceho pôvoduDomestic Car 5147651476
NissanNissan Nákladné auto domáceho pôvoduDomestic Truck 4734347343
NissanNissan Auto vyrobené v zahraničíImport Car 54855485
NissanNissan Nákladné auto vyrobené v zahraničíImport Truck 14301430
ToyotaToyota Auto domáceho pôvoduDomestic Car 5564355643
ToyotaToyota Nákladné auto domáceho pôvoduDomestic Truck 6122761227
ToyotaToyota Auto vyrobené v zahraničíImport Car 2079920799
ToyotaToyota Nákladné auto vyrobené v zahraničíImport Truck 2361423614

Vizuál následne používa nasledujúce priradenie zobrazení údajov:And the visual uses the following data view mapping:

{
    "dataRoles": [
        {
            "displayName": "Columns",
            "name": "columns",
            "kind": "Grouping"
        },
        {
            "displayName": "Rows",
            "name": "rows",
            "kind": "Grouping"
        },
        {
            "displayName": "Values",
            "name": "values",
            "kind": "Measure"
        }
    ],
    "dataViewMappings": [
        {
            "categorical": {
                "categories": {
                    "for": {
                        "in": "columns"
                    }
                },
                "values": {
                    "group": {
                        "by": "rows",
                        "select": [
                            {
                                "for": {
                                    "in": "values"
                                }
                            }
                        ]
                    }
                }
            }
        }
    ]
}

V ukážke hodnota Manufacturer predstavuje columns a hodnota Type predstavuje rows.In the sample, Manufacturer is columns and Type is rows. Vytvoril sa rad zoskupením hodnôt podľa hodnoty rows (Type).There's series created by groupings values by rows (Type).

Vizuál by mal mať tiež možnosť rýchleho filtrovania údajov podľa hodnôt ManufacturerType.And visual should able to slice data by Manufacturer and Type too.

Ak používateľ napríklad vyberie hodnotu Chrysler podľa hodnoty Manufacturer, ďalšie vizuály by mali zobraziť nasledujúce údaje:For example, when user selects Chrysler by Manufacturer, other visuals should show following data:

VýrobcaManufacturer TypType HodnotaValue
ChryslerChrysler Auto domáceho pôvoduDomestic Car 2888328883
ChryslerChrysler Nákladné auto domáceho pôvoduDomestic Truck 117131117131
ChryslerChrysler Auto vyrobené v zahraničíImport Car 00
ChryslerChrysler Nákladné auto vyrobené v zahraničíImport Truck 63626362

Ak používateľ vyberie hodnotu Import Car podľa hodnoty Type (vyberie údaje podľa radu), ostatné vizuály by mali zobraziť nasledujúce údaje:When user selects Import Car by Type (selects data by series), other visuals should show following data:

VýrobcaManufacturer TypType HodnotaValue
ChryslerChrysler Auto vyrobené v zahraničíImport Car 00
FordFord Auto vyrobené v zahraničíImport Car 00
GMGM Auto vyrobené v zahraničíImport Car 197197
HondaHonda Auto vyrobené v zahraničíImport Car 29322932
NissanNissan Auto vyrobené v zahraničíImport Car 54855485
ToyotaToyota Auto vyrobené v zahraničíImport Car 2079920799

Vizuál s výbermi kategórií a radov

Je potrebné vyplniť koše údajov vizuálu.Need to fill the visual data baskets.

Koše údajov vizuálu s výbermi

Sú tu hodnota Manufacturer ako kategória (stĺpce), hodnota Type ako rad (riadky) a hodnota Value ako Values pre rad.There are Manufacturer as category (columns), Type as series (rows) and Value as Values for series.

Poznámka

Values sa vyžadujú pre rad, pretože podľa priradenia zobrazení údajov vizuál očakáva, že Values budú zoskupené podľa údajov Rows.The Values are required for series because according to data view mapping the visual expects that Values will be grouped by Rows data.

Vytvorenie výberov kategóriíCreate selections for categories

// categories
const categories = dataView.categorical.categories;

// create label for 'Manufacturer' column
const p = document.createElement("p") as HTMLParagraphElement;
p.innerText = categories[0].source.displayName.toString();
this.target.appendChild(p);

// get count of category elements
const categoriesCount = categories[0].values.length;

// iterate all categories to generate selection and create button elements to use selections
for (let categoryIndex = 0; categoryIndex < categoriesCount; categoryIndex++) {
    const categoryValue: powerbi.PrimitiveValue = categories[0].values[categoryIndex];

    const categorySelectionId = this.host.createSelectionIdBuilder()
        .withCategory(categories[0], categoryIndex) // we have only one category (only one `Manufacturer` column)
        .createSelectionId();
    this.dataPoints.push({
        value: categoryValue,
        selection: categorySelectionId
    });
    console.log(categorySelectionId);

    // create button element to apply selection on click
    const button = document.createElement("button") as HTMLButtonElement;
    button.value = categoryValue.toString();
    button.innerText = categoryValue.toString();
    button.addEventListener("click", () => {
        // handle click event to apply correspond selection
        this.selectionManager.select(categorySelectionId);
    });
    this.target.appendChild(button);
}

V kóde ukážky je možné vidieť, že iterujeme všetky kategórie.In the sample code, you can see that we iterate all categories. V každej iterácii zavoláme metódu createSelectionIdBuilder a vytvoríme ďalší výber každej kategórie zavolaním metódy withCategory zostavovača výberu.And in each iteration, we call createSelectionIdBuilder to create the next selection for each category by calling withCategory method of the selection builder. Metóda createSelectionId sa používa ako záverečná metóda na vrátenie vygenerovaného objektu selection.The method createSelectionId is used as a final method to return the generated selection object.

V metóde withCategory odovzdáme stĺpec category, v ukážke je to Manufacturer a index prvku kategórie.In withCategory method, we pass the column of category, in the sample, it's Manufacturer and index of category element.

Vytvorenie výberov radovCreate selections for series

// get groupped values for series
const series: powerbi.DataViewValueColumnGroup[] = dataView.categorical.values.grouped();

// create label for 'Type' column
const p2 = document.createElement("p") as HTMLParagraphElement;
p2.innerText = dataView.categorical.values.source.displayName;
this.target.appendChild(p2);

// iterate all series to generate selection and create button elements to use selections
series.forEach( (ser: powerbi.DataViewValueColumnGroup) => {
    // create selection id for series
    const seriesSelectionId = this.host.createSelectionIdBuilder()
        .withSeries(dataView.categorical.values, ser)
        .createSelectionId();

    this.dataPoints.push({
        value: ser.name,
        selection: seriesSelectionId
    });

    // create button element to apply selection on click
    const button = document.createElement("button") as HTMLButtonElement;
    button.value =ser.name.toString();
    button.innerText = ser.name.toString();
    button.addEventListener("click", () => {
        // handle click event to apply correspond selection
        this.selectionManager.select(seriesSelectionId);
    });
    this.target.appendChild(button);
});

Vytvorenie výberov pre priradenia zobrazení údajov tabuľkyCreate selections for table data view mapping

Ukážka priradenia zobrazení údajov tabuľkySample of table data views mapping

{
    "dataRoles": [
        {
            "displayName": "Values",
            "name": "values",
            "kind": "GroupingOrMeasure"
        }
    ],
    "dataViewMappings": [
        {
            "table": {
                "rows": {
                    "for": {
                        "in": "values"
                    }
                }
            }
        }
    ]
}

Ak chcete pre jednotlivé riadky priradenia zobrazení údajov tabuľky vytvoriť výber, musíte zavolať metódu withTable zostavovača výberu.To create a selection for each row of table data view mapping, you need to call withTable method of selection builder.

public update(options: VisualUpdateOptions) {
    const dataView = options.dataViews[0];
    dataView.table.rows.forEach((row: DataViewTableRow, rowIndex: number) => {
        this.target.appendChild(rowDiv);
        const selection: ISelectionId = this.host.createSelectionIdBuilder()
            .withTable(dataView.table, rowIndex)
            .createSelectionId();
    }
}

Kód vizuálu iteruje riadky tabuľky a každý riadok zavolá metódu tabuľky withTable.The visual code iterates the rows of the table and each row calls withTable table method. Parametre metódy withTable sú objekt table a index riadka tabuľky.Parameters of withTable method are table object and index of the table row.

Vytvorenie výberov pre priradenie zobrazení údajov maticeCreate selections for matrix data view mapping

public update(options: VisualUpdateOptions) {
    const host = this.host;
    const rowLevels: powerbi.DataViewHierarchyLevel[] = dataView.matrix.rows.levels;
    const columnLevels: powerbi.DataViewHierarchyLevel[] = dataView.matrix.rows.levels;

    // iterate rows hierarchy
    nodeWalker(dataView.matrix.rows.root, rowLevels);
    // iterate columns hierarchy
    nodeWalker(dataView.matrix.columns.root, columnLevels);

    function nodeWalker(node: powerbi.DataViewMatrixNode, levels: powerbi.DataViewHierarchyLevel[]) {
        const nodeSelection = host.createSelectionIdBuilder().withMatrixNode(node, levels);

        if (node.children && node.children.length) {
            node.children.forEach(child => {
                nodeWalker(child, levels);
            });
        }
    }
}

V ukážke vykoná nodeWalker rekurzívne volanie pre každý uzol a podriadené uzly.In the sample, nodeWalker calls recursively for each node and child nodes.

Funkcia nodeWalker vytvorí objekt nodeSelection pri každom volaní.nodeWalker creates nodeSelection object on each call. Každá funkcia nodeSelection predstavuje selection zodpovedajúcich uzlov.And each nodeSelection represent selection of correspond nodes.

Výber údajových bodov na rýchle filtrovanie ďalších vizuálovSelect datapoints to slice other visuals

Vo vzorových kódoch výberov pre priradenie zobrazení kategorických údajov ste mohli vidieť, že sme vytvorili obslužný program kliknutí pre prvky button.In the sample, codes of selections for categorical data view mapping, you saw that we created a click handler for button elements. Obslužný program zavolá metódu select funkcie Selection Manager a odovzdá objekt výberu.The handler calls select method of the selection manager and passes the selection object.

button.addEventListener("click", () => {
    // handle click event to apply correspond selection
    this.selectionManager.select(categorySelectionId);
});

Rozhranie metódy select jeThe interface of select method is

interface ISelectionManager {
    // ...
    select(selectionId: ISelectionId | ISelectionId[], multiSelect?: boolean): IPromise<ISelectionId[]>;
    // ...
}

Môžete vidieť, že metóda select dokáže prijať pole výberov.You can see select can accept an array of selections. Znamená to, že váš vizuál môže vybrať niekoľko údajových bodov.It means your visual can select several datapoints. Druhý parameter multiSelect zodpovedá za viacnásobný výber.The second parameter multiSelect responsible for multi-select. Ak je hodnota TRUE, služba Power BI nevymaže predchádzajúci stav výberu a použije aktuálny výber, v opačnom prípade sa obnoví predchádzajúci výber.If the value is true, Power BI doesn't clear the previous selection state and apply current selection otherwise previous selection will reset.

Typický scenár použitia funkcie multiSelect, ktorá obsluhuje stav tlačidla CTRL pri kliknutí.The typical scenario of using multiSelect handling CTRL button state on click event.

button.addEventListener("click", (mouseEvent) => {
    const multiSelect = (mouseEvent as MouseEvent).ctrlKey;
    this.selectionManager.select(seriesSelectionId, multiSelect);
});

Ďalšie krokyNext steps