Přidání interaktivity k vizuálu pomocí výběrů vizuálů Power BIAdd interactivity into visual by Power BI visuals selections

Power BI poskytuje dva způsoby interakce mezi vizuály – výběr a filtrování.Power BI provides two ways of interaction between visuals - selection and filtering. Následující ukázka předvádí, jak vybrat libovolné položky v jednom vizuálu a oznámit nový stav výběru dalším vizuálům v sestavě.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 odpovídá rozhraní: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;
}

Jak používat správce výběrů k výběru datových bodůHow to use SelectionManager to select data points

Hostitelský objekt vizuálu poskytuje metodu pro vytvoření instance správce výběrů.The visual host object provides the method for creating an instance of selection manager. Správce výběrů je zodpovědný za výběr, zrušení výběru, zobrazení místní nabídky, ukládání aktuálních výběrů a kontrolu stavu výběru.The selection manager responsible to select, to clear selection, to show the context menu, to store current selections and check selection state. A správce výběrů má pro tyto akce odpovídající metody.And the selection manager has corresponded methods for those actions.

Vytvoření instance správce výběrůCreate an instance of the selection manager

Abyste mohli správce výběrů používat, musíte vytvořit instanci správce výběrů.For using the selection manager, you need to create the instance of a selection manager. Vizuály obvykle vytvářejí instanci správce výběrů v konstruktoru (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();
    }
    // ...
}

Vytvoření instance tvůrce výběrůCreate an instance of the selection builder

Když je instance správce výběrů vytvořená, musíte vytvořit výběry (selections) pro jednotlivé datové body vizuálu.When the selection manager instance is created, you need to create selections for each data point of the visual. Hostitelský objekt vizuálu poskytuje metodu createSelectionIdBuilder k vygenerování výběru pro každý datový bod.The visual host object provides createSelectionIdBuilder method to generate selection for each data point. Tato metoda vrací instanci 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á odpovídající metody k vytvoření výběrů (selections) pro různé typy mapování zobrazení dat.This object has corresponded methods to create selections for different types of data view mappings.

Poznámka

Metody withTable a withMatrixNode byly představeny u rozhraní API 2.5.0 vizuálů Power BI.The methods withTable and withMatrixNode were introduced on API 2.5.0 of the Power BI visuals. Pokud potřebujete použít výběry pro mapování zobrazení dat tabulky nebo matice, musíte verzi rozhraní API aktualizovat na 2.5.0 nebo vyšší.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.

Vytvoření výběrů pro mapování zobrazení dat kategoriíCreate selections for categorical data view mapping

Pojďme se podívat, jak jsou výběry reprezentovány u mapování zobrazení dat kategorií pro ukázkovou datovou sadu:Let's review how selections represent on categorical data view mapping for sample dataset:

ManufacturerManufacturer TypType HodnotaValue
ChryslerChrysler Domestic CarDomestic Car 2888328883
ChryslerChrysler Domestic TruckDomestic Truck 117131117131
ChryslerChrysler Import CarImport Car 00
ChryslerChrysler Import TruckImport Truck 63626362
FordFord Domestic CarDomestic Car 5003250032
FordFord Domestic TruckDomestic Truck 122446122446
FordFord Import CarImport Car 00
FordFord Import TruckImport Truck 00
GMGM Domestic CarDomestic Car 6542665426
GMGM Domestic TruckDomestic Truck 138122138122
GMGM Import CarImport Car 197197
GMGM Import TruckImport Truck 00
HondaHonda Domestic CarDomestic Car 5145051450
HondaHonda Domestic TruckDomestic Truck 4611546115
HondaHonda Import CarImport Car 29322932
HondaHonda Import TruckImport Truck 00
NissanNissan Domestic CarDomestic Car 5147651476
NissanNissan Domestic TruckDomestic Truck 4734347343
NissanNissan Import CarImport Car 54855485
NissanNissan Import TruckImport Truck 14301430
ToyotaToyota Domestic CarDomestic Car 5564355643
ToyotaToyota Domestic TruckDomestic Truck 6122761227
ToyotaToyota Import CarImport Car 2079920799
ToyotaToyota Import TruckImport Truck 2361423614

A vizuál používá následující mapování zobrazení dat: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ázce Manufacturer je columns a Type je rows.In the sample, Manufacturer is columns and Type is rows. Řada je vytvořená seskupením hodnot podle rows (Type).There's series created by groupings values by rows (Type).

A vizuál by měl být schopný vytvořit datový řez podle Manufacturer a také podle Type.And visual should able to slice data by Manufacturer and Type too.

