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

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

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

Подсказка

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

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

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

Снимок экрана: область форматирования.

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

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

Установите значение apiVersion в вашем файле pbiviz.json на 5.1 или более позднюю версию.
Определите все настраиваемые objects параметры в файлеcapabilities.json . Затем эти объекты сопоставляются со свойствами области форматирования. Для каждого объекта требуются следующие свойства:
- Имя объекта
- название свойства
- Тип свойства
Все остальные свойства, включая DisplayName и description, теперь являются необязательными.
Создайте пользовательскую визуализацию FormattingModel, выбрав один из нижеперечисленных методов.
- Используйте formattingmodel util. (Рекомендуется)
- Без этой утилиты используйте только API.

Определите свойства пользовательской модели форматирования визуальных элементов и создайте его с помощью кода (а не JSON).

getFormattingModel Реализуйте API в пользовательском визуальном классе, который возвращает пользовательскую модель форматирования визуальных элементов. (Этот API заменяет используемый enumerateObjectInstances в предыдущих версиях).

Пример реализации модели форматирования

Пример использования утилиты formattingmodel для моделирования форматирования. (Рекомендуется)
Форматирование модели с использованием только API пример.

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

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

Установите значение apiVersion в вашем файле pbiviz.json на 5.1 или более позднюю версию.
Для каждого имени объекта и имени свойства в capabilities.jsonсоздайте соответствующее свойство форматирования. Свойство форматирования должно иметь дескриптор, содержащий objectName и propertyName, которые соответствуют имени объекта и имени свойства в 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
        }
    }
}

Если одно из следующих условий выполняется (является истинным), возникает ошибка.

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

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

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

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

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

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

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

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

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

Тип	Тип значения возможностей	Свойство форматирования
Булев	Булев	Переключатель
Номер	числовой целое число	NumUpDown Слайдер
Список перечислений	перечисление:[]	ItemDropdown ItemFlagsSelection AutoDropdown Выбор автознаков ^* См. примечание ниже
Цвет	Заполнять	ColorPicker
Градиент	Правило заполнения	GradientBar: значение свойства должно быть строкой, состоящей из: `minValue[,midValue],maxValue`
Текст	Текст	TextInput Текстовое поле

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

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

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

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

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

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

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

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

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

Снимок экрана: составной срез шрифта с семейством шрифтов, размером шрифта, полужирным шрифтом, курсивом и параметрами подчеркивания.

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

Недвижимость	Тип возможностей	Тип форматирования
Семейство шрифтов	Форматирование: { fontFamily}	FontPicker
Размер шрифта	Форматирование: {fontSize}	NumUpDown
Смелый	Булев	ПереключательSwitch
Курсив	Булев	ПереключательSwitch
Подчеркивание	Булев	ПереключательSwitch

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

Лево
Правильно
Верх
Низ

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

Недвижимость	Тип возможностей	Тип форматирования
Лево	Числовое	NumUpDown
Правильно	Числовое	NumUpDown
Верх	Числовое	NumUpDown
Низ	Числовое	NumUpDown

Ресурсы GitHub

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

Дополнительные вопросы? Обратитесь к сообществу Power BI

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2025-12-15