Skapa en start-URL

Artikel
09/08/2023

Genom att skapa en start-URL kan du öppna en ny webbläsarflik eller ett nytt fönster genom att lägga till API-anropet host.launchUrl() i koden för ett visuellt Power BI-objekt.

Viktigt!

Metoden host.launchUrl() introducerades i Visuals API 1.9.0.

Exempel

IVisualHost Importera gränssnittet och spara länken till host objektet i konstruktorn för det visuella objektet.

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

    // ...
}

Användning

Använd API-anropet host.launchUrl() och skicka mål-URL:en som ett strängargument:

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

Begränsningar

Använd endast absoluta sökvägar, inte relativa sökvägar. Använd till exempel en absolut sökväg, till exempel https://some.link.net/subfolder/page.html. Den relativa sökvägen/page.html öppnas inte.
För närvarande stöds endast HTTP- och HTTPS-protokoll . Undvik FTP, MAILTO och andra protokoll.

Metodtips

Vanligtvis är det bäst att bara öppna en länk som svar på en användares explicita åtgärd. Gör det enkelt för användaren att förstå att om du klickar på länken eller knappen öppnas en ny flik. Det kan vara förvirrande eller frustrerande för användaren om ett launchUrl() anrop utlöses utan en användares åtgärd eller som en bieffekt av en annan åtgärd.
Om länken inte är nödvändig för att det visuella objektet ska fungera korrekt rekommenderar vi att du ger rapportens författare ett sätt att inaktivera och dölja länken. Särskilda Power BI-användningsfall, till exempel att bädda in en rapport i ett program från tredje part eller publicera den på webben, kan kräva att länken inaktiveras och döljs.
Undvik att utlösa ett launchUrl() anrop inifrån en loop, det visuella objektets update funktion eller någon annan ofta återkommande kod.

Ett steg för steg-exempel

Lägga till ett länkstartselement

Lägg till följande rader i det visuella objektets constructor funktion:

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

Lägg till en privat funktion som skapar och kopplar fästpunktselementet:

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

Definiera formatmallen för länkelementet 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;
    }
}

Lägga till en växlingsmekanism

Om du vill lägga till en växlingsmekanism måste du lägga till ett statiskt objekt så att rapportens författare kan ändra synligheten för länkelementet. (Standardvärdet är dolt.) Mer information finns i självstudiekursen för statiska objekt.

Lägg till det showHelpLink booleska statiska objektet i objektposten för filen capabilities.json :

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

Screenshot of the Power BI Visualizations pane, which shows the new Enable Help Button option.

Lägg till följande rader i det visuella objektets update funktion:

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

Den dolda klassen definieras i filen visual.less för att styra visningen av elementet.

Dela via