Créer une URL de lancement

Article
11/21/2024

Une URL de lancement vous permet d’ouvrir un nouvel onglet ou fenêtre de navigateur en ajoutant l’appel host.launchUrl() d’API au code d’un visuel Power BI.

Remarque

La méthode host.launchUrl() a été introduite dans l’API Visuels 1.9.0.

Exemple

Importez l’interface IVisualHost et enregistrez le lien vers l’objet host dans le constructeur du visuel.

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

    // ...
}

Utilisation

Utilisez l’appel d’API host.launchUrl() et passez l’URL de destination en tant qu’argument de chaîne :

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

Bonnes pratiques

En règle générale, il est préférable d’ouvrir un lien uniquement en réponse à une action explicite de l’utilisateur. L’utilisateur doit comprendre facilement que le fait de cliquer sur le lien ou le bouton entraîne l’ouverture d’un nouvel onglet. Le déclenchement d’un appel launchUrl() sans action d’un utilisateur ou comme effet secondaire d’une autre action peut être confus ou frustrant pour l’utilisateur.
Si le lien n’est pas essentiel au bon fonctionnement du visuel, nous recommandons d’offrir à l’auteur du rapport un moyen de désactiver et masquer le lien. Des cas spéciaux d’utilisation de Power BI, tels que l’incorporation d’un rapport dans une application tierce ou sa publication sur le web, peuvent nécessiter de désactiver ou de masquer le lien.
Évitez de déclencher un appel launchUrl() à partir d’une boucle, la fonction update du visuel ou tout autre code récurrent fréquent.

Exemple pas à pas

Ajouter un élément de lancement de lien

Ajoutez les lignes suivantes à la fonction constructor du visuel :

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

Ajoutez une fonction privée qui crée et attache l’élément d’ancrage :

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

Définissez le style de l’élément de lien dans le fichier 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;
    }
}

Ajouter un mécanisme de basculement

Pour ajouter un mécanisme de basculement, vous devez ajouter un objet statique qui permette à l’auteur du rapport d’afficher ou de masquer l’élément de lien. (Par défaut, l’élément est masqué.) Pour plus d’informations, consultez le tutoriel sur les objets statiques.

Ajoutez l’objet statique booléen showHelpLink à l’entrée d’objets du fichier capabilities.json :

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

Capture d’écran du volet Visualisations Power BI, qui montre la nouvelle option Activer le bouton d’aide.

Ajoutez les lignes suivantes dans la fonction update du visuel :

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

La classe hidden est définie dans le fichier visual.less pour contrôler l’affichage de l’élément.

Observations et limitations

Utilisez uniquement des chemins absolus, pas des chemins relatifs. Par exemple, utilisez un chemin absolu tel que https://some.link.net/subfolder/page.html. Le chemin relatif /page.html ne s’ouvre pas.
Actuellement, seuls les protocoles HTTP et HTTPS sont pris en charge. Évitez, entre autres, les protocoles FTP et MAILTO.

Partage via