FormattingModel Utils

Άρθρο
10/31/2023

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

Υπηρεσία ρυθμίσεων μορφοποίησης

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

Προετοιμασία υπηρεσίας ρυθμίσεων μορφοποίησης:

import { FormattingSettingsService } from "powerbi-visuals-utils-formattingmodel";

export class MyVisual implements IVisual {
    // declaring formatting settings service 
    private formattingSettingsService: FormattingSettingsService;

    constructor(options: VisualConstructorOptions) {
        
        this.formattingSettingsService = new FormattingSettingsService();
        
        // ...
    }
}

Το περιβάλλον εργασίας υπηρεσίας ρυθμίσεων μορφοποίησης IFormatting Ρυθμίσεις Service διαθέτει δύο κύριες μεθόδους:

    /**
     * Build visual formatting settings model from metadata dataView
     * 
     * @param dataViews metadata dataView object
     * @returns visual formatting settings model 
     */
    populateFormattingSettingsModel<T extends Model>(typeClass: new () => T, dataViews: powerbi.DataView[]): T;

    /**
     * Build formatting model by parsing formatting settings model object 
     * 
     * @returns powerbi visual formatting model
     */
    buildFormattingModel(formattingSettingsModel: Model): visuals.FormattingModel;

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

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

export class Model {
    cards: Array<Cards>;
}

Αυτό το παράδειγμα δηλώνει ένα νέο μοντέλο ρυθμίσεων μορφοποίησης:

import { formattingSettings } from "powerbi-visuals-utils-formattingmodel";

import FormattingSettingsCompositeCard = formattingSettings.CompositeCard;
import FormattingSettingsCards = formattingSettings.Cards;
import FormattingSettingsModel = formattingSettings.Model;

export class VisualSettingsModel extends FormattingSettingsModel {
    // Building my visual formatting settings card
    myVisualCard: FormattingSettingsCompositeCard = new myVisualCardSettings();

    // Add formatting settings card to cards list in model
    cards: FormattingSettingsCards[] = [this.myVisualCard];
}

Κάρτα ρυθμίσεων μορφοποίησης

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

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

Οι κάρτες, οι αναλυτές και οι ομάδες μπορούν να κρυφτούν δυναμικά ορίζοντας την visible παράμετρο σε false (true από προεπιλογή).

Η κάρτα μπορεί να συμπληρώσει είτε το τμήμα παραθύρου μορφοποίησης είτε το τμήμα παραθύρου ανάλυσης ορίζοντας την analyticsPane παράμετρο σε true ή false.

Παράδειγμα δήλωσης κάρτας ρυθμίσεων μορφοποίησης, συμπεριλαμβανομένης μίας ομάδας ρυθμίσεων μορφοποίησης και ενός αναλυτή:

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

import { formattingSettings } from "powerbi-visuals-utils-formattingmodel";

import FormattingSettingsCompositeCard = formattingSettings.CompositeCard;
import FormattingSettingsGroup = formattingSettings.Group;
import FormattingSettingsSlice = formattingSettings.Slice;

// Formatting settings group
class myVisualGroupSettings extends FormattingSettingsGroup {
    // Formatting settings slice
    myAnotherNumericSlice = new formattingSettings.NumUpDown({
        name: "myAnotherNumericSlice",
        displayName: "My Formatting Numeric Slice in group",
        value: 15,
        visible: true,
    });

    name: string = "myVisualCard";
    displayName: string = "My Formatting Card";
    analyticsPane: boolean = false;
    visible: boolean = true;
    slices: Array<FormattingSettingsSlice> = [this.myNumericSlice];
}

// Formatting settings card
class myVisualCardSettings extends FormattingSettingsCompositeCard {
    // Formatting settings slice
    myNumericSlice = new formattingSettings.NumUpDown({
        name: "myNumericSlice",
        displayName: "My Formatting Numeric Slice",
        value: 50,
        visible: true,
        options: {
            minValue: {
                type: powerbi.visuals.ValidatorType.Min,
                value: 0,
            },
            maxValue: {
                type: powerbi.visuals.ValidatorType.Max,
                value: 100,
            },
        }
    });

    name: string = "myVisualCard";
    displayName: string = "My Formatting Card";
    analyticsPane: boolean = false;
    visible: boolean = true;

    groupSetting = new myVisualGroupSettings(Object())
    groups: Array<FormattingSettingsGroup> = [this.groupSetting]
    slices: Array<FormattingSettingsSlice> = [this.myNumericSlice];
}

Η δήλωση ιδιότητας capabilities.json πρέπει να είναι:

"objects": {
    "myVisualCard": {
        "properties": {
            "myNumericSlice": {
                "type": {
                    "numeric": true 
                }
            },
            "myAnotherNumericSlice": {
                "type": {
                    "numeric": true 
                }
            },
        }
    }
}

Ομάδα ρυθμίσεων μορφοποίησης

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

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

import { formattingSettings } from "powerbi-visuals-utils-formattingmodel";

import FormattingSettingsGroup = formattingSettings.Group;
import FormattingSettingsSlice = formattingSettings.Slice;

class myVisualGroupSettings extends FormattingSettingsGroup {
    myAnotherNumericSlice = new formattingSettings.NumUpDown({
        name: "myAnotherNumericSlice",
        displayName: "My Formatting Numeric Slice in group",
        value: 15,
        visible: true
    });

    name: string = "myVisualCard";
    displayName: string = "My Formatting Card";
    analyticsPane: boolean = false;
    visible: boolean = true;
    slices: Array<FormattingSettingsSlice> = [this.myNumericSlice];
}

Ανάλυση ρυθμίσεων μορφοποίησης

Ο τύπος αναλυτή ρυθμίσεων μορφοποίησης αποτελείται από δύο τύπους αναλυτών- απλούς και σύνθετους.

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

Παράδειγμα δήλωσης ανάλυσης ρυθμίσεων μορφοποίησης τύπου NumUpDown με περιορισμούς:

Το όνομα του αναλυτή θα πρέπει να συμφωνεί με το όνομα ιδιότητας από το capabilities.json.

    import { formattingSettings } from "powerbi-visuals-utils-formattingmodel";

    myNumericSlice = new formattingSettings.NumUpDown({
        name: "myNumericSlice",
        displayName: "My Formatting Numeric Slice",
        value: 50,
        visible: true,
        options: {
            minValue: {
                type: powerbi.visuals.ValidatorType.Min,
                value: 0,
            },
            maxValue: {
                type: powerbi.visuals.ValidatorType.Max,
                value: 100,
            },
        }
    });

Δημιουργία μοντέλου τμήματος παραθύρου μορφοποίησης με χρήση της formattingModel Utils

Ανοίξτε το αρχείο σας settings.ts .
Δημιουργήστε το δικό σας μοντέλο ρυθμίσεων μορφοποίησης με όλα τα στοιχεία του (κάρτες, ομάδες, αναλυτές, ιδιότητες ...) και ονομάστε το VisualFormattingSettings. Αντικαταστήστε τον κωδικό ρυθμίσεων με τα εξής:

import { formattingSettings } from "powerbi-visuals-utils-formattingmodel";

import FormattingSettingsCompositeCard = formattingSettings.CompositeCard;
import FormattingSettingsSlice = formattingSettings.Slice;
import FormattingSettingsModel = formattingSettings.Model;

export class VisualSettingsModel extends FormattingSettingsModel {
    // Building my visual formatting settings card
    myVisualCard: FormattingSettingsCard = new myVisualCardSettings();

    // Add formatting settings card to cards list in model
    cards: Array<FormattingSettingsCompositeCard> = [this.myVisualCard];
}

class myVisualCardSettings extends FormattingSettingsCompositeCard {
    myNumericSlice = new formattingSettings.NumUpDown({
        name: "myNumericSlice",
        displayName: "My Formatting Numeric Slice",
        value: 100,
    });

    name: string = "myVisualCard";
    displayName: string = "My Formatting Card";
    analyticsPane: boolean = false;
    slices: Array<FormattingSettingsSlice> = [this.myNumericSlice];
}

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

"objects": {
    "myVisualCard": {
        "properties": {
            "myNumericSlice": {
                "type": {
                    "numeric": true 
                }
            }
        }
    }
}

Στην κλάση απεικόνισής σας, εισαγάγετε τα εξής:

import { FormattingSettingsService } from "powerbi-visuals-utils-formattingmodel";
import { VisualFormattingSettingsModel } from "./settings";

Δήλωση ρυθμίσεων μορφοποίησης και υπηρεσίας ρυθμίσεων μορφοποίησης

   private formattingSettings: VisualFormattingSettingsModel;
   private formattingSettingsService: FormattingSettingsService;

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

constructor(options: VisualConstructorOptions) {
    this.formattingSettingsService = new FormattingSettingsService();

    // ...
}

Δημιουργία ρυθμίσεων μορφοποίησης στο API ενημέρωσης με χρήση της υπηρεσίας ρυθμίσεων μορφοποίησης populateFormattingSettingsModel

public update(options: VisualUpdateOptions) {
    this.formattingSettings = this.formattingSettingsService.populateFormattingSettingsModel(VisualFormattingSettingsModel, options.dataViews);
    // ...
}

Δημιουργία μοντέλου μορφοποίησης και επιστροφή του στο getFormattingModel API

public getFormattingModel(): powerbi.visuals.FormattingModel {
    return this.formattingSettingsService.buildFormattingModel(this.formattingSettings);
}

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

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

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

new formattingSettings.ColorPicker({
    name: "fill",
    displayName: dataPoint.category,
    value: { value: dataPoint.color },
    selector: dataViewWildcard.createDataViewWildcardSelector(dataViewWildcard.DataViewWildcardMatchingOption.InstancesAndTotals),
    altConstantSelector: dataPoint.selectionId.getSelector(),
    instanceKind: powerbi.VisualEnumerationInstanceKinds.ConstantOrRule
}

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

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

Μπορείτε να ενεργοποιήσετε την επαναφορά ρυθμίσεων μορφοποίησης από:

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

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

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

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

constructor(options: VisualConstructorOptions) {

    const localizationManager = options.host.createLocalizationManager();
    this.formattingSettingsService = new FormattingSettingsService(localizationManager);
    
    // ...
}

Προσθέστε displayNameKey ή descriptionKey αντί displayName για και description στο κατάλληλο στοιχείο μορφοποίησης κάθε φορά που θέλετε να μεταφραστεί μια συμβολοσειρά. Παράδειγμα για τη δημιουργία ενός αναλυτή μορφοποίησης με μεταφρασμένο εμφανιζόμενο όνομα και περιγραφή

 myFormattingSlice = new formattingSettings.NumUpDown({
        name: "myFormattingSlice",
        displayNameKey: "myFormattingSlice_Key",
        descriptionKey: "myFormattingSlice_DescriptionKey",
        value: 100
    });

displayNameKey και descriptionKey οι τιμές πρέπει να προστεθούν στα resources.json αρχεία.

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