Objek dan properti visual Power BI
Objek menjelaskan properti yang dapat disesuaikan yang terkait dengan visual. Objek dapat memiliki beberapa properti, dan setiap properti memiliki jenis terkait yang menjelaskan apa yang akan menjadi properti tersebut. Artikel ini menyediakan informasi tentang objek dan jenis properti.
myCustomObject adalah nama internal yang digunakan untuk mereferensikan objek dalam dataView.
"objects": {
"myCustomObject": {
"properties": { ... }
}
}
Nama tampilan dan deskripsi
Catatan
Nama tampilan dan deskripsi tidak digunakan lagi dari API versi 5.1+. Nama tampilan dan deskripsi sekarang ditambahkan dalam model pemformatan alih-alih file capabilities.json .
displayName adalah nama yang akan ditampilkan di panel properti.
description adalah deskripsi properti pemformatan yang akan ditampilkan kepada pengguna sebagai tipsalat.
Properti
properties adalah peta properti yang ditentukan oleh developer.
"properties": {
"myFirstProperty": {
"type": ValueTypeDescriptor | StructuralTypeDescriptor
}
}
Catatan
show adalah properti khusus yang memungkinkan pengalih untuk mengalihkan objek.
Contoh:
"properties": {
"show": {
"type": {"bool": true}
}
}
Jenis properti
Ada dua jenis properti: ValueTypeDescriptor dan StructuralTypeDescriptor.
Deskriptor jenis nilai
ValueTypeDescriptor jenis sebagian besar primitif dan biasanya digunakan sebagai objek statis.
Berikut adalah beberapa elemen ValueTypeDescriptor yang umum:
export interface ValueTypeDescriptor {
text?: boolean;
numeric?: boolean;
integer?: boolean;
bool?: boolean;
}
Deskriptor jenis struktural
StructuralTypeDescriptor jenis sebagian besar digunakan untuk objek yang terikat dengan data.
Jenis yang paling umum StructuralTypeDescriptor adalah isi.
export interface StructuralTypeDescriptor {
fill?: FillTypeDescriptor;
}
Properti gradien
Properti gradien adalah properti yang tidak dapat diatur sebagai properti standar. Sebagai gantinya, Anda perlu menetapkan aturan untuk penggantian properti pemilih warna (jenis isi).
Contoh ditunjukkan dalam kode berikut:
"properties": {
"showAllDataPoints": {
"type": {
"bool": true
}
},
"fill": {
"type": {
"fill": {
"solid": {
"color": true
}
}
}
},
"fillRule": {
"type": {
"fillRule": {}
},
"rule": {
"inputRole": "Gradient",
"output": {
"property": "fill",
"selector": [
"Category"
]
}
}
}
}
Perhatikan properti isian dan fillRule. Yang pertama adalah pemilih warna, dan yang kedua adalah aturan penggantian untuk gradien yang akan menggantikan properti isian, visually, ketika kondisi aturan terpenuhi.
Link antara properti isian dan aturan substitusi ini diatur di bagian "rule">"output" dari properti fillRule.
"Rule">Properti "InputRole" menetapkan peran data mana yang memicu aturan (kondisi). Dalam contoh ini, jika peran data "Gradient" berisi data, aturan akan diterapkan untuk properti "fill".
Contoh peran data yang memicu aturan isian (the last item) ditampilkan dalam kode berikut:
{
"dataRoles": [
{
"name": "Category",
"kind": "Grouping",
"displayName": "Details",
"displayNameKey": "Role_DisplayName_Details"
},
{
"name": "Series",
"kind": "Grouping",
"displayName": "Legend",
"displayNameKey": "Role_DisplayName_Legend"
},
{
"name": "Gradient",
"kind": "Measure",
"displayName": "Color saturation",
"displayNameKey": "Role_DisplayName_Gradient"
}
]
}
Panel pemformatan
Untuk mengkustomisasi properti di panel pemformatan, gunakan salah satu metode berikut, bergantung pada versi API apa yang Anda gunakan.
Catatan
Metode getFormattingModel API didukung dari API versi 5.1+. Untuk mengetahui versi mana yang Anda gunakan, periksa apiVersion di file pbiviz.json .
Untuk menggunakan objek secara efektif di API versi 5.1+, Anda perlu menerapkan metode .getFormattingModel
Metode ini menyusun dan mengembalikan model pemformatan yang menyertakan hierarki panel properti lengkap kartu pemformatan, grup pemformatan, Juga berisi properti pemformatan dan nilainya.
Objek kemampuan yang tercermin dalam model pemformatan
Setiap properti pemformatan dalam model pemformatan memerlukan objek yang sesuai dalam file capabilities.json . Properti pemformatan harus berisi deskriptor dengan nama objek dan nama properti yang sama persis dengan objek kemampuan yang sesuai (nama objek dan properti peka huruf besar/kecil).
Contohnya:
Untuk properti pemformatan berikut dalam model pemformatan (Lihat konten objek deskriptor):
const myCustomCard: powerbi.visuals.FormattingCard = {
displayName: "My Custom Object Card",
uid: "myCustomObjectCard_uid",
groups: [{
displayName: undefined,
uid: "myCustomObjectGroup_uid",
slices: [
{
uid: "myCustomProperty_uid",
displayName: "My Custom Property",
control: {
type: powerbi.visuals.FormattingComponent.ColorPicker,
properties: {
descriptor: {
objectName: "myCustomObject",
propertyName: "myCustomProperty",
selector: null // selector is optional
},
value: { value: "#000000" }
}
}
}
],
}],
};
Objek yang sesuai dari bagian kemampuan objects harus:
"objects": {
"myCustomObject": {
"properties": {
"myCustomProperty": {
"type": {
"fill": {
"solid": {
"color": true
}
}
}
}
}
}
}
Pemilih properti pemformatan
Pemilih opsional dalam pendeskripsi properti pemformatan menentukan di mana setiap properti terikat dalam dataView. Ada empat pilihan yang berbeda.
Contoh
Contoh di atas myCustomCard menunjukkan properti pemformatan apa dalam model pemformatan yang akan terlihat untuk objek dengan satu properti myCustomProperty. Objek properti ini terikat secara statis ke dataViews[index].metadata.objects.
Pemilih dalam deskriptor dapat diubah sesuai dengan jenis pemilih yang Anda pilih.
Jenis pemilih objek
Pemilih di enumerateObjectInstances menentukan di mana setiap objek terikat dalam dataView. Ada empat opsi yang berbeda:
statik
Objek ini terikat ke metadata dataviews[index].metadata.objects, seperti yang ditunjukkan di sini.
selector: null
columns
Objek ini terikat ke kolom dengan pencocokan QueryName.
selector: {
metadata: 'QueryName'
}
pemilih
Objek ini terikat pada elemen yang Anda buat selectionID. Dalam contoh ini, mari kita asumsikan bahwa kita membuat selectionIDuntuk beberapa titik data, dan kita mengulanginya.
for (let dataPoint in dataPoints) {
...
selector: dataPoint.selectionID.getSelector()
}
Identitas cakupan
Objek ini terikat pada nilai-nilai tertentu di persimpangan grup. Misalnya, jika Anda memiliki kategori ["Jan", "Feb", "March", ...] dan seri ["Small", "Medium", "Large"], Anda mungkin ingin memiliki objek di persimpangan nilai yang cocok dengan Feb dan Large. Untuk mencapai ini, Anda bisa mendapatkan DataViewScopeIdentity dari kedua kolom, mendorongnya ke variabel identities, dan menggunakan sintaks ini dengan pemilih.
selector: {
data: <DataViewScopeIdentity[]>identities
}