Creare un URL di avvio

Articolo
08/16/2024

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

Nota

Il metodo host.launchUrl() è 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 host.launchUrl() e passare l'URL di destinazione come argomento stringa:

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

Procedure consigliate

In genere, è preferibile aprire un collegamento solo come risposta a un'azione esplicita dell'utente. Spiegare chiaramente all'utente che facendo clic sul collegamento o sul pulsante verrà aperta una nuova scheda. L'attivazione di una chiamata launchUrl() senza un'azione da parte dell'utente o come effetto collaterale di un'azione diversa può causare confusione o frustrazione nell'utente.
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 terzi o la pubblicazione sul Web, potrebbero richiedere di disanbilitare e nascondere il collegamento.
Evitare di attivare una chiamata launchUrl() all'interno di un ciclo, della funzione update dell'oggetto visivo o di qualsiasi altro codice che ricorre di frequente.

Esempio dettagliato

Aggiungere un elemento di avvio di un collegamento

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

    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 link. Il valore predefinito è hidden. Per altre informazioni, vedere l'esercitazione sugli oggetti statici.

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

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

Screenshot del riquadro Visualizzazioni di Power BI, che mostra la nuova opzione Abilita pulsante Guida.

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

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

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

Considerazioni e limitazioni

Usare solo i percorsi assoluti, non quelli relativi. Ad esempio, usare un percorso assoluto come https://some.link.net/subfolder/page.html. Il percorso relativo, /page.html, non verrà aperto.
Attualmente sono supportati solo i protocolli HTTP e HTTPS. Evitare FTP, MAILTO e altri protocolli.

Condividi tramite