Power BI görsel seçimleriyle görsele etkileşim eklemeAdd interactivity into visual by Power BI visuals selections

Power BI görseller arasında iki yönlü etkileşim sağlar: seçim ve filtreleme.Power BI provides two ways of interaction between visuals - selection and filtering. Aşağıdaki örnekte bir görseldeki öğelerin nasıl seçildiği ve rapordaki diğer görsellere yeni seçim durumunun nasıl bildirildiği gösterilir.The sample below demonstrates how to select any items in one visual and notify other visuals in the report about new selection state.

Selection nesnesi arabirime karşılık gelir: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;
}

Veri noktalarını seçmek için SelectionManager'ı kullanmaHow to use SelectionManager to select data points

Görsel konak nesnesi seçim yöneticisi örneği oluşturma yöntemini sağlar.The visual host object provides the method for creating an instance of selection manager. Seçim yöneticisi seçim yapmaktan, bağlam menüsünü göstermekten, geçerli seçimleri depolamaktan ve seçim durumunu denetlemekten sorumludur.The selection manager responsible to select, to clear selection, to show the context menu, to store current selections and check selection state. Ayrıca seçim yöneticisinin bu eylemlere karşılık gelen yöntemleri vardır.And the selection manager has corresponded methods for those actions.

Seçim yöneticisinin örneğini oluşturmaCreate an instance of the selection manager

Seçim yöneticisi kullanmak için, seçim yöneticisinin örneğini oluşturmanız gerekir.For using the selection manager, you need to create the instance of a selection manager. Genellikle görseller seçim yöneticisi örneğini görsel nesnesinin constructor öğesinde oluşturur.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();
    }
    // ...
}

Seçim oluşturucusunun örneğini oluşturmaCreate an instance of the selection builder

Seçim yöneticisi örneği oluşturulduğunda, görselin her veri noktası için selections oluşturmanız gerekir.When the selection manager instance is created, you need to create selections for each data point of the visual. Her veri noktasına seçim oluşturmak için görsel konak nesnesi createSelectionIdBuilder yöntemini sağlar.The visual host object provides createSelectionIdBuilder method to generate selection for each data point. Bu yöntem powerbi.visuals.ISelectionIdBuilder arabirimiyle nesnenin örneğini döndürür: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;
}

Bu nesnenin veri görünümü eşlemelerinin farklı türleri için selections oluşturmaya yönelik ilgili yöntemleri vardır.This object has corresponded methods to create selections for different types of data view mappings.

Not

withTable ve withMatrixNode yöntemleri Power BI görsellerinin API 2.5.0 sürümünde tanıtılmıştır.The methods withTable and withMatrixNode were introduced on API 2.5.0 of the Power BI visuals. Tablo veya matris veri görünümü eşlemeleri için seçimler kullanmaya ihtiyacınız varsa, API'nin sürümünü 2.5.0 veya üzerine yükseltmelisiniz.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.

Kategorik veri görünümü eşlemesi için seçimler oluşturmaCreate selections for categorical data view mapping

Şimdi örnek veri kümesi için seçimlerin kategorik veri görünümünde nasıl temsil edildiğini gözden geçirelim:Let's review how selections represent on categorical data view mapping for sample dataset:

ÜreticiManufacturer TürType DeğerValue
ChryslerChrysler Yerli ArabaDomestic Car 2888328883
ChryslerChrysler Yerli KamyonDomestic Truck 117131117131
ChryslerChrysler İthal ArabaImport Car 00
ChryslerChrysler İthal KamyonImport Truck 63626362
FordFord Yerli ArabaDomestic Car 5003250032
FordFord Yerli KamyonDomestic Truck 122446122446
FordFord İthal ArabaImport Car 00
FordFord İthal KamyonImport Truck 00
GMGM Yerli ArabaDomestic Car 6542665426
GMGM Yerli KamyonDomestic Truck 138122138122
GMGM İthal ArabaImport Car 197197
GMGM İthal KamyonImport Truck 00
HondaHonda Yerli ArabaDomestic Car 5145051450
HondaHonda Yerli KamyonDomestic Truck 4611546115
HondaHonda İthal ArabaImport Car 29322932
HondaHonda İthal KamyonImport Truck 00
NissanNissan Yerli ArabaDomestic Car 5147651476
NissanNissan Yerli KamyonDomestic Truck 4734347343
NissanNissan İthal ArabaImport Car 54855485
NissanNissan İthal KamyonImport Truck 14301430
ToyotaToyota Yerli ArabaDomestic Car 5564355643
ToyotaToyota Yerli KamyonDomestic Truck 6122761227
ToyotaToyota İthal ArabaImport Car 2079920799
ToyotaToyota İthal KamyonImport Truck 2361423614

Görselde de aşağıdaki veri görünümü eşlemesi kullanılır: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"
                                }
                            }
                        ]
                    }
                }
            }
        }
    ]
}

Örnekte, Manufacturer``columns ve Type``rows olur.In the sample, Manufacturer is columns and Type is rows. rows temelinde değerler gruplandırılarak oluşturulan bir seri vardır (Type).There's series created by groupings values by rows (Type).

Görselin de Manufacturer ve Type temelinde verileri dilimleyebilmesi gerekir.And visual should able to slice data by Manufacturer and Type too.

