设置视觉对象属性的格式

在 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);

上次更新时间为 2025-03-05