教程:向圆形卡片视觉对象添加格式设置选项

创建视觉对象时,可以添加用于自定义其属性的选项。 一些可自定义格式的项包括:

  • 标题
  • 背景
  • 边框
  • Shadow
  • 颜色

在本教程中,你将了解如何执行以下操作:

  • 向视觉对象添加格式设置属性。
  • 打包视觉对象
  • 将自定义视觉对象导入到 Power BI Desktop 或服务报表

先决条件

本教程介绍如何向视觉对象添加常见格式设置属性。 我们将以圆形卡片视觉对象为例。 我们将添加更改圆形的颜色和粗细的功能。 如果你没有在该教程中创建的圆形卡片项目文件夹,请在继续之前重新完成该教程。

添加格式设置选项

  1. 在 PowerShell 中,导航到圆形卡片项目文件夹,然后启动圆形卡片视觉对象。 托管在计算机上的视觉对象现在正在运行。

    pbiviz start
    
  2. 在“Power BI”中,选择“格式页”。

    应看到一条消息 - 格式设置选项对此视觉对象不可用。

    格式设置画笔

    如果在此处看到格式设置选项但无法更改它们,请跳过添加自定义格式设置选项以对其进行自定义。

  3. 在 Visual Studio Code 中,打开 capabilities.json 文件。

  4. 在“dataViewMappings”数组前,添加“对象”(第 8 行后)。

    "objects": {},
    

    添加对象

  5. 保存 capabilities.json 文件。

  6. 在“Power BI”中,再次查看格式设置选项。

    备注

    如果没有看到格式设置选项更改,则选择“重新加载自定义视觉对象”。

    查看格式设置选项

  7. 将“标题”选项设置为“关闭”。 请注意,视觉对象不再在左上角显示度量值名称。

    磁贴选项处于关闭状态

    没有名称磁贴

添加自定义格式设置选项

现在,我们添加名为“颜色”的新组来配置圆形的颜色和宽度。

  1. 在 PowerShell 中,按 Ctrl+C 以停止自定义视觉对象。

  2. 在 Visual Studio Code 的 capabilities.json 文件中,将以下 JSON 片段插入标记为 objects 的对象 。

        {
            "circle": {
                "displayName": "Circle",
                "properties": {
                    "circleColor": {
                        "displayName": "Color",
                        "description": "The fill color of the circle.",
                        "type": {
                            "fill": {
                                "solid": {
                                    "color": true
                                }
                            }
                        }
                    },
                    "circleThickness": {
                        "displayName": "Thickness",
                        "description": "The circle thickness.",
                        "type": {
                            "numeric": true
                        }
                    }
                }
            }
        }
    

    JSON 片段描述一个名为“circle”的组,该组包含 circleColor 和 circleThickness 两个变量 。

    圆圈粗细代码

  3. 保存 capabilities.json 文件。

  4. 在“资源管理器”窗格中,转到 src 文件夹,然后选择 settings.ts 。 此文件表示入门版视觉对象的设置。

  5. settings.ts 文件中,将两个类替换为以下代码。

    export class CircleSettings {
        public circleColor: string = "white";
        public circleThickness: number = 2;
    }
    export class VisualSettings extends DataViewObjectsParser {
        public circle: CircleSettings = new CircleSettings();
    }
    

    模块类

    此模块类定义两个类。 CircleSettings 类定义两个名称与 capabilities.json 文件中定义的对象(circleColor 和 circleThickness)匹配的属性,并且还设置了默认值 。 VisualSettings 类继承 DataViewObjectParser 类并添加命名为 circle 的属性,该属性匹配 capabilities.json 文件中定义的对象,并返回“CircleSettings”的实例 。

  6. 保存 settings.ts 文件。

  7. 打开 visual.ts 文件。

  8. visual.ts 文件中,导入 VisualSettings、VisualObjectInstanceEnumeration 和 EnumerateVisualObjectInstancesOptions :

    import { VisualSettings } from "./settings";
    import VisualObjectInstanceEnumeration = powerbi.VisualObjectInstanceEnumeration;
    import EnumerateVisualObjectInstancesOptions = powerbi.EnumerateVisualObjectInstancesOptions;
    

    然后在“Visual”类中,添加以下属性:

    private visualSettings: VisualSettings;
    

    此属性存储“VisualSettings”对象的引用,描述视觉对象设置。

    添加 visual 类

  9. 在“Visual”类中,在“更新”方法前添加以下方法。 此方法用于填充格式设置选项。

    public enumerateObjectInstances(options: EnumerateVisualObjectInstancesOptions): VisualObjectInstanceEnumeration {
        const settings: VisualSettings = this.visualSettings || <VisualSettings>VisualSettings.getDefault();
        return VisualSettings.enumerateObjectInstances(settings, options);
    }
    

    此方法用于填充格式设置选项。

    视觉对象设置对象

  10. 在“更新”方法中,在“radius”变量的声明后,添加以下代码。

    this.visualSettings = VisualSettings.parse<VisualSettings>(dataView);
    
    this.visualSettings.circle.circleThickness = Math.max(0, this.visualSettings.circle.circleThickness);
    this.visualSettings.circle.circleThickness = Math.min(10, this.visualSettings.circle.circleThickness);
    

    此代码检索格式选项。 它将调整传递到“circleThickness”属性的任何值,如果为负值,则将其转换为 0,如果为大于 10 的值,则将其转换为 10。

    Radius 变量

  11. 在 circle 元素中,按如下所示修改传递到“填充样式”和“笔划宽度样式”的值 :

    this.visualSettings.circle.circleColor
    
    this.visualSettings.circle.circleThickness
    

    填充 circle 元素

  12. 保存 visual.ts 文件。

  13. 在 PowerShell 中,启动视觉对象。

    pbiviz start
    
  14. 在“Power BI”中,在视觉对象上浮动的工具栏中,选择“切换自动重新加载”。

    切换自动重新加载

  15. 在“视觉对象格式”选项中,展开“Circle”。

    Circle 格式

    修改“颜色”和“粗细”选项。

    将“粗细”选项修改为小于零的值,和大于 10 的值。 然后注意,视觉对象将该值更新为可承受的最小值或最大值。