Když například uživatel vybere Chrysler podle Manufacturer, ostatní vizuály by měly zobrazit následující data:For example, when user selects Chrysler by Manufacturer, other visuals should show following data:

ManufacturerManufacturer TypType HodnotaValue
ChryslerChrysler Domestic CarDomestic Car 2888328883
ChryslerChrysler Domestic TruckDomestic Truck 117131117131
ChryslerChrysler Import CarImport Car 00
ChryslerChrysler Import TruckImport Truck 63626362

Když uživatel vybere Import Car podle Type (vybere data podle řady), ostatní vizuály by měly zobrazit následující data:When user selects Import Car by Type (selects data by series), other visuals should show following data:

ManufacturerManufacturer TypType HodnotaValue
ChryslerChrysler Import CarImport Car 00
FordFord Import CarImport Car 00
GMGM Import CarImport Car 197197
HondaHonda Import CarImport Car 29322932
NissanNissan Import CarImport Car 54855485
ToyotaToyota Import CarImport Car 2079920799

Vizuál s výběry pro kategorie a řady

Je potřeba naplnit košíky vizuálních dat.Need to fill the visual data baskets.

Košíky dat vizuálu s výběry

Jsou tu Manufacturer jako kategorie (sloupce), Type jako řady (řádky) a Value jako Values pro řady.There are Manufacturer as category (columns), Type as series (rows) and Value as Values for series.

Poznámka

Pro řady jsou vyžadovány Values, protože podle mapování zobrazení dat vizuál očekává, že Values budou seskupovány pomocí dat Rows.The Values are required for series because according to data view mapping the visual expects that Values will be grouped by Rows data.

Vytvoření výběrů pro kategorieCreate 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 ukázkovém kódu vidíte, že iterujeme všechny kategorie.In the sample code, you can see that we iterate all categories. A v každé iteraci voláme createSelectionIdBuilder k vytvoření dalšího výběru pro každou kategorii voláním metody withCategory tvůrce výběrů.And in each iteration, we call createSelectionIdBuilder to create the next selection for each category by calling withCategory method of the selection builder. Metoda createSelectionId se používá jako konečná metoda k vrácení vygenerovaného objektu selection.The method createSelectionId is used as a final method to return the generated selection object.

V metodě withCategory předáme sloupec category (v ukázce je to Manufacturer) a index prvku kategorie.In withCategory method, we pass the column of category, in the sample, it's Manufacturer and index of category element.

Vytvoření výběrů pro řadyCreate 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);
});

Vytvoření výběrů pro mapování zobrazení dat tabulkyCreate selections for table data view mapping

Ukázka mapování zobrazení dat tabulkySample of table data views mapping

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

Abyste vytvořili výběr pro každý řádek mapování zobrazení dat tabulky, musíte volat metodu withTable tvůrce výběrů.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 řádky tabulky a každý řádek volá metodu tabulky withTable.The visual code iterates the rows of the table and each row calls withTable table method. Parametry metody withTable jsou objekt table a index řádku tabulky.Parameters of withTable method are table object and index of the table row.

Vytvoření výběrů pro mapování zobrazení dat 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ázce se funkce nodeWalker volá rekurzivně pro každý uzel a podřízené uzly.In the sample, nodeWalker calls recursively for each node and child nodes.

nodeWalker při každém volání vytvoří objekt nodeSelection.nodeWalker creates nodeSelection object on each call. A každý nodeSelection představuje selection odpovídajících uzlů.And each nodeSelection represent selection of correspond nodes.

Výběr datových bodů k vytvoření řezů jiných vizuálůSelect datapoints to slice other visuals

V ukázkových kódech výběrů pro mapování zobrazení dat kategorií jste viděli, že jsme pro tlačítkové prvky vytvořili obslužnou rutinu události kliknutí.In the sample, codes of selections for categorical data view mapping, you saw that we created a click handler for button elements. Obslužná rutina volá metodu select správce výběrů a předá objekt výběru.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);
});

Rozhraní metody select jeThe interface of select method is

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

Je vidět, že select může přijmout pole výběrů.You can see select can accept an array of selections. Znamená to, že váš vizuál může vybrat několik datových bodů.It means your visual can select several datapoints. Druhý parametr multiSelect je zodpovědný za vícenásobný výběr.The second parameter multiSelect responsible for multi-select. Pokud má hodnotu true, Power BI nevymaže předchozí stav výběru a použije aktuální výběr. V opačném případě předchozí výběr vynuluje.If the value is true, Power BI doesn't clear the previous selection state and apply current selection otherwise previous selection will reset.

Typický scénář použití parametru multiSelect ke zpracování stavu tlačítka CTRL při události 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);
});

Další krokyNext steps