Vytvoření adresy URL pro spuštěníCreate a launch URL

Po vytvoření adresy URL pro spuštění můžete otevírat novou kartu prohlížeče (nebo okno) delegováním skutečné práce na Power BI.By creating a launch URL, you can open a new browser tab (or window) by delegating the actual work to Power BI.

Důležité

Metoda host.launchUrl() byla představena v rozhraní API vizuálů verze 1.9.0.The host.launchUrl() was introduced in Visuals API 1.9.0.

SampleSample

Importujte rozhraní IVisualHost a uložte odkaz na objekt host v konstruktoru vizuálu.Import IVisualHost interface and save link to host object in the constructor of the 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;
        // ...
    }

    // ...
}

VyužitíUsage

Použijte volání rozhraní API host.launchUrl() a cílovou adresu URL předejte jako argument řetězce:Use the host.launchUrl() API call, passing your destination URL as a string argument:

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

OmezeníRestrictions

  • Používejte jenom absolutní cesty, nikoli relativní cesty.Use only absolute paths, not relative paths. Použijte například absolutní cestu https://some.link.net/subfolder/page.html.For example, use an absolute path such as https://some.link.net/subfolder/page.html. Relativní cesta /page.html se neotevře.The relative path,/page.html, won't be opened.

  • V současné době se podporují jenom protokoly HTTP a HTTPS.Currently, only HTTP and HTTPS protocols are supported. Vyhněte se protokolům FTP, MAILTO atd.Avoid FTP, MAILTO, and so on.

Osvědčené postupyBest practices

  • Obvykle je nejlepší otevírat odkaz jenom jako reakci na explicitní akci uživatele.Usually, it's best to open a link only as a response to a user's explicit action. Usnadněte uživatelům pochopení, že kliknutí na odkaz nebo tlačítko otevře novou kartu. Aktivace volání launchUrl(), aniž by uživatel provedl nějakou akci, nebo jako vedlejší účinek jiné akce, může být pro uživatele matoucí nebo frustrující.Make it easy for the user to understand that clicking the link or button will result in opening a new tab. Triggering a launchUrl() call without a user's action, or as a side effect of a different action can be confusing or frustrating for the user.

  • Pokud není odkaz pro správné fungování vizuálu nezbytně nutný, doporučujeme, abyste autorovi sestavy umožnili tento odkaz zakázat a skrýt.If the link isn't essential for the proper functioning of the visual, we recommend that you give the report's author a way to disable and hide the link. Toto doporučení je důležité zejména ve speciálních případech použití Power BI, například při vkládání sestavy do aplikace třetí strany nebo při jejím publikování na webu.This recommendation is especially relevant for special Power BI use cases, such as embedding a report in a third-party application or publishing it to the web.

  • Vyhněte se aktivaci volání launchUrl() zevnitř smyčky, funkce update vizuálu nebo jiného často se opakujícího kódu.Avoid triggering a launchUrl() call from inside a loop, the visual's update function, or any other frequently recurring code.

Podrobný příkladA step-by-step example

Do funkce constructor vizuálu byly přidány následující řádky:The following lines were added to the visual's constructor function:

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

Byla přidána funkce private, která vytvoří a připojí element anchor:A private function that creates and attaches the anchor element was added:

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://docs.microsoft.com/power-bi/developer/visuals/custom-visual-develop-tutorial");
    });
    return linkElement;
};

Položka v souboru visual.less definuje styl elementu link:Finally, an entry in the visual.less file defines the style for the link element:

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

Přidání mechanismu přepínáníAdd a toggling mechanism

Pokud chcete přidat mechanismus přepínání, je nutné přidat statický objekt, aby autor sestavy mohl přepínat viditelnost elementu link.To add a toggling mechanism, you need to add a static object so that the report's author can toggle the visibility of the link element. (Ve výchozím nastavení je skrytý.) Další informace najdete v kurzu ke statickému objektu.(The default is set to hidden.) For more information, see the static object tutorial.

Do položky objects v souboru capabilities.json byl přidán logický statický objekt showHelpLink, jak je znázorněno v následujícím kódu:A showHelpLink Boolean static object was added to the capabilities.json file's objects entry, as shown in the following code:

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

Přepnutí adresy URL pro spuštění

Do funkce update vizuálu byly přidány následující řádky:And, in the visual's update function, the following lines were added:

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

Třída hidden je definována v souboru visual.less za účelem řízení zobrazení elementu.The hidden class is defined in the visual.less file to control the display of the element.