Bagikan melalui

Menambahkan keterangan alat ke visual Power BI Anda

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

  • Tampilkan tooltip.
  • Sembunyikan tooltip.
  • Pindahkan tooltip.

Tooltip dapat menampilkan elemen teks dengan judul, nilai dalam warna tertentu, dan opasitas pada koordinat yang ditentukan. 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 tooltip dalam bagan batang contoh:

Cuplikan layar yang memperlihatkan tooltip contoh bagan batang.

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

Mengelola keterangan alat

Anda dapat mengelola tooltip 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 interaksi mouse dalam visual dan, sesuai kebutuhan, memanggil delegasi show(), move(), dan hide() dengan konten yang sesuai yang diisi dalam objek Tooltip options. TooltipShowOptions dan TooltipHideOptions pada gilirannya menentukan apa yang harus ditampilkan dan cara bertindak dalam acara-acara 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 SampleBarChart visual. Anda dapat memeriksa kode sumber di barChart.ts.

Buat TooltipServiceWrapper

Konstruktor bagan batang sekarang memiliki anggota objek TooltipServiceWrapper, yang diinisialisasi di dalam 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 tooltip selama kejadian MouseMove (tidak digunakan dalam sampel ini).

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

Panggil metode 'show' untuk menampilkan tooltip

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 tooltip dari tooltipEventArgs. Ini adalah panggilan balik ke kelas BarChart, karena itu adalah logika visual. Ini adalah konten teks sebenarnya untuk ditampilkan di tooltip.
  • getDataPointIdentity: Tidak digunakan dalam sampel ini.
  • this.visualHostTooltipService.show: Panggilan untuk menampilkan tooltip.

Penanganan tambahan dapat ditemukan dalam contoh untuk kejadian mouseout dan mousemove.

Untuk informasi selengkapnya, lihat repositori visual SampleBarChart.

Isi konten tooltip 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 tooltip. 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 tooltipsobjek 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 tooltip yang didukung oleh visual dan tercermin dengan baik di bidang.
    • 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.

Cuplikan layar yang memperlihatkan dialog tipsalat halaman Laporan.

Untuk informasi selengkapnya, lihat Panduan penggunaan tooltip 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 tooltip 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 .

Cuplikan layar yang memperlihatkan tooltip modern.

Untuk mengelola dukungan tooltip modern pada halaman laporan, tambahkan properti supportEnhancedTooltips ke dalam tooltipsobjek di dalam file capabilities.json.

Contohnya:

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

Lihat contoh fitur tooltip modern yang digunakan dalam kode SampleBarChart.

Catatan

Menambahkan fitur ini ke file capabilities.json memberi pengguna kemungkinan mengaktifkan fitur ini untuk laporan. Perlu diingat bahwa pengguna masih harus mengaktifkan fitur tipsalat modern di pengaturan laporan.

Konten terkait