Creación de una URL de inicio

Al crear una dirección URL de inicio, puede abrir una nueva pestaña o ventana del explorador agregando la llamada API host.launchUrl() al código de un objeto visual de Power BI.

Importante

El método host.launchUrl() se presentó en Visuals API 1.9.0.

Ejemplo

Importe la interfaz IVisualHost y guarde el vínculo en el objeto host del constructor del objeto visual.

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

    // ...
}

Uso

Use la llamada API host.launchUrl() y pase la dirección URL de destino como argumento de cadena:

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

Restricciones

• Use solo rutas de acceso absolutas, no relativas. Por ejemplo, use una ruta de acceso absoluta como https://some.link.net/subfolder/page.html. La ruta de acceso relativa /page.html no se abrirá.

• Actualmente, solo se admiten los protocolos HTTP y HTTPS. Evite FTP, MAILTO y otros protocolos.

Procedimientos recomendados

• Normalmente, es mejor abrir un vínculo solo como respuesta a una acción explícita del usuario. Los usuarios deben entender fácilmente que al hacer clic en el vínculo o el botón se abre una pestaña nueva. Desencadenar una llamada a launchUrl() sin la acción de un usuario, o como un efecto secundario de otra acción, puede ser confuso o frustrante para el usuario.

• Si el vínculo no es fundamental para el funcionamiento correcto del objeto visual, le recomendamos que proporcione al autor del informe una manera de deshabilitar y ocultar el vínculo. Los casos de uso especiales de Power BI, como insertar un informe en una aplicación de terceros o publicarlo en la web, podría requerir que el vínculo se deshabilite y se oculte.

• Evite activar una llamada a launchUrl() desde dentro de un bucle, la función update del objeto visual o cualquier otro código que se repita con frecuencia.

Ejemplo paso a paso

Adición de un elemento de inicio de vínculo

Agregue las líneas siguientes a la función constructor del objeto visual:

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

Agregue una función privada que cree y adjunte el elemento de anclaje:

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

Defina el estilo del elemento de vínculo con una entrada en el archivo 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;
    }
}

Adición de un mecanismo de alternancia

Para agregar un mecanismo de alternancia, debe agregar un objeto estático para que el autor del informe pueda alternar la visibilidad del elemento de vínculo. (El valor predeterminado se establece en hidden). Para obtener más información, vea el tutorial sobre objetos estáticos.

Agregue el objeto estático booleano showHelpLink a la entrada de objetos del archivo capabilities.json:

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

Agregue las líneas siguientes en la función update del objeto visual:

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

La clase hidden se define en el archivo visual.less para controlar la presentación del elemento.