Mengkustomisasi panel format dalam visual kustom Power BI
Mulai dari API versi 5.1, pengembang dapat membuat visual yang menggunakan panel format Power baru. Pengembang dapat menentukan kartu dan kategorinya untuk properti apa pun dalam visual kustom mereka, sehingga memudahkan pembuat laporan untuk menggunakan visual ini.
API baru menggunakan metode FormattingModel untuk menyesuaikan bagian panel format dan analitik.
Tip
Metode menggantikan getFormattingModelenumerateObjectInstances metode di versi API sebelumnya.
mengembalikan getFormattingModel yang FormattingModel menentukan tampilan panel pemformatan dan analitik visual.
Selain semua kemampuan panel pemformatan lama, model pemformatan baru mendukung kemampuan panel format baru, properti baru, dan hierarki baru.
Untuk meningkatkan ke API versi 5.1+, atur apiVersion di file pbiviz.json Anda ke 5.1 atau yang lebih baru dan lakukan salah satu hal berikut:
- Gunakan formattingmodel util. (Disarankan)
- Tanpa util ini, gunakan HANYA API sesuai dengan metode berikut.
Membuat visual yang mendukung panel format baru
Untuk membuat visual kustom yang menggunakan panel format baru:
Tentukan semua yang dapat
objectsdisesuaikan dalam file capabilities.json Anda.
Properti berikut diperlukan untuk setiap objek:- nama objek
- nama properti
- jenis properti
Semua properti lainnya, termasuk
DisplayNamedandescription, sekarang opsional.Buat Visual FormattingModel kustom. Tentukan properti model pemformatan visual kustom Anda dan buat menggunakan kode (bukan JSON).
Terapkan
getFormattingModelAPI di kelas visual kustom yang mengembalikan model pemformatan visual kustom. (API ini menggantikanenumerateObjectInstancesyang digunakan dalam versi sebelumnya).
Properti pemformatan peta
Jika Anda memiliki visual kustom yang dibuat dengan API yang lebih lama dan ingin bermigrasi ke panel format baru, atau jika Anda membuat visual kustom baru:
Atur
apiVersiondalam file pbiviz.json Anda ke atau yang5.1lebih baru.Untuk setiap nama objek dan nama properti di capabilities.json, buat properti pemformatan yang cocok. Properti pemformatan harus memiliki deskriptor yang berisi dan
propertyNameyang cocok denganobjectNamenama objek dan nama properti di capabilities.json.
Properti objects dalam file kemampuan masih memiliki format yang sama dan tidak perlu diubah.
Misalnya, jika circle objek dalam file capabilities.json Anda didefinisikan seperti ini:
"objects": {
"circle": {
"properties": {
"circleColor": {
"type": {
"fill": {
"solid": {
"color": true
}
}
}
},
}
}
}
Properti pemformatan dalam model Anda harus berjenis ColorPicker dan terlihat seperti ini:
control: {
type: "ColorPicker",
properties: {
descriptor: {
objectName: "circle",
propertyName: "circleColor"
},
value: {
value: this.visualSettings.circle.circleColor
}
}
}
Anda akan mendapatkan kesalahan jika salah satu kondisi berikut ini benar:
- Nama objek atau properti dalam file kapabilitas tidak cocok dengan objek dalam model pemformatan
- Jenis properti dalam file kapabilitas tidak cocok dengan jenis dalam model pemformatan
Model pemformatan
Model pemformatan adalah tempat Anda menjelaskan dan mengkustomisasi semua properti panel format Anda.
Komponen model pemformatan
Dalam model pemformatan baru, komponen properti dikelompokkan bersama dalam kategori logis dan subkatoner. Grup ini membuat model lebih mudah dipindai. Ada lima komponen dasar, dari yang terbesar hingga terkecil:
Model pemformatan
Kontainer panel terbesar, digunakan untuk memformat antarmuka frontal panel. Ini berisi daftar kartu pemformatan.Kartu pemformatan
Kontainer pengelompokan properti tingkat atas untuk properti pemformatan. Setiap kartu terdiri dari satu atau beberapa grup pemformatan, seperti yang ditunjukkan di sini.
Grup pemformatan
Kontainer pengelompokan properti tingkat sekunder. Grup pemformatan ditampilkan sebagai kontainer pengelompokan untuk irisan pemformatan.
Iringan pemformatan
Kontainer properti. Ada dua jenis irisan:- Iringan sederhana: Kontainer properti individual
- Ikatan komposit: Beberapa kontainer properti terkait dikelompokkan ke dalam satu ikatan pemformatan
Gambar berikut menunjukkan berbagai jenis irisan. "Font" adalah iringan komposit yang terdiri dari keluarga font, ukuran, dan huruf tebal, miring, dan sakelar garis bawah. "Warna", "unit tampilan" dan irisan lainnya adalah irisan sederhana dengan masing-masing satu komponen.
Properti pemformatan panel visualisasi
Setiap properti dalam model pemformatan harus cocok dan jenis objek dalam file capabilities.json .
Tabel berikut ini memperlihatkan tipe properti pemformatan dalam file capabilities.json dan kelas jenis yang cocok dalam properti model pemformatan modern:
| Jenis | Jenis Nilai Kapabilitas | Properti Pemformatan |
|---|---|---|
| Boolean | Bool | BeralihSwitch |
| Angka | ||
| Daftar enumerasi | enumerasi:[] | |
| Warna | Isi | Colorpicker |
| Gradien | FillRule | GradientBar: nilai properti harus berupa string yang terdiri dari: minValue[,midValue],maxValue |
| Teks | Teks |
Objek Pemformatan Kapabilitas
| Jenis | Jenis Nilai Kapabilitas | Properti Pemformatan |
|---|---|---|
| Ukuran font | FontSize | NumUpDown |
| Kelompok font | FontFamily | FontPicker |
| Perataan Garis | Penjajaran | AlignmentGroup |
| Unit Tampilan Label | LabelDisplayUnits | AutoDropDown |
* Properti pemformatan daftar enumerasi berbeda dalam model pemformatan dan dalam file kemampuan.
Deklarasikan properti berikut dalam kelas pengaturan pemformatan, termasuk daftar item enumerasi:
- ItemDropdown
- ItemFlagsSelection
Deklarasikan properti berikut dalam kelas pengaturan pemformatan, tanpa daftar item enumerasi. Deklarasikan daftar item enumerasi mereka di capabilities.json di bawah objek yang sesuai. (Jenis ini sama seperti pada versi API sebelumnya):
- AutoDropdown
- AutoFlagSelection
Properti ilis komposit
Ikatan komposit pemformatan adalah ikatan pemformatan yang berisi beberapa properti terkait bersama-sama.
Untuk saat ini kita memiliki dua jenis ilis komposit:
FontControl
Ini membuat semua properti terkait font tetap bersama-sama. Ini terdiri dari properti berikut:- Keluarga Font
- Ukuran Font
- Tebal [opsional]
- Miring [opsional]
- Garis bawah [opsional]
Masing-masing properti ini harus memiliki objek yang sesuai dalam file kemampuan:
Properti Jenis Kemampuan Tipe Pemformatan Keluarga Font Pemformatan: { fontFamily} FontPicker Ukuran Font Pemformatan: {fontSize} NumUpDown Bold Bool BeralihSwitch Italic Bool BeralihSwitch Garis Bawah Bool BeralihSwitch MarginPadding Margin padding menentukan perataan teks dalam visual. Ini terdiri dari properti berikut:
- Left
- Right
- Atas
- Bawah
Masing-masing properti ini harus memiliki objek yang sesuai dalam file kemampuan:
Properti Jenis Kemampuan Tipe Pemformatan Left Numerik NumUpDown Right Numerik NumUpDown Atas Numerik NumUpDown Bawah Numerik NumUpDown
Contoh: Memformat kartu data
Dalam contoh ini, kami menunjukkan cara membuat model pemformatan visual kustom dengan satu kartu.
Kartu ini memiliki dua grup:
- Grup kontrol font dengan satu properti komposit
- Kontrol font
- Grup desain data dengan dua properti sederhana
- Warna huruf
- Perataan garis
Pertama, tambahkan objek ke file kemampuan:
"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
}
}
}
}
}
}
Kemudian, buat 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;
}
Berikut adalah panel yang dihasilkan:
Mengatur ulang pengaturan ke default
Panel format baru memiliki opsi untuk mengatur ulang semua nilai properti kartu pemformatan ke default dengan mengklik tombol Reset ke default yang muncul di kartu terbuka.
Untuk mengaktifkan fitur ini, tambahkan daftar deskriptor properti kartu pemformatan ke kartu revertToDefaultDescriptorspemformatan .
Contoh berikut menunjukkan cara menambahkan reset ke tombol default :
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 Menambahkan ke kartu pemformatan juga memungkinkan untuk mengatur ulang semua properti kartu pemformatan sekaligus dengan mengklik tombol reset semua pengaturan ke default di bilah atas panel format:
Pemilih properti pemformatan
Pemilih opsional dalam pendeskripsi properti pemformatan menentukan di mana setiap properti terikat dalam dataView. Ada empat opsi berbeda. Baca tentang mereka dalam jenis pemilih objek.
Pelokalan
Untuk informasi selengkapnya tentang fitur pelokalan dan untuk menyiapkan lingkungan pelokalan, lihat Menambahkan bahasa lokal ke visual Power BI Anda Gunakan manajer pelokalan untuk memformat komponen yang ingin Anda lokalkan:
displayName: this.localization.getDisplayName("Font_Color_DisplayNameKey");
description: this.localization.getDisplayName("Font_Color_DescriptionKey");
Untuk melokalisasi model pemformatan, utils pemformatan pelokalan utils.
Sumber Daya GitHub
Semua antarmuka model pemformatan dapat ditemukan di GitHub - microsoft/powerbi-visuals-api: Power BI custom visuals API dalam "formatting-model-api.d.ts"
Sebaiknya gunakan utils model pemformatan baru di GitHub - microsoft/powerbi-visuals-utils-formattingmodel: Utils pembantu model pemformatan visual Power BI
Anda dapat menemukan contoh Visual SampleBarChart kustom yang menggunakan API versi 5.1.0 dan mengimplementasikan
getFormattingModelmenggunakan util model pemformatan baru di GitHub - microsoft/PowerBI-visuals-sampleBarChart: Visual Kustom Bagan Batang untuk tutorial.
Konten terkait
Ada pertanyaan lagi? Tanyakan kepada Komunitas Power BI