Power BI 自定义视觉对象中的格式窗格

使用 API 版本 5.1 及更高版本，开发人员可以使用 “格式”窗格创建视觉对象。 开发人员可以为自定义视觉对象中的任何属性定义卡片及其类别，从而使报表创建者更轻松地使用这些视觉对象。

API 使用 FormattingModel 方法自定义格式和分析窗格的各个部分。

getFormattingModel 返回一个 FormattingModel，它定义视觉对象的格式设置方式和分析窗格的外观。

除了所有旧的格式窗格功能之外， 格式设置模型 还支持当前格式窗格功能、属性和层次结构。

创建支持最新格式面板的视觉对象

向自定义视觉对象添加“格式”窗格支持的常规步骤：

1. 将你的 pbiviz.json 文件中的 apiVersion 设置为 5.1 或更高。

2. 在 capabilities.json 文件中定义所有自定义的objects内容。 这些对象之后映射到格式设置窗格的属性。 每个对象都需要以下属性：

   • 对象名称
   • 属性名称
   • 属性类型

   所有其他属性（包括 DisplayName 和 description）现在都是可选的。

3. 通过执行以下其中之一来生成自定义可视化FormattingModel：

   • 使用 formattingmodel util。 （推荐）
   • 如果没有此工具，请仅使用 API。

定义自定义视觉对象格式模型的属性，并使用代码（而不是 JSON）生成它。

4. 在用于自定义视觉对象的类中实现 getFormattingModel API，该 API 返回自定义视觉格式模型。 （此 API 替换以前版本中使用的 enumerateObjectInstances）。

格式设置模型实现的示例

• 使用 formattingmodel util 示例设置模型的格式。 （推荐）
• 仅使用 API 示例的格式设置模型。

映射格式设置属性

如果已使用较旧的 API 创建了自定义视觉对象，并且想要使用格式窗格更新该视觉对象，或者要创建新的自定义视觉对象：

1. 在 pbiviz.json 文件中，将 apiVersion 设置为 5.1 或更高。

2. 对于 capabilities.json中的每个对象名称和属性名称，请创建匹配的格式设置属性。 格式设置属性应具有一个描述符，该描述符包含objectName和propertyName，与capabilities.json中的对象名称和属性名称相匹配。

objects功能文件中的属性仍具有相同的格式，无需更改。

例如，如果在 capabilities.json 文件中，circle 对象定义如下：

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

模型中的格式设置属性应为类型 ColorPicker ，如下所示：

control: {
    type: "ColorPicker",
    properties: {
        descriptor: {
            objectName: "circle",
            propertyName: "circleColor"
        },
        value: {
            value: this.visualSettings.circle.circleColor
        }
    }
}

如果满足以下条件之一，则会出现错误：

• 功能文件中的对象或属性名称与格式设置模型中的对象或属性名称不匹配
• 功能文件中的属性类型与格式设置模型中的类型不匹配

格式设置模型

格式设置模型用于描述和自定义格式窗格的所有属性。

格式化模型组件

在格式设置模型中，属性组件按逻辑类别和子类别组合在一起。 这些组使模型更易于扫描。 有五个基本组件，从最大到最小：

• 格式设置模型 最大的窗格容器，用于设置窗格的正面界面的格式。 它包含格式设置卡片的列表。

• 格式设置卡片 用于格式设置属性的顶级属性分组容器。 每个卡片由一个或多个格式组组成，如下所示。

  

• 格式设置组
  辅助级别属性分组容器。 格式设置组显示为用于格式设置切片的分组容器。

  

• 设置容器格式
  辅助级别属性分组容器。 格式容器将格式分片分组到单独的容器项中，并允许通过下拉列表在它们之间切换。

  

• 格式设置切片
  属性容器。 有两种类型的切片：

  • 简单切片：单个属性容器
  • 复合切片：多个相关属性容器分组为一个格式切片

  下图显示了不同类型的切片。 “字体”是一个复合切片，由字体系列、字号、粗体、斜体和下划线开关组成。 “颜色”、“显示单元”和其他切片是简单切片，每个切片都有一个组件。

  

可视化窗格格式属性

格式设置模型中的每个属性都应匹配 capabilities.json文件中的对象 类型。

下表显示了 capabilities.json 文件中的格式属性类型及其新式格式设置模型属性属性中的匹配类型类：

功能格式设置对象

^* 枚举列表格式属性在格式设置模型和功能文件中不同。

• 在格式设置类中声明以下属性，包括枚举项列表：

  • ItemDropdown
  • ItemFlagsSelection

• 在格式设置类中声明以下属性，而不使用枚举项列表。 在相应对象下 capabilities.json 中声明其枚举项列表。 （这些类型与以前的 API 版本中相同）：

  • AutoDropdown
  • 自动旗帜选择

复合切片属性

格式复合切片是一个格式切片，其中包含多个相关属性。

目前，我们有两种复合切片类型：

• FontControl
  这会将所有与字体相关的属性保存在一起。 它包含以下属性：

  • 字体系列
  • 字体大小
  • 粗体 [可选]
  • 斜体 [可选]
  • 下划线 [可选]

  

  其中每个属性都应在功能文件中具有相应的对象：

  资产	功能类型	格式设置类型
  字体系列	格式设置：{fontFamily}	FontPicker
  字体大小	格式设置： {fontSize}	NumUpDown
  加粗	布尔值	ToggleSwitch
  斜体	布尔值	ToggleSwitch
  下划线	布尔值	ToggleSwitch

• MarginPadding 边距填充决定文本在视觉效果中的对齐方式。 它包含以下属性：

  • 左边
  • 正确
  • 顶部
  • 底部

  其中每个属性都应在功能文件中具有相应的对象：

  资产	功能类型	格式设置类型
  左边	数值	NumUpDown
  正确	数值	NumUpDown
  顶部	数值	NumUpDown
  底部	数值	NumUpDown

GitHub 资源

• 可在 GitHub - microsoft/powerbi-visuals-api 中找到所有格式设置模型接口：“formatting-model-api.d.ts”中的 Power BI 自定义视觉对象 API

• 建议使用 GitHub - microsoft/powerbi-visuals-utils-formattingmodel：Power BI 视觉对象格式设置模型帮助程序 utils 中提供的最新格式设置模型 utils

• 可以在 GitHub - microsoft/PowerBI-visuals-sampleBarChart：教程的条形图自定义可视化对象找到使用 API 版本 5.1.0 并使用最新格式设置模型 utils 实现 getFormattingModel 的自定义视觉对象 SampleBarChart 的示例。

相关内容

更多问题？ 询问 Power BI 社区。