API pemformatan pada objek (pratinjau)

Artikel
22/12/2024

Pemformatan objek memungkinkan pengguna untuk memodifikasi format visual dengan cepat dan mudah dengan langsung memilih elemen yang ingin mereka ubah. Saat elemen dipilih, panel format secara otomatis menavigasi dan memperluas pengaturan pemformatan tertentu untuk elemen yang dipilih. Untuk informasi selengkapnya tentang pemformatan pada objek, lihat Pemformatan objek di Power BI Desktop.

Untuk menambahkan fungsionalitas ini ke visual Anda, setiap visual perlu menyediakan opsi gaya subbagian dan pintasan untuk setiap wilayah subpilih.

Catatan

Visual yang mendukung pemformatan on-object perlu mengimplementasikan getFormattingModel API yang tersedia dari API versi 5.1.
Jika Anda menggunakan powerbi-visuals-utils-formattingmodel, gunakan versi 6.0.0 setidaknya.

Membuat pengalaman on-object

Gunakan layanan subbagian saat pengguna memilih elemen subpilih untuk mengirim Power BI subbagian. Berikan gaya dan pintasan sub-pemilihan menggunakan API sub-pemilihan . Pembantu subbagian dapat digunakan untuk menyederhanakan proses.

Mode format

Mode format adalah mode baru di mana pengguna dapat mengaktifkan dan menonaktifkan pemformatan onObject saat dalam mode penulisan. Visual diperbarui dengan status mode format dalam opsi pembaruan. Opsi pembaruan juga menyertakan subSeleksi yang saat ini dipilih sebagai CustomVisualSubSelection.

Cara mengimplementasikan API pemformatan pada objek

File kapabilitas

Dalam file capabilites.json, tambahkan properti berikut untuk menyatakan bahwa visual mendukung pemformatan objek:

{
  "supportsOnObjectFormatting": true,
  "enablePointerEventsFormatMode": true,
}

Antarmuka IVisual

Visual perlu mengimplementasikan antarmuka VisualOnObjectFormatting sebagai bagian dari antarmuka IVisual.

VisualOnObjectFormatting berisi tiga metode:

getSubSelectionStyles
getSubSelectionShortcuts
getSubSelectables

getSubSelectionStyles

Setiap visual diperlukan untuk mengimplementasikan metode getSubSelectionStyles, yang dipanggil ketika elemen subpilih dipilih. Metode getSubSelectionStyles disediakan dengan elemen subpilih saat ini sebagai array CustomVisualSubSelection dan diharapkan mengembalikan objek SubSelectionStyles atau undefined.

Ada tiga kategori gaya subbagian yang mencakup sebagian besar skenario:

Teks
Teks Numerik
Rupa

Setiap objek SubSelectionStyles memberikan pengalaman yang berbeda bagi pengguna untuk memodifikasi gaya elemen.

getSubSelectionShortcuts

Untuk menyediakan lebih banyak opsi bagi pengguna, visual harus menerapkan metode getSubSelectionShortcuts. Metode ini mengembalikan VisualSubSelectionShortcuts atau undefined. Selain itu, jika SubSelectionShortcuts disediakan, VisualNavigateSubSelectionShortcut juga harus disediakan sehingga ketika pengguna memilih elemen dan panel format terbuka, panel secara otomatis menggulir ke kartu yang sesuai.

Ada beberapa pintasan sub-pemilihan untuk mengubah status visual. Masing-masing menentukan item menu di menu konteks dengan label yang sesuai.

Sub-Selection Menu Disambiguasi: Menu disambiguasi On-Object menyediakan metode bagi pengguna untuk memilih sub-pemilihan yang diinginkan ketika tidak jelas elemen visual mana yang sedang dipilih. Ini sering terjadi ketika pengguna memilih latar belakang visual. Agar menu disambigu menyajikan lebih banyak sub-bagian, visual harus menyediakan semua subkelas melalui metode getSubSelectables.

getSubSelectables

