Power BI 视觉对象的功能和属性

每个视觉对象都有一个 capabilities.json 文件，该文件是在你运行 pbiviz new <visual project name> 命令以创建新视觉对象时自动创建的。 capabilities.json 文件向主机描述视觉对象。

capabilities.json 文件告诉主机视觉对象要接受的数据类型、要放置在属性窗格中的可自定义属性，以及创建视觉对象所需的其他信息。 从 API v4.6.0 开始，功能模型上的所有属性都是可选的，但 privileges 是必需的。

capabilities.json 文件按以下格式列出根对象：

{
    "privileges": [ ... ],
    "dataRoles": [ ... ],
    "dataViewMappings": [ ... ],
    "objects":  { ... },
    "supportsHighlight": true|false,
    "advancedEditModeSupport": 0|1|2,
    "sorting": { ... }
    ...
}

创建新视觉对象时，默认 capabilities.json 文件包含以下根对象：

• privileges
• dataRoles
• dataViewMappings
• objects

以上对象是数据绑定所需的对象。 可以根据需要为视觉对象编辑这些对象。

以下其他根对象是可选的，可以根据需要添加：

• tooltips
• supportsHighlight
• sorting
• 明细
• expandCollapse
• supportsKeyboardFocus
• supportsSynchronizingFilterState
• advancedEditModeSupport
• supportsLandingPage
• supportsEmptyDataView
• supportsMultiVisualSelection
• 小计
• keepAllMetadataColumns
• 迁移

可以在 capabilities.json 架构中找到所有这些对象及其参数

privileges：定义视觉对象所需的特殊权限

特权是视觉对象需要访问权限才能进行操作的特殊操作。 特权采用一组 privilege 对象，它定义了所有特权属性。 以下部分介绍 Power BI 中可用的特权。

注意

从 API v4.6.0 开始，必须在 capabilities.json 文件中指定特权。 在早期版本中，会自动授予远程访问权限，并且无法下载到文件。 若要了解正在使用的版本，请检查 pbiviz.json 文件中的 apiVersion。

定义特权

JSON 特权定义包含以下几个部分：

• name -（字符串）特权的名称。
• essential -（布尔）指示视觉对象功能是否需要此特权。 true 值表示需要特权；false 值表示该特权不是必需的。
• parameters -（字符串数组）（可选）参数。 如果缺少 parameters，则将其视为空数组。

以下是必须定义的特权类型：

• 访问外部资源
• 下载到文件
• 本地存储特权

注意

即使在视觉对象中授予这些特权，管理员也必须启用管理员设置中的开关，让组织中的人员可以从这些设置中受益。

允许 Web 访问

若要允许视觉对象访问外部资源或网站，请在功能部分中添加该信息作为特权。 特权定义包括一个可选的 URL 列表，该列表允许视觉对象访问，格式为 http://xyz.com 或 https://xyz.com。 每个 URL 还可以包含一个用于指定子域的通配符。

以下代码是允许访问外部资源的特权设置示例：

{
    "name": "WebAccess",
    "essential": true,
    "parameters": [ "https://*.microsoft.com", "http://example.com" ]
}

前面的 WebAccess 特权意味着视觉对象只需要通过 HTTPS 协议访问 microsoft.com 域的任何子域，以及通过 HTTP 访问没有子域的 example.com，并且此访问特权对于视觉对象的功能至关重要。

下载到文件

若要允许用户将数据从视觉对象导出到文件中，请将 ExportContent 设置为 true。

此 ExportContent 设置使视觉对象能够以以下格式将数据导出到文件：

• .txt
• .csv
• .json
• .tmplt
• .xml
• .pdf
• .xlsx

此设置独立于组织的导出和共享租户设置中应用的下载限制且不受其影响。

以下代码是允许下载到文件的特权设置示例：

"privileges": [
    {
        "name": "ExportContent",
        "essential": true
    }
]

本地存储特权

此特权允许自定义视觉对象在用户的本地浏览器上存储信息。

以下是允许使用本地存储的特权设置示例：

"privileges": [
    {
        "name": "LocalStorage",
        "essential": true
    }
]

不需要特权

如果视觉对象不需要任何特殊权限，privileges 数组应为空：

  "privileges": []

多个特权

以下示例显示如何为自定义视觉对象设置多个特权。

"privileges": [
    {
        "name": "WebAccess",
        "essential": true,
        "parameters": [ "https://*.virtualearth.net" ]
    },
    {
        "name": "ExportContent",
        "essential": false
    }
]

dataroles：定义视觉对象所需的数据字段

要定义可绑定到数据的字段，请使用 dataRoles。 dataRoles 是 DataViewRole 对象的数组，它定义所有必需的属性。 dataRoles 对象是显示在属性窗格中的字段。

用户将数据字段拖入其中，以将数据字段绑定到对象。

DataRole 属性

使用以下属性定义 DataRoles：

• name：此数据字段的内部名称（必须是唯一的）。
• displayName：在“属性”窗格中向用户显示的名称。
• kind：字段类型：
  • Grouping：用于对度量值字段进行分组的离散值的集。
  • Measure：单个数字值。
  • GroupingOrMeasure：可用作组别或度量值的值。
• description：字段的简短文本说明（可选）。
• requiredTypes：此数据角色所需的数据类型。 不匹配的值设置为 null（可选）。
• preferredTypes：此数据角色的首选数据类型（可选）。

requiredTypes 和 preferredTypes 的有效数据类型

• bool：布尔值
• integer：整数值
• numeric：数值
• text：文本值
• geography：地理数据

dataRoles 示例

"dataRoles": [
    {
        "displayName": "My Category Data",
        "name": "myCategory",
        "kind": "Grouping",
        "requiredTypes": [
            {
                "text": true
            },
            {
                "numeric": true
            },
            {
                "integer": true
            }
        ],
        "preferredTypes": [
            {
                "text": true
            }
        ]
    },
    {
        "displayName": "My Measure Data",
        "name": "myMeasure",
        "kind": "Measure",
        "requiredTypes": [
            {
                "integer": true
            },
            {
                "numeric": true
            }
        ],
        "preferredTypes": [
            {
                "integer": true
            }
        ]
    }
]
...
}

前面的数据角色将创建如下图所示的字段：

dataViewMappings：数据映射的方式

该 dataViewMappings 对象描述数据角色之间的关联方式，并使你能够指定显示数据视图的条件要求。

大多数视觉对象提供单个映射，但你可以提供多个 dataViewMapping。 每个有效映射都会生成数据视图。

"dataViewMappings": [
    {
        "conditions": [ ... ],
        "categorical": { ... },
        "table": { ... },
        "single": { ... },
        "matrix": { ... }
    }
]

有关详细信息，请参阅了解 Power BI 视觉对象中的数据视图映射。

objects：定义属性窗格选项

对象描述与视觉对象关联的可自定义属性。 此部分中定义的对象是出现在“格式”窗格中的对象。 每个对象可以具有多个属性，每个属性都有与之关联的类型。

"objects": {
    "myCustomObject": {
        "properties": { ... }
    }
}

例如，要支持自定义视觉对象中的动态格式字符串，请定义以下对象：

"objects": {
        "general": {
            "properties": {
                "formatString": {
                    "type": {
                        "formatting": {
                            "formatString": true
                        }
                    }
                }
            }
        },

有关详细信息，请参阅 Power BI 视觉对象的对象和属性。

相关内容

• 了解 Power BI 视觉对象中的数据视图映射
• Power BI 视觉对象的对象和属性
• Power BI 视觉对象的排序选项