教學課程:開發 Power BI 圓形卡片視覺效果
在本教學課程中,您會開發名為 circle card 的 Power BI 視覺效果,以在圓形內顯示格式化的量值。 圓形卡片視覺效果支援自訂填滿色彩和外框粗細。
在本教學課程中,您會了解如何:
- 為您的視覺效果建立開發專案。
- 使用 D3 視覺效果元素開發視覺效果。
- 設定視覺效果來處理資料。
- 設定視覺效果以適應大小變更。
- 設定視覺效果的調適型色彩和框線設定。
注意
如需此視覺效果的完整原始程式碼,請參閱 圓形卡片 Power BI 視覺效果 。
必要條件
開始開發 Power BI 視覺效果之前,請確認您已在本節中列出所有專案。
Power BI Pro 或 進階版每位使用者 (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 。 它允許傳遞量值欄位或加總的欄位。
在 VS Code 中開啟 capabilities.json 檔案。
移除 dataRoles 陣列內 的所有內容。
將下列程式碼 插入 dataRoles 陣列。
{ "displayName": "Measure", "name": "measure", "kind": "Measure" }
儲存 capabilities.json 檔案。
定義資料檢視對應
在 dataViewMappings 陣列中 定義名為 measure 的 欄位。 此欄位可以傳遞至資料角色。
在 VS Code 中開啟 capabilities.json 檔案。
移除 dataViewMappings 陣列內 的所有內容。
將下列程式碼 插入 dataViewMappings 陣列。
{ "conditions": [ { "measure": { "max": 1 } } ], "single": { "role": "measure" } }
儲存 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 視覺效果。 您可以將 格式化選項 新增至其中,也可以 將它封裝 為立即使用。