Untuk memberikan sub-pemilihan ke menu disambiguasi, visual perlu menerapkan metode getSubSelectables. Metode ini disediakan argumen filterType opsional, jenis SubSelectionStylesType dan mengembalikan array CustomVisualSubSelection atau undefined. Jika digunakan untuk membuat subbagian, metode HTMLSubSelectionHelper.getSubSelectables() dapat digunakan untuk mengumpulkan elemen subpilih dari DOM.

Sub-Selection Pengeditan Teks Langsung: Dengan pemformatan On-Object, Anda dapat mengklik dua kali teks elemen subs-electable untuk langsung mengeditnya. Untuk menyediakan kemampuan edit langsung, Anda perlu menyediakan RectangleSubSelectionOutline dengan Properti cVDirectEdit yang sesuai yang diisi dengan objek SubSelectableDirectEdit. Kerangka dapat disediakan sebagai kerangka kustom atau, jika Anda menggunakan HTMLSubSelectionHelper Anda dapat menggunakan atribut SubSelectableDirectEdit. (Lihat atribut yang disediakan oleh HTMLSubSelectionHelper)

Menambahkan pengeditan langsung untuk titik data tertentu (menggunakan pemilih) belum didukung.

Antarmuka FormattingId

Antarmuka berikut digunakan untuk mereferensikan pintasan dan gaya subSelection.

interface FormattingId {
            objectName: string;
            propertyName: string;
            selector?: powerbi.data.Selector;
        }

objectName: nama objek seperti yang dideklarasikan dalam capabilities.json.
propertyName: nama properti objek seperti yang dinyatakan dalam capabilities.json.
pemilih: jika titik data memiliki selectionId, gunakan selectionId.getSelector(), pemilih ini harus sama dengan yang disediakan untuk ikatan model pemformatan.

Contoh

Dalam contoh ini, kami membangun visual kustom yang memiliki dua objek, colorSelector dan directEdit. Kami menggunakan HTMLSubSelectionHelper dari util onobjectFormatting, untuk menangani sebagian besar pekerjaan subSeleksi. Untuk informasi selengkapnya, lihat utils on-object.

Pertama, kita membuat kartu untuk panel pemformatan dan menyediakan subSelectionShortcuts dan gaya untuk setiap sub-pilihan.

Tentukan objek

Tentukan objek dan nyatakan bahwa visual mendukung Pemformatan OnObject di capabilities.json:

"objects": {
      "directEdit": {
      "properties": {
        "show": {
          "displayName": "Show",
          "type": {
            "bool": true
          }
        },
        "textProperty": {
          "displayName": "Text",
          "type": {
            "text": true
          }
        },
        "fontFamily": {
          "type": {
            "formatting": {
              "fontFamily": true
            }
          }
        },
        "fontSize": {
          "type": {
            "formatting": {
              "fontSize": true
            }
          }
        },
        "bold": {
          "type": {
            "bool": true
          }
        },
        "italic": {
          "type": {
            "bool": true
          }
        },
        "underline": {
          "type": {
            "bool": true
          }
        },
        "fontColor": {
          "displayName": "Font Color",
          "type": {
            "fill": {
              "solid": {
                "color": true
              }
            }
          }
        },
        "background": {
          "displayName": "Background",
          "type": {
            "fill": {
              "solid": {
                "color": true
              }
            }
          }
        },
        "position": {
          "displayName": "Position",
          "type": {
            "enumeration": [
              { "displayName": "Left", "value": "Left" }, { "displayName": "Right", "value": "Right" }
            ]
          }
        }
      }
    },
    "colorSelector": {
      "displayName": "Data Colors",
      "properties": {
        "fill": {
          "displayName": "Color",
          "type": {
            "fill": {
              "solid": {
                "color": true
              }
            }
          }
        }
      }
    },
   },
  "supportsOnObjectFormatting": true,
  "enablePointerEventsFormatMode": true,

Menyusun kartu pemformatan

Buat kartu pemformatan mereka menggunakan utils formattingModel.

Pengaturan kartu pemilih warna

class ColorSelectorCardSettings extends Card {
    name: string = "colorSelector";
    displayName: string = "Data Colors";
    slices = [];
}

Tambahkan metode ke pemformatanSetting sehingga kita dapat mengisi irisan secara dinamis untuk objek colorSelector (titik data kita).

