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

文章
06/07/2024

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

在本教學課程中，您會了解如何：

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

注意

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

必要條件

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

Power BI Pro 或 Premium Per User （PPU） 帳戶。如果您沒有訂用帳戶，請註冊免費試用。
Visual Studio Code （VS Code）。 VS Code 是開發 JavaScript 和 TypeScript 應用程式的理想整合開發環境（IDE）。
Windows PowerShell 第 4 版或更新版本（適用於 Windows）。或終端機（適用於 OSX）。
準備好開發Power BI視覺效果的環境。設定您的環境以開發Power BI 視覺效果。
本教學課程使用 美國銷售分析 報告。您可以下載此報表並將其上傳至 Power BI 服務，或使用您自己的報表。如果您需要 Power BI 服務和上傳檔案的詳細資訊，請參閱開始在 Power BI 服務教學課程中建立。

建立開發專案

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

注意

在本教學課程中， Visual Studio Code （VS Code ）用於開發 Power BI 視覺效果。

在 VS Code 中開啟新的終端機，並流覽至您要在中建立項目的資料夾。
在 PowerShell 終端機中輸入下列命令：
```
pbiviz new CircleCard
```
在 VS Code 總管中開啟 CircleCard 資料夾。（檔案>開啟資料夾）。

如需每個檔案函式的詳細說明，請參閱 Power BI 視覺項目結構。
檢查終端機視窗，並確認您位於 circleCard 目錄中。安裝 Power BI 視覺效果工具相依性。
```
npm install
```
提示

若要查看視覺效果中已安裝哪些相依性，請檢查 package.json 檔案。
啟動圓形卡片視覺效果。
```
pbiviz start
```
您的視覺效果現在正在在計算機上裝載時執行。

重要

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

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

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

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

注意

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

登入 PowerBI.com 並開啟 [美國銷售分析] 報表。
選取編輯。
按兩下 Power BI 服務介面底部的 [新增頁面] 按鈕，建立新的頁面以進行測試。
從 [ 視覺效果] 窗格中，選取 [ 開發人員視覺效果]。

此視覺效果代表您在計算機上執行的自定義視覺效果。只有在啟用自定義視覺偵錯設定時，才能使用。
確認視覺效果已新增至報表畫布。

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

注意

如果視覺效果顯示連線錯誤訊息，請在瀏覽器中開啟新的索引標籤，流覽至 https://localhost:8080/assets，並授權您的瀏覽器使用此位址。
選取新的視覺效果時，請移至 [字段 ] 窗格，展開 [銷售]，然後選取 [ 數量]。
若要測試視覺效果的回應方式，請重設大小，並注意到每次調整視覺效果的大小時， 更新計數 值都會遞增。

新增視覺元素和文字

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

修改視覺效果檔案

設定 visual.ts 檔案。

提示

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

在 VS Code 的 [總管] 窗格中，展開 src 資料夾，然後選取檔案 visual.ts。
拿掉 MIT 授權批注下的所有程式代碼。

重要

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

匯入所需的連結庫和模組，並定義 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 連結庫。

