Opret en START-URL-adresse

Med en START-URL-adresse kan du åbne en ny browserfane eller et nyt vindue ved at føje host.launchUrl() API-kaldet til koden for en Power BI-visualisering.

Bemærk

Metoden host.launchUrl() blev introduceret i Visuals API 1.9.0.

Eksempel

Importér grænsefladen, IVisualHost og gem linket til host objektet i visualiseringens konstruktør.

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

    // ...
}

Brug

Brug API-kaldet, host.launchUrl() og send url-adressen til destinationen som et strengargument:

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

Bedste praksis

• Normalt er det bedst kun at åbne et link som svar på en brugers eksplicitte handling. Gør det nemt for brugeren at forstå, at hvis du klikker på linket eller knappen, åbnes en ny fane. Det kan være forvirrende eller frustrerende for brugeren, hvis et launchUrl() kald udløses uden en brugers handling eller som en bivirkning af en anden handling.

• Hvis linket ikke er vigtigt for, at visualiseringen fungerer korrekt, anbefaler vi, at du giver rapportens forfatter mulighed for at deaktivere og skjule linket. Særlige Power BI-use cases, f.eks. integrering af en rapport i et tredjepartsprogram eller publicering af den på internettet, kan kræve deaktivering og skjulning af linket.

• Undgå at udløse et launchUrl() kald inde fra en løkke, visualiseringens update funktion eller andre ofte tilbagevendende koder.

Et trinvist eksempel

Tilføj et element til start af et link

Føj følgende linjer til visualiseringens constructor funktion:

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

Tilføj en privat funktion, der opretter og tilknytter ankerelementet:

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

Definer typografien for linkelementet med en post i filen 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;
    }
}

Tilføj en toggling-mekanisme

Hvis du vil tilføje en toggling-mekanisme, skal du tilføje et statisk objekt, så rapportens forfatter kan slå synligheden af linkelementet til eller fra. (Standardindstillingen er angivet til skjult). Du kan få flere oplysninger i selvstudiet om statiske objekter.

Føj det showHelpLink booleske statiske objekt til objektposten for capabilities.json-filen:

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

Tilføj følgende linjer i visualiseringens update funktion:

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

Den skjulte klasse er defineret i filen visual.less for at styre visningen af elementet.

Overvejelser og begrænsninger

• Brug kun absolutte stier, ikke relative stier. Brug f.eks. en absolut sti, f.eks https://some.link.net/subfolder/page.html. . Den relative sti åbnes/page.html ikke.

• I øjeblikket understøttes kun HTTP- og HTTPS-protokoller . Undgå FTP, MAILTO og andre protokoller.