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
• drilldown
• expandCollapse
• supportsKeyboardFocus
• supportsSynchronizingFilterState
• advancedEditModeSupport
• supportsLandingPage
• supportsEmptyDataView
• supportsMultiVisualSelection
• subtotals
• keepAllMetadataColumns
• migration

您可以在 capabilities.json 結構描述中找到所有這些物件及其參數

privileges：定義視覺效果所需的特殊權限

權限是視覺效果需要存取才能運作的特殊作業。 權限接受 privilege 物件的陣列，其會定義所有權限屬性。 以下幾節描述可在 Power BI 中使用的權限。

注意

從 API v4.6.0 起，「必須」在 capabilities.json 檔案中指定權限。 在舊版中，會自動授與遠端存取權，但無法將其下載至檔案。 若要了解您正在使用哪個版本，請檢查 pbiviz.json 檔案中的 apiVersion。

定義權限

JSON 權限定義包含下列元件：

• name - (字串) 權限的名稱。
• essential - (布林值) 指出視覺效果功能是否需要此權限。 true 值表示需要權限；false 表示權限並非必要。
• parameters - (字串陣列) (選用) 引數。 如果遺漏 parameters，則會將其視為空陣列。

以下是必須定義的權限類型：

• 存取外部資源
• 下載成檔案
• 本機存放區屬性

注意

即使在視覺效果中授與了這些權限，系統管理員仍必須啟用系統管理員設定中的切換，以允許組織中的人員受益於這些設定。

允許 Web 存取

若要允許視覺效果存取外部資源或網站，請將該資訊新增為功能區段中的「權限」。 權限定義包含允許視覺效果以 http://xyz.com 或 https://xyz.com 格式存取的選用 URL 清單。 每個 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 物件會描述資料角色的相互關係，並可讓您指定顯示資料檢視的條件式需求。

大部分的視覺效果都提供單一對應，但您可以提供多個 dataViewMappings。 每個有效對應都會產生資料檢視。

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

如需詳細資訊，請參閱了解 Power BI 視覺效果中的資料檢視對應。

objects：定義屬性窗格選項

Objects 描述與視覺效果相關聯的可自訂屬性。 本節中定義的物件是出現在格式窗格中的物件。 每個物件都可以具有多個屬性，而且每個屬性都有一個與其相關聯的類型。

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

例如，若要在自訂視覺效果中支援動態格式字串，請定義下列物件：

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

如需詳細資訊，請參閱 Power BI 視覺效果的物件和屬性。

相關內容

• 了解 Power BI 視覺效果中的資料檢視對應
• Power BI 視覺效果的物件和屬性
• Power BI 視覺效果的排序選項