教學課程:開發 Power BI 圓形卡片視覺效果

在本教學課程中,您會開發名為 circle card 的 Power BI 視覺效果,以在圓形內顯示格式化的量值。 圓形卡片視覺效果支援自訂填滿色彩和外框粗細。

在本教學課程中,您會了解如何:

  • 為您的視覺效果建立開發專案。
  • 使用 D3 視覺效果元素開發視覺效果。
  • 設定視覺效果來處理資料。
  • 設定視覺效果以適應大小變更。
  • 設定視覺效果的調適型色彩和框線設定。

注意

如需此視覺效果的完整原始程式碼,請參閱 圓形卡片 Power BI 視覺效果

必要條件

開始開發 Power BI 視覺效果之前,請確認您已在本節中列出所有專案。

建立開發專案

在本節中,您會建立圓形卡片視覺效果的專案。

注意

在本教學課程中, Visual Studio Code (VS Code ) 用於開發 Power BI 視覺效果。

  1. 在 VS Code 開啟新的終端機,並流覽至您要在 中建立專案的資料夾。

  2. 在 PowerShell 終端機中輸入下列命令:

    pbiviz new CircleCard
    
  3. VS Code 總管中 開啟 CircleCard 資料夾。 ( 檔案 > 開啟資料夾 )。

    Screenshot of VS code window opened to the circle card folder.

    如需每個檔案函式的詳細說明,請參閱 Power BI 視覺專案結構

  4. 檢查終端機視窗,並確認您位於 circleCard 目錄中。 安裝 Power BI 視覺效果工具相 依性

    npm install
    

    提示

    若要查看視覺效果中已安裝哪些相依性,請檢查 package.json 檔案。

  5. 啟動圓形卡片視覺效果。

    pbiviz start
    

    您的視覺效果現在正在在電腦上裝載時執行。

    重要

    在教學課程結束時,請勿關閉 PowerShell 視窗。 若要停止視覺效果執行,請輸入 Ctrl + C ,如果系統提示您終止批次作業,請輸入 Y ,然後 輸入 Enter。

檢視Power BI 服務中的視覺效果

若要在 Power BI 服務 中測試視覺效果,我們將使用 美國銷售分析 報表。 您可以 下載 此報表,並將其上傳至Power BI 服務。

您也可以使用自己的報表來測試視覺效果。

注意

繼續之前,請確認您 已啟用視覺效果開發人員設定

  1. 登入 PowerBI.com 並開啟 [美國銷售分析 ] 報表。

  2. 選取編輯

    Screenshot of the edit option in Power B I service.

  3. 按一下 Power BI 服務介面底部的 [新增頁面] 按鈕,以建立測試的新頁面

    Screenshot of the new page button in Power B I service.

  4. 從 [ 視覺效果] 窗格中,選取 [ 開發人員視覺效果 ]。

    Screenshot of the developer visual in the visualizations pane.

    此視覺效果代表您在電腦上執行的自訂視覺效果。 只有在啟用自訂視覺偵錯 設定時 ,才能使用。

  5. 確認視覺效果已新增至報表畫布。

    Screenshot of the new visual added to the report.

    這是一個簡單的視覺效果,會顯示已呼叫其更新方法的次數。 在這個階段,視覺效果不會擷取任何資料。

    注意

    如果視覺效果顯示連線錯誤訊息,請在瀏覽器中開啟新的索引標籤,流覽至 https://localhost:8080/assets ,並授權您的瀏覽器使用此位址。

    Screenshot of the new visual displaying a connection error.

  6. 選取新的視覺效果時,請移至 [欄位 ] 窗格,展開 [銷售 ],然後選取 [ 數量 ]。

    Screenshot of the Power B I service quantity field in the sales table in the U S sales analysis report.

  7. 若要測試視覺效果的回應方式,請調整大小,並注意到每次調整視覺效果的大小時, 更新計數 值都會遞增。

    Screenshot of the new visual displaying a different update count number, after being resized.

新增視覺元素和文字

在本節中,您將瞭解如何將視覺效果變成圓形,並讓它顯示文字。

修改視覺效果檔案

設定 visual.ts 檔案。

提示

