Menambahkan keterangan alat ke visual Power BI Anda

Keterangan alat adalah cara yang elegan untuk memberikan informasi dan detail yang lebih kontekstual ke titik data pada visual. API keterangan alat Power BI dapat menangani interaksi berikut:

• Tampilkan tipsalat.
• Sembunyikan tipsalat.
• Memindahkan tipsalat.

Keterangan alat dapat menampilkan elemen tekstual dengan judul, nilai dalam warna tertentu, dan opasitas pada serangkaian koordinat tertentu. Data ini disediakan untuk API, dan host Power BI merendernya dengan cara yang sama seperti merender keterangan alat untuk visual asli.

Anda dapat mengubah gaya keterangan alat atau menambahkan tindakan pengeboran dengan mengaktifkan fitur keterangan alat modern.

Gambar berikut ini memperlihatkan tipsalat dalam contoh bagan batang:

Gambar tipsalat di atas menggambarkan kategori dan nilai bilah tunggal. Anda dapat memperluas tipsalat untuk menampilkan beberapa nilai.

Mengelola keterangan alat

Anda dapat mengelola keterangan alat di visual Anda melalui antarmuka ITooltipService. ITooltipService memberi tahu host bahwa tipsalat perlu ditampilkan, dihapus, atau dipindahkan.

    interface ITooltipService {
        enabled(): boolean;
        show(options: TooltipShowOptions): void;
        move(options: TooltipMoveOptions): void;
        hide(options: TooltipHideOptions): void;
    }

Visual Anda harus mendeteksi peristiwa mouse dalam visual dan memanggil show()delegasi , , move()dan hide() , sesuai kebutuhan, dengan konten yang sesuai yang diisi dalam objek Tooltip options . TooltipShowOptions dan TooltipHideOptions pada gilirannya menentukan apa yang harus ditampilkan dan cara berulah dalam peristiwa ini.

Memanggil metode ini melibatkan peristiwa pengguna seperti gerakan mouse dan peristiwa sentuh, jadi ada baiknya untuk membuat pendengar untuk peristiwa ini, yang pada gilirannya akan memanggil anggota TooltipService. Contoh berikut digabungkan dalam kelas yang disebut TooltipServiceWrapper.

Kelas TooltipServiceWrapper

Ide dasar di balik kelas ini adalah untuk menahan instance TooltipService, mendengarkan aktivitas mouse D3 pada elemen yang relevan, lalu membuat panggilan ke elemen show() dan hide() bila diperlukan.

Kelas menyimpan dan mengelola status dan logika yang relevan untuk peristiwa ini, yang sebagian besar diarahkan untuk berinteraksi dengan kode D3 yang mendasarinya. Antarmuka dan konversi D3 berada di luar cakupan artikel ini.

Contoh kode dalam artikel ini didasarkan pada visual SampleBarChart. Anda dapat memeriksa kode sumber di barChart.ts.

Buat TooltipServiceWrapper

Konstruktor bagan batang sekarang memiliki anggota TooltipServiceWrapper, yang dibuat di konstruktor dengan instans host tooltipService.

        private tooltipServiceWrapper: ITooltipServiceWrapper;

        this.tooltipServiceWrapper = createTooltipServiceWrapper(this.host.tooltipService, options.element);

Kelas TooltipServiceWrapper ini memegang instans tooltipService, juga sebagai elemen D3 akar dari parameter visual dan sentuhan.

    class TooltipServiceWrapper implements ITooltipServiceWrapper {
        private handleTouchTimeoutId: number;
        private visualHostTooltipService: ITooltipService;
        private rootElement: Element;
        private handleTouchDelay: number;

        constructor(tooltipService: ITooltipService, rootElement: Element, handleTouchDelay: number) {
            this.visualHostTooltipService = tooltipService;
            this.handleTouchDelay = handleTouchDelay;
            this.rootElement = rootElement;
        }
        .
        .
        .
    }

Titik masuk tunggal untuk kelas ini untuk mendaftarkan pendengar peristiwa adalah metode addTooltip.

Metode addTooltip

        public addTooltip<T>(
            selection: d3.Selection<Element>,
            getTooltipInfoDelegate: (args: TooltipEventArgs<T>) => VisualTooltipDataItem[],
            getDataPointIdentity: (args: TooltipEventArgs<T>) => ISelectionId,
            reloadTooltipDataOnMouseMove?: boolean): void {

            if (!selection || !this.visualHostTooltipService.enabled()) {
                return;
            }
        ...
        ...
        }

• selection: d3.Selection<Element>: Elemen d3 yang menangani keterangan alat.
• getTooltipInfoDelegate: (args: TooltipEventArgs<T>) => VisualTooltipDataItem[]: Delegasi untuk mengisi konten tooltip (apa yang akan ditampilkan) per konteks.
• getDataPointIdentity: (args: TooltipEventArgs<T>) => ISelectionId: Delegasi untuk mengambil ID titik data (tidak digunakan dalam contoh ini).
• reloadTooltipDataOnMouseMove? boolean: Boolean yang menunjukkan apakah akan menyegarkan data tipsalat selama peristiwa MouseMove (tidak digunakan dalam sampel ini).

Seperti yang Anda lihat, addTooltip keluar tanpa tindakan jika tooltipService dinonaktifkan atau tidak ada pilihan nyata.

Memanggil metode tampilkan untuk menampilkan tipsalat

