Een start-URL maken

Door een start-URL te maken, kunt u een nieuw browsertabblad of -venster openen door de host.launchUrl() API-aanroep toe te voegen aan de code van een Power BI-visual.

Belangrijk

De host.launchUrl() methode is geïntroduceerd in Visuals API 1.9.0.

Voorbeeld

Importeer de IVisualHost interface en sla de koppeling op naar het host object in de constructor van de 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;
        // ...
    }

    // ...
}

Gebruik

Gebruik de host.launchUrl() API-aanroep en geef uw doel-URL door als een tekenreeksargument:

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

Beperkingen

• Gebruik alleen absolute paden, niet relatieve paden. Gebruik bijvoorbeeld een absoluut pad, zoals https://some.link.net/subfolder/page.html. Het relatieve pad/page.html wordt niet geopend.

• Momenteel worden alleen HTTP- en HTTPS-protocollen ondersteund. Vermijd FTP, MAILTO en andere protocollen.

Aanbevolen procedures

• Meestal is het raadzaam om een koppeling alleen te openen als reactie op de expliciete actie van een gebruiker. Maak het voor de gebruiker gemakkelijk om te begrijpen dat klikken op de koppeling of de knop resulteert in het openen van een nieuw tabblad. Het kan verwarrend of frustrerend zijn voor de gebruiker als een launchUrl() oproep wordt geactiveerd zonder de actie van een gebruiker of als neveneffect van een andere actie.

• Als de koppeling niet essentieel is voor een goede werking van de visual, raden we u aan de auteur van het rapport een manier te geven om de koppeling uit te schakelen en te verbergen. Speciale Power BI-gebruiksvoorbeelden, zoals het insluiten van een rapport in een toepassing van derden of het publiceren ervan op internet, vereisen mogelijk het uitschakelen en verbergen van de koppeling.

• Vermijd het activeren van een launchUrl() aanroep vanuit een lus, de functie van update de visual of andere regelmatig terugkerende code.

Een stapsgewijs voorbeeld

Een element voor het starten van een koppeling toevoegen

Voeg de volgende regels toe aan de functie van constructor de visual:

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

Voeg een privéfunctie toe waarmee het ankerelement wordt gemaakt en gekoppeld:

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;
};

Definieer de stijl voor het koppelingselement met een vermelding in het bestand 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;
    }
}

Een wisselmechanisme toevoegen

Als u een wisselmechanisme wilt toevoegen, moet u een statisch object toevoegen, zodat de auteur van het rapport de zichtbaarheid van het koppelingselement kan in- of uitschakelen. (De standaardwaarde is ingesteld op verborgen.) Zie de zelfstudie voor statisch object voor meer informatie.

Voeg het showHelpLink booleaanse statische object toe aan de objectvermelding capabilities.json-bestand :

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

Voeg de volgende regels toe aan de functie van update de visual:

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

De verborgen klasse wordt gedefinieerd in het bestand visual.less om de weergave van het element te beheren.