起動 URL を作成する

起動 URL を作成することにより、Power BI ビジュアルのコードに host.launchUrl() API の呼び出しを追加して、新しいブラウザー タブまたはウィンドウを開くことができます。

重要

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');

制限

• 絶対パスのみを使用し、相対パスは使用しません。 たとえば、https://some.link.net/subfolder/page.html のような絶対パスを使用します。 相対パス /page.html を開くことはできません。

• 現在は、HTTP および HTTPS プロトコルのみがサポートされています。 FTP、MAILTO、およびその他のプロトコルは使わないでください。

ベスト プラクティス

• 通常は、ユーザーの明示的なアクションへの応答としてのみリンクを開くことをお勧めします。 リンクまたはボタンをクリックすると新しいタブが開くことを、ユーザーが容易に理解できるようにします。ユーザーのアクションがないまま、または別のアクションの副作用として launchUrl() の呼び出しをトリガーすると、ユーザーが混乱したり不満を感じたりする場合があります。

• ビジュアルが正しく機能するためにリンクが必須ではない場合は、レポートの作成者に、リンクを無効にしたり非表示にしたりする方法を提供することをお勧めします。 サードパーティのアプリケーションへのレポートの埋め込みや、Web への公開など、Power BI の特殊なユース ケースでは、リンクを無効にして非表示にすることが必要になる場合があります。

• launchUrl() の呼び出しを、ループ内、ビジュアルの update 関数、またはその他の頻繁に繰り返されるコードから、トリガーしないようにします。

ステップバイステップの例

リンク起動要素を追加する

ビジュアルの 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;
    }
}

切り替えメカニズムを追加する

切り替えメカニズムを追加するには、レポートの作成者がリンク要素の表示を切り替えることができるように、静的なオブジェクトを追加する必要があります。 (既定では "非表示" に設定されています。)詳細については、静的オブジェクトのチュートリアルに関するページを参照してください。

showHelpLink ブール型静的オブジェクトを capabilities.json ファイルの objects エントリに追加します。

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

ビジュアルの update 関数に次の行を追加します。

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

要素の表示を制御するために、hidden クラスが visual.less ファイルで定義されています。