Настройка области форматирования в пользовательских визуальных элементах Power BI

Мақала
12/12/2023

Начиная с API версии 5.1 разработчики могут создавать визуальные элементы, использующие новую область формата Power. Разработчики могут определять карта и их категории для любого свойства в пользовательском визуальном элементе, что упрощает использование этих визуальных элементов создателями отчетов.

Новый API использует метод FormattingModel для настройки частей областей формата и аналитики.

Совет

Метод getFormattingModel заменяет enumerateObjectInstances метод в более ранних версиях API.

Возвращает значение getFormattingModel , определяющее FormattingModel , как выглядит область форматирования и аналитики визуального элемента.

Помимо всех старых возможностей области форматирования новая модель форматирования поддерживает новые возможности области форматирования, новые свойства и новые иерархии.

Screenshot of the new formatting pane.

Чтобы выполнить обновление до API версии 5.1+, задайте apiVersion для файла pbiviz.json или 5.1 более поздней версии и выполните одно из следующих действий:

Используйте util formattingmodel. (Рекомендуется)
Без этого использования используйте только API в соответствии со следующим методом.

Создание визуального элемента, поддерживающего новую область форматирования

Чтобы создать пользовательский визуальный элемент, использующий новую область форматирования:

Определите все настраиваемые objects параметры в файле capabilities.json .
Для каждого объекта требуются следующие свойства:
- имя объекта
- Имя свойства
- Тип свойства
Все остальные свойства, включая DisplayName и description, теперь являются необязательными.
Создайте пользовательский визуальный элемент FormattingModel. Определите свойства пользовательской модели форматирования визуальных элементов и создайте его с помощью кода (а не JSON).
getFormattingModel Реализуйте API в пользовательском визуальном классе, который возвращает пользовательскую модель форматирования визуальных элементов. (Этот API заменяет используемый enumerateObjectInstances в предыдущих версиях).

Свойства форматирования карты

Если у вас есть пользовательский визуальный элемент, созданный с помощью более старого API, и вы хотите перенести его в новую область форматирования или при создании нового пользовательского визуального элемента:

Задайте для apiVersionфайла 5.1 pbiviz.json значение или более поздней версии.
Для каждого имени объекта и имени свойства в capabilities.json создайте соответствующее свойство форматирования. Свойство форматирования должно содержать дескриптор, содержащий и objectNamepropertyName соответствующий имени объекта и имени свойства в capabilities.json.

Свойства objects в файле возможностей по-прежнему имеют тот же формат и не нужно изменять.

Например, если circle объект в файле capabilities.json определен следующим образом:

"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
        }
    }
}

Вы получите ошибку, если одно из следующих условий имеет значение true:

Имя объекта или свойства в файле возможностей не соответствует одному в модели форматирования
Тип свойства в файле возможностей не соответствует типу в модели форматирования

Модель форматирования

Модель форматирования заключается в том, где описаны и настроены все свойства области форматирования.

Форматирование компонентов модели

В новой модели форматирования компоненты свойств группируются в логические категории и подкатегории. Эти группы упрощают сканирование модели. Существует пять основных компонентов, от крупнейших до наименьших:

Модель форматирования
Самый большой контейнер панели, используемый для форматирования интерфейсного интерфейса панели. Он содержит список карта форматирования.
Форматирование карта
Контейнер группирования свойств верхнего уровня для свойств форматирования. Каждая карта состоит из одной или нескольких групп форматирования, как показано здесь.
Группа форматирования
Контейнер группирования свойств вторичного уровня. Группа форматирования отображается как контейнер группирования для форматирования срезов.
Форматирование среза
Контейнер свойств. Существует два типа срезов:
- Простой срез: отдельный контейнер свойств
- Составной срез: несколько связанных контейнеров свойств сгруппированы в один срез форматирования
На следующем рисунке показаны различные типы срезов. "Шрифт" — это составной срез, состоящий из семейства шрифтов, размера и полужирного шрифта, курсивов и коммутаторов подчеркивания. "Цвет", "единицы отображения" и другие срезы являются простыми срезами с одним компонентом.

Свойства форматирования области визуализации

Каждое свойство в модели форматирования должно соответствовать и типу объекта в файле capabilities.json .

В следующей таблице показаны типы свойств форматирования в файле capabilities.json и их соответствующий класс типов в современных свойствах модели форматирования:

Тип	Тип значения возможностей	Свойство форматирования
Логический	Bool	ToggleSwitch
Число	numeric Целое число	NumUpDown Ползунок
Список перечислений	перечисление:[]	ItemDropdown ItemFlagsSelection AutoDropdown AutoFlagsSelection ^* См. примечание ниже
Цвет	Заливка	ColorPicker
Градиент	FillRule	GradientBar: значение свойства должно быть строкой, состоящей из: `minValue[,midValue],maxValue`
Text	Text	TextInput Textarea

Возможности форматирования объектов

Тип	Тип значения возможностей	Свойство форматирования
Размер шрифта	FontSize	NumUpDown
Семейство шрифтов	FontFamily	FontPicker
Выравнивание строк	Точное понимание	Выравнивание Группы
Единицы отображения меток	LabelDisplayUnits	AutoDropDown

^* Свойство форматирования списка перечисления отличается в модели форматирования и в файле возможностей.

Объявите следующие свойства в классе параметров форматирования, включая список элементов перечисления:
- ItemDropdown
- ItemFlagsSelection
Объявите следующие свойства в классе параметров форматирования без списка элементов перечисления. Объявите список элементов перечисления в файле capabilities.json в соответствующем объекте. (Эти типы совпадают с предыдущими версиями API):
- AutoDropdown
- AutoFlagSelection

Свойства составного среза

Составной срез форматирования — это срез форматирования, содержащий несколько связанных свойств вместе.

Теперь у нас есть два составных типа среза:

FontControl
Это сохраняет все связанные с шрифтом свойства вместе. Он состоит из следующих свойств:

Семейство шрифтов
Размер шрифта
Полужирный [необязательный]
Курсив [необязательно]
Подчеркивание [необязательно]

Screenshot of font composite slice with font family, font size, bold, italic, and underline options.

Каждый из этих свойств должен иметь соответствующий объект в файле возможностей:

Свойство	Тип возможностей	Тип форматирования
Семейство шрифтов	Форматирование: { fontFamily}	FontPicker
Размер шрифта	Форматирование: {fontSize}	NumUpDown
Жирный	Bool	ToggleSwitch
Italic	Bool	ToggleSwitch
Подчеркнутый	Bool	ToggleSwitch

Заполнение поля MarginPadding определяет выравнивание текста в визуальном элементе. Он состоит из следующих свойств:

Left
Right
Верх
Снизу

Каждый из этих свойств должен иметь соответствующий объект в файле возможностей:

Свойство	Тип возможностей	Тип форматирования
Left	Числовое	NumUpDown
Right	Числовое	NumUpDown
Верх	Числовое	NumUpDown
Снизу	Числовое	NumUpDown

Пример. Форматирование карта данных

В этом примере показано, как создать пользовательскую модель форматирования визуальных элементов с помощью одной карта.
В карта есть две группы:

Группа элементов управления шрифтом с одним составным свойством
- Элемент управления шрифтом
Группа конструктора данных с двумя простыми свойствами
- Цвет шрифта
- Выравнивание линии

Сначала добавьте объекты в файл возможностей:

"objects": {
        "dataCard": {
            "properties": {
                "displayUnitsProperty": {
                    "type":
                    {
                        "formatting": {
                            "labelDisplayUnits": true
                        }
                    }
                },
                "fontSize": { 
                    "type": {
                        "formatting": {
                            "fontSize": true
                        }
                    }
                },
                "fontFamily": {
                    "type": {
                        "formatting": {
                            "fontFamily": true
                        }
                    }
                },
                "fontBold": {
                    "type": {
                        "bool": true
                    }
                },
                "fontUnderline": {
                    "type": {
                        "bool": true
                    }
                },
                "fontItalic": {
                    "type": {
                        "bool": true
                    }
                },
                "fontColor": {
                    "type": {
                        "fill": {
                            "solid": {
                                "color": true
                            }
                        }
                    }
                },
                "lineAlignment": {
                    "type": {
                        "formatting": {
                            "alignment": true
                        }
                    }
                }
            }
        }
    }

Затем создайте getFormattingModel

    public getFormattingModel(): powerbi.visuals.FormattingModel {
        // Building data card, We are going to add two formatting groups "Font Control Group" and "Data Design Group"
        let dataCard: powerbi.visuals.FormattingCard = {
            description: "Data Card Description",
            displayName: "Data Card",
            uid: "dataCard_uid",
            groups: []
        }

        // Building formatting group "Font Control Group"
        // Notice that "descriptor" objectName and propertyName should match capabilities object and property names
        let group1_dataFont: powerbi.visuals.FormattingGroup = {
            displayName: "Font Control Group",
            uid: "dataCard_fontControl_group_uid",
            slices: [
                {
                    uid: "dataCard_fontControl_displayUnits_uid",
                    displayName:"display units",
                    control: {
                        type: powerbi.visuals.FormattingComponent.Dropdown,
                        properties: {
                            descriptor: {
                                objectName: "dataCard",
                                propertyName:"displayUnitsProperty"
                            },
                            value: 0
                        }
                    }
                },
                // FontControl slice is composite slice, It means it contain multiple properties inside it
                {
                    uid: "data_font_control_slice_uid",
                    displayName: "Font",
                    control: {
                        type: powerbi.visuals.FormattingComponent.FontControl,
                        properties: {
                            fontFamily: {
                                descriptor: {
                                    objectName: "dataCard",
                                    propertyName: "fontFamily"
                                },
                                value: "wf_standard-font, helvetica, arial, sans-serif"
                            },
                            fontSize: {
                                descriptor: {
                                    objectName: "dataCard",
                                    propertyName: "fontSize"
                                },
                                value: 16
                            },
                            bold: {
                                descriptor: {
                                    objectName: "dataCard",
                                    propertyName: "fontBold"
                                },
                                value: false
                            },
                            italic: {
                                descriptor: {
                                    objectName: "dataCard",
                                    propertyName: "fontItalic"
                                },
                                value: false
                            },
                            underline: {
                                descriptor: {
                                    objectName: "dataCard",
                                    propertyName: "fontUnderline"
                                },
                                value: false
                            }
                        }
                    }
                }
            ],
        };
        // Building formatting group "Font Control Group"
        // Notice that "descriptor" objectName and propertyName should match capabilities object and property names
        let group2_dataDesign: powerbi.visuals.FormattingGroup = {
            displayName: "Data Design Group",
            uid: "dataCard_dataDesign_group_uid",
            slices: [
                // Adding ColorPicker simple slice for font color
                {
                    displayName: "Font Color",
                    uid: "dataCard_dataDesign_fontColor_slice",
                    control: {
                        type: powerbi.visuals.FormattingComponent.ColorPicker,
                        properties: {
                            descriptor:
                            {
                                objectName: "dataCard",
                                propertyName: "fontColor"
                            },
                            value: { value: "#01B8AA" }
                        }
                    }
                },
                // Adding AlignmentGroup simple slice for line alignment
                {
                    displayName: "Line Alignment",
                    uid: "dataCard_dataDesign_lineAlignment_slice",
                    control: {
                        type: powerbi.visuals.FormattingComponent.AlignmentGroup,
                        properties: {
                            descriptor:
                            {
                                objectName: "dataCard",
                                propertyName: "lineAlignment"
                            },
                            mode: powerbi.visuals.AlignmentGroupMode.Horizonal,
                            value: "right"
                        }
                    }
                },
            ]
        };

        // Add formatting groups to data card
        dataCard.groups.push(group1_dataFont);
        dataCard.groups.push(group2_dataDesign);

        // Build and return formatting model with data card
        const formattingModel: powerbi.visuals.FormattingModel = { cards: [dataCard] };
        return formattingModel;
    }

Ниже приведена результирующая область:

Screenshot of format pane that results from the data card example.

Сброс параметров по умолчанию

В области нового формата есть возможность сброса всех значений свойств форматирования карта по умолчанию, нажав кнопку "Сброс к умолчанию", которая отображается в открытом карта.

Screenshot of format card reset to default button.

Чтобы включить эту функцию, добавьте список дескрипторов форматирования карта свойств для форматирования картаrevertToDefaultDescriptors. В следующем примере показано, как добавить сброс к кнопке по умолчанию :

let dataCard: powerbi.visuals.FormattingCard = {
    displayName: "Data Card",
    // ... card parameters and groups list

    revertToDefaultDescriptors: [
        {
            objectName: "dataCard",
            propertyName:"displayUnitsProperty"
        },
        {
            objectName: "dataCard",
            propertyName: "fontFamily"
        },

        // ... the rest of properties descriptors 
    ]
};

Добавление revertToDefaultDescriptors к форматированию карта также позволяет сбросить все свойства форматирования карта одновременно, нажав кнопку сброса всех параметров по умолчанию в верхней строке области форматирования:

Screenshot of format pane reset all settings to default button.

Селектор форматирования свойств

Необязательный селектор в дескрипторе свойств форматирования определяет, где каждое свойство привязано в dataView. Существует четыре различных варианта. Ознакомьтесь с ними в типах селекторов объектов.

Локализация

Дополнительные сведения о функции локализации и настройке среды локализации см. в разделе "Добавление локального языка в визуальный элемент Power BI" с помощью диспетчера локализации для форматирования компонентов, которые требуется локализовать:

displayName: this.localization.getDisplayName("Font_Color_DisplayNameKey");
description: this.localization.getDisplayName("Font_Color_DescriptionKey");

Локализация локализации модели форматирования, используемой для форматирования utils.

Ресурсы GitHub

Все интерфейсы модели форматирования можно найти в GitHub — microsoft/powerbi-visuals-api: API пользовательских визуальных элементов Power BI в разделе "formatting-model-api.d.ts"
Мы рекомендуем использовать новую модель форматирования на сайте GitHub — microsoft/powerbi-visuals-utils-formattingmodel: вспомогательные utils модели форматирования визуальных элементов Power BI
Вы можете найти пример пользовательского визуального элемента SampleBarChart, использующего API версии 5.1.0 и реализующий getFormattingModel использование новой модели форматирования на сайте GitHub — microsoft/PowerBI-visuals-sampleBarChart: настраиваемый визуальный элемент линейчатой диаграммы для учебника.

Есть еще вопросы? Спросите Сообщество Power BI

Бөлісу құралы:

Настройка области форматирования в пользовательских визуальных элементах Power BI

Создание визуального элемента, поддерживающего новую область форматирования

Свойства форматирования карты

Модель форматирования

Форматирование компонентов модели

Свойства форматирования области визуализации

Свойства составного среза

Пример. Форматирование карта данных

Сброс параметров по умолчанию

Селектор форматирования свойств

Локализация

Ресурсы GitHub

Кері байланыс

Кері байланыс

Қосымша ресурстар

Бөлісу құралы:

Настройка области форматирования в пользовательских визуальных элементах Power BI

Создание визуального элемента, поддерживающего новую область форматирования

Свойства форматирования карты

Модель форматирования

Форматирование компонентов модели

Свойства форматирования области визуализации

Свойства составного среза

Пример. Форматирование карта данных

Сброс параметров по умолчанию

Селектор форматирования свойств

Локализация

Ресурсы GitHub

Связанный контент

Кері байланыс

Кері байланыс

Қосымша ресурстар