populateColorSelector(dataPoints: BarChartDataPoint[]) {
        let slices: formattingSettings.ColorPicker[] = this.colorSelector.slices;
        if (dataPoints) {
            dataPoints.forEach(dataPoint => {
                slices.push(new formattingSettings.ColorPicker({
                    name: "fill",
                    displayName: dataPoint.category,
                    value: { value: dataPoint.color },
                    selector: dataPoint.selectionId.getSelector(),
                }));
            });
        }
    }

Kami meneruskan pemilih titik data tertentu di bidang pemilih. Pemilih ini adalah pemilih yang digunakan saat mengimplementasikan API get onObject.

Pengaturan kartu edit langsung

class DirectEditSettings extends Card {
    displayName = 'Direct Edit';
    name = 'directEdit';
    private minFontSize: number = 8;
    private defaultFontSize: number = 11;
    show = new formattingSettings.ToggleSwitch({
        name: "show",
        displayName: undefined,
        value: true,
    });
    topLevelSlice = this.show;
    textProperty = new formattingSettings.TextInput({
        displayName: "Text Property",
        name: "textProperty",
        value: "What is your quest?",
        placeholder: ""
    });
    position = new formattingSettings.ItemDropdown({
        name: 'position',
        items: [{ displayName: 'Left', value: 'Left' }, { displayName: 'Right', value: 'Right' }],
        value: { displayName: 'Right', value: 'Right' }
    });
    font = new formattingSettings.FontControl({
        name: "font",
        displayName: 'Font',
        fontFamily: new formattingSettings.FontPicker({
            name: "fontFamily",
            displayName: "Font Family",
            value: "Segoe UI, wf_segoe-ui_normal, helvetica, arial, sans-serif"
        }),
        fontSize: new formattingSettings.NumUpDown({
            name: "fontSize",
            displayName: "Font Size",
            value: this.defaultFontSize,
            options: {
                minValue: {
                    type: powerbi.visuals.ValidatorType.Min,
                    value: this.minFontSize,
                }
            }
        }),
        bold: new formattingSettings.ToggleSwitch({
            name: 'bold',
            displayName: "Font Size",
            value: true
        }),
        italic: new formattingSettings.ToggleSwitch({
            name: 'italic',
            displayName: "Font Size",
            value: true
        }),
        underline: new formattingSettings.ToggleSwitch({
            name: 'underline',
            displayName: "Font Size",
            value: true
        })
    });
    fontColor = new formattingSettings.ColorPicker({
        name: "fontColor",
        displayName: "Color",
        value: { value: "#000000" }
    });
    background = new formattingSettings.ColorPicker({
        name: "background",
        displayName: "Color",
        value: { value: "#FFFFFF" }
    });
    slices = [this.show, this.textProperty, this.font, this.fontColor, this.background, this.position];
}

Menggunakan atribut pembantu sub-pemilihan

Tambahkan atribut HTMLSubSelectionHelper ke objek kami. Untuk melihat atribut mana yang disediakan HTMLSubSelectionHelper, periksa dokumentasi utils objek .

Untuk atribut directEdit:

import {
   HtmlSubSelectableClass, HtmlSubSelectionHelper, SubSelectableDirectEdit as SubSelectableDirectEditAttr,
   SubSelectableDisplayNameAttribute, SubSelectableObjectNameAttribute, SubSelectableTypeAttribute 
} from 'powerbi-visuals-utils-onobjectutils';

const DirectEdit: powerbi.visuals.SubSelectableDirectEdit = {
    reference: {
        objectName: 'directEdit',
        propertyName: 'textProperty'
    },
    style: SubSelectableDirectEditStyle.Outline,
};
private visualDirectEditSubSelection = JSON.stringify(DirectEdit);

this.directEditElement
            .classed('direct-edit', true)
            .classed('hidden', !this.formattingSettings.directEditSettings.show.value)
            .classed(HtmlSubSelectableClass, options.formatMode && this.formattingSettings.directEditSettings.show.value)
            .attr(SubSelectableObjectNameAttribute, 'directEdit')
            .attr(SubSelectableDisplayNameAttribute, 'Direct Edit')
            .attr(SubSelectableDirectEditAttr, this.visualDirectEditSubSelection)

