FormattingModel yardımcı programları

Makale
10/31/2023

Biçimlendirme modeli yardımcı programları , Power BI özel görselinizin özellik bölmelerini (biçim ve analiz bölmeleri) doldurmak üzere biçimlendirme ayarları modeli oluşturmak için gereken sınıfları, arabirimleri ve yöntemleri içerir.

Biçimlendirme ayarları hizmeti

Biçimlendirme ayarları hizmeti bir biçimlendirme ayarları modeli alır ve bunu biçimlendirme bölmesini dolduran bir biçimlendirme modeline dönüştürür. Biçimlendirme modeli hizmeti, dize yerelleştirmelerini de destekler.

Biçimlendirme ayarları hizmeti başlat başlangıç:

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();
        
        // ...
    }
}

IFormattingSettingsService biçimlendirme ayarları hizmet arabiriminin iki ana yöntemi vardır:

    /**
     * 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;

Biçimlendirme ayarları modeli

Ayarlar modeli , biçimlendirme bölmesi ve analiz bölmesi için tüm biçimlendirme kartlarını içerir ve sarmalar.

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

Bu örnekte yeni bir biçimlendirme ayarları modeli bildirmektedir:

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];
}

Biçimlendirme ayarları kartı

Biçimlendirme ayarları kartı , biçimlendirme veya analiz bölmesinde bir biçimlendirme kartı belirtir. Biçimlendirme ayarları kartı birden çok biçimlendirme dilimi, kapsayıcı, grup ve özellik içerebilir.

Dilimleri biçimlendirme ayarları kartına eklemek, bu dilimlerin tümünü tek bir biçimlendirme kartına yerleştirir.

Kartlar, Dilimler ve Gruplar parametresi false (visible) olarak ayarlanarak dinamik olarak gizlenebilir.

Kart, parametreyi analyticsPane veya false olarak ayarlayarak biçimlendirme bölmesini veya analiz bölmesini doldurabilir.

Bir biçimlendirme ayarları grubu ve dilimi dahil olmak üzere biçimlendirme ayarları kartını bildirme örneği:

Kart adı, capabilities.json nesne adıyla eşleşmelidir
Dilim adı, capabilities.json özellik adıyla eşleşmelidir

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 özellik bildirimi şu şekilde olmalıdır:

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

Biçimlendirme ayarları grubu

Bazı biçimlendirme ayarları kartlarının içinde gruplar olabilir. Gruplar dilimlerden oluşur ve genişletilebilir/daraltılabilir.

Bir dilimle biçimlendirme ayarları grubunu bildirme örneği:

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];
}

Biçimlendirme ayarları dilimi

Biçimlendirme ayarları dilim türü, basit ve bileşik olmak üzere iki tür dilimden oluşur.

Her dilim biçimlendirme özellikleri içerir. Kullanılabilir biçimlendirme özellikleri türlerinin uzun bir listesi vardır.

Sınırlamaları olan tür biçimlendirme NumUpDown ayarları dilimini bildirme örneği:

Dilim adı, capabilities.json özellik adıyla eşleşmelidir.

    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,
            },
        }
    });

FormatModel Yardımcı Programları kullanarak biçimlendirme bölmesi modeli oluşturma

Dosyanızı settings.ts açın.
Tüm bileşenleriyle (kartlar, gruplar, dilimler, özellikler ...) kendi biçimlendirme ayarları modelinizi oluşturun ve adını verin VisualFormattingSettings. Ayarlar kodunuzu aşağıdakilerle değiştirin:

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];
}

Yetenek dosyanıza biçimlendirme nesnelerinizi ve özelliklerinizi ekleyin

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

Görsel sınıfınızda aşağıdakileri içeri aktarın:

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

Biçimlendirme ayarlarını ve biçimlendirme ayarları hizmetini bildirme

   private formattingSettings: VisualFormattingSettingsModel;
   private formattingSettingsService: FormattingSettingsService;

Oluşturucuda biçimlendirme ayarları hizmetini başlatma

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

    // ...
}

Biçimlendirme ayarları hizmetini kullanarak güncelleştirme API'sinde biçimlendirme ayarları oluşturma populateFormattingSettingsModel

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

Biçimlendirme modeli oluşturma ve API'de getFormattingModel döndürme

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

Biçimlendirme özelliği seçicisi

Biçimlendirme özellikleri tanımlayıcısında isteğe bağlı seçici, her özelliğin dataView'da nereye bağlandığını belirler. Dört farklı seçenek vardır.

Tanımlayıcı nesnesindeki biçimlendirme özelliğine seçici ekleyebilirsiniz. Bu örnek, özellik seçicileri kullanılarak renk özel görsel veri noktaları için SampleBarChart'tan alınmıştır:

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
}

Ayarları varsayılana sıfırla

Biçimlendirme modeli yardımcı programları, tüm biçimlendirme özellikleri tanımlayıcılarını varsayılan tanımlayıcılara geri döndürmek için özelliklerin biçimlendirme kartı listesine otomatik olarak ekleyerek ayarları varsayılanarevertToDefaultDescriptorsolanak tanır.

Biçimlendirme ayarlarını sıfırlamayı şu şekilde etkinleştirebilirsiniz:

Biçimlendirme kartı varsayılana sıfırla düğmesi
Biçimlendirme bölmesi üst çubuğu tüm ayarları varsayılan düğmeye sıfırlar

Localization (Yerelleştirme)

Yerelleştirme özelliği hakkında daha fazla bilgi edinmek ve yerelleştirme ortamını ayarlamak için bkz . Power BI görselinize yerel dil ekleme.

Özel görselinizde yerelleştirmenin gerekli olması durumunda yerelleştirme yöneticisiyle başlatma biçimlendirme ayarları hizmeti:

constructor(options: VisualConstructorOptions) {

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

Bir dizenin displayNameKey yerelleştirilmesini istediğiniz her durumda uygun biçimlendirme bileşenine ve descriptionKey yerine veya displayName ekleyindescription. Yerelleştirilmiş görünen ad ve açıklama ile biçimlendirme dilimi oluşturma örneği

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

displayNameKey ve descriptionKey değerleri dosyalara resources.json eklenmelidir.

Aracılığıyla paylaş