建立啟動 URL

文章
08/03/2024

啟動 URL 可讓您將 host.launchUrl() API 呼叫新增至 Power BI 視覺效果的程式碼，以開啟新的瀏覽器索引標籤或視窗。

注意

host.launchUrl() 方法是在 Visuals API 1.9.0 中引進。

範例

匯入 IVisualHost 介面，並在視覺效果的建構函式中儲存 host 物件的連結。

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

    // ...
}

使用方式

使用 host.launchUrl() API 呼叫，並傳遞您的目的地 URL 作為字串引數：

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

最佳作法

通常最好只在回應使用者的明確動作時才開啟連結。讓使用者輕鬆了解按一下連結或按鈕會導致開啟新的索引標籤。如果 launchUrl() 呼叫觸發而不需要使用者採取動作，或作為其他動作的副作用，可能會讓使用者感到困惑或挫折。
如果連結對於視覺效果的正常運作並不重要，則建議為報表作者提供停用和隱藏連結的方式。特殊的 Power BI 使用案例，例如將報表內嵌在第三方應用程式中，或將其發佈至 Web，可能需要停用並隱藏連結。
避免從迴圈內部、視覺效果的 update 函式或任何其他經常重複出現的程式碼內觸發 launchUrl() 呼叫。

逐步說明範例

新增連結啟動元素

將下列幾行新增至視覺效果的 constructor 函式：

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

新增能建立和連結錨點元素的私人函式：

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

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

新增切換機制

若要新增切換機制，您需要新增靜態物件，使報表作者能切換連結元素的可見性。 (預設值是設定為 hidden。)如需詳細資訊，請參閱靜態物件教學課程 \(英文\)。

將 showHelpLink 布林值靜態物件新增至 capabilities.json 檔案的物件項目：

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

Power BI [視覺效果] 窗格的螢幕擷取畫面，其中顯示新的 [啟用說明按鈕] 選項。

在視覺效果的 update 函式中新增下列幾行：

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

hidden 類別已定義於 visual.less 檔案中，以控制元素的顯示。

考量與限制

只能使用絕對路徑，不能使用相對路徑。例如，請使用 https://some.link.net/subfolder/page.html之類的絕對路徑。系統不會開啟像 /page.html 這樣的相對路徑。
目前僅支援 HTTP 和 HTTPS 通訊協定。避免 FTP、MAILTO 和其他通訊協定。

分享方式：