Udostępnij za pośrednictwem

Obiekty i właściwości wizualizacji usługi Power BI

  • Artykuł

Obiekty opisują konfigurowalne właściwości skojarzone z wizualizacją. Obiekt może mieć wiele właściwości, a każda właściwość ma skojarzony typ, który opisuje, jaka będzie właściwość. Ten artykuł zawiera informacje o obiektach i typach właściwości.

myCustomObject to wewnętrzna nazwa używana do odwołowania się do obiektu w obiekcie dataView.

"objects": {
    "myCustomObject": {
        "properties": { ... }
    }
}

Nazwa wyświetlana i opis

Uwaga

Nazwa wyświetlana i opis są przestarzałe z interfejsu API w wersji 5.1 lub nowszej. Nazwa wyświetlana i opis są teraz dodawane w modelu formatowania zamiast pliku capabilities.json .

displayName to nazwa wyświetlana w okienku właściwości. description to opis właściwości formatowania, która będzie wyświetlana użytkownikowi jako etykietka narzędzia.

Właściwości

properties to mapa właściwości zdefiniowanych przez dewelopera.

"properties": {
    "myFirstProperty": {
        "type": ValueTypeDescriptor | StructuralTypeDescriptor
    }
}

Uwaga

show jest specjalną właściwością, która umożliwia przełączenie obiektu.

Przykład:

"properties": {
    "show": {
        "type": {"bool": true}
    }
}

Typy właściwości

Istnieją dwa typy właściwości: ValueTypeDescriptor i StructuralTypeDescriptor.

Deskryptor typu wartości

ValueTypeDescriptor typy są przeważnie pierwotne i są zwykle używane jako obiekt statyczny.

Oto niektóre typowe ValueTypeDescriptor elementy:

export interface ValueTypeDescriptor {
    text?: boolean;
    numeric?: boolean;
    integer?: boolean;
    bool?: boolean;
}

Deskryptor typów strukturalnych

StructuralTypeDescriptor typy są najczęściej używane dla obiektów powiązanych z danymi. Najbardziej typowym StructuralTypeDescriptor typem jest wypełnienie.

export interface StructuralTypeDescriptor {
    fill?: FillTypeDescriptor;
}

Właściwość gradientu

Właściwość gradientu jest właściwością, która nie może być ustawiona jako właściwość standardowa. Zamiast tego należy ustawić regułę podstawiania właściwości selektora kolorów (typ wypełnienia ).

Przykład pokazano w poniższym kodzie:

"properties": {
    "showAllDataPoints": {
        "type": {
            "bool": true
        }
    },
    "fill": {
        "type": {
            "fill": {
                "solid": {
                    "color": true
                }
            }
        }
    },
    "fillRule": {
        "type": {
            "fillRule": {}
        },
        "rule": {
            "inputRole": "Gradient",
            "output": {
                "property": "fill",
                    "selector": [
                        "Category"
                    ]
            }
        }
    }
}

Zwróć uwagę na właściwości fill i fillRule . Pierwszy to selektor kolorów, a drugi to reguła podstawienia gradientu, która zastąpi właściwość fill, visually, gdy zostaną spełnione warunki reguły.

Ten link między właściwością fill i regułą podstawienia jest ustawiany w"rule"> sekcji "output"

"Rule" > "InputRole" właściwość ustawia, która rola danych wyzwala regułę (warunek). W tym przykładzie jeśli rola "Gradient" danych zawiera dane, reguła "fill" jest stosowana dla właściwości .

Przykład roli danych, która wyzwala regułę wypełnienia (the last item) jest pokazana w następującym kodzie:

{
    "dataRoles": [
            {
                "name": "Category",
                "kind": "Grouping",
                "displayName": "Details",
                "displayNameKey": "Role_DisplayName_Details"
            },
            {
                "name": "Series",
                "kind": "Grouping",
                "displayName": "Legend",
                "displayNameKey": "Role_DisplayName_Legend"
            },
            {
                "name": "Gradient",
                "kind": "Measure",
                "displayName": "Color saturation",
                "displayNameKey": "Role_DisplayName_Gradient"
            }
    ]
}

Okienko formatowania

Aby dostosować właściwości w okienku formatowania, użyj jednej z następujących metod, w zależności od używanej wersji interfejsu API.

Uwaga

Metoda interfejsu API jest obsługiwana getFormattingModel z poziomu interfejsu API w wersji 5.1 lub nowszej. Aby dowiedzieć się, której wersji używasz, sprawdź apiVersion plik pbiviz.json .

Aby efektywnie używać obiektów w interfejsie API w wersji 5.1 lub nowszej, należy zaimplementować metodę getFormattingModel .
Ta metoda kompiluje i zwraca model formatowania, który zawiera pełną hierarchię okienka właściwości kart formatowania, grup formatowania, zawiera również właściwości formatowania i ich wartości.

Obiekty możliwości odzwierciedlone w modelu formatowania

Każda właściwość formatowania w modelu formatowania wymaga odpowiedniego obiektu w pliku capabilities.json . Właściwość formatowania powinna zawierać deskryptor z nazwą obiektu i nazwą właściwości, która dokładnie odpowiada odpowiedniemu obiektowi możliwości (w nazwach obiektów i właściwości jest rozróżniana wielkość liter).
Na przykład:

Następująca właściwość formatowania w modelu formatowania (zobacz zawartość obiektu deskryptora):

 const myCustomCard: powerbi.visuals.FormattingCard = {
            displayName: "My Custom Object Card",
            uid: "myCustomObjectCard_uid",
            groups: [{
                displayName: undefined,
                uid: "myCustomObjectGroup_uid",
                slices: [
                    {
                        uid: "myCustomProperty_uid",
                        displayName: "My Custom Property",
                        control: {
                            type: powerbi.visuals.FormattingComponent.ColorPicker,
                            properties: {
                                descriptor: {
                                    objectName: "myCustomObject",
                                    propertyName: "myCustomProperty",
                                    selector: null // selector is optional
                                },
                                value: { value: "#000000" }
                            }
                        }
                    }
                ],
            }],
        };

Odpowiedni obiekt z sekcji możliwości objects powinien być:

    "objects": {
        "myCustomObject": {
            "properties": {
                "myCustomProperty": {
                    "type": {
                         "fill": {
                            "solid": {
                                "color": true
                            }
                        }
                    }
                }
            }
        }
    }

Selektor właściwości formatowania

Opcjonalny selektor w deskryptorze właściwości formatowania określa, gdzie każda właściwość jest powiązana w widoku dataView. Istnieją cztery różne opcje.

Przykład

W powyższym myCustomCard przykładzie pokazano, jak wygląda właściwość formatowania w modelu formatowania dla obiektu z jedną właściwością myCustomProperty. Ten obiekt właściwości jest powiązany statycznie z dataViews[index].metadata.objects. Selektor w deskryptorze można odpowiednio zmienić na wybrany typ selektora.

Typy selektorów obiektów

Selektor w enumerateObjectInstances programie określa, gdzie każdy obiekt jest powiązany w obiekcie dataView. Istnieją cztery różne opcje:

static

Ten obiekt jest powiązany z metadanymi dataviews[index].metadata.objects, jak pokazano tutaj.

selector: null

kolumny

Ten obiekt jest powiązany z kolumnami z pasującym QueryNameelementem .

selector: {
    metadata: 'QueryName'
}

Selektor

Ten obiekt jest powiązany z elementem, dla którego utworzono selectionID element . W tym przykładzie załóżmy, że utworzyliśmy selectionIDdla niektórych punktów danych i przechodzimy przez nie w pętli.

for (let dataPoint in dataPoints) {
    ...
    selector: dataPoint.selectionID.getSelector()
}

Tożsamość zakresu

Ten obiekt jest powiązany z określonymi wartościami na przecięciu grup. Jeśli na przykład masz kategorie ["Jan", "Feb", "March", ...] i serie ["Small", "Medium", "Large"], możesz mieć obiekt na przecięciu wartości pasujących Feb do wartości i Large. Aby to osiągnąć, możesz pobrać DataViewScopeIdentity obie kolumny, wypchnąć je do zmiennej identitiesi użyć tej składni z selektorem.

selector: {
    data: <DataViewScopeIdentity[]>identities
}

Powiązana zawartość

Porady dotyczące wydajności