打包自定义视觉对象

现在视觉对象已完成并可供使用,可以将其打包。 可以将打包的视觉对象导入 Power BI 报表或服务,供其他人使用和欣赏。

在本部分中,你将了解如何

编辑视觉对象的属性值

  1. 在 PowerShell 中,按 Ctrl+C 以停止自定义视觉对象。

  2. 在 Visual Studio Code 中打开 pbiviz.json 文件。

  3. 在“visual”对象中,将“displayName”属性修改为“Circle Card”。

    在“可视化效果”窗格中,将鼠标悬停在图标上方将显示显示名称。

    “显示名称”视觉对象

  4. 对于“description”属性,请输入以下文本。

    显示一个圆圈内带格式的度量值

  5. 为视觉对象填充 supportUrl 和 gitHubUrl。

    示例:

    {
        "supportUrl": "https://community.powerbi.com",
        "gitHubUrl": "https://github.com/microsoft/PowerBI-visuals-circlecard"
    }
    
  6. 在“作者”对象中输入你的详细信息。

  7. 保存 pbiviz.json 文件。

更新图标

  1. pbiviz.json 文件的“资产”对象中,请注意,文档定义图标的路径。 图标是显示在“可视化效果”**** 窗格中的图像。 它必须是 PNG 文件,20 x 20 像素。

  2. 在 Windows 资源管理器中,复制 icon.png 文件,然后粘贴该文件,以替换位于“资产”文件夹中的默认文件。

  3. 在 Visual Studio Code 的“资源管理器”窗格中,展开“资产”文件夹,然后选择 icon.png 文件 。

  4. 查看图标。

    Viz 窗格图像

打包视觉对象

  1. 在 Visual Studio Code 中,确保已保存所有文件。

  2. 若要打包自定义视觉对象,在 PowerShell 中,输入以下命令。

    pbiviz package
    

此命令在视觉对象项目的 dist/ 目录中创建一个 pbiviz 文件,并覆盖可能存在的任何先前的 pbiviz 文件。

Dist 文件夹

该包包含将自定义视觉对象导入到 Power BI 服务或 Power BI Desktop 报表所需的所有内容。 现在已打包自定义视觉对象,且它可供使用。

导入自定义视觉对象

现在,你已准备好导入圆形卡片自定义视觉对象,以便可以在报表中使用它。 按照将视觉对象文件从本地计算机导入到 Power BI 中的说明,将 circleCard.pbiviz 文件从 dist 文件夹导入到 Power BI 报表中 。

调试

有关调试自定义视觉对象的提示,请参阅调试指南

后续步骤