시작 URL 만들기

시작 URL을 만들면 Power BI 시각적 개체의 코드에 host.launchUrl() API 호출을 추가하여 새 브라우저 탭 또는 창을 열 수 있습니다.

Important

host.launchUrl() 메서드는 시각적 개체 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() 호출이 사용자 작업 없이 또는 다른 작업의 부작용으로 트리거되면 사용자가 당황하거나 불만을 가질 수 있습니다.

• 시각적 개체를 제대로 작동하는 데 링크가 중요하지 않은 경우, 보고서 작성자에게 링크를 사용하지 않도록 설정하고 숨기는 방법을 제공하는 것이 좋습니다. 타사 애플리케이션에 보고서를 포함하거나 웹에 게시하는 것과 같은 특별한 Power BI 사용 사례에서는 링크를 비활성화하고 숨겨야 할 수 있습니다.

• 루프, 시각적 개체의 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
                    }
                }
            }
        }
    }

시각적 개체의 update 함수에 다음 줄을 추가합니다.

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

숨겨진 클래스는 요소의 표시를 제어하기 위해 visual.less 파일에 정의되어 있습니다.