Örneğin kullanıcı Manufacturer olarak Chrysler seçtiğinde diğer görseller aşağıdaki verileri göstermelidir:For example, when user selects Chrysler by Manufacturer, other visuals should show following data:

ÜreticiManufacturer TürType DeğerValue
ChryslerChrysler Yerli ArabaDomestic Car 2888328883
ChryslerChrysler Yerli KamyonDomestic Truck 117131117131
ChryslerChrysler İthal ArabaImport Car 00
ChryslerChrysler İthal KamyonImport Truck 63626362

Kullanıcı Type olarak Import Car seçtiğinde (seriye göre verileri seçtiğinde) diğer görseller aşağıdaki verileri göstermelidir:When user selects Import Car by Type (selects data by series), other visuals should show following data:

ÜreticiManufacturer TürType DeğerValue
ChryslerChrysler İthal ArabaImport Car 00
FordFord İthal ArabaImport Car 00
GMGM İthal ArabaImport Car 197197
HondaHonda İthal ArabaImport Car 29322932
NissanNissan İthal ArabaImport Car 54855485
ToyotaToyota İthal ArabaImport Car 2079920799

Kategoriler ve seriler için seçimleri olan görsel

Görsel veri sepetleri doldurulmalıdır.Need to fill the visual data baskets.

Seçimler içeren görselin veri sepetleri

Kategori (sütunlar) olarak Manufacturer, seri (satırlar) olarak Type as series (rows) ve seriler için Values olarak Value vardır.There are Manufacturer as category (columns), Type as series (rows) and Value as Values for series.

Not

Seriler için Values gereklidir çünkü veri görünümü eşlemesine göre görsel Values öğelerinin Rows verilerine göre gruplandırılmasını bekler.The Values are required for series because according to data view mapping the visual expects that Values will be grouped by Rows data.

Kategoriler için seçimler oluşturmaCreate 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);
}

Örnek kodda tüm kategorileri yinelediğimizi görebilirsiniz.In the sample code, you can see that we iterate all categories. Her yinelemede, seçim oluşturucusunun withCategory yöntemini çağırarak her kategoriye bir sonraki seçimi oluşturmak için createSelectionIdBuilder çağrısı yaparız.And in each iteration, we call createSelectionIdBuilder to create the next selection for each category by calling withCategory method of the selection builder. createSelectionId yöntemi, oluşturulan selection nesnesini döndürmek için son yöntem olarak kullanılır.The method createSelectionId is used as a final method to return the generated selection object.

withCategory yönteminde category sütununu geçiririz; örnekte bu Manufacturer öğesi ve kategori öğesinin dizinidir.In withCategory method, we pass the column of category, in the sample, it's Manufacturer and index of category element.

Seriler için seçimler oluşturmaCreate 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);
});

Tablo veri görünümü eşlemesi için seçimler oluşturmaCreate selections for table data view mapping

Tablo veri görünümleri eşleme örneğiSample of table data views mapping

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

Tablo veri görünümü eşlemesinin her satırına yönelik seçim oluşturmak için seçim oluşturucusunun withTable yöntemini çağırmalısınız.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();
    }
}

Görsel kodu tablonun satırlarını yineler ve her satır withTable tablo yöntemini çağırır.The visual code iterates the rows of the table and each row calls withTable table method. withTable yönteminin parametreleri table nesnesi ve tablo satırının dizinidir.Parameters of withTable method are table object and index of the table row.

Matris veri görünümü eşlemesi için seçimler oluşturmaCreate 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);
            });
        }
    }
}

Örnekte her düğüm ve alt düğüm için nodeWalker yinelemeli olarak çağrı yapar.In the sample, nodeWalker calls recursively for each node and child nodes.

Her çağrıda nodeWalker``nodeSelection nesnesi oluşturur.nodeWalker creates nodeSelection object on each call. Ayrıca her nodeSelection, ilgili düğümlerin selection öğesini temsil eder.And each nodeSelection represent selection of correspond nodes.

Diğer görselleri dilimlemek için veri noktalarını seçmeSelect datapoints to slice other visuals

Kategorik veri görünümü eşlemesi için örnek seçim kodlarında, düğme öğeleri için tıklama işleyici oluşturduğumuzu gördünüz.In the sample, codes of selections for categorical data view mapping, you saw that we created a click handler for button elements. İşleyici, seçim yöneticisinin select yöntemini çağırır ve seçim nesnesini geçirir.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);
});

select yönteminin arabirimiThe interface of select method is

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

select yönteminin seçim dizisini kabul edebildiğini gördünüz.You can see select can accept an array of selections. Diğer bir deyişle görseliniz çeşitli veri noktaları seçebilir.It means your visual can select several datapoints. İkinci parametre (multiSelect) çoklu seçimden sorumludur.The second parameter multiSelect responsible for multi-select. Değer doğru ise Power BI önceki seçim durumunu temizlemez ve aksi takdirde önceki seçimin sıfırlayacağı geçerli seçimi uygular.If the value is true, Power BI doesn't clear the previous selection state and apply current selection otherwise previous selection will reset.

Normal bir multiSelect kullanım senaryosunda her olayda CTRL düğmesinin durumu işlenir.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);
});

Sonraki adımlarNext steps