Condividi tramite

Formattare le proprietà dell'oggetto visivo

  • Articolo

Quando si modifica un report in Power BI, è possibile personalizzare ogni oggetto visivo nel report usando l'opzione Formato nel riquadro Visualizzazioni . È possibile personalizzare molti elementi di ogni visualizzazione, ad esempio titolo, legenda, sfondo e descrizione comando. Con le API di creazione di report di Power BI è possibile recuperare, impostare o reimpostare le proprietà visive a livello di codice, senza la necessità della modalità di modifica di Power BI.

Per formattare un oggetto visivo usando le API delle proprietà visive, è necessario ottenere l'oggetto visivo da formattare. Per ottenere un elenco di tutti gli oggetti visivi in un report, usare il metodo getVisuals della Page classe .

Selezione dell'oggetto formato e della proprietà

Per selezionare la proprietà che si desidera recuperare, impostare o reimpostare, è necessario definire un'istanza IVisualPropertySelector che include un oggetto objectName e un oggetto propertyName.

export interface IVisualPropertySelector {
  objectName: string;
  propertyName: string;
}
  • objectName: nome dell'oggetto (ad esempio: "title").
  • propertyName: nome della proprietà all'interno dell'oggetto (ad esempio: "titleText").

Proprietà disponibili per gli oggetti visivi predefiniti

Gli oggetti visivi predefiniti sono oggetti visivi di Power BI visualizzati nel riquadro Visualizzazione per impostazione predefinita.

Nome dell'oggetto Nome proprietà Type
descrizione comando
visible Boolean
valueColor Colore esadecimale, IThemeColorProperty
labelColor Colore esadecimale, IThemeColorProperty
textSize Number
Fontfamily string
backgroundColor Colore esadecimale, IThemeColorProperty
trasparenza Number
background
visible Boolean
color Colore esadecimale, IThemeColorProperty
trasparenza Number
visualHeader
visible Boolean
backgroundColor Colore esadecimale, IThemeColorProperty
border Colore esadecimale, IThemeColorProperty
trasparenza Number
iconColor Colore esadecimale, IThemeColorProperty
border
visible Boolean
color Colore esadecimale, IThemeColorProperty
radius Number
lockAspect
Enabled Boolean
title
visible Boolean
allineamento String (TextAlignment)
fontColor Colore esadecimale, IThemeColorProperty
textSize Number
Fontfamily string
backgroundColor Colore esadecimale, IThemeColorProperty
titleText string
legenda
visible Boolean
position Stringa (LegendPosition)
dataLabels
visible Boolean
categoryAxis
visible Boolean
valueAxis
visible Boolean

Proprietà disponibili per gli oggetti visivi personalizzati

Gli autori di oggetti visivi personalizzati definiscono le relative proprietà, pertanto, per trovare objectName e propertyName, è necessario controllare il codice sorgente dell'oggetto visivo personalizzato. Il codice degli oggetti visivi personalizzati è open source e i relativi repository sono disponibili in GitHub.

Ad esempio, esaminando l'oggetto visivo personalizzato Mekko Chart, è possibile trovare il repository open source qui. src/visual.ts Nel file è possibile visualizzare le proprietà definite.

Le proprietà definite dell'oggetto visivo personalizzato del grafico Mekko sono elencate di seguito.

Nota

Questo elenco è stato copiato dal codice sorgente dell'oggetto visivo personalizzato del grafico Mekko nel gennaio 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" },
    }
};

Nota

L'oggetto dataPoint non è supportato.

Definizione del valore della proprietà

Il valore della proprietà è rappresentato da un IVisualPropertyValue oggetto.

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

  • schema : definisce il tipo del valore. Sono disponibili due schemi:

    • Schema delle proprietà: "http://powerbi.com/product/schema#property" usato per definire una proprietà.

    • Schema predefinito: "http://powerbi.com/product/schema#default" usato per definire un valore predefinito.

  • value : valore da assegnare alla proprietà.

Tipi di valore della proprietà

Questa sezione elenca i tipi di valore della proprietà che è possibile configurare.

Valore della proprietà Color

Un valore della proprietà color può essere un colore esadecimale (stringa), ad esempio #0000FF per il colore blu o un IThemeColorProperty oggetto per impostare un colore del tema del report .

interface IThemeColorProperty {
  id: number;
  shade: number;
}
  • id - ID del colore del tema
  • shade : definisce la percentuale dell'ombreggiatura dei colori, i valori possono essere compresi tra -1 e 1.

Ad esempio, per definire il colore tema 2, il 50% più scuro, come illustrato di seguito, l'oggetto IThemeColorProperty deve essere definito come segue:

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

Screenshot che mostra una finestra dei colori dei temi di Power B.

Valore della proprietà di allineamento del testo

Definisce l'allineamento del testo

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

Valore della proprietà Legend position

Definisce la posizione della legenda nell'oggetto visivo

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

Valore predefinito della proprietà

Valore utilizzato per definire il valore predefinito della proprietà. Ad esempio, è possibile impostare il titolo sul titolo generato automaticamente dell'oggetto visivo.

interface IDefaultProperty {
}

Se una proprietà non è stata modificata (usando l'interfaccia utente o l'API), il relativo valore viene definito come IDefaultProperty, sia nei getPropertysetProperty metodi.

Il valore predefinito della proprietà deve essere definito come segue:

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

API delle proprietà

Questa sezione elenca le API usate per formattare le proprietà visive.

Recupero di una proprietà

Recuperare un valore di proprietà di un oggetto visivo in base al selettore di proprietà.

getProperty(selector: IVisualPropertySelector): Promise<IVisualPropertyValue>

Ad esempio:

const selector = { ... };

let propertyValue = await visual.getProperty(selector);

Impostazione di una proprietà

Impostare un valore della proprietà su un oggetto visivo in base al selettore delle proprietà.

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

Ad esempio:

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

await visual.setProperty(selector, propertyValue);

Reimpostazione di una proprietà

Reimpostare un valore di proprietà di un oggetto visivo in base al selettore di proprietà, verrà restituita la proprietà al relativo valore predefinito, ad esempio, è possibile impostare il titolo sul titolo generato automaticamente dell'oggetto visivo.

resetProperty(selector: IVisualPropertySelector): Promise<void>

Ad esempio:

const selector = { ... };

await visual.resetProperty(selector);

Esempio completo

Di seguito è riportato un esempio di allineamento al centro del titolo dell'oggetto visivo con il nome VisualContainer1 (identifer univoco).

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

Passaggi successivi

Panoramica della creazione di report

Aggiungere, eliminare o rinominare una pagina del report