HTMLSubSelectionHelper menggunakan atribut SubSelectableDirectEditAttr untuk memberikan referensi directEdit dari kerangka directEdit, sehingga pengeditan langsung dimulai ketika pengguna mengklik dua kali pada elemen .

Cuplikan layar memperlihatkan cara kerja pembantu sub-pemilihan.

Untuk colorSelector:

barSelectionMerged
          .attr(SubSelectableObjectNameAttribute, 'colorSelector')
          .attr(SubSelectableDisplayNameAttribute, (dataPoint: BarChartDataPoint) => this.formattingSettings.colorSelector.slices[dataPoint.index].displayName)
          .attr(SubSelectableTypeAttribute, powerbi.visuals.SubSelectionStylesType.Shape)
          .classed(HtmlSubSelectableClass, options.formatMode)

Tentukan referensi

Tentukan antarmuka berikut untuk menyederhanakan contoh:

Catatan

cardUid yang Anda berikan harus sama dengan yang disediakan untuk API getFormattingModel. Misalnya, jika Anda menggunakan powerbi-visuals-utils-formattingmodel, berikan cardUid sebagai Visual-cardName-card, di mana cardName adalah nama yang Anda tetapkan ke kartu ini dalam pengaturan model pemformatan. Jika tidak, berikan sebagai Visual-cardUid Anda tetapkan ke kartu ini.

interface References {
    cardUid?: string;
    groupUid?: string;
    fill?: FormattingId;
    font?: FormattingId;
    fontColor?: FormattingId;
    show?: FormattingId;
    fontFamily?: FormattingId;
    bold?: FormattingId;
    italic?: FormattingId;
    underline?: FormattingId;
    fontSize?: FormattingId;
    position?: FormattingId;
    textProperty?: FormattingId;
}

Untuk tujuan contoh ini, buat enum untuk nama objek:

const enum BarChartObjectNames {
    ColorSelector = 'colorSelector',
    DirectEdit = 'directEdit'
}

Referensi untuk objek directEdit:

const directEditReferences: References = {
    cardUid: 'Visual-directEdit-card',
    groupUid: 'directEdit-group',
    fontFamily: {
        objectName: BarChartObjectNames.DirectEdit,
        propertyName: 'fontFamily'
    },
    bold: {
        objectName: BarChartObjectNames.DirectEdit,
        propertyName: 'bold'
    },
    italic: {
        objectName: BarChartObjectNames.DirectEdit,
        propertyName: 'italic'
    },
    underline: {
        objectName: BarChartObjectNames.DirectEdit,
        propertyName: 'underline'
    },
    fontSize: {
        objectName: BarChartObjectNames.DirectEdit,
        propertyName: 'fontSize'
    },
    fontColor: {
        objectName: BarChartObjectNames.DirectEdit,
        propertyName: 'fontColor'
    },
    show: {
        objectName: BarChartObjectNames.DirectEdit,
        propertyName: 'show'
    },
    position: {
        objectName: BarChartObjectNames.DirectEdit,
        propertyName: 'position'
    },
    textProperty: {
        objectName: BarChartObjectNames.DirectEdit,
        propertyName: 'textProperty'
    }
};

Untuk colorSelector:

const colorSelectorReferences: References = {
    cardUid: 'Visual-colorSelector-card',
    groupUid: 'colorSelector-group',
    fill: {
        objectName: BarChartObjectNames.ColorSelector,
        propertyName: 'fill'
    }
};

Menerapkan API

Sekarang mari kita terapkan dapatkan API untuk pemformatan onObject dan berikan dalam visualOnObjectFormatting:

Dalam kode konstruktor, berikan metode get di visualOnObjectFormatting:

public visualOnObjectFormatting: powerbi.extensibility.visual.VisualOnObjectFormatting;
constructor(options: VisualConstructorOptions) {
        this.subSelectionHelper = HtmlSubSelectionHelper.createHtmlSubselectionHelper({
                 hostElement: options.element,
                 subSelectionService: options.host.subSelectionService,
                 selectionIdCallback: (e) => this.selectionIdCallback(e),
            });

 this.visualOnObjectFormatting = {
                getSubSelectionStyles: (subSelections) => this.getSubSelectionStyles(subSelections),
                getSubSelectionShortcuts: (subSelections, filter) => this.getSubSelectionShortcuts(subSelections, filter),
                getSubSelectables: (filter) => this. getSubSelectables(filter)
            }
   }

