Creare un URL di avvio

Creando un URL di avvio, è possibile aprire una nuova scheda o una nuova finestra del browser aggiungendo la host.launchUrl() chiamata API al codice di un oggetto visivo di Power BI.

Importante

Il host.launchUrl() metodo è stato introdotto nell'API Visuals 1.9.0.

Esempio

Importare l'interfaccia IVisualHost e salvare il collegamento all'oggetto host nel costruttore dell'oggetto visivo.

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

    // ...
}

Utilizzo

Usare la chiamata API e passare l'URL host.launchUrl() di destinazione come argomento stringa:

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

Limitazioni

• Usare solo percorsi assoluti, non percorsi relativi. Ad esempio, usare un percorso assoluto, https://some.link.net/subfolder/page.htmlad esempio . Il percorso/page.html relativo, non verrà aperto.

• Attualmente sono supportati solo i protocolli HTTP e HTTPS . Evitare FTP, MAILTO e altri protocolli.

Procedure consigliate

• In genere, è preferibile aprire un collegamento solo come risposta all'azione esplicita di un utente. Rendere più semplice per l'utente comprendere che facendo clic sul collegamento o il pulsante si apre una nuova scheda. Può essere confuso o frustrante per l'utente se una launchUrl() chiamata si attiva senza l'azione di un utente o come effetto collaterale di un'azione diversa.

• Se il collegamento non è essenziale per il corretto funzionamento dell'oggetto visivo, è consigliabile fornire all'autore del report un modo per disabilitare e nascondere il collegamento. Casi d'uso speciali di Power BI, ad esempio l'incorporamento di un report in un'applicazione di terze parti o la pubblicazione sul Web, potrebbero richiedere la disabilitazione e la nascondere del collegamento.

• Evitare di attivare una launchUrl() chiamata dall'interno di un ciclo, dalla funzione dell'oggetto update visivo o da qualsiasi altro codice ricorrente di frequente.

Esempio dettagliato

Aggiungere un elemento di avvio dei collegamenti

Aggiungere le righe seguenti alla funzione dell'oggetto constructor visivo:

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

Aggiungere una funzione privata che crea e collega l'elemento di ancoraggio:

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

Definire lo stile per l'elemento di collegamento con una voce nel 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;
    }
}

Aggiungere un meccanismo di attivazione/disattivazione

Per aggiungere un meccanismo di attivazione/disattivazione, è necessario aggiungere un oggetto statico in modo che l'autore del report possa attivare o disattivare la visibilità dell'elemento di collegamento. L'impostazione predefinita è nascosta. Per altre informazioni, vedere l'esercitazione sull'oggetto statico.

Aggiungere l'oggetto showHelpLink statico booleano alla voce degli oggetti del file capabilities.json :

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

Aggiungere le righe seguenti nella funzione dell'oggetto update visivo:

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

La classe nascosta è definita nel file visual.less per controllare la visualizzazione dell'elemento.