API for formatering på objektet (forhåndsversjon)

formatering på objektet gjør det mulig for brukere å raskt og enkelt endre visualobjektformatet ved å velge elementene de vil endre direkte. Når et element er valgt, navigerer formatruten automatisk og utvider den bestemte formateringsinnstillingen for det valgte elementet. Hvis du vil ha mer informasjon om formatering på objektet, kan du se Formatering på objektet i Power BI Desktop.

Hvis du vil legge til disse funksjonene i visualobjektet, må hvert visualobjekt gi et alternativ for valgstil og snarvei for hvert område som kan velges.

Notat

Visualobjekter som støtter objektformatering, må implementere getFormattingModel API- som er tilgjengelig fra API versjon 5.1.
Hvis du bruker powerbi-visuals-utils-formattingmodel, bruker du minst versjon 6.0.0.

Opprette en opplevelse på objektet

Bruk undervalgstjenesten når brukeren velger et element som kan velges, for å sende Power BI undervalget. Angi undervalgstiler og snarveier ved hjelp av API-en for undermerking. undervalgshjelperen kan brukes til å forenkle prosessen.

Formatmodus

Formatmodus er en ny modus der brukeren kan slå onObject formatering på og av når han er i redigeringsmodus. Visualobjektet oppdateres med statusen for formatmodusen i oppdateringsalternativene. Oppdateringsalternativene inkluderer også det merkede undervalget som CustomVisualSubSelection.

Slik implementerer du API-en for objektformatering

Egenskapsfil

Legg til følgende egenskaper i den capabilites.json filen for å deklarere at visualobjektet støtter objektformatering:

{
  "supportsOnObjectFormatting": true,
  "enablePointerEventsFormatMode": true,
}

IVisual-grensesnitt

Visualobjektet må implementere VisualOnObjectFormatting-grensesnittet som en del av IVisual-grensesnittet.

VisualOnObjectFormatting inneholder tre metoder:

getSubSelectionStyles
getSubSelectionShortcuts
getSubSelectables

getSubSelectionStyles

Hvert visualobjekt kreves for å implementere en getSubSelectionStyles metode, som kalles når et element som kan velges, er undermerket. Metoden getSubSelectionStyles leveres med gjeldende undermerkede elementer som en CustomVisualSubSelection matrise og forventes å returnere enten et SubSelectionStyles objekt eller undefined.

Det finnes tre kategorier med undervalgstiler som dekker de fleste scenarioer:

Tekst
Numerisk tekst
Skikkelse

Hvert SubSelectionStyles objekt gir en annen opplevelse for brukeren for å endre stilen til et element.

getSubSelectionShortcuts

Hvis du vil ha flere alternativer for brukeren, må visualobjektet implementere getSubSelectionShortcuts metoden. Denne metoden returnerer enten VisualSubSelectionShortcuts eller undefined. I tillegg, hvis SubSelectionShortcuts er angitt, må en VisualNavigateSubSelectionShortcut også angis, slik at når en bruker merker et element og formatruten er åpen, ruller ruten automatisk til det aktuelle kortet.

Det finnes flere snarveier for undermerking for å endre visualobjekttilstanden. Hver av dem definerer et menyelement i hurtigmenyen med riktig etikett.

Sub-Selection Andretykkelsesmeny: On-Object-menyen gir brukerne en metode for å velge ønsket undervalg når det ikke er klart hvilket visualobjekt som er undermerket. Dette skjer ofte når brukeren merker bakgrunnen til visualobjektet. For at den entydige menyen skal kunne presentere flere undervalg, må visualobjektet gi alle undervalg via getSubSelectables metoden.

getSubSelectables

Visualobjektet må implementere getSubSelectables-metoden for å gi undervalg til menyen for entydighet. Denne metoden er angitt som et valgfritt filterType argument, av typen SubSelectionStylesType og returnerer en matrise med CustomVisualSubSelection eller undefined. Hvis HTMLSubSelectionHelper brukes til å opprette et undervalg, kan HTMLSubSelectionHelper.getSubSelectables()-metoden brukes til å samle inn elementer som kan velges fra DOM.

Sub-Selection Direkte tekstredigering: Med formatering på objektet, kan du dobbeltklikke teksten i et element som kan velges, for å redigere den direkte. Hvis du vil gi direkte redigeringsfunksjonalitet, må du angi en RectangleSubSelectionOutline med riktig cVDirectEdit-egenskap fylt ut med et SubSelectableDirectEdit-objekt. Disposisjonen kan enten angis som en egendefinert disposisjon, eller hvis du bruker HTMLSubSelectionHelper kan du bruke SubSelectableDirectEdit-attributtet. (Se attributtene fra HTMLSubSelectionHelper)

Å legge til en direkte redigering for et bestemt datapunkt (ved hjelp av velgere) støttes ennå ikke.

FormateringS-ID-grensesnitt

Følgende grensesnitt brukes til å referere til subSelection snarveier og stiler.

interface FormattingId {
            objectName: string;
            propertyName: string;
            selector?: powerbi.data.Selector;
        }

objectName: objektnavnet som deklarert i capabilities.json.
propertyName: egenskapsnavnet for et objekt som deklarert i capabilities.json.
velger: Hvis datapunktet har en selectionId, bruker du selectionId.getSelector(), må denne velgeren være den samme som angitt for formateringsmodellslicen.

Eksempler

I dette eksemplet bygger vi et egendefinert visualobjekt som har to objekter, colorSelector og directEdit. Vi bruker HTMLSubSelectionHelper fra onobjectFormatting-verktøy, til å håndtere det meste av subSelection-jobben. Hvis du vil ha mer informasjon, kan du se objektverktøy.

Først bygger vi kort for formateringsruten og gir subSelectionShortcuts og stiler for hver undervalgbar.

Definer objektene

Definer objektene og deklarer at visualobjektet støtter OnObject-formatering i capabilities.json:

"objects": {
      "directEdit": {
      "properties": {
        "show": {
          "displayName": "Show",
          "type": {
            "bool": true
          }
        },
        "textProperty": {
          "displayName": "Text",
          "type": {
            "text": true
          }
        },
        "fontFamily": {
          "type": {
            "formatting": {
              "fontFamily": true
            }
          }
        },
        "fontSize": {
          "type": {
            "formatting": {
              "fontSize": true
            }
          }
        },
        "bold": {
          "type": {
            "bool": true
          }
        },
        "italic": {
          "type": {
            "bool": true
          }
        },
        "underline": {
          "type": {
            "bool": true
          }
        },
        "fontColor": {
          "displayName": "Font Color",
          "type": {
            "fill": {
              "solid": {
                "color": true
              }
            }
          }
        },
        "background": {
          "displayName": "Background",
          "type": {
            "fill": {
              "solid": {
                "color": true
              }
            }
          }
        },
        "position": {
          "displayName": "Position",
          "type": {
            "enumeration": [
              { "displayName": "Left", "value": "Left" }, { "displayName": "Right", "value": "Right" }
            ]
          }
        }
      }
    },
    "colorSelector": {
      "displayName": "Data Colors",
      "properties": {
        "fill": {
          "displayName": "Color",
          "type": {
            "fill": {
              "solid": {
                "color": true
              }
            }
          }
        }
      }
    },
   },
  "supportsOnObjectFormatting": true,
  "enablePointerEventsFormatMode": true,

Bygg formateringskortene

Bygg formateringskortene ved hjelp av formateringsverktøyene.

Innstillinger for fargevelgerkort

class ColorSelectorCardSettings extends Card {
    name: string = "colorSelector";
    displayName: string = "Data Colors";
    slices = [];
}

Legg til en metode i formateringsinnstillingen, slik at vi kan fylle ut sektorene dynamisk for colorSelector-objektet (våre datapunkter).

populateColorSelector(dataPoints: BarChartDataPoint[]) {
        let slices: formattingSettings.ColorPicker[] = this.colorSelector.slices;
        if (dataPoints) {
            dataPoints.forEach(dataPoint => {
                slices.push(new formattingSettings.ColorPicker({
                    name: "fill",
                    displayName: dataPoint.category,
                    value: { value: dataPoint.color },
                    selector: dataPoint.selectionId.getSelector(),
                }));
            });
        }
    }

Vi sender velgeren for det bestemte datapunktet i velgerfeltet. Denne velgeren brukes når du implementerer hent API-er for OnObject.

Innstillinger for direkte redigeringskort

class DirectEditSettings extends Card {
    displayName = 'Direct Edit';
    name = 'directEdit';
    private minFontSize: number = 8;
    private defaultFontSize: number = 11;
    show = new formattingSettings.ToggleSwitch({
        name: "show",
        displayName: undefined,
        value: true,
    });
    topLevelSlice = this.show;
    textProperty = new formattingSettings.TextInput({
        displayName: "Text Property",
        name: "textProperty",
        value: "What is your quest?",
        placeholder: ""
    });
    position = new formattingSettings.ItemDropdown({
        name: 'position',
        items: [{ displayName: 'Left', value: 'Left' }, { displayName: 'Right', value: 'Right' }],
        value: { displayName: 'Right', value: 'Right' }
    });
    font = new formattingSettings.FontControl({
        name: "font",
        displayName: 'Font',
        fontFamily: new formattingSettings.FontPicker({
            name: "fontFamily",
            displayName: "Font Family",
            value: "Segoe UI, wf_segoe-ui_normal, helvetica, arial, sans-serif"
        }),
        fontSize: new formattingSettings.NumUpDown({
            name: "fontSize",
            displayName: "Font Size",
            value: this.defaultFontSize,
            options: {
                minValue: {
                    type: powerbi.visuals.ValidatorType.Min,
                    value: this.minFontSize,
                }
            }
        }),
        bold: new formattingSettings.ToggleSwitch({
            name: 'bold',
            displayName: "Font Size",
            value: true
        }),
        italic: new formattingSettings.ToggleSwitch({
            name: 'italic',
            displayName: "Font Size",
            value: true
        }),
        underline: new formattingSettings.ToggleSwitch({
            name: 'underline',
            displayName: "Font Size",
            value: true
        })
    });
    fontColor = new formattingSettings.ColorPicker({
        name: "fontColor",
        displayName: "Color",
        value: { value: "#000000" }
    });
    background = new formattingSettings.ColorPicker({
        name: "background",
        displayName: "Color",
        value: { value: "#FFFFFF" }
    });
    slices = [this.show, this.textProperty, this.font, this.fontColor, this.background, this.position];
}

Bruke hjelpeattributter for undermerking

Legg til HTMLSubSelectionHelper attributter i objektene våre. Hvis du vil se hvilke attributter HTMLSubSelectionHelper gir, kan du se dokumentasjonen for objektverktøy.

For directEdit-attributtet:

import {
   HtmlSubSelectableClass, HtmlSubSelectionHelper, SubSelectableDirectEdit as SubSelectableDirectEditAttr,
   SubSelectableDisplayNameAttribute, SubSelectableObjectNameAttribute, SubSelectableTypeAttribute 
} from 'powerbi-visuals-utils-onobjectutils';

const DirectEdit: powerbi.visuals.SubSelectableDirectEdit = {
    reference: {
        objectName: 'directEdit',
        propertyName: 'textProperty'
    },
    style: SubSelectableDirectEditStyle.Outline,
};
private visualDirectEditSubSelection = JSON.stringify(DirectEdit);

this.directEditElement
            .classed('direct-edit', true)
            .classed('hidden', !this.formattingSettings.directEditSettings.show.value)
            .classed(HtmlSubSelectableClass, options.formatMode && this.formattingSettings.directEditSettings.show.value)
            .attr(SubSelectableObjectNameAttribute, 'directEdit')
            .attr(SubSelectableDisplayNameAttribute, 'Direct Edit')
            .attr(SubSelectableDirectEditAttr, this.visualDirectEditSubSelection)

HTMLSubSelectionHelper bruker SubSelectableDirectEditAttr-attributtet til å gi directEdit-referansen til directEdit-disposisjonen, slik at en direkte redigering starter når en bruker dobbeltklikker på elementet.

Skjermbilde som viser hvordan undervalgshjelperen fungerer.

For colorSelector:

barSelectionMerged
          .attr(SubSelectableObjectNameAttribute, 'colorSelector')
          .attr(SubSelectableDisplayNameAttribute, (dataPoint: BarChartDataPoint) => this.formattingSettings.colorSelector.slices[dataPoint.index].displayName)
          .attr(SubSelectableTypeAttribute, powerbi.visuals.SubSelectionStylesType.Shape)
          .classed(HtmlSubSelectableClass, options.formatMode)

Definer referanser

Definer følgende grensesnitt for å forenkle eksemplene:

Notat

Den cardUid du oppgir, skal være den samme som den som er angitt for getFormattingModel-API-en. Hvis du for eksempel bruker powerbi-visuals-utils-formattingmodel, kan du angi cardUid som Visual-cardName-card-, der cardName er navnet du tilordnet til dette kortet i innstillingene for formateringsmodellen. Ellers kan du angi det som Visual-cardUid- du har tilordnet til dette kortet.

interface References {
    cardUid?: string;
    groupUid?: string;
    fill?: FormattingId;
    font?: FormattingId;
    fontColor?: FormattingId;
    show?: FormattingId;
    fontFamily?: FormattingId;
    bold?: FormattingId;
    italic?: FormattingId;
    underline?: FormattingId;
    fontSize?: FormattingId;
    position?: FormattingId;
    textProperty?: FormattingId;
}

For dette eksemplet kan du opprette en opplisting for objektnavnene:

const enum BarChartObjectNames {
    ColorSelector = 'colorSelector',
    DirectEdit = 'directEdit'
}

Referanser for objektet directEdit:

const directEditReferences: References = {
    cardUid: 'Visual-directEdit-card',
    groupUid: 'directEdit-group',
    fontFamily: {
        objectName: BarChartObjectNames.DirectEdit,
        propertyName: 'fontFamily'
    },
    bold: {
        objectName: BarChartObjectNames.DirectEdit,
        propertyName: 'bold'
    },
    italic: {
        objectName: BarChartObjectNames.DirectEdit,
        propertyName: 'italic'
    },
    underline: {
        objectName: BarChartObjectNames.DirectEdit,
        propertyName: 'underline'
    },
    fontSize: {
        objectName: BarChartObjectNames.DirectEdit,
        propertyName: 'fontSize'
    },
    fontColor: {
        objectName: BarChartObjectNames.DirectEdit,
        propertyName: 'fontColor'
    },
    show: {
        objectName: BarChartObjectNames.DirectEdit,
        propertyName: 'show'
    },
    position: {
        objectName: BarChartObjectNames.DirectEdit,
        propertyName: 'position'
    },
    textProperty: {
        objectName: BarChartObjectNames.DirectEdit,
        propertyName: 'textProperty'
    }
};

For colorSelector:

const colorSelectorReferences: References = {
    cardUid: 'Visual-colorSelector-card',
    groupUid: 'colorSelector-group',
    fill: {
        objectName: BarChartObjectNames.ColorSelector,
        propertyName: 'fill'
    }
};

Implementer API-er

La oss nå implementere hent API-er for onObject-formateringen og gi dem i visualObjektetOnObjectFormatting:

Angi hent metoder i visualOnObjectFormatting i konstruktørkoden:

public visualOnObjectFormatting: powerbi.extensibility.visual.VisualOnObjectFormatting;
constructor(options: VisualConstructorOptions) {
        this.subSelectionHelper = HtmlSubSelectionHelper.createHtmlSubselectionHelper({
                 hostElement: options.element,
                 subSelectionService: options.host.subSelectionService,
                 selectionIdCallback: (e) => this.selectionIdCallback(e),
            });

 this.visualOnObjectFormatting = {
                getSubSelectionStyles: (subSelections) => this.getSubSelectionStyles(subSelections),
                getSubSelectionShortcuts: (subSelections, filter) => this.getSubSelectionShortcuts(subSelections, filter),
                getSubSelectables: (filter) => this. getSubSelectables(filter)
            }
   }

private getSubSelectionStyles(subSelections: CustomVisualSubSelection[]): powerbi.visuals.SubSelectionStyles | undefined {
        const visualObject = subSelections[0]?.customVisualObjects[0];
        if (visualObject) {
            switch (visualObject.objectName) {
                case BarChartObjectNames.ColorSelector:
                    return this.getColorSelectorStyles(subSelections);
                 case BarChartObjectNames.DirectEdit:
                    return this.getDirectEditStyles();
            }
        }
    }

private getSubSelectionShortcuts(subSelections: CustomVisualSubSelection[], filter: SubSelectionShortcutsKey | undefined):    VisualSubSelectionShortcuts | undefined {
        const visualObject = subSelections[0]?.  customVisualObjects[0];
        if (visualObject) {
            switch (visualObject.objectName) {
                case BarChartObjectNames.ColorSelector:
                    return this.getColorSelectorShortcuts(subSelections);
                case BarChartObjectNames.DirectEdit:
                    return this.getDirectEditShortcuts();
            }
        }
    }

Implementer snarveiene og stilen getSubSelection for colorSelector:

private getColorSelectorShortcuts(subSelections:  CustomVisualSubSelection[]): VisualSubSelectionShortcuts   {
        const selector = subSelections[0].customVisualObjects[0].selectionId?.getSelector();
        return [
            {
                type: VisualShortcutType.Reset,
                relatedResetFormattingIds: [{
                    ...colorSelectorReferences.fill,
                    selector
                }],
            },
            {
                type: VisualShortcutType.Navigate,
                destinationInfo: { cardUid: colorSelectorReferences.cardUid },
                label: 'Color'
            }
        ];
    }

Snarveien ovenfor returnerer relevant menyelement i hurtigmenyen og legger til følgende funksjoner:

VisualShortcutType.Navigate: Når en bruker velger på en av stolpene (datapunktet), og formateringsruten er åpen, ruller formatruten til fargevelgerkortet og åpner det
VisualShortcutType.Reset: legger til en tilbakestillingssnarvei i hurtigmenyen. Den er aktivert hvis fyllfargen ble endret.

private getColorSelectorStyles(subSelections: CustomVisualSubSelection[]): SubSelectionStyles {
        const selector = subSelections[0].customVisualObjects[0].selectionId?.getSelector();
        return {
            type: SubSelectionStylesType.Shape,
            fill: {
                label: 'Fill',
                reference: {
                    ...colorSelectorReferences.fill,
                 selector
                },
            },
        };
    }

Når en bruker høyreklikker på en stolpe, vises følgende:

Skjermbilde av brukergrensesnittet når en bruker høyreklikker på en stolpe.

Når du endrer fargen:

Skjermbilde av endring av farge.

Snarveier for underseksjon

Slik implementerer du snarveier og stiler for undervalg for directEdit:

private getDirectEditShortcuts(): VisualSubSelectionShortcuts {
        return [
            {
                type: VisualShortcutType.Reset,
                relatedResetFormattingIds: [
                    directEditReferences.bold,
                    directEditReferences.fontFamily,
                    directEditReferences.fontSize,
                    directEditReferences.italic,
                    directEditReferences.underline,
                    directEditReferences.fontColor,
                    directEditReferences.textProperty
                ]
            },
            {
                type: VisualShortcutType.Toggle,
                relatedToggledFormattingIds: [{
                    ...directEditReferences.show,
                }],
                ...directEditReferences.show,
                disabledLabel: 'Delete',
            },
            {
                type: VisualShortcutType.Picker,
                ...directEditReferences.position,
                label: 'Position'
            },
            {
                type: VisualShortcutType.Navigate,
                destinationInfo: { cardUid: directEditReferences.cardUid },
                label: 'Direct edit'
            }
        ];
    }

Denne snarveien legger til et relevant menyelement i hurtigmenyen og legger til følgende funksjoner:

VisualShortcutType.Reset: legger til en tilbakestilling i standardelementet i hurtigmenyen når én av egenskapene i relatedResetFormattingIds-matrise endres.
VisualShortcutType.Toggle: legger til slettealternativer i hurtigmenyen. Når du klikker, deaktiveres vekslebryteren for directEdit-kortet.
VisualShortcutType.Picker: Legger til et alternativ i hurtigmenyen for å velge mellom Høyre og Venstre, siden vi la til posisjonsslicen i formateringskortet for directEdit.
VisualShortcutType.Navigate: Når formatruten er åpen og brukeren velger directEdit-elementet, ruller formatruten og åpner directEdit-kortet.

private getDirectEditStyles(): SubSelectionStyles {
        return {
            type: powerbi.visuals.SubSelectionStylesType.Text,
            fontFamily: {
                reference: {
                    ...directEditReferences.fontFamily
                },
                label: 'font family'
            },
            bold: {
                reference: {
                    ...directEditReferences.bold
                },
                label: 'bold'
            },
            italic: {
                reference: {
                    ...directEditReferences.italic
                },
                label: 'italic'
            },
            underline: {
                reference: {
                    ...directEditReferences.underline
                },
                label: 'underline'
            },
            fontSize: {
                reference: {
                    ...directEditReferences.fontSize
                },
                label: 'font size'
            },
            fontColor: {
                reference: {
                    ...directEditReferences.fontColor
                },
                label: 'font color'
            },
            background: {
                reference: {
                    objectName: 'directEdit',
                    propertyName: 'background'
                },
                label: 'background'
            }
        }
    }

Vi leverte de relevante egenskapene da vi la dem til i formateringsinnstillingene.

Bildet nedenfor illustrerer hvordan brukergrensesnittet ser ut når du høyreklikker på directEdit-elementet:

Skjermbilde av grensesnittet for direkte redigering.

Lokalisering

Visualobjektet bør håndtere lokaliseringen og gi lokaliserte strenger.

GitHub-ressurser

Du finner alt på objektformateringsgrensesnitt i (kobling som skal angis når API-en er utgitt) i on-object-formatting-api.d.ts
Vi anbefaler at du bruker [på objektverktøy], som inkluderer [HTMLSubSelectionHelper](koblingen som skal angis når API-en er utgitt)
Du kan finne et eksempel på et egendefinert visualobjekt SampleBarChart som bruker API versjon 5.8.0 og implementerer støtte for objektformatering ved hjelp av objektverktøyene på (kobling som skal oppgis når API-en er utgitt)

Tilbakemeldinger

Var denne siden nyttig?

Last updated on 2025-12-15