Criar uma URL de inicialização

Uma URL de inicialização permite que você abra uma nova guia ou janela do navegador adicionando a host.launchUrl() chamada à API ao código de um visual do Power BI.

Amostra

Importe a interface IVisualHost e salve o link do objeto host no construtor do 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 a chamada à API host.launchUrl() e passe a URL de destino como um argumento de cadeia de caracteres:

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

Práticas recomendadas

• Geralmente, é melhor abrir apenas um link como resposta à ação explícita de um usuário. Facilite para o usuário entender que clicar no link ou no botão resulta na abertura de uma nova guia. Pode ser confuso ou frustrante para o usuário se uma chamada launchUrl() for acionada sem uma ação do usuário ou como efeito colateral de uma ação diferente.

• Se o link não for crucial para o visual funcionar corretamente, recomendamos fornecer ao autor do relatório uma maneira de desabilitar e ocultar o link. Os casos especiais de uso de Power BI, como inserir um relatório em um aplicativo de terceiros ou publicá-lo na Web, podem exigir a desativação ou ocultação do link.

• Evite disparar uma chamada launchUrl() de dentro de um loop, da função update do visual ou de qualquer outro código recorrente com frequência.

Um exemplo passo a passo

Adicionar um elemento de inicialização de link

Adicione as linhas a seguir à função constructor do visual:

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

Adicione uma função particular que cria e anexa o elemento de âncora:

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 o estilo do elemento de link com uma entrada no arquivo 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;
    }
}

Adicionar um mecanismo de alternância

Para adicionar um mecanismo de alternância, você precisa adicionar um objeto estático para que o autor do relatório possa alternar a visibilidade do elemento de link. (O padrão é definido como oculto.) Para obter mais informações, confira o tutorial objeto estático.

Adicione o objeto estático booliano showHelpLink à entrada de objetos do arquivo capabilities.json:

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

Adicione as linhas a seguir na função update do visual:

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

A classe oculto é definida no arquivo visual.less para controlar a exibição do elemento.

Considerações e limitações

• Use apenas caminhos absolutos, não relativos. Por exemplo, use um caminho absoluto, como https://some.link.net/subfolder/page.html. O caminho relativo,/page.html, não será aberto.

• No momento, há suporte apenas para os protocolos HTTP e HTTPS. Evite FTP, MAILTO e outros protocolos.