Поделиться через

Форматирование визуальных свойств

  • Статья

При редактировании отчета в Power BI можно настроить каждый визуальный элемент в отчете с помощью параметра Форматирования в области визуализаций. Вы можете настроить множество элементов каждой визуализации, таких как название, условные обозначения, фон и подсказка. С помощью API создания отчетов Power BI можно получить, задать или сбросить визуальные свойства программными средствами без необходимости в режиме редактирования Power BI.

Чтобы отформатировать визуальный элемент с помощью API визуальных свойств, необходимо получить визуальный элемент, который вы хотите отформатировать. Чтобы получить список всех визуальных элементов в отчете, используйте метод getVisuals класса Page.

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

Чтобы выбрать свойство, которое вы хотите получить, задать или сбросить, необходимо определить экземпляр IVisualPropertySelector, включающий objectName и propertyName.

export interface IVisualPropertySelector {
  objectName: string;
  propertyName: string;
}
  • objectName: имя объекта (например, "title").
  • propertyName: имя свойства в объекте (например, titleText).

Доступные свойства для внешних визуальных элементов

Внешние визуальные элементы — это визуальные элементы Power BI, которые отображаются в области визуализации по умолчанию.

Имя объекта Имя свойства Тип
подсказка
видимый Булев
valueColor Шестнадцатеричный цвет, IThemeColorProperty
labelColor Шестнадцатеричный цвет, IThemeColorProperty
textSize Число
fontFamily Струна
backgroundColor Шестнадцатеричный цвет, IThemeColorProperty
прозрачность Число
фон
видимый Булев
Цвет Шестнадцатеричный цвет, IThemeColorProperty
прозрачность Число
visualHeader
видимый Булев
backgroundColor Шестнадцатеричный цвет, IThemeColorProperty
граница Шестнадцатеричный цвет, IThemeColorProperty
прозрачность Число
iconColor Шестнадцатеричный цвет, IThemeColorProperty
граница
видимый Булев
Цвет Шестнадцатеричный цвет, IThemeColorProperty
радиус Число
lockAspect
Включен Булев
титул
видимый Булев
выравнивание String (TextAlignment)
fontColor Шестнадцатеричный цвет, IThemeColorProperty
textSize Число
fontFamily Струна
backgroundColor Шестнадцатеричный цвет, IThemeColorProperty
titleText Струна
легенда
видимый Булев
позиция String (LegendPosition)
dataLabels
видимый Булев
categoryAxis
видимый Булев
valueAxis
видимый Булев

Доступные свойства для пользовательских визуальных элементов

Пользовательские создатели визуальных элементов определяют их свойства, поэтому для поиска objectName и propertyNameследует проверить пользовательский исходный код визуального элемента. Пользовательский код визуальных элементов является открытым исходным кодом, и их репозитории можно найти на GitHub.

Например: просмотр пользовательского визуального элемента диаграммы Mekko, можно найти репозиторий с открытым исходным кодом здесь. В файле src/visual.ts можно увидеть определенные Свойства.

Ниже перечислены определенные свойства пользовательского визуального элемента Диаграмма Мекко.

Заметка

Этот список был скопирован из диаграммы Mekko исходный код пользовательского визуального элемента в январе 2021 года.

public static Properties: MekkoChartProperties = <MekkoChartProperties>{
    dataPoint: {
        defaultColor: { objectName: "dataPoint", propertyName: "defaultColor" },
        fill: { objectName: "dataPoint", propertyName: "fill" },
        showAllDataPoints: { objectName: "dataPoint", propertyName: "showAllDataPoints" },
        categoryGradient: { objectName: "dataPoint", propertyName: "categoryGradient" },
        colorGradientEndColor: { objectName: "dataPoint", propertyName: "colorGradientEndColor" },
        colorDistribution: { objectName: "dataPoint", propertyName: "colorDistribution" }
    },
    columnBorder: {
        show: { objectName: "columnBorder", propertyName: "show", },
        color: { objectName: "columnBorder", propertyName: "color" },
        width: { objectName: "columnBorder", propertyName: "width" }
    },
    sortSeries: {
        enabled: { objectName: "sortSeries", propertyName: "enabled", },
        direction: { objectName: "sortSeries", propertyName: "direction" },
        displayPercents: { objectName: "sortSeries", propertyName: "displayPercents" }
    },
    sortLegend: {
        enabled: { objectName: "sortLegend", propertyName: "enabled", },
        direction: { objectName: "sortLegend", propertyName: "direction" },
        groupByCategory: { objectName: "sortLegend", propertyName: "groupByCategory" },
        groupByCategoryDirection: { objectName: "sortLegend", propertyName: "groupByCategoryDirection" }
    },
    xAxisLabels: {
        enableRotataion: { objectName: "xAxisLabels", propertyName: "enableRotataion", },
    },
    categoryColors: {
        color: { objectName: "categoryColors", propertyName: "color" },
    }
};

Заметка

Объект dataPoint не поддерживается.

Определение значения свойства

Значение свойства представлено объектом IVisualPropertyValue.

export interface IVisualPropertyValue {
  schema?: string;
  value: any;
}

  • схема — определяет тип значения. Доступны две схемы:

    • Схема свойств: "http://powerbi.com/product/schema#property" используется для определения свойства.

    • Схема по умолчанию: "http://powerbi.com/product/schema#default" используется для определения значения по умолчанию.

  • значение — значение, которое необходимо назначить свойству.

Типы значений свойств

В этом разделе перечислены типы значений свойств, которые можно настроить.

Значение свойства цвета

Значение свойства цвета может быть либо шестнадцатеричным цветом (строкой), например, #0000FF для цвета синего цвета, либо IThemeColorProperty для задания цвета темы отчета цвета.

interface IThemeColorProperty {
  id: number;
  shade: number;
}
  • идентификатор — идентификатор цвета темы
  • оттенка . Определяет процент цветового оттенка, значения могут быть от -1 до 1.

Например, чтобы определить цвет темы 2, 50% темнее, как показано ниже, необходимо определить объект IThemeColorProperty следующим образом:

let themeColorProperty = {
    id: 2,
  shade: -0.5
};

снимок экрана с окном цветов темы Power B I.

Значение свойства выравнивания текста

Определяет выравнивание текста

const TextAlignment = {
    Left: 'left',
    Center: 'center',
    Right: 'right',
};

Значение свойства позиции условных обозначений

Определяет позицию условных обозначений в визуальном элементе

const LegendPosition = {
    Top: 'Top',
    Bottom: 'Bottom',
    Right: 'Right',
    Left: 'Left',
    TopCenter: 'TopCenter',
    BottomCenter: 'BottomCenter',
    RightCenter: 'RightCenter',
    LeftCenter: 'LeftCenter',
};

Значение свойства по умолчанию

Значение, используемое для определения значения свойства по умолчанию. Например, можно задать заголовок автоматически созданного заголовка визуального элемента.

interface IDefaultProperty {
}

Если свойство не было изменено (с помощью пользовательского интерфейса или API), его значение определяется как IDefaultProperty, как в getProperty, так и в методах setProperty.

Значение свойства по умолчанию должно быть определено следующим образом:

const defaultValue = {
    schema: "http://powerbi.com/product/schema#default",
    value: {}
};

API свойств

В этом разделе перечислены API, используемые для форматирования визуальных свойств.

Получение свойства

Получение значения свойства визуального элемента в соответствии с селектором свойств.

getProperty(selector: IVisualPropertySelector): Promise<IVisualPropertyValue>

Например:

const selector = { ... };

let propertyValue = await visual.getProperty(selector);

Задание свойства

Задайте для визуального элемента значение свойства в соответствии с селектором свойств.

setProperty(selector: IVisualPropertySelector, value: IVisualPropertyValue): Promise<void>

Например:

const selector = { ... };
const propertyValue = { ... };

await visual.setProperty(selector, propertyValue);

Сброс свойства

Сбросить значение свойства визуального элемента в соответствии с селектором свойств, это возвращает свойство в значение по умолчанию, например, вы можете задать заголовок автоматически созданного заголовка визуального элемента.

resetProperty(selector: IVisualPropertySelector): Promise<void>

Например:

const selector = { ... };

await visual.resetProperty(selector);

Полный пример

Ниже показан пример выравнивания по центру заголовка визуального элемента с именем VisualContainer1 (уникальный идентификатор).

let pages = await report.getPages()

// Retrieve the active page.
let activePage = pages.find(function (page) {
    return page.isActive
});

let visuals = await activePage.getVisuals();

// Retrieve the wanted visual. (replace "VisualContainer1" with the requested visual name)
let visual = visuals.find(function (visual) {
    return visual.name === "VisualContainer1";
});

// Build a selector for title alignment
const selector = { 
    objectName: "title",
    propertyName: "alignment"
};

// Build the property value
const propertyValue = {
    schema: "http://powerbi.com/product/schema#property",
    value: models.TextAlignment.Center
};

await visual.setProperty(selector, propertyValue);

Связанное содержимое