若要改善可讀性,建議您在每次將程式碼片段複製到專案中時格式化檔。 以滑鼠右鍵按一下 VS 程式碼中的任何位置,然後選取 [格式化檔 ] (或輸入 Alt + Shift + F)。

  1. 在 VS Code 的 [總管] 窗格中 ,展開 src 資料夾,然後選取 visual.ts 檔案

    Screenshot of accessing the visual.ts file in V S code.

  2. 移除 MIT 授權批註下的所有程式碼。

    重要

    請注意 visual.ts 檔案頂端的 批註。 根據麻塞諸塞理工大學 (MIT) 授權條款,有權使用 Power BI 視覺效果套件。 在合約中,您必須在檔案頂端留下批註。

  3. 匯入所需的程式庫和模組,並定義 d3 程式庫的類型選取範圍:

    "use strict";
    
    import "./../style/visual.less";
    import powerbi from "powerbi-visuals-api";
    import VisualConstructorOptions = powerbi.extensibility.visual.VisualConstructorOptions;
    import VisualUpdateOptions = powerbi.extensibility.visual.VisualUpdateOptions;
    import IVisual = powerbi.extensibility.visual.IVisual;
    import DataView = powerbi.DataView;
    import IVisualHost = powerbi.extensibility.IVisualHost;
    import * as d3 from "d3";
    type Selection<T extends d3.BaseType> = d3.Selection<T, any, any, any>;
    

    注意

    如果 D3 JavaScript 程式庫未安裝為安裝程式的一部分,請立即安裝。 從 PowerShell 執行 npm i d3@latest --save

    請注意,您匯入的專案包括:

    • IVisualHost - 用來與視覺主機互動的屬性和服務集合(Power BI)。
    • D3 程式庫 - 用來建立資料驅動檔的 JavaScript 程式庫。
  4. 在匯入下方,建立空 的視覺 類別。 視覺效果 類別會實作所有視覺效果開始的 IVisual 介面:

    export class Visual implements IVisual {
    
    }
    

    如需視覺類別內容的相關資訊,請參閱 Visual API 。 在接下來的三個步驟中,我們會定義這個類別。

  5. 在視覺化 類別的 開頭新增類別層級 用方法:

    private host: IVisualHost;
    private svg: Selection<SVGElement>;
    private container: Selection<SVGElement>;
    private circle: Selection<SVGElement>;
    private textValue: Selection<SVGElement>;
    private textLabel: Selection<SVGElement>;
    

    請注意,其中有些私用方法會使用 Selection 類型。

  6. 在建構 函式方法中 定義圓形和文字專案。 當視覺效果具現化時,會呼叫這個方法。 D3 可調整向量圖形 (SVG) 可讓您建立三個圖形:圓形和兩個文字元素:

    constructor(options: VisualConstructorOptions) {
        this.svg = d3.select(options.element)
            .append('svg')
            .classed('circleCard', true);
        this.container = this.svg.append("g")
            .classed('container', true);
        this.circle = this.container.append("circle")
            .classed('circle', true);
        this.textValue = this.container.append("text")
            .classed("textValue", true);
        this.textLabel = this.container.append("text")
            .classed("textLabel", true);
    }
    
  7. 在更新方法中定義寬度和高度。 每次資料或主機環境發生變更時,都會呼叫這個方法,例如新的值或調整大小。

    public update(options: VisualUpdateOptions) {
        let width: number = options.viewport.width;
        let height: number = options.viewport.height;
        this.svg.attr("width", width);
        this.svg.attr("height", height);
        let radius: number = Math.min(width, height) / 2.2;
        this.circle
            .style("fill", "white")
            .style("fill-opacity", 0.5)
            .style("stroke", "black")
            .style("stroke-width", 2)
            .attr("r", radius)
            .attr("cx", width / 2)
            .attr("cy", height / 2);
        let fontSizeValue: number = Math.min(width, height) / 5;
        this.textValue
            .text("Value")
            .attr("x", "50%")
            .attr("y", "50%")
            .attr("dy", "0.35em")
            .attr("text-anchor", "middle")
            .style("font-size", fontSizeValue + "px");
        let fontSizeLabel: number = fontSizeValue / 4;
        this.textLabel
            .text("Label")
            .attr("x", "50%")
            .attr("y", height / 2)
            .attr("dy", fontSizeValue / 1.2)
            .attr("text-anchor", "middle")
            .style("font-size", fontSizeLabel + "px");
    }
    
  8. 儲存 visual.ts 檔案。

(選擇性)檢閱視覺效果檔案中的程式碼

確認 visual.ts 檔案中的 最終程式碼看起來像這樣:

/*
*  Power BI Visual CLI
*
*  Copyright (c) Microsoft Corporation
*  All rights reserved.
*  MIT License
*
*  Permission is hereby granted, free of charge, to any person obtaining a copy
*  of this software and associated documentation files (the ""Software""), to deal
*  in the Software without restriction, including without limitation the rights
*  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
*  copies of the Software, and to permit persons to whom the Software is
*  furnished to do so, subject to the following conditions:
*
*  The above copyright notice and this permission notice shall be included in
*  all copies or substantial portions of the Software.
*
*  THE SOFTWARE IS PROVIDED *AS IS*, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
*  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
*  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
*  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
*  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
*  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
*  THE SOFTWARE.
*/
"use strict";

import "./../style/visual.less";
import powerbi from "powerbi-visuals-api";
import VisualConstructorOptions = powerbi.extensibility.visual.VisualConstructorOptions;
import VisualUpdateOptions = powerbi.extensibility.visual.VisualUpdateOptions;
import IVisual = powerbi.extensibility.visual.IVisual;
import DataView = powerbi.DataView;
import IVisualHost = powerbi.extensibility.IVisualHost;
import * as d3 from "d3";
type Selection<T extends d3.BaseType> = d3.Selection<T, any, any, any>;

export class Visual implements IVisual {
    private host: IVisualHost;
    private svg: Selection<SVGElement>;
    private container: Selection<SVGElement>;
    private circle: Selection<SVGElement>;
    private textValue: Selection<SVGElement>;
    private textLabel: Selection<SVGElement>;
    
    constructor(options: VisualConstructorOptions) {
        this.svg = d3.select(options.element)
            .append('svg')
            .classed('circleCard', true);
        this.container = this.svg.append("g")
            .classed('container', true);
        this.circle = this.container.append("circle")
            .classed('circle', true);
        this.textValue = this.container.append("text")
            .classed("textValue", true);
        this.textLabel = this.container.append("text")
            .classed("textLabel", true);
    }
    
    public update(options: VisualUpdateOptions) {
        let width: number = options.viewport.width;
        let height: number = options.viewport.height;
        this.svg.attr("width", width);
        this.svg.attr("height", height);
        let radius: number = Math.min(width, height) / 2.2;
        this.circle
            .style("fill", "white")
            .style("fill-opacity", 0.5)
            .style("stroke", "black")
            .style("stroke-width", 2)
            .attr("r", radius)
            .attr("cx", width / 2)
            .attr("cy", height / 2);
        let fontSizeValue: number = Math.min(width, height) / 5;
        this.textValue
            .text("Value")
            .attr("x", "50%")
            .attr("y", "50%")
            .attr("dy", "0.35em")
            .attr("text-anchor", "middle")
            .style("font-size", fontSizeValue + "px");
        let fontSizeLabel: number = fontSizeValue / 4;
        this.textLabel
            .text("Label")
            .attr("x", "50%")
            .attr("y", height / 2)
            .attr("dy", fontSizeValue / 1.2)
            .attr("text-anchor", "middle")
            .style("font-size", fontSizeLabel + "px");
    }
}

修改功能檔案

圓形卡片視覺效果是簡單的視覺效果,不會在 [格式] 窗格中建立任何物件。 因此,您可以安全地移除 檔案的 objects 區段。

  1. 在 VS Code 中開啟您的專案 ( 檔案 > 開啟資料夾)。

  2. 選取 capabilities.json 檔案。

    Screenshot of accessing the capabilities.json file in V S code.

  3. 移除整個 物件 陣列。
    請勿在 dataRoles dataViewMappings 之間 保留任何空白行。

  4. 儲存 capabilities.json 檔案。

重新開機圓形卡片視覺效果

停止視覺效果執行並重新啟動。

  1. 啟動視覺效果的 PowerShell 視窗中,輸入 Ctrl + C。 如果系統提示您終止批次作業,請輸入 Y ,然後 輸入 Enter

  2. 在 PowerShell ,再次啟動視覺效果。

    pbiviz start
    

使用新增的專案測試視覺效果

確認視覺效果顯示新加入的專案。

  1. 在 Power BI 服務 中,開啟 Power BI US Sales Analysis 報表。 如果您使用不同的報表來開發圓形卡片視覺效果,請流覽至該報表。

  2. 將值拖曳到 [量值 ] 方塊中,並確定視覺效果已形成圓形。

    Screenshot of the circle card visual shaped as a circle.

    如果視覺效果未顯示任何專案,請從 [欄位 ] 窗格將 [數量 ] 欄位拖曳 至開發人員視覺效果。

  3. 調整視覺效果的大小。

    請注意,圓形和文字縮放以符合視覺效果的維度。 當您調整視覺效果大小時,會呼叫 update 方法,因此視覺效果元素會重新調整。

啟用自動重載

使用此設定可確保每次儲存專案變更時,都會自動重載視覺效果。

  1. 流覽至 Power BI US 銷售分析 報表(或具有圓形卡片視覺效果的專案)。

  2. 選取圓形卡片視覺效果。

  3. 在浮動工具列中,選取 [ 切換自動重載 ]。

    Screenshot of clicking the toggle auto reload option, in the circle card visual floating toolbar.

取得視覺效果以處理資料

在本節中,您會定義資料角色和資料檢視對應。 您也會修改視覺效果,以顯示它正在顯示的值名稱。

設定功能檔案

修改 capabilities.json 檔案,以定義資料角色、物件和資料檢視對應。

  • 定義資料角色

    使用 類型量值 的單一資料角色定義 dataRoles 陣列。 此資料角色稱為 量值 ,並顯示為 Measure 。 它允許傳遞量值欄位或加總的欄位。

    1. VS Code 中開啟 capabilities.json 檔案。

    2. 移除 dataRoles 陣列內 的所有內容。

    3. 將下列程式碼 插入 dataRoles 陣列。

      {
          "displayName": "Measure",
          "name": "measure",
          "kind": "Measure"
      }
      
    4. 儲存 capabilities.json 檔案。

  • 定義資料檢視對應

    在 dataViewMappings 陣列中 定義名為 measure 欄位。 此欄位可以傳遞至資料角色。

    1. VS Code 中開啟 capabilities.json 檔案。

    2. 移除 dataViewMappings 陣列內 的所有內容。

    3. 將下列程式碼 插入 dataViewMappings 陣列。

      {
          "conditions": [
              { "measure": { "max": 1 } }
          ],
          "single": {
              "role": "measure"
          }
      }
      
    4. 儲存 capabilities.json 檔案。

確認您的 capabilities.json 檔案看起來像這樣:

{
    "dataRoles": [
        {
            "displayName": "Measure",
            "name": "measure",
            "kind": "Measure"
        }
    ],
    "dataViewMappings": [
        {
            "conditions": [
                { "measure": { "max": 1 } }
            ],
            "single": {
                "role": "measure"
            }
        }
    ],
    "privileges": []
}

(選擇性)檢閱功能檔案程式碼變更

確認圓形卡片視覺效果會顯示量值 欄位,並檢閱您使用 [ 顯示資料檢視 ] 選項所做的變更。

  1. 在 Power BI 服務 中,開啟 Power BI US Sales Analysis 報表。 如果您使用不同的報表來開發圓形卡片視覺效果,請流覽至該報表。

  2. 請注意,圓形卡片視覺效果現在可以使用標題為 Measure 欄位進行設定。 您可以將專案從 [ 欄位 ] 窗格拖放到 [ 量值] 欄位。

    Screenshot of the circle card measure filed, in the Power BI service visualization pane.

    注意

    視覺化專案尚未包含資料系結邏輯。

  3. 在浮動工具列中,選取 [ 顯示資料檢視 ]。

    Screenshot of the show dataview button, located in the circle card floating toolbar.

  4. 選取三個點展開顯示,然後選取 單一 以檢視值。

    Screenshot of the value figure as it's displayed in the circle card show dataview option.

  5. 展開中繼資料,然後展開 資料 陣列,然後檢閱 格式 displayName 值。

    Screenshot of the format and display name values as displayed in the circle card show dataview option.

  6. 若要切換回視覺效果,請在視覺效果上方的工具列中,選取 [ 顯示資料檢視 ]。

設定視覺效果以取用資料

到目前為止,視覺效果會轉譯,但不會顯示任何資料。 在本節中,您會變更 visual.ts 檔案,讓圓形卡片視覺效果可以取用資料。

  1. VS Code 中開啟 visual.ts 檔案。

  2. 在更新 方法中

    • 將下列語句新增為第一個語句。 語句會將 dataView 指派給變數以便輕鬆存取,並宣告變數來參考 dataView 物件。

      let dataView: DataView = options.dataViews[0];
      
    • 以這行程式碼取代 .text(「Value」)

      .text(<string>dataView.single.value)
      
    • 以這行程式碼取代 .text(「Label」)

      .text(dataView.metadata.columns[0].displayName)
      
  3. 儲存 visual.ts 檔案。

  4. 檢閱Power BI 服務中的視覺效果。

視覺效果現在會顯示所選資料欄位的名稱和值。

Screenshot of a circle card visual displaying the quantity value.

您現在已建立可運作的 Power BI 視覺效果。 您可以將 格式化選項 新增至其中,也可以 將它封裝 為立即使用。