教學課程：將格式化選項新增至 Circle Card 視覺效果

當您建立視覺效果時，您可以新增自訂其屬性的選項。 一些可自訂格式化的專案包括：

• 標題
• 背景
• Border
• Shadow
• 顏色

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

• 將格式化屬性新增至視覺效果。
• 封裝視覺效果
• 將自訂視覺效果匯入 Power BI Desktop 或服務報告

先決條件

本教學課程說明如何將通用格式屬性新增至視覺效果。 我們將使用 Circle 卡片 視覺效果作為範例。 我們將新增變更圓形色彩和粗細的功能。 如果您沒有在該教學課程中建立的 Circle 記憶卡 專案資料夾，請先重做教學課程再繼續進行。

新增格式設定選項

1. 在 PowerShell 中 ，流覽至您的圓形卡片專案資料夾，然後啟動圓形卡片視覺效果。 您的視覺效果現在正在在電腦上裝載時執行。

   pbiviz start
   

2. 在 Power BI 中，選取 [ 格式] 面板 。

   您應該會看到一般格式設定選項，但不應該看到任何視覺格式設定選項。

   

3. 在 Visual Studio Code 中，開啟 capabilities.json 檔案。

4. 在 dataViewMappings 陣列之前，新增 物件 。

   "objects": {},
   

   

5. 儲存capabilities.json檔案。

6. 在 Power BI 中 ，再次檢閱格式化選項。

   注意

   如果您沒有看到格式化選項變更，請選取 [ 重載自訂視覺效果 ]。

   

7. 將 [ 標題] 選項設定為 [ 關閉 ]。 請注意，視覺效果不再顯示左上角的量值名稱。

   

   

新增自訂格式設定選項

現在，讓我們新增名為 color 的新群組，以設定圓形外框的圓形色彩和粗細。

1. 在 PowerShell 中，輸入 Ctrl + C 以停止自訂視覺效果。

2. 在 Visual Studio Code 的 檔案中 capabilities.json ，將下列 JSON 片段插入標示的物件 中。

       "circle": {
           "properties": {
               "circleColor": {
                   "type": {
                       "fill": {
                           "solid": {
                               "color": true
                           }
                       }
                   }
               },
               "circleThickness": {
                   "type": {
                       "numeric": true
                   }
               }
           }
       }
   

   此 JSON 片段描述名為 circle 的群組，其中包含兩個變數 - circleColor 和 circleThickness 。

3. 儲存capabilities.json檔案。

4. 在 [總 管] 窗格中 ，移至 src 資料夾，然後選取 settings.ts 。 此檔案代表入門視覺效果 的設定。

5. 在 檔案中 settings.ts ，將匯入行和兩個類別取代為下列程式碼。

   import { formattingSettings } from "powerbi-visuals-utils-formattingmodel";
   
   import FormattingSettingsCard = formattingSettings.SimpleCard;
   import FormattingSettingsSlice = formattingSettings.Slice;
   import FormattingSettingsModel = formattingSettings.Model;
   
   export class CircleSettings extends FormattingSettingsCard{
       public circleColor = new formattingSettings.ColorPicker({
           name: "circleColor",
           displayName: "Color",
           value: { value: "#ffffff" },
           visible: true
       });
   
       public circleThickness = new formattingSettings.NumUpDown({
           name: "circleThickness",
           displayName: "Thickness",
           value: 2,
           visible: true
       });
   
       public name: string = "circle";
       public displayName: string = "Circle";
       public visible: boolean = true;
       public slices: FormattingSettingsSlice[] = [this.circleColor, this.circleThickness]
   }
   
   export class VisualSettings extends FormattingSettingsModel {
       public circle: CircleSettings = new CircleSettings();
       public cards: FormattingSettingsCard[] = [this.circle];
   }
   

   此課程模組會定義兩個類別。 Circle設定 類別會定義兩個屬性，其名稱符合 capabilities.json 檔案中定義的物件（ circleColor 和 circleThickness ），並設定預設值。 Visual設定 類別會根據檔案中所述 capabilities.json 的屬性來定義 circle 物件。

6. 儲存settings.ts檔案。

7. 開啟 visual.ts 檔案。

8. 在 檔案中 visual.ts ，匯入 ：

   import { VisualSettings } from "./settings";
   import { FormattingSettingsService } from "powerbi-visuals-utils-formattingmodel";
   

   在 Visual 類別中 新增下列屬性：

   private visualSettings: VisualSettings;
   private formattingSettingsService: FormattingSettingsService;
   
   

   這個屬性會儲存 Visual設定 物件的參考 ，描述視覺效果設定。

9. 在 Visual 類別中 ，插入下列專案作為建構函 式的第一行 ：

   this.formattingSettingsService = new FormattingSettingsService();
   

10. 在 Visual 類別中 ，于 update 方法之後 新增下列 方法。

    public getFormattingModel(): powerbi.visuals.FormattingModel {
        return this.formattingSettingsService.buildFormattingModel(this.visualSettings);
    }
    

    此函式會在每個格式化窗格轉譯上呼叫。 它可讓您選取要公開給屬性窗格中使用者的物件和屬性。

11. 在 update 方法中 ，在 radius 變數的 宣告之後，新增下列程式 代碼。

    this.visualSettings = this.formattingSettingsService.populateFormattingSettingsModel(VisualSettings, options.dataViews);
    this.visualSettings.circle.circleThickness.value = Math.max(0, this.visualSettings.circle.circleThickness.value);
    this.visualSettings.circle.circleThickness.value = Math.min(10, this.visualSettings.circle.circleThickness.value);
    

    此程式碼會擷取格式選項。 它會調整傳入 circleThickness 屬性的任何值，並將它轉換成介於零到 10 之間的數位。

    

12. 在 circle 元素 中 ，修改傳遞至 填滿樣式和 筆劃寬度樣式 的值，如下所示：

    .style("fill", this.visualSettings.circle.circleColor.value.value)
    

    .style("stroke-width", this.visualSettings.circle.circleThickness.value)
    

    

13. 儲存visual.ts檔案。

14. 在 PowerShell 中，啟動視覺效果。

    pbiviz start
    

15. 在 Power BI 中，在 視覺效果上方的工具列中，選取 [ 切換自動重載 ]。

    

16. 在視覺格式選項中 ，展開 [圓形 ]。

    

    修改色彩 和 粗細 選項。

將 粗細 選項修改為小於零的值，以及大於 10 的值。 然後請注意，視覺效果會將值更新為可容忍的最小值或最大值。

偵錯

如需偵錯自訂視覺效果的秘訣，請參閱偵 錯指南 。

封裝自訂視覺效果

現在視覺效果已完成且可供使用，現在可以封裝它。 封裝的視覺效果可以匯入 Power BI 報表或服務，供其他人使用及享受。

當您的視覺效果準備就緒時，請遵循封裝 Power BI 視覺效果 中的 指示，然後，如果您想要，請與其他人共用它，讓他們可以 匯入 並享受它。

相關內容

• 建立 Power BI 橫條圖視覺效果
• 瞭解如何對您所建立的 Power BI 視覺效果進行偵錯
• Power BI 視覺效果專案結構