Metode addTooltip berikutnya mendengarkan peristiwa D3 mouseover, seperti yang ditunjukkan dalam kode berikut:

        ...
        ...
        selection.on("mouseover.tooltip", () => {
            // Ignore mouseover while handling touch events
            if (!this.canDisplayTooltip(d3.event))
                return;

            let tooltipEventArgs = this.makeTooltipEventArgs<T>(rootNode, true, false);
            if (!tooltipEventArgs)
                return;

            let tooltipInfo = getTooltipInfoDelegate(tooltipEventArgs);
            if (tooltipInfo == null)
                return;

            let selectionId = getDataPointIdentity(tooltipEventArgs);

            this.visualHostTooltipService.show({
                coordinates: tooltipEventArgs.coordinates,
                isTouchEvent: false,
                dataItems: tooltipInfo,
                identities: selectionId ? [selectionId] : [],
            });
        });

• makeTooltipEventArgs: Mengekstrak konteks dari elemen yang dipilih D3 ke dalam tooltipEventArgs. Ini juga menghitung koordinat.
• getTooltipInfoDelegate: Kemudian membangun konten tipsalat dari tooltipEventArgs. Ini adalah panggilan balik ke kelas BarChart, karena itu adalah logika visual. Ini adalah konten teks aktual untuk ditampilkan di tipsalat.
• getDataPointIdentity: Tidak digunakan dalam sampel ini.
• this.visualHostTooltipService.show: Panggilan untuk menampilkan keterangan alat.

Penanganan tambahan dapat ditemukan dalam sampel untuk peristiwa mouseout dan mousemove.

Untuk informasi selengkapnya, lihat repositori visual SampleBarChart.

Mengisi konten tipsalat dengan metode getTooltipData

Kelas BarChart ditambahkan dengan anggota getTooltipData, yang hanya mengekstrak category, value, dan color titik data ke dalam elemen VisualTooltipDataItem[].

        private static getTooltipData(value: any): VisualTooltipDataItem[] {
            return [{
                displayName: value.category,
                value: value.value.toString(),
                color: value.color,
                header: 'ToolTip Title'
            }];
        }

Dalam implementasi sebelumnya, anggota header adalah konstan, tetapi Anda dapat menggunakannya untuk implementasi yang lebih kompleks, yang memerlukan nilai dinamis. Anda dapat mengisi VisualTooltipDataItem[] dengan lebih dari satu elemen, yang menambahkan beberapa baris ke tipsalat. Ini dapat berguna dalam visual seperti bagan batang bertumpuk di mana tipsalat mungkin menampilkan data dari lebih dari satu titik data.

Memanggil metode addTooltip

Langkah terakhir adalah memanggil metode addTooltip ketika data aktual mungkin berubah. Panggilan ini terjadi dalam metode BarChart.update(). Panggilan dilakukan untuk memantau pemilihan semua elemen "bar", hanya BarChart.getTooltipData()meneruskan , seperti yang disebutkan sebelumnya.

        this.tooltipServiceWrapper.addTooltip(this.barContainer.selectAll('.bar'),
            (tooltipEvent: TooltipEventArgs<number>) => BarChart.getTooltipData(tooltipEvent.data),
            (tooltipEvent: TooltipEventArgs<number>) => null);

Menambahkan dukungan keterangan alat ke halaman laporan

Untuk menambahkan dukungan tipsalat halaman laporan (kemampuan untuk memodifikasi tipsalat di panel format halaman laporan), tambahkan tooltips objek dalam file capabilities.json .

Contohnya:

{
    "tooltips": {
        "supportedTypes": {
            "default": true,
            "canvas": true
        },
        "roles": [
            "tooltips"
        ]
    }
}

Anda kemudian dapat menentukan keterangan alat dari panel Pemformatan halaman laporan.

• supportedTypes: Konfigurasi tipsalat yang didukung oleh visual dan tercermin di bidang dengan baik.
  • default: Menentukan apakah keterangan alat "otomatis" yang mengikat melalui bidang data didukung.
  • canvas: Menentukan apakah keterangan alat halaman laporan didukung.
• roles: (Opsional) Setelah ditentukan, ini menginstruksikan peran data apa yang terikat dengan opsi tipsalat yang dipilih di bidang dengan baik.

Untuk informasi selengkapnya, lihat Panduan penggunaan keterangan alat halaman laporan.

Untuk menampilkan tipsalat halaman laporan, setelah host Power BI memanggil ITooltipService.Show(options: TooltipShowOptions) atau ITooltipService.Move(options: TooltipMoveOptions), host tersebut menggunakan selectionId (identities properti dari argumen options sebelumnya). Untuk diambil oleh tipsalat, SelectionId harus mewakili data yang dipilih (kategori, seri, dan sebagainya) item yang Anda arahkan.

Contoh pengiriman selectionId ke panggilan tampilan tipsalat diperlihatkan dalam kode berikut:

    this.tooltipServiceWrapper.addTooltip(this.barContainer.selectAll('.bar'),
        (tooltipEvent: TooltipEventArgs<number>) => BarChart.getTooltipData(tooltipEvent.data),
        (tooltipEvent: TooltipEventArgs<number>) => tooltipEvent.data.selectionID);

Menambahkan dukungan keterangan alat modern ke halaman laporan

Dari API versi 3.8.3 Anda juga dapat membuat keterangan alat visual modern. Keterangan alat visual modern menambahkan tindakan penelusuran titik data ke keterangan alat Anda, dan memperbarui gaya agar sesuai dengan tema laporan Anda. Untuk mengetahui versi mana yang Anda gunakan, periksa apiVersion di file pbiviz.json .

Untuk mengelola dukungan tipsalat modern halaman laporan, tambahkan supportEnhancedTooltips properti ke tooltips objek dalam file capabilities.json .

Contohnya:

{
    "tooltips": {
        ... ,
        "supportEnhancedTooltips": true
    }
}

Lihat contoh fitur tipsalat modern yang digunakan dalam kode SampleBarChart .

Konten terkait

• Util tipsalat
• Menyesuaikan keterangan alat di Power BI
• Membuat keterangan alat berdasarkan halaman laporan di Power BI Desktop