Del via

API til formatering i objektet (prøveversion)

  • Artikel

formatering i objektet gør det muligt for brugerne hurtigt og nemt at ændre formatet af visualiseringer ved direkte at vælge de elementer, de vil ændre. Når et element vælges, navigerer og udvider formatruden automatisk den specifikke formateringsindstilling for det valgte element. Du kan få flere oplysninger om formatering i objektet under Formatering i det pågældende objekt i Power BI Desktop.

Hvis du vil føje disse funktioner til din visualisering, skal hver visualisering angive en indstilling for undervalgstypografi og genvej for hvert område, der kan vælges.

Seddel

  • Visualiseringer, der understøtter formatering i objektet, skal implementere api'en getFormattingModel, som er tilgængelig fra API-version 5.1.
  • Hvis du bruger powerbi-visuals-utils-formattingmodel, skal du bruge mindst version 6.0.0.

Opret en oplevelse i et objekt

Brug undersektionstjenesten, når brugeren vælger et element, der kan vælges, for at sende underafsnittet til Power BI. Angiv undersektionstypografier og -genveje ved hjælp af API'en til undersektion. Hjælpefunktionen til undersektion kan bruges til at forenkle processen.

Formattilstand

Formattilstand er en ny tilstand, hvor brugeren kan slå onObject formatering til og fra, når brugeren er i oprettelsestilstand. Visualiseringen opdateres med status for formattilstanden i opdateringsindstillingerne. Opdateringsindstillingerne omfatter også den aktuelt undermarkerede undersektion som CustomVisualSubSelection.

Sådan implementerer du API'en til formatering i objektet

Filen Capabilities

I den capabilites.json fil skal du tilføje følgende egenskaber for at erklære, at visualiseringen understøtter formatering i objektet:

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

IVisual-grænseflade

Visualiseringen skal implementere grænsefladen VisualOnObjectFormatting som en del af IVisual-grænsefladen.

VisualOnObjectFormatting indeholder tre metoder:

getSubSelectionStyles

Hver enkelt visualisering kræves for at implementere en getSubSelectionStyles metode, som kaldes, når et element, der kan vælges, er undermarkeret. Metoden getSubSelectionStyles leveres med de aktuelle undermarkerede elementer som en CustomVisualSubSelection matrix og forventes at returnere enten et SubSelectionStyles-objekt eller undefined.

Der er tre kategorier af undersektionstypografier, der dækker de fleste scenarier:

  • Tekst
  • Numerisk tekst
  • Form

Hvert SubSelectionStyles-objekt giver brugeren en anden oplevelse, når det gælder ændring af typografien for et element.

getSubSelectionShortcuts

Hvis du vil angive flere indstillinger for brugeren, skal visualiseringen implementere metoden getSubSelectionShortcuts. Denne metode returnerer enten VisualSubSelectionShortcuts eller undefined. Hvis der er angivet SubSelectionShortcuts, skal der også angives en VisualNavigateSubSelectionShortcut, så når en bruger undervælger et element, og formatruden er åben, ruller ruden automatisk til det relevante kort.

Der er flere undersektionsgenveje til ændring af visualiseringstilstanden. Hver af dem definerer et menupunkt i genvejsmenuen med den relevante etiket.

Sub-Selection Menu til fjernelse af flertydige udtryk: Menuen Til fjernelse af flertydige objekter indeholder en metode, som brugerne kan bruge til at vælge den ønskede undersektion, når det ikke er klart, hvilket visuelt element der undermarkeres. Dette sker ofte, når brugeren undermarker baggrunden i visualiseringen. Hvis den flertydige menu skal vise flere undermarkeringer, skal visualiseringen indeholde alle undermarkeringer via metoden getSubSelectables.

getSubSelectables

Hvis du vil angive undermarkeringer i menuen til fjernelse af flertydige udtryk, skal visualiseringen implementere metoden getSubSelectables. Denne metode leveres som et valgfrit filterType argument af typen SubSelectionStylesType og returnerer en matrix af CustomVisualSubSelection eller undefined. Hvis HTMLSubSelectionHelper bruges til at oprette en undersektion, kan metoden HTMLSubSelectionHelper.getSubSelectables() bruges til at indsamle elementer, der kan fravælges, fra DOM.

Sub-Selection Direkte tekstredigering: Med formatering i objektet kan du dobbeltklikke på teksten i et element, der kan vælges, for at redigere det direkte. Hvis du vil have mulighed for direkte redigering, skal du angive en RectangleSubSelectionOutline med den relevante cVDirectEdit-egenskab udfyldt med et SubSelectableDirectEdit-objekt. Dispositionen kan enten angives som en brugerdefineret disposition, eller hvis du bruger HTMLSubSelectionHelper kan du bruge attributten SubSelectableDirectEdit. (Se de attributter, der leveres af HTMLSubSelectionHelper)

Tilføjelse af en direkte redigering for et bestemt datapunkt (ved hjælp af selektorer) understøttes endnu ikke.

Grænsefladen FormattingId

Følgende grænseflade bruges til at referere til subSelection genveje og typografier.

interface FormattingId {
            objectName: string;
            propertyName: string;
            selector?: powerbi.data.Selector;
        }
  • objectName: objektnavnet som erklæret i capabilities.json.
  • propertyName: egenskabsnavnet på et objekt som defineret i capabilities.json.
  • selector: Hvis datapunktet har et selectionId, skal du bruge selectionId.getSelector(), skal denne selektor være den samme som den, der er angivet for formateringsmodeludsnittet.

Eksempler

I dette eksempel opretter vi en brugerdefineret visualisering, der indeholder to objekter, colorSelector og directEdit. Vi bruger HTMLSubSelectionHelper fra onobjectFormatting hjælpeprogrammer til at håndtere det meste af undervalgsjobbet. Du kan få flere oplysninger under hjælpeprogrammer på objektet.

Først skal du oprette kort til formateringsruden og angive underValgShortcuts og typografier for hver undermarkering.

Definer objekterne

Definer objekterne, og deklarer, at visualiseringen understø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,

Opret formateringskortene

Byg deres formateringskort ved hjælp af formateringshjælpeprogrammer.

Indstillinger for farvevælgerkort

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

Føj en metode til formateringsindstillingerne, så vi kan udfylde udsnittene dynamisk for objektet colorSelector (vores 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 overfører vælgeren for det specifikke datapunkt i selektorfeltet. Denne selektor er den, der bruges til implementering af Hent API'er for OnObject.

Indstillinger for direkte redigering af kort

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];
}

Brug hjælpeattributter for undersektion

Føj attributterne HTMLSubSelectionHelper til vores objekter. Hvis du vil se, hvilke attributter HTMLSubSelectionHelper indeholder, skal du se dokumentationen til objekthjælpeprogrammer.

  • For attributten directEdit:

    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)

    I HTMLSubSelectionHelper bruges attributten SubSelectableDirectEditAttr til at angive directEdit-referencen til directEdit-dispositionen, så en direkte redigering starter, når en bruger dobbeltklikker på elementet.

    Skærmbillede, der viser, hvordan hjælpefunktionen til undersektion 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 referencer

Definer følgende grænseflade for at forenkle eksemplerne:

Seddel

Den cardUid, du angiver, skal være den samme som den, der er angivet for getFormattingModel-API'en. Hvis du f.eks. bruger powerbi-visuals-utils-formattingmodel, skal du angive cardUid som Visual-cardName-card, hvor cardName er det navn, du har tildelt til dette kort under indstillingerne for formateringsmodel. Ellers skal du angive det som det Visual-cardUid-, du har tildelt til dette kort.

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

I dette eksempel skal du oprette en optælling for objektnavnene:

const enum BarChartObjectNames {
    ColorSelector = 'colorSelector',
    DirectEdit = 'directEdit'
}
  • Referencer til det directEdit objekt:
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

Lad os nu implementere hent API'er til formateringen onObject og angive dem i visualOnObjectFormatting:

  1. Angiv hent-metoderne 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();
            }
        }
    }

  2. Implementer genvejene og typografien getSubSelection til 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'
            }
        ];
    }

    Ovenstående genvej returnerer det relevante menupunkt i genvejsmenuen og tilføjer følgende funktioner:

    • VisualShortcutType.Navigate: Når en bruger vælger en af søjlerne (datapunktet), og formateringsruden er åben, ruller formatruden til farvevælgerkortet og åbner det
    • VisualShortcutType.Reset: føjer en genvej til nulstilling til genvejsmenuen. Den er aktiveret, hvis fyldfarven blev ændret.
    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 bruger højreklikker på en søjle, vises følgende:

Skærmbillede af brugergrænsefladen, når en bruger højreklikker på en søjle.

Når du ændrer farven:

Skærmbillede af ændring af farve.

Genveje til undersektion

Sådan implementerer du genveje og typografier i underafsnittet til 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 genvej tilføjer et relevant menupunkt i genvejsmenuen og tilføjer følgende funktioner:

  • VisualShortcutType.Reset: føjer en nulstilling til standardelementet i genvejsmenuen, når en af egenskaberne i matrixen relatedResetFormattingIds ændres.
  • VisualShortcutType.Toggle: føjer sletteindstillinger til genvejsmenuen. Når der klikkes på den, er til/fra-knappen for directEdit-kortet slået fra.
  • VisualShortcutType.Picker: Tilføjer en indstilling i genvejsmenuen for at vælge mellem højre og venstre, da vi har tilføjet placeringsudsnittet på formateringskortet for directEdit.
  • VisualShortcutType.Navigate: Når formatruden er åben, og brugeren vælger directEdit-elementet, ruller formatruden og åbner kortet directEdit.
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 har angivet de relevante egenskaber, da vi har tilføjet dem i formateringsindstillingerne.

På følgende billede kan du se, hvordan brugergrænsefladen ser ud, når du højreklikker på elementet directEdit:

Skærmbillede af grænsefladen til direkte redigering.

Lokalisering

Visualiseringen skal håndtere lokaliseringen og levere lokaliserede strenge.

GitHub-ressourcer

  • Alle på grænseflader til objektformatering kan findes i (link, der skal angives, når API'en udgives) i on-object-formatting-api.d.ts
  • Vi anbefaler, at du bruger [på objekthjælpeprogrammer], som omfatter [HTMLSubSelectionHelper](link, der skal angives, når API'en udgives)
  • Du kan finde et eksempel på en brugerdefineret visualisering SampleBarChart-, der bruger API version 5.8.0 og implementerer understøttelse af objektformatering ved hjælp af objekthjælpeprogrammer på (link, der skal angives, når API'en udgives)

Relateret indhold