Supporto per la modalità a contrasto elevato negli oggetti visivi di Power BIHigh-contrast mode support in Power BI visuals

L'impostazione Contrasto elevato di Windows migliora la visualizzazione di testo e app usando colori più nitidi.The Windows high contrast setting makes text and apps easier to see by displaying more distinct colors. Questo articolo descrive come aggiungere il supporto per la modalità a contrasto elevato agli oggetti visivi di Power BI.This article discusses how to add high-contrast mode support to Power BI visuals. Per altre informazioni, vedere Supporto per il contrasto elevato in Power BI.For more information, see high-contrast support in Power BI.

Per visualizzare un'implementazione del supporto per il contrasto elevato, vedere il repository dell'oggetto visivo PowerBI-visuals-sampleBarChart.To view an implementation of high-contrast support, go to the PowerBI-visuals-sampleBarChart visual repository.

Durante l'inizializzazioneOn initialization

Il membro colorPalette di options.host include diverse proprietà per la modalità a contrasto elevato.The colorPalette member of options.host has several properties for high-contrast mode. Usare queste proprietà per determinare se la modalità a contrasto elevato è attiva e, in tal caso, quali colori usare.Use these properties to determine whether high-contrast mode is active and, if it is, what colors to use.

Determinare che Power BI è in modalità a contrasto elevatoDetect that Power BI is in high-contrast mode

Se host.colorPalette.isHighContrast è true, la modalità a contrasto elevato è attiva e l'oggetto visivo apparirà di conseguenza.If host.colorPalette.isHighContrast is true, high-contrast mode is active and the visual should draw itself accordingly.

Ottenere i colori a contrasto elevatoGet high-contrast colors

In modalità a contrasto elevato l'oggetto visivo deve limitarsi alle impostazioni seguenti:In high-contrast mode, your visual should limit itself to the following settings:

  • Il colore di primo piano viene usato per disegnare qualsiasi linea, icona, testo, contorno o riempimento delle forme.Foreground color is used to draw any lines, icons, text, and outline or fill of shapes.
  • Il colore di sfondo viene usato per lo sfondo e come colore di riempimento delle forme con contorno.Background color is used for background, and as the fill color of outlined shapes.
  • Il colore di primo piano di una selezione viene usato per indicare un elemento selezionato o attivo.Foreground - selected color is used to indicate a selected or active element.
  • Il colore dei collegamenti ipertestuali viene usato solo per il testo dei collegamenti ipertestuali.Hyperlink color is used only for hyperlink text.

Nota

Se è necessario un colore secondario, è possibile usare il colore di primo piano con una certa opacità. Gli oggetti visivi nativi di Power BI usano un'opacità del 40%.If a secondary color is needed, foreground color may be used with some opacity (Power BI native visuals use 40% opacity). Usare questa opzione con cautela per mantenere facilmente visualizzabili i dettagli degli oggetti visivi.Use this sparingly to keep the visual details easy to see.

Durante l'inizializzazione, è possibile archiviare i valori seguenti:During initialization, you can store the following values:

private isHighContrast: boolean;

private foregroundColor: string;
private backgroundColor: string;
private foregroundSelectedColor: string;
private hyperlinkColor: string;
//...

constructor(options: VisualConstructorOptions) {
    this.host = options.host;
    let colorPalette: ISandboxExtendedColorPalette = host.colorPalette;
    //...
    this.isHighContrast = colorPalette.isHighContrast;
    if (this.isHighContrast) {
        this.foregroundColor = colorPalette.foreground.value;
        this.backgroundColor = colorPalette.background.value;
        this.foregroundSelectedColor = colorPalette.foregroundSelected.value;
        this.hyperlinkColor = colorPalette.hyperlink.value;
    }

In alternativa, è possibile archiviare l'oggetto host durante l'inizializzazione e accedere alle proprietà colorPalette pertinenti durante l'aggiornamento.Or you can store the host object during initialization and access the relevant colorPalette properties during update.

All'aggiornamentoOn update

Le implementazioni specifiche del supporto per il contrasto elevato variano a seconda dell'oggetto visivo e dipendono dai dettagli della progettazione grafica.The specific implementations of high-contrast support vary from visual to visual and depend on the details of the graphic design. Per rendere i dettagli importanti più facilmente distinguibili con i colori limitati, in genere la modalità a contrasto elevato richiede una progettazione leggermente diversa da quella predefinita.To keep important details easy to distinguish with the limited colors, high-contrast mode ordinarily requires a design that's slightly different from the default mode.

Gli oggetti visivi nativi di Power BI seguono le linee guida seguenti:Power BI native visuals follow these guidelines:

  • Tutti i punti dati usano lo stesso colore (di primo piano).All data points use the same color (foreground).
  • Tutto il testo, gli assi, le frecce, le linee e così via usano il colore di primo piano.All text, axes, arrows, lines, and so on use the foreground color.
  • Le forme spesse vengono disegnate come contorni, con tratti spessi (almeno due pixel) e riempimento del colore di sfondo.Thick shapes are drawn as outlines, with thick strokes (at least two pixels) and background color fill.
  • Quando sono rilevanti, i punti dati si distinguono tramite forme del marcatore diverse, mentre le righe di dati si distinguono per il tratteggio diverso.When data points are relevant, they're distinguished by different marker shapes, and data lines are distinguished by different dashing.
  • Quando un elemento dati è evidenziato, tutti gli altri elementi passano a un'opacità del 40%.When a data element is highlighted, all other elements change their opacity to 40%.
  • Per i filtri dei dati, gli elementi del filtro attivo usano il colore selezionato in primo piano.For slicers, active filter elements use foreground-selected color.

Nel grafico a barre di esempio seguente tutte le barre vengono disegnate con un contorno nel colore di primo piano di due pixel e un riempimento di sfondo.In the following sample bar chart, for example, all bars are drawn with two pixels of thick foreground outline and background fill. Confrontare il modo in cui appare con i colori predefiniti e con un paio di temi a contrasto elevato:Compare the way it looks with default colors and with a couple of high-contrast themes:

Grafico a barre di esempio che usa colori standard Grafico a barre di esempio che usa la combinazione di colori Scuro n. 2 Grafico a barre di esempio che usa la combinazione di colori BiancoSample Bar Chart using standard colors Sample Bar Chart using Dark #2 color theme Sample Bar Chart using White color theme

La sezione successiva mostra un punto nella funzione visualTransform che è stato modificato per supportare il contrasto elevato.The next section shows one place in the visualTransform function that was changed to support high contrast. Viene chiamato come parte del rendering durante l'aggiornamento.It's called as part of rendering during the update.

PrimaBefore

for (let i = 0, len = Math.max(category.values.length, dataValue.values.length); i < len; i++) {
    let defaultColor: Fill = {
        solid: {
            color: colorPalette.getColor(category.values[i] + '').value
        }
    };

    barChartDataPoints.push({
        category: category.values[i] + '',
        value: dataValue.values[i],
        color: getCategoricalObjectValue<Fill>(category, i, 'colorSelector', 'fill', defaultColor).solid.color,
        selectionId: host.createSelectionIdBuilder()
            .withCategory(category, i)
            .createSelectionId()
    });
}

AfterAfter

for (let i = 0, len = Math.max(category.values.length, dataValue.values.length); i < len; i++) {
    const color: string = getColumnColorByIndex(category, i, colorPalette);

    const selectionId: ISelectionId = host.createSelectionIdBuilder()
        .withCategory(category, i)
        .createSelectionId();

    barChartDataPoints.push({
        color,
        strokeColor,
        strokeWidth,
        selectionId,
        value: dataValue.values[i],
        category: `${category.values[i]}`,
    });
}

//...

function getColumnColorByIndex(
    category: DataViewCategoryColumn,
    index: number,
    colorPalette: ISandboxExtendedColorPalette,
): string {
    if (colorPalette.isHighContrast) {
        return colorPalette.background.value;
    }

    const defaultColor: Fill = {
        solid: {
            color: colorPalette.getColor(`${category.values[index]}`).value,
        }
    };

    return getCategoricalObjectValue<Fill>(category, index, 'colorSelector', 'fill', defaultColor).solid.color;
}