Power BI özel görsellerinde biçim bölmesini özelleştirme
Api sürüm 5.1'den başlayarak geliştiriciler yeni Power format bölmesini kullanan görseller oluşturabilir. Geliştiriciler, özel görsellerindeki herhangi bir özellik için kartları ve kategorilerini tanımlayarak rapor oluşturucularının bu görselleri kullanmasını kolaylaştırabilir.
Yeni API, format ve analiz bölmelerinin bölümlerini özelleştirmek için FormattingModel yöntemini kullanır.
Bahşiş
yöntemi, getFormattingModel önceki API sürümlerinde yönteminin enumerateObjectInstances yerini alır.
, getFormattingModel görselin biçimlendirme ve analiz bölmesinin nasıl göründüğünü tanımlayan bir FormattingModel döndürür.
Tüm eski biçimlendirme bölmesi özelliklerine ek olarak, yeni biçimlendirme modeli yeni biçim bölmesi özelliklerini, yeni özellikleri ve yeni hiyerarşileri destekler.
API sürüm 5.1+ sürümüne yükseltmek için pbiviz.json dosyanızda öğesini veya sonraki bir sürüme 5.1 ayarlayın apiVersion ve aşağıdakilerden birini yapın:
- Biçimlendirme modeli yardımcı programı kullanın. (Önerilen)
- Bu yardımcı program olmadan, aşağıdaki yönteme göre yalnızca API'leri kullanın.
Yeni biçim bölmesini destekleyen bir görsel oluşturma
Yeni biçim bölmesini kullanan özel bir görsel oluşturmak için:
Capabilities.json dosyanızda tüm özelleştirilebilirleri
objectstanımlayın.
Her nesne için aşağıdaki özellikler gereklidir:- nesne adı
- özellik adı
- özellik türü
ve
descriptiondahil olmak üzereDisplayNamediğer tüm özellikler artık isteğe bağlıdır.Özel görsel FormattingModel'i oluşturun. Özel görsel biçimlendirme modelinizin özelliklerini tanımlayın ve kodu (JSON değil) kullanarak oluşturun.
API'yi
getFormattingModelözel görsel biçimlendirme modeli döndüren özel görsel sınıfına uygulayın. (Bu API, önceki sürümlerde kullanılanın yerini alırenumerateObjectInstances).
Eşleme biçimlendirme özellikleri
Eski bir API ile oluşturulmuş bir özel görsele sahipseniz ve yeni biçim bölmesine geçmek istiyorsanız veya yeni bir özel görsel oluşturuyorsanız:
apiVersionpbiviz.json dosyanızdaki öğesini veya sonraki bir sürüme5.1ayarlayın.capabilities.json dosyasındaki her nesne adı ve özellik adı için eşleşen bir biçimlendirme özelliği oluşturun. Biçimlendirme özelliğinin, capabilities.json dosyasındaki nesne adı ve özellik adıyla eşleşen ve içeren bir
objectNamepropertyNametanımlayıcısı olmalıdır.
objects Özellikler dosyasındaki özellikler hala aynı biçime sahiptir ve değiştirilmesi gerekmez.
Örneğin, capabilities.json dosyanızdaki nesne şu şekilde tanımlanmışsacircle:
"objects": {
"circle": {
"properties": {
"circleColor": {
"type": {
"fill": {
"solid": {
"color": true
}
}
}
},
}
}
}
Modelinizdeki biçimlendirme özelliği türünde ColorPicker olmalı ve şu şekilde görünmelidir:
control: {
type: "ColorPicker",
properties: {
descriptor: {
objectName: "circle",
propertyName: "circleColor"
},
value: {
value: this.visualSettings.circle.circleColor
}
}
}
Aşağıdaki koşullardan biri doğruysa bir hata alırsınız:
- Yetenek dosyasındaki nesne veya özellik adı biçimlendirme modelindeki adla eşleşmiyor
- Yetenek dosyasındaki özellik türü, biçimlendirme modelindeki türle eşleşmiyor
Biçimlendirme modeli
Biçimlendirme modeli, biçim bölmenizin tüm özelliklerini açıkladığınız ve özelleştirdiğiniz yerdir.
Model bileşenlerini biçimlendirme
Yeni biçimlendirme modelinde, özellik bileşenleri mantıksal kategorilerde ve alt kategorilerde birlikte gruplandırılır. Bu gruplar modeli taramayı kolaylaştırır. En büyükten en küçüğe beş temel bileşen vardır:
Biçimlendirme modeli
Bölmenin ön arabirimini biçimlendirmek için kullanılan en büyük bölme kapsayıcısı. Biçimlendirme kartlarının listesini içerir.Biçimlendirme kartı
Biçimlendirme özellikleri için en üst düzey özellikler gruplandırma kapsayıcısı. Her kart, burada gösterildiği gibi bir veya daha fazla biçimlendirme grubundan oluşur.
Biçimlendirme grubu
İkincil düzey özellikler gruplandırma kapsayıcısı. Biçimlendirme grubu, dilimleri biçimlendirmek için bir gruplandırma kapsayıcısı olarak görüntülenir.
Dilim biçimlendirme
Özellik kapsayıcısı. İki tür dilim vardır:- Basit dilim: Tek tek özellik kapsayıcısı
- Bileşik dilim: Tek bir biçimlendirme diliminde gruplandırılmış birden çok ilgili özellik kapsayıcısı
Aşağıdaki görüntüde farklı dilim türleri gösterilmektedir. "Yazı Tipi", yazı tipi ailesi, boyutu ve kalın, italik ve alt çizgi anahtarlarından oluşan bileşik bir dilimdir. "Color", "display units" ve diğer dilimler her biri tek bileşenli basit dilimlerdir.
Görselleştirme bölmesi biçimlendirme özellikleri
Biçimlendirme modelindeki her özellik, capabilities.json dosyasındaki ve nesne türüyle eşleşmelidir.
Aşağıdaki tabloda capabilities.json dosyasındaki biçimlendirme özelliği türleri ve modern biçimlendirme modeli özelliklerinde eşleşen tür sınıfı gösterilmektedir:
| Tür | YetenekLer Değer Türü | Biçimlendirme Özelliği |
|---|---|---|
| Boolean | Boole | ToggleSwitch |
| Sayı | ||
| Numaralandırma listesi | sabit listesi:[] | |
| Color | Doldur | ColorPicker |
| Degrade | Fillrule | GradientBar: özellik değeri aşağıdakilerden oluşan bir dize olmalıdır: minValue[,midValue],maxValue |
| Metin | Metin |
Nesneleri Biçimlendirme Özellikleri
| Tür | YetenekLer Değer Türü | Biçimlendirme Özelliği |
|---|---|---|
| Yazı tipi boyutu | FontSize | NumUpDown |
| Yazı tipi ailesi | FontFamily | FontPicker |
| Satır Hizalama | Hizalama | AlignmentGroup |
| Etiket Görüntüleme Birimleri | LabelDisplayUnits | AutoDropDown |
* Numaralandırma listesi biçimlendirme özelliği, biçimlendirme modelinde ve yetenek dosyasında farklıdır.
Numaralandırma öğelerinin listesi de dahil olmak üzere biçimlendirme ayarları sınıfında aşağıdaki özellikleri bildirin:
- ItemDropdown
- ItemFlagsSelection
Numaralandırma öğelerinin listesi olmadan biçimlendirme ayarları sınıfında aşağıdaki özellikleri bildirin. Numaralandırma öğeleri listesini uygun nesnenin altında capabilities.json dosyasında bildirin. (Bu türler önceki API sürümlerindekiyle aynıdır):
- Otomatik Açılan Liste
- AutoFlagSelection
Bileşik dilim özellikleri
Biçimlendirme bileşik dilimi, birden çok ilgili özelliği bir arada içeren bir biçimlendirme dilimidir.
Şimdilik iki bileşik dilim türüne sahibiz:
FontControl
Bu, yazı tipiyle ilgili tüm özellikleri bir arada tutar. Aşağıdaki özelliklerden oluşur:- Yazı Tipi Ailesi
- Yazı Tipi Boyutu
- Kalın [isteğe bağlı]
- italik [isteğe bağlı]
- Altı çizili [isteğe bağlı]
Bu özelliklerin her birinin capabilities dosyasında karşılık gelen bir nesnesi olmalıdır:
Özellik Yetenek Türü Biçimlendirme Türü Yazı Tipi Ailesi Biçimlendirme: { fontFamily} FontPicker Yazı Tipi Boyutu Biçimlendirme: {fontSize} NumUpDown Kalın Boole ToggleSwitch Normal Boole ToggleSwitch Altı çizili Boole ToggleSwitch MarginPadding Margin doldurma, görseldeki metnin hizalamasını belirler. Aşağıdaki özelliklerden oluşur:
- Left
- Right
- Üst
- Alt
Bu özelliklerin her birinin capabilities dosyasında karşılık gelen bir nesnesi olmalıdır:
Özellik Yetenek Türü Biçimlendirme Türü Left Sayısal NumUpDown Right Sayısal NumUpDown Üst Sayısal NumUpDown Alt Sayısal NumUpDown
Örnek: Veri kartını biçimlendirme
Bu örnekte, bir kartla özel görsel biçimlendirme modelinin nasıl der yapılacağını göstereceğiz.
Kartın iki grubu vardır:
- Tek bileşik özelliği olan yazı tipi denetim grubu
- Yazı tipi denetimi
- İki basit özelliğe sahip veri tasarım grubu
- Yazı tipi rengi
- Çizgi hizalama
İlk olarak, capabilities dosyasına nesneler ekleyin:
"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
}
}
}
}
}
}
Ardından, 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;
}
Elde edilen bölme aşağıdadır:
Ayarları varsayılana sıfırla
Yeni biçim bölmesinde, açık kartta görüntülenen Varsayılana sıfırla düğmesine tıklayarak tüm biçimlendirme kartı özellikleri değerlerini varsayılan olarak sıfırlama seçeneği vardır.
Bu özelliği etkinleştirmek için, biçimlendirme kartına biçimlendirme kartı özellikleri tanımlayıcılarının revertToDefaultDescriptorslistesini ekleyin.
Aşağıdaki örnekte, varsayılana sıfırla düğmesinin nasıl ekleneceği gösterilmektedir:
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
]
};
Biçimlendirme kartlarına eklemerevertToDefaultDescriptors, biçim bölmesinin üst çubuğundaki Tüm ayarları varsayılana sıfırla düğmesine tıklayarak tüm biçimlendirme kartları özelliklerini aynı anda sıfırlamayı da mümkün kılar:
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. Nesne seçici türlerinde bunlar hakkında bilgi edinin.
Yerelleştirme
Yerelleştirme özelliği hakkında daha fazla bilgi edinmek ve yerelleştirme ortamı ayarlamak için bkz . Power BI görselinize yerel dil ekleme Yerelleştirme yöneticisini kullanarak yerelleştirmek istediğiniz bileşenleri biçimlendirme:
displayName: this.localization.getDisplayName("Font_Color_DisplayNameKey");
description: this.localization.getDisplayName("Font_Color_DescriptionKey");
Biçimlendirme modeli yardımcı programları biçimlendirmeyi yerelleştirmek için yerelleştirme.
GitHub Kaynakları
Tüm biçimlendirme modeli arabirimleri GitHub'da bulunabilir - microsoft/powerbi-visuals-api: "formatting-model-api.d.ts" içindeki Power BI özel görseller API'si
API sürüm 5.1.0'ı kullanan ve yeni biçimlendirme modeli yardımcı programlarını
getFormattingModelkullanarak uygulayan özel bir Görsel SampleBarChart örneğini GitHub'da bulabilirsiniz - microsoft/PowerBI-visuals-sampleBarChart: Öğretici için Çubuk Grafik Özel Görseli.
İlgili içerik
Başka sorunuz var mı? Power BI Topluluğu sorun
Geri Bildirim
Çok yakında: 2024 boyunca, içerik için geri bildirim mekanizması olarak GitHub Sorunları’nı kullanımdan kaldıracak ve yeni bir geri bildirim sistemiyle değiştireceğiz. Daha fazla bilgi için bkz. https://aka.ms/ContentUserFeedback.
Gönderin ve geri bildirimi görüntüleyin