在匯入下方，建立空 的視覺 類別。 視覺效果類別會實作所有視覺效果開始的 IVisual 介面：
```
export class Visual implements IVisual {

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

在可視化類別的開頭新增類別層級私用方法：

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

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

在建構函式方法中定義圓形和文字專案。當視覺效果具現化時，會呼叫這個方法。 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);
}

在更新方法中定義寬度和高度。每次數據或主機環境發生變更時，都會呼叫這個方法，例如新的值或重設大小。

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

儲存 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 區段。

在 VS Code 中開啟您的專案（檔案>開啟資料夾）。
選取capabilities.json檔案。
拿掉整個物件陣列。
請勿在 dataRoles 與 dataViewMappings 之間保留任何空白行。
儲存 capabilities.json 檔案。

重新啟動圓形卡片視覺效果

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

在啟動視覺效果的 PowerShell 視窗中，輸入 Ctrl+C。 如果系統提示您終止批次作業，請輸入 Y，然後輸入 Enter。
在 PowerShell 中，再次啟動視覺效果。
```
pbiviz start
```

使用新增的項目測試視覺效果

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

在 Power BI 服務中，開啟 Power BI US Sales Analysis 報表。如果您使用不同的報表來開發圓形卡片視覺效果，請流覽至該報表。
將值拖曳到 [量值 ] 方塊中，並確定視覺效果已形成圓形。

如果視覺效果未顯示任何專案，請從 [字段] 窗格將 [數量] 字段拖曳至開發人員視覺效果。
調整視覺效果的大小。

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

啟用自動重載

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

流覽至 Power BI US 銷售分析 報表（或具有圓形卡片視覺效果的專案）。
選取圓形卡片視覺效果。
在浮動工具列中，選取 [ 切換自動重載]。

取得視覺效果以處理數據

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

設定功能檔案

修改capabilities.json檔案，以定義數據角色、對象和數據檢視對應。

定義數據角色

使用類型量值的單一數據角色定義dataRoles陣列。此數據角色稱為量值，並顯示為 Measure。它允許傳遞量值欄位或加總的欄位。
1. 在 VS Code 中開啟capabilities.json 檔案。
2. 拿掉 dataRoles 陣列內的所有內容。
3. 將下列程式代碼插入 dataRoles 陣列程式代碼插入 dataRoles 陣列程式代碼 插入 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": []
}

（選擇性）檢閱功能檔案程式代碼變更

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

在 Power BI 服務中，開啟 Power BI US Sales Analysis 報表。如果您使用不同的報表來開發圓形卡片視覺效果，請流覽至該報表。
請注意，圓形卡片視覺效果現在可以使用標題為 Measure 的字段進行設定。您可以將項目從 [ 欄位 ] 窗格拖放到 [ 量值] 欄位。

注意

可視化專案尚未包含數據系結邏輯。
在浮動工具列中，選取 [ 顯示數據檢視]。
選取三個點展開顯示，然後選取單一以檢視值。
展開元數據，然後展開數據行數位，然後檢閱格式和 displayName 值。
若要切換回視覺效果，請在視覺效果上方的工具列中，選取 [ 顯示數據檢視]。

設定視覺效果以取用數據

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

在 VS Code 中開啟visual.ts 檔案。
在更新方法中：
- 將下列語句新增為第一個語句。語句會將 dataView 指派給變數以便輕鬆存取，並宣告變數來參考 dataView 物件。
```
let dataView: DataView = options.dataViews[0];
```
- 以這行程式代碼取代 .text（“Value”） ：
```
.text(<string>dataView.single.value)
```
- 以這行程式代碼取代 .text（“Label”） ：
```
.text(dataView.metadata.columns[0].displayName)
```
儲存 visual.ts 檔案。
檢閱 Power BI 服務中的視覺效果。

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

圓形卡片視覺效果的螢幕快照，其中顯示數量值。

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

分享方式：

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

必要條件

建立開發專案

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

新增視覺元素和文字

修改視覺效果檔案

（選擇性）檢閱視覺效果檔案中的程序代碼

修改功能檔案

重新啟動圓形卡片視覺效果

使用新增的項目測試視覺效果

啟用自動重載

取得視覺效果以處理數據

設定功能檔案

（選擇性）檢閱功能檔案程式代碼變更

設定視覺效果以取用數據

意見反映

意見反映

更多資源

分享方式：

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

必要條件

建立開發專案

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

新增視覺元素和文字

修改視覺效果檔案

（選擇性）檢閱視覺效果檔案中的程序代碼

修改功能檔案

重新啟動圓形卡片視覺效果

使用新增的項目測試視覺效果

啟用自動重載

取得視覺效果以處理數據

設定功能檔案

（選擇性）檢閱功能檔案程式代碼變更

設定視覺效果以取用數據

相關內容

意見反映

意見反映

更多資源

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