Membuat URL peluncuran

URL peluncuran memungkinkan Anda membuka tab atau jendela browser baru dengan menambahkan host.launchUrl() panggilan API ke kode visual Power BI.

Catatan

Metode host.launchUrl() ini diperkenalkan dalam Visuals API 1.9.0.

Sampel

IVisualHost Impor antarmuka dan simpan tautan ke host objek di konstruktor visual.

import powerbi from "powerbi-visuals-api";
import IVisualHost = powerbi.extensibility.visual.IVisualHost;

export class Visual implements IVisual {
    private host: IVisualHost;
    // ...
    constructor(options: VisualConstructorOptions) {
        // ...
        this.host = options.host;
        // ...
    }

    // ...
}

Penggunaan

Gunakan panggilan API dan teruskan host.launchUrl() URL tujuan Anda sebagai argumen string:

this.host.launchUrl('https://some.link.net');

Praktik terbaik

• Biasanya, yang terbaik adalah membuka link hanya sebagai respons terhadap tindakan eksplisit pengguna. Permudah pengguna untuk memahami bahwa mengklik tautan atau tombol menghasilkan pembukaan tab baru. Ini bisa membingungkan atau membuat frustrasi pengguna jika launchUrl() panggilan memicu tanpa tindakan pengguna atau sebagai efek samping dari tindakan yang berbeda.

• Jika tautan tidak penting agar visual berfungsi dengan baik, kami sarankan Anda memberi penulis laporan cara untuk menonaktifkan dan menyembunyikan tautan. Kasus penggunaan Power BI khusus, seperti menyematkan laporan di aplikasi pihak ketiga atau menerbitkannya ke web, mungkin perlu menonaktifkan dan menyembunyikan tautan.

• Hindari memicu panggilan launchUrl() dari dalam pengulangan, fungsi update visual, atau kode lain yang sering berulang.

Contoh langkah demi langkah

Menambahkan elemen peluncuran link

Tambahkan baris berikut ke fungsi visual constructor :

    this.helpLinkElement = this.createHelpLinkElement();
    options.element.appendChild(this.helpLinkElement);

Tambahkan fungsi privat yang membuat dan melampirkan elemen jangkar:

private createHelpLinkElement(): Element {
    let linkElement = document.createElement("a");
    linkElement.textContent = "?";
    linkElement.setAttribute("title", "Open documentation");
    linkElement.setAttribute("class", "helpLink");
    linkElement.addEventListener("click", () => {
        this.host.launchUrl("https://learn.microsoft.com/power-bi/developer/visuals/custom-visual-develop-tutorial");
    });
    return linkElement;
};

Tentukan gaya untuk elemen tautan dengan entri dalam file visual.less :

.helpLink {
    position: absolute;
    top: 0px;
    right: 12px;
    display: block;
    width: 20px;
    height: 20px;
    border: 2px solid #80B0E0;
    border-radius: 20px;
    color: #80B0E0;
    text-align: center;
    font-size: 16px;
    line-height: 20px;
    background-color: #FFFFFF;
    transition: all 900ms ease;

    &:hover {
        background-color: #DDEEFF;
        color: #5080B0;
        border-color: #5080B0;
        transition: all 250ms ease;
    }

    &.hidden {
        display: none;
    }
}

Menambahkan mekanisme pengalih

Untuk menambahkan mekanisme pengalihan, Anda perlu menambahkan objek statis sehingga penulis laporan dapat mengaktifkan visibilitas elemen link. (Defaultnya diatur ke tersembunyi.) Untuk informasi selengkapnya, lihat tutorial objek statis.

showHelpLink Tambahkan objek statis Boolean ke entri objek file capabilities.json:

"objects": {
    "generalView": {
            "displayName": "General View",
            "properties":
                "showHelpLink": {
                    "displayName": "Show Help Button",
                    "type": {
                        "bool": true
                    }
                }
            }
        }
    }

Tambahkan baris berikut dalam fungsi visual update :

if (settings.generalView.showHelpLink) {
    this.helpLinkElement.classList.remove("hidden");
} else {
    this.helpLinkElement.classList.add("hidden");
}

Kelas tersembunyi didefinisikan dalam file visual.less untuk mengontrol tampilan elemen.

Pertimbangan dan batasan

• Gunakan hanya jalur absolut, bukan jalur relatif. Misalnya, gunakan jalur absolut seperti https://some.link.net/subfolder/page.html. Jalur relatif,/page.html, tidak akan dibuka.

• Saat ini, hanya protokol HTTP dan HTTPS yang didukung. Hindari FTP, MAILTO, dan protokol lainnya.