private getSubSelectionStyles(subSelections: CustomVisualSubSelection[]): powerbi.visuals.SubSelectionStyles | undefined {
        const visualObject = subSelections[0]?.customVisualObjects[0];
        if (visualObject) {
            switch (visualObject.objectName) {
                case BarChartObjectNames.ColorSelector:
                    return this.getColorSelectorStyles(subSelections);
                 case BarChartObjectNames.DirectEdit:
                    return this.getDirectEditStyles();
            }
        }
    }

private getSubSelectionShortcuts(subSelections: CustomVisualSubSelection[], filter: SubSelectionShortcutsKey | undefined):    VisualSubSelectionShortcuts | undefined {
        const visualObject = subSelections[0]?.  customVisualObjects[0];
        if (visualObject) {
            switch (visualObject.objectName) {
                case BarChartObjectNames.ColorSelector:
                    return this.getColorSelectorShortcuts(subSelections);
                case BarChartObjectNames.DirectEdit:
                    return this.getDirectEditShortcuts();
            }
        }
    }

Terapkan pintasan dan gaya getSubSelection untuk colorSelector:

private getColorSelectorShortcuts(subSelections:  CustomVisualSubSelection[]): VisualSubSelectionShortcuts   {
        const selector = subSelections[0].customVisualObjects[0].selectionId?.getSelector();
        return [
            {
                type: VisualShortcutType.Reset,
                relatedResetFormattingIds: [{
                    ...colorSelectorReferences.fill,
                    selector
                }],
            },
            {
                type: VisualShortcutType.Navigate,
                destinationInfo: { cardUid: colorSelectorReferences.cardUid },
                label: 'Color'
            }
        ];
    }

Pintasan di atas mengembalikan item menu yang relevan di menu konteks dan menambahkan fungsionalitas berikut:

VisualShortcutType.Navigate: saat pengguna memilih salah satu bilah (titik data), dan panel pemformatan terbuka, panel format menggulir ke kartu pemilih warna dan membukanya
VisualShortcutType.Reset: menambahkan pintasan reset ke menu konteks. Ini diaktifkan jika warna isian diubah.

private getColorSelectorStyles(subSelections: CustomVisualSubSelection[]): SubSelectionStyles {
        const selector = subSelections[0].customVisualObjects[0].selectionId?.getSelector();
        return {
            type: SubSelectionStylesType.Shape,
            fill: {
                label: 'Fill',
                reference: {
                    ...colorSelectorReferences.fill,
                 selector
                },
            },
        };
    }

Saat pengguna mengklik kanan pada bilah, berikut ini muncul:

Cuplikan layar antarmuka pengguna saat pengguna mengklik kanan pada bilah.

Saat mengubah warna:

Cuplikan layar perubahan warna.

Pintasan sub-bagian

Untuk mengimplementasikan pintasan dan gaya subSeleksi untuk directEdit:

private getDirectEditShortcuts(): VisualSubSelectionShortcuts {
        return [
            {
                type: VisualShortcutType.Reset,
                relatedResetFormattingIds: [
                    directEditReferences.bold,
                    directEditReferences.fontFamily,
                    directEditReferences.fontSize,
                    directEditReferences.italic,
                    directEditReferences.underline,
                    directEditReferences.fontColor,
                    directEditReferences.textProperty
                ]
            },
            {
                type: VisualShortcutType.Toggle,
                relatedToggledFormattingIds: [{
                    ...directEditReferences.show,
                }],
                ...directEditReferences.show,
                disabledLabel: 'Delete',
            },
            {
                type: VisualShortcutType.Picker,
                ...directEditReferences.position,
                label: 'Position'
            },
            {
                type: VisualShortcutType.Navigate,
                destinationInfo: { cardUid: directEditReferences.cardUid },
                label: 'Direct edit'
            }
        ];
    }

Pintasan ini menambahkan item menu yang relevan di menu konteks dan menambahkan fungsionalitas berikut:

VisualShortcutType.Reset: menambahkan reset ke item default ke menu konteks, ketika salah satu properti yang disediakan dalam array relatedResetFormattingIds berubah.
VisualShortcutType.Toggle: menambahkan opsi Hapus ke menu konteks. Saat diklik, sakelar pengalih untuk kartu directEdit dinonaktifkan.
VisualShortcutType.Picker: Menambahkan opsi di menu konteks untuk memilih antara Kanan dan Kiri, karena kami menambahkan poong posisi dalam kartu pemformatan untuk directEdit.
VisualShortcutType.Navigate: Saat panel format terbuka dan pengguna memilih elemen directEdit, panel format menggulir dan membuka kartu directEdit.

private getDirectEditStyles(): SubSelectionStyles {
        return {
            type: powerbi.visuals.SubSelectionStylesType.Text,
            fontFamily: {
                reference: {
                    ...directEditReferences.fontFamily
                },
                label: 'font family'
            },
            bold: {
                reference: {
                    ...directEditReferences.bold
                },
                label: 'bold'
            },
            italic: {
                reference: {
                    ...directEditReferences.italic
                },
                label: 'italic'
            },
            underline: {
                reference: {
                    ...directEditReferences.underline
                },
                label: 'underline'
            },
            fontSize: {
                reference: {
                    ...directEditReferences.fontSize
                },
                label: 'font size'
            },
            fontColor: {
                reference: {
                    ...directEditReferences.fontColor
                },
                label: 'font color'
            },
            background: {
                reference: {
                    objectName: 'directEdit',
                    propertyName: 'background'
                },
                label: 'background'
            }
        }
    }

Kami menyediakan properti yang relevan saat kami menambahkannya dalam pemformatanSettings.

Gambar berikut menggambarkan bagaimana UI terlihat saat mengklik kanan pada elemen directEdit:

Cuplikan layar antarmuka edit langsung.

Lokalisasi

Visual harus menangani pelokalan dan menyediakan string yang dilokalkan.

Sumber daya GitHub

Semua antarmuka pemformatan objek dapat ditemukan di (tautan yang akan disediakan setelah API dirilis) di on-object-formatting-api.d.ts
Sebaiknya gunakan [pada util objek], yang mencakup [HTMLSubSelectionHelper](tautan yang akan disediakan setelah API dirilis)
Anda dapat menemukan contoh visual kustom SampleBarChart yang menggunakan API versi 5.8.0 dan mengimplementasikan dukungan untuk pemformatan objek menggunakan util pada objek di (tautan yang akan disediakan setelah API dirilis)

API Sub-Pemilihan
utils on-object

Masa depan adalah milik Anda

Bagikan melalui

API pemformatan pada objek (pratinjau)

Membuat pengalaman on-object

Mode format

Cara mengimplementasikan API pemformatan pada objek

File kapabilitas

Antarmuka IVisual

getSubSelectionStyles

getSubSelectionShortcuts

getSubSelectables

Antarmuka FormattingId

Contoh

Tentukan objek

Menyusun kartu pemformatan

Pengaturan kartu pemilih warna

Pengaturan kartu edit langsung

Menggunakan atribut pembantu sub-pemilihan

Tentukan referensi

Menerapkan API

Pintasan sub-bagian

Lokalisasi

Sumber daya GitHub

Saran dan Komentar

Sumber Daya Tambahan:

Masa depan adalah milik Anda

Bagikan melalui

API pemformatan pada objek (pratinjau)

Membuat pengalaman on-object

Mode format

Cara mengimplementasikan API pemformatan pada objek

File kapabilitas

Antarmuka IVisual

getSubSelectionStyles

getSubSelectionShortcuts

getSubSelectables

Antarmuka FormattingId

Contoh

Tentukan objek

Menyusun kartu pemformatan

Pengaturan kartu pemilih warna

Pengaturan kartu edit langsung

Menggunakan atribut pembantu sub-pemilihan

Tentukan referensi

Menerapkan API

Pintasan sub-bagian

Lokalisasi

Sumber daya GitHub

Konten terkait

Saran dan Komentar

Sumber Daya Tambahan: