通过

设置视觉对象属性的格式

  • 项目

在 Power BI 中编辑报表时，可以使用 可视化效果 窗格中的“格式”选项自定义报表中的每个视觉对象。 可以自定义每个可视化效果的许多元素，例如标题、图例、背景和工具提示。 借助 Power BI 报表创作 API，你可以以编程方式检索、设置或重置视觉对象属性，而无需 Power BI 编辑 模式。

若要使用视觉对象属性 API 设置视觉对象的格式，需要获取要设置格式的视觉对象。 若要获取报表中所有视觉对象的列表，请使用 类的 Page 方法。

选择格式对象和属性

若要选择要检索、设置或重置的属性，需要定义包含 objectName 和 propertyName的 IVisualPropertySelector 实例。

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
启用 布尔
标题
可见 布尔
对准 字符串 （TextAlignment）
fontColor 十六进制颜色，IThemeColorProperty
textSize 数
fontFamily 字符串
backgroundColor 十六进制颜色，IThemeColorProperty
titleText 字符串
传说
可见 布尔
位置 字符串 （LegendPosition）
dataLabels
可见 布尔
categoryAxis
可见 布尔
valueAxis
可见 布尔

自定义视觉对象的可用属性

因此，自定义视觉对象创建者定义其属性，若要查找 objectName 和 propertyName，应检查自定义视觉对象源代码。 自定义视觉对象代码是开源的，可以在 GitHub 上找到其存储库。

例如：查看 Mekko Chart的自定义视觉 对象，可以在此处找到开源存储库 。 在 src/visual.ts 文件中，可以看到定义的 属性。

下面列出了 Mekko 图表 自定义视觉对象的定义属性。

注意

此列表是从 2021 年 1 月 Mekko Chart 自定义视觉对象的源代码复制的。

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;
}
  • id - 主题颜色的 ID
  • 阴影 - 定义颜色阴影的百分比，这些值可以是从 -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 {
}

如果未更改属性（使用 UI 或 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);

相关内容