Προσαρμογή του τμήματος παραθύρου μορφοποίησης σε προσαρμοσμένες απεικονίσεις του Power BI

Άρθρο
12/12/2023

Ξεκινώντας από την έκδοση API 5.1, οι προγραμματιστές μπορούν να δημιουργήσουν απεικονίσεις που χρησιμοποιούν το νέο τμήμα παραθύρου μορφοποίησης Power. Οι προγραμματιστές μπορούν να ορίσουν τις κάρτες και τις κατηγορίες τους για οποιαδήποτε ιδιότητα στην προσαρμοσμένη απεικόνισή τους, διευκολύνοντας τους δημιουργούς αναφορών στη χρήση αυτών των απεικονίσεων.

Το νέο API χρησιμοποιεί τη μέθοδο FormattingModel για την προσαρμογή τμημάτων της μορφής και των τμημάτων παραθύρου ανάλυσης.

Φιλοδώρημα

Η getFormattingModel μέθοδος αντικαθιστά τη enumerateObjectInstances μέθοδο σε προηγούμενες εκδόσεις του API.

Η getFormattingModel επιστρέφει ένα FormattingModel που καθορίζει την εμφάνιση του τμήματος παραθύρου μορφοποίησης και ανάλυσης της απεικόνισης.

Εκτός από όλες τις παλαιές δυνατότητες του τμήματος παραθύρου μορφοποίησης, το νέο μοντέλο μορφοποίησης υποστηρίζει νέες δυνατότητες παραθύρου μορφοποίησης, νέες ιδιότητες και νέες ιεραρχίες.

Screenshot of the new formatting pane.

Για αναβάθμιση σε έκδοση API 5.1+, ορίστε το apiVersion στο αρχείο σας pbiviz.json σε 5.1 ή νεότερη έκδοση και κάντε ένα από τα εξής:

Χρησιμοποιήστε το βοηθητικό πρόγραμμα formattingmodel. (Συνιστάται)
Χωρίς αυτό το βοηθητικό πρόγραμμα, χρησιμοποιήστε μόνο API σύμφωνα με την ακόλουθη μέθοδο.

Δημιουργία απεικόνισης που υποστηρίζει το τμήμα παραθύρου νέας μορφοποίησης

Για να δημιουργήσετε μια προσαρμοσμένη απεικόνιση που χρησιμοποιεί το τμήμα παραθύρου νέας μορφής:

Καθορίστε όλα τα στοιχεία με δυνατότητα objects προσαρμογής στο αρχείο capabilities.json.
Απαιτούνται οι ακόλουθες ιδιότητες για κάθε αντικείμενο:
- όνομα αντικειμένου
- Όνομα ιδιότητας
- τύπος ιδιότητας
Όλες οι άλλες ιδιότητες, συμπεριλαμβανομένων των DisplayName και description, είναι πλέον προαιρετικές.
Δημιουργία της προσαρμοσμένης απεικόνισης FormattingModel. Καθορίστε τις ιδιότητες του μοντέλου μορφοποίησης προσαρμοσμένης απεικόνισης και δημιουργήστε το χρησιμοποιώντας κώδικα (όχι JSON).
Υλοποιήστε το getFormattingModel API στην κλάση προσαρμοσμένης απεικόνισης που επιστρέφει το μοντέλο μορφοποίησης προσαρμοσμένης απεικόνισης. (Αυτό το API αντικαθιστά αυτό enumerateObjectInstances που χρησιμοποιήθηκε σε προηγούμενες εκδόσεις).

Ιδιότητες μορφοποίησης χάρτη

Εάν έχετε μια προσαρμοσμένη απεικόνιση που δημιουργήθηκε με ένα παλαιότερο API και θέλετε να κάνετε μετεγκατάσταση στο νέο τμήμα παραθύρου μορφοποίησης ή εάν δημιουργείτε μια νέα προσαρμοσμένη απεικόνιση:

Ορίστε το apiVersion στο αρχείο σας pbiviz.json σε 5.1 ή νεότερη έκδοση.
Για κάθε όνομα αντικειμένου και όνομα ιδιότητας στο capabilities.json, δημιουργήστε μια αντίστοιχη ιδιότητα μορφοποίησης. Η ιδιότητα μορφοποίησης θα πρέπει να έχει μια περιγραφή που περιέχει μια objectName και propertyName που αντιστοιχεί στο όνομα αντικειμένου και ιδιότητας στο capabilities.json.

Οι objects ιδιότητες στο αρχείο δυνατοτήτων εξακολουθούν να έχουν την ίδια μορφή και δεν χρειάζεται να αλλάξουν.

Για παράδειγμα, εάν το circle αντικείμενο στο αρχείο capabilities.json έχει οριστεί ως εξής:

"objects": {
    "circle": {
        "properties": {
            "circleColor": {
                "type": {
                    "fill": {
                        "solid": {
                            "color": true
                        }
                    }
                  }
          },
        }
      }
    }

Η ιδιότητα μορφοποίησης στο μοντέλο σας πρέπει να είναι τύπου ColorPicker και να μοιάζει κάπως έτσι:

control: {
    type: "ColorPicker",
    properties: {
        descriptor: {
            objectName: "circle",
            propertyName: "circleColor"
        },
        value: {
            value: this.visualSettings.circle.circleColor
        }
    }
}

Θα λάβετε ένα σφάλμα εάν ισχύει μία από τις ακόλουθες συνθήκες:

Το όνομα αντικειμένου ή ιδιότητας στο αρχείο δυνατοτήτων δεν συμφωνεί με αυτό στο μοντέλο μορφοποίησης
Ο τύπος ιδιότητας στο αρχείο δυνατοτήτων δεν συμφωνεί με τον τύπο στο μοντέλο μορφοποίησης

Μοντέλο μορφοποίησης

Το μοντέλο μορφοποίησης είναι το σημείο όπου περιγράφεται και προσαρμόζετε όλες τις ιδιότητες του τμήματος παραθύρου μορφοποίησης.

Μορφοποίηση στοιχείων μοντέλου

Στο νέο μοντέλο μορφοποίησης, τα στοιχεία ιδιοτήτων ομαδοποιούνται σε λογικές κατηγορίες και υποκατηγορίες. Αυτές οι ομάδες διευκολύνουν τη σάρωση του μοντέλου. Υπάρχουν τα πέντε βασικά στοιχεία, από το μεγαλύτερο προς το μικρότερο:

Μοντέλο μορφοποίησης
Το μεγαλύτερο κοντέινερ τμήματος παραθύρου, που χρησιμοποιείται για τη μορφοποίηση της μετωπικής διασύνδεσης του τμήματος παραθύρου. Περιέχει μια λίστα με κάρτες μορφοποίησης.
Μορφοποίηση κάρτας
Οι ιδιότητες ανώτατου επιπέδου ομαδοποιούν το κοντέινερ για μορφοποίηση ιδιοτήτων. Κάθε κάρτα αποτελείται από μία ή περισσότερες ομάδες μορφοποίησης, όπως φαίνεται εδώ.
Ομάδα μορφοποίησης
Το κοντέινερ ομαδοποίησης ιδιοτήτων δευτερεύοντος επιπέδου. Η ομάδα μορφοποίησης εμφανίζεται ως κοντέινερ ομαδοποίησης για τη μορφοποίηση αναλυτών.
Ανάλυση μορφοποίησης
Κοντέινερ ιδιοτήτων. Υπάρχουν δύο τύποι αναλυτών:
- Απλός αναλυτής: Μεμονωμένο κοντέινερ ιδιοτήτων
- Σύνθετος αναλυτής: Πολλά σχετικά κοντέινερ ιδιοτήτων ομαδοποιημένα σε μία φέτα μορφοποίησης
Η παρακάτω εικόνα εμφανίζει τους διαφορετικούς τύπους αναλυτών. Η "Γραμματοσειρά" είναι μια σύνθετη φέτα που αποτελείται από οικογένεια γραμματοσειράς, μέγεθος και έντονη γραφή, πλάγια γραφή και ενσωματωμένους διακόπτες. "Χρώμα", "μονάδες εμφάνισης" και οι άλλες φέτες είναι απλές φέτες με ένα στοιχείο το καθένα.

Ιδιότητες μορφοποίησης τμήματος παραθύρου απεικόνισης

Κάθε ιδιότητα στο μοντέλο μορφοποίησης θα πρέπει να συμφωνεί και ο τύπος αντικειμένου στο αρχείο capabilities.json .

Ο παρακάτω πίνακας εμφανίζει τους τύπους ιδιοτήτων μορφοποίησης στο αρχείο capabilities.json και την αντίστοιχη κλάση τύπου τους στις ιδιότητες μοντέλου σύγχρονης μορφοποίησης:

Τύπος	Τύπος τιμής δυνατοτήτων	Ιδιότητα μορφοποίησης
Δυαδική τιμή	Bool	Εναλλαγή τουSwitch
Αριθμός	Αριθμητική Ακέραιος	NumUpDown Ρυθμιστικό
Λίστα απαρίθμησης	enumeration:[]	ItemDropdown ItemFlagsSelection Αυτόματη κατάργηση AutoFlagsSelection ^* Δείτε την παρακάτω σημείωση
Color	Fill	ColorPicker
Διαβάθμισης	FillRule	Γραμμή διαβάθμισης: Η τιμή ιδιότητας πρέπει να είναι συμβολοσειρά που αποτελείται από: `minValue[,midValue],maxValue`
Κείμενο	Κείμενο	TextInput Textarea

Αντικείμενα μορφοποίησης δυνατοτήτων

Τύπος	Τύπος τιμής δυνατοτήτων	Ιδιότητα μορφοποίησης
Μέγεθος γραμματοσειράς	FontSize	NumUpDown
Οικογένεια γραμματοσειράς	FontFamily	FontPicker
Στοίχιση γραμμής	Στοίχιση	AlignmentGroup
Εμφανιζόμενες μονάδες ετικέτας	LabelDisplayUnits	Αυτόματη κατάργηση

^* Η ιδιότητα μορφοποίησης λίστας απαρίθμησης είναι διαφορετική στο μοντέλο μορφοποίησης και στο αρχείο δυνατοτήτων.

Δηλώστε τις ακόλουθες ιδιότητες στην κλάση ρυθμίσεων μορφοποίησης, συμπεριλαμβανομένης της λίστας στοιχείων απαρίθμησης:
- ItemDropdown
- ItemFlagsSelection
Δηλώστε τις ακόλουθες ιδιότητες στην κλάση ρυθμίσεων μορφοποίησης, χωρίς τη λίστα στοιχείων απαρίθμησης. Δηλώστε τη λίστα στοιχείων απαρίθμησης στο capabilities.json κάτω από το κατάλληλο αντικείμενο. (Αυτοί οι τύποι είναι ίδιοι με τις προηγούμενες εκδόσεις API):
- Αυτόματη κατάργηση
- AutoFlagSelection

Ιδιότητες σύνθετου αναλυτή

Ένας σύνθετος αναλυτής μορφοποίησης είναι ένας αναλυτής μορφοποίησης που περιέχει πολλές σχετικές ιδιότητες μαζί.

Προς το παρόν, έχουμε δύο τύπους σύνθετων αναλυτών:

FontControl
Αυτό διατηρεί όλες τις ιδιότητες που σχετίζονται με γραμματοσειρές μαζί. Αποτελείται από τις ακόλουθες ιδιότητες:

Οικογένεια γραμματοσειράς
Μέγεθος γραμματοσειράς
Έντονη γραφή [προαιρετικό]
Πλάγια γραφή [προαιρετικό]
Υπογράμμιση [προαιρετικό]

Screenshot of font composite slice with font family, font size, bold, italic, and underline options.

Καθεμία από αυτές τις ιδιότητες θα πρέπει να έχει ένα αντίστοιχο αντικείμενο στο αρχείο δυνατοτήτων:

Ιδιότητα	Τύπος δυνατοτήτων	Τύπος μορφοποίησης
Οικογένεια γραμματοσειράς	Μορφοποίηση: { fontFamily}	FontPicker
Μέγεθος γραμματοσειράς	Μορφοποίηση: {fontSize}	NumUpDown
Έντονα	Bool	Εναλλαγή τουSwitch
Πλάγια	Bool	Εναλλαγή τουSwitch
Υπογράμμιση	Bool	Εναλλαγή τουSwitch

Η αναπλήρωση περιθωρίου προσδιορίζουν τη στοίχιση του κειμένου στην απεικόνιση. Αποτελείται από τις ακόλουθες ιδιότητες:

Left
Right
Κορυφαίο
Κάτω

Καθεμία από αυτές τις ιδιότητες θα πρέπει να έχει ένα αντίστοιχο αντικείμενο στο αρχείο δυνατοτήτων:

Ιδιότητα	Τύπος δυνατοτήτων	Τύπος μορφοποίησης
Left	Αριθμός	NumUpDown
Right	Αριθμός	NumUpDown
Κορυφαίο	Αριθμός	NumUpDown
Κάτω	Αριθμός	NumUpDown

Παράδειγμα: Μορφοποίηση κάρτας δεδομένων

Σε αυτό το παράδειγμα, δείχνουμε πώς μπορείτε να δημιουργήσετε ένα μοντέλο μορφοποίησης προσαρμοσμένης απεικόνισης με μία κάρτα.
Η κάρτα έχει δύο ομάδες:

Ομάδα ελέγχου γραμματοσειράς με μία σύνθετη ιδιότητα
- Στοιχείο ελέγχου "Γραμματοσειρά"
Ομάδα σχεδίασης δεδομένων με δύο απλές ιδιότητες
- Χρώμα γραμματοσειράς
- Στοίχιση γραμμής

Πρώτα, προσθέστε αντικείμενα στο αρχείο δυνατοτήτων:

"objects": {
        "dataCard": {
            "properties": {
                "displayUnitsProperty": {
                    "type":
                    {
                        "formatting": {
                            "labelDisplayUnits": true
                        }
                    }
                },
                "fontSize": { 
                    "type": {
                        "formatting": {
                            "fontSize": true
                        }
                    }
                },
                "fontFamily": {
                    "type": {
                        "formatting": {
                            "fontFamily": true
                        }
                    }
                },
                "fontBold": {
                    "type": {
                        "bool": true
                    }
                },
                "fontUnderline": {
                    "type": {
                        "bool": true
                    }
                },
                "fontItalic": {
                    "type": {
                        "bool": true
                    }
                },
                "fontColor": {
                    "type": {
                        "fill": {
                            "solid": {
                                "color": true
                            }
                        }
                    }
                },
                "lineAlignment": {
                    "type": {
                        "formatting": {
                            "alignment": true
                        }
                    }
                }
            }
        }
    }

Στη συνέχεια, δημιουργήστε getFormattingModel

    public getFormattingModel(): powerbi.visuals.FormattingModel {
        // Building data card, We are going to add two formatting groups "Font Control Group" and "Data Design Group"
        let dataCard: powerbi.visuals.FormattingCard = {
            description: "Data Card Description",
            displayName: "Data Card",
            uid: "dataCard_uid",
            groups: []
        }

        // Building formatting group "Font Control Group"
        // Notice that "descriptor" objectName and propertyName should match capabilities object and property names
        let group1_dataFont: powerbi.visuals.FormattingGroup = {
            displayName: "Font Control Group",
            uid: "dataCard_fontControl_group_uid",
            slices: [
                {
                    uid: "dataCard_fontControl_displayUnits_uid",
                    displayName:"display units",
                    control: {
                        type: powerbi.visuals.FormattingComponent.Dropdown,
                        properties: {
                            descriptor: {
                                objectName: "dataCard",
                                propertyName:"displayUnitsProperty"
                            },
                            value: 0
                        }
                    }
                },
                // FontControl slice is composite slice, It means it contain multiple properties inside it
                {
                    uid: "data_font_control_slice_uid",
                    displayName: "Font",
                    control: {
                        type: powerbi.visuals.FormattingComponent.FontControl,
                        properties: {
                            fontFamily: {
                                descriptor: {
                                    objectName: "dataCard",
                                    propertyName: "fontFamily"
                                },
                                value: "wf_standard-font, helvetica, arial, sans-serif"
                            },
                            fontSize: {
                                descriptor: {
                                    objectName: "dataCard",
                                    propertyName: "fontSize"
                                },
                                value: 16
                            },
                            bold: {
                                descriptor: {
                                    objectName: "dataCard",
                                    propertyName: "fontBold"
                                },
                                value: false
                            },
                            italic: {
                                descriptor: {
                                    objectName: "dataCard",
                                    propertyName: "fontItalic"
                                },
                                value: false
                            },
                            underline: {
                                descriptor: {
                                    objectName: "dataCard",
                                    propertyName: "fontUnderline"
                                },
                                value: false
                            }
                        }
                    }
                }
            ],
        };
        // Building formatting group "Font Control Group"
        // Notice that "descriptor" objectName and propertyName should match capabilities object and property names
        let group2_dataDesign: powerbi.visuals.FormattingGroup = {
            displayName: "Data Design Group",
            uid: "dataCard_dataDesign_group_uid",
            slices: [
                // Adding ColorPicker simple slice for font color
                {
                    displayName: "Font Color",
                    uid: "dataCard_dataDesign_fontColor_slice",
                    control: {
                        type: powerbi.visuals.FormattingComponent.ColorPicker,
                        properties: {
                            descriptor:
                            {
                                objectName: "dataCard",
                                propertyName: "fontColor"
                            },
                            value: { value: "#01B8AA" }
                        }
                    }
                },
                // Adding AlignmentGroup simple slice for line alignment
                {
                    displayName: "Line Alignment",
                    uid: "dataCard_dataDesign_lineAlignment_slice",
                    control: {
                        type: powerbi.visuals.FormattingComponent.AlignmentGroup,
                        properties: {
                            descriptor:
                            {
                                objectName: "dataCard",
                                propertyName: "lineAlignment"
                            },
                            mode: powerbi.visuals.AlignmentGroupMode.Horizonal,
                            value: "right"
                        }
                    }
                },
            ]
        };

        // Add formatting groups to data card
        dataCard.groups.push(group1_dataFont);
        dataCard.groups.push(group2_dataDesign);

        // Build and return formatting model with data card
        const formattingModel: powerbi.visuals.FormattingModel = { cards: [dataCard] };
        return formattingModel;
    }

Ακολουθεί το τμήμα παραθύρου που προκύπτει:

Screenshot of format pane that results from the data card example.

Επαναφορά προεπιλογών ρυθμίσεων

Το τμήμα παραθύρου νέας μορφής έχει την επιλογή επαναφοράς όλων των τιμών ιδιοτήτων κάρτας μορφοποίησης στην προεπιλογή, κάνοντας κλικ στο κουμπί Επαναφορά προεπιλογών που εμφανίζεται στην ανοιχτή κάρτα.

Screenshot of format card reset to default button.

Για να ενεργοποιήσετε αυτήν τη δυνατότητα, προσθέστε μια λίστα με περιγραφές ιδιοτήτων κάρτας μορφοποίησης στην κάρτα revertToDefaultDescriptorsμορφοποίησης . Το παρακάτω παράδειγμα δείχνει πώς μπορείτε να προσθέσετε το κουμπί επαναφοράς προεπιλογών :

let dataCard: powerbi.visuals.FormattingCard = {
    displayName: "Data Card",
    // ... card parameters and groups list

    revertToDefaultDescriptors: [
        {
            objectName: "dataCard",
            propertyName:"displayUnitsProperty"
        },
        {
            objectName: "dataCard",
            propertyName: "fontFamily"
        },

        // ... the rest of properties descriptors 
    ]
};

Η προσθήκη revertToDefaultDescriptors σε κάρτες μορφοποίησης επιτρέπει επίσης την επαναφορά όλων των ιδιοτήτων καρτών μορφοποίησης ταυτόχρονα, κάνοντας κλικ στο κουμπί επαναφοράς όλων των ρυθμίσεων προεπιλογών στην επάνω γραμμή του τμήματος παραθύρου μορφοποίησης:

Screenshot of format pane reset all settings to default button.

Επιλογέας ιδιοτήτων μορφοποίησης

Ο προαιρετικός επιλογέας στην περιγραφή ιδιοτήτων μορφοποίησης προσδιορίζει το σημείο σύνδεσης κάθε ιδιότητας στο dataView. Υπάρχουν τέσσερις ξεχωριστές επιλογές. Διαβάστε σχετικά με αυτές στους τύπους επιλογέων αντικειμένων.

Τοπική προσαρμογή

Για περισσότερες πληροφορίες σχετικά με τη δυνατότητα τοπικής προσαρμογής και για να ρυθμίσετε ένα περιβάλλον τοπικής προσαρμογής, ανατρέξτε στο θέμα Προσθήκη τοπικής γλώσσας στην απεικόνιση Power BI Χρησιμοποιήστε τη διαχείριση τοπικής προσαρμογής για να μορφοποιήσετε τα στοιχεία που θέλετε να μεταφρασετε:

displayName: this.localization.getDisplayName("Font_Color_DisplayNameKey");
description: this.localization.getDisplayName("Font_Color_DescriptionKey");

Για να μετάφραση της τοπικής προσαρμογής της τοπικής προσαρμογής βοηθητικών προγραμμάτων μορφοποίησης βοηθητικών προγραμμάτων.

Πόροι GitHub

Μπορείτε να βρείτε όλες τις διασυνδέσεις μοντέλου μορφοποίησης στο GitHub - microsoft/powerbi-visuals-api: API προσαρμοσμένων απεικονίσεων Power BI στο "formatting-model-api.d.ts"
Συνιστούμε τη χρήση των νέων βοηθητικών προγραμμάτων μοντέλου μορφοποίησης στο GitHub - microsoft/powerbi-visuals-utils-formattingmodel: Βοηθητικά βοηθητικά προγράμματα μορφοποίησης απεικονίσεων Power BI
Μπορείτε να βρείτε ένα παράδειγμα μιας προσαρμοσμένης απεικόνισης SampleBarChart που χρησιμοποιεί την έκδοση API 5.1.0 και υλοποιεί χρησιμοποιώντας τα νέα βοηθητικά προγράμματα getFormattingModel μοντέλου μορφοποίησης στο GitHub - microsoft/PowerBI-visuals-sampleBarChart: Προσαρμοσμένη απεικόνιση γραφήματος ράβδων για εκπαιδευτικό βοήθημα.

Περισσότερες ερωτήσεις; Ρωτήστε τον Κοινότητα Power BI

Κοινή χρήση μέσω

Προσαρμογή του τμήματος παραθύρου μορφοποίησης σε προσαρμοσμένες απεικονίσεις του Power BI

Δημιουργία απεικόνισης που υποστηρίζει το τμήμα παραθύρου νέας μορφοποίησης

Ιδιότητες μορφοποίησης χάρτη

Μοντέλο μορφοποίησης

Μορφοποίηση στοιχείων μοντέλου

Ιδιότητες μορφοποίησης τμήματος παραθύρου απεικόνισης

Ιδιότητες σύνθετου αναλυτή

Παράδειγμα: Μορφοποίηση κάρτας δεδομένων

Επαναφορά προεπιλογών ρυθμίσεων

Επιλογέας ιδιοτήτων μορφοποίησης

Τοπική προσαρμογή

Πόροι GitHub

Σχόλια

Πρόσθετοι πόροι

Κοινή χρήση μέσω

Προσαρμογή του τμήματος παραθύρου μορφοποίησης σε προσαρμοσμένες απεικονίσεις του Power BI

Δημιουργία απεικόνισης που υποστηρίζει το τμήμα παραθύρου νέας μορφοποίησης

Ιδιότητες μορφοποίησης χάρτη

Μοντέλο μορφοποίησης

Μορφοποίηση στοιχείων μοντέλου

Ιδιότητες μορφοποίησης τμήματος παραθύρου απεικόνισης

Ιδιότητες σύνθετου αναλυτή

Παράδειγμα: Μορφοποίηση κάρτας δεδομένων

Επαναφορά προεπιλογών ρυθμίσεων

Επιλογέας ιδιοτήτων μορφοποίησης

Τοπική προσαρμογή

Πόροι GitHub

Σχετικό περιεχόμενο

Σχόλια

Πρόσθετοι πόροι