Jaa

Objektin muotoilun ohjelmointirajapinta (esikatselu)

  • Artikkeli

Objektien muotoilun avulla käyttäjät voivat nopeasti ja helposti muokata visualisointien muotoa valitsemalla suoraan elementit, joita he haluavat muokata. Kun elementti on valittu, muotoiluruudussa siirrytään automaattisesti ja laajennetaan valitun elementin muotoiluasetusta. Lisätietoja objektien paikallisesta muotoilusta on artikkelissa Objektien automaattinen muotoilu Power BI Desktopissa.

Jotta voit lisätä näitä toimintoja visualisointiisi, kunkin visualisoinnin on tarjottava alivalintatyylinen asetus ja pikakuvake kullekin alivalinnan alueelle.

Muistiinpano

  • Visualisointien, jotka tukevat objektien automaattista muotoilua, on käytettävä getFormattingModel-ohjelmointirajapintaa , joka on saatavilla ohjelmointirajapinnan versiosta 5.1.
  • Jos käytät powerbi-visuals-utils-formattingmodel-versiota 6.0.0 vähintään.

Luo on-object-käyttökokemus

Käytä alivalintapalvelua, kun käyttäjä valitsee alivalinnan elementin alivalinnan lähettämiseksi Power BI:lle. Anna alivalintatyylit ja -pikakuvakkeet aliosioiden ohjelmointirajapinnan avulla. Alivalinta-aputoimintoa voidaan käyttää prosessin yksinkertaistamiseen.

Muotoilutila

Muotoilutila on uusi tila, jossa käyttäjä voi ottaa muotoilun käyttöön onObject ja poistaa sen käytöstä luontitilassa. Visualisointiin päivitetään muotoilutilan tila päivitysasetuksissa. Päivitysasetukset sisältävät myös alivalinnan CustomVisualSubSelectionnimellä .

Objektin muotoilun ohjelmointirajapinnan käyttöönotto

Toimintotiedosto

Lisää capabilites.json-tiedostoon seuraavat ominaisuudet sen ilmaisemiseksi, että visualisointi tukee objektinkohtaista muotoilua:

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

IVisual-liittymä

Visualisoinnin on otettava liittymä käyttöön VisualOnObjectFormatting osana IVisual-liittymää.

VisualOnObjectFormatting sisältää kolme menetelmää:

getSubSelectionStyles

Kutakin visualisointia getSubSelectionStyles tarvitaan toteuttamaan menetelmä, jota kutsutaan, kun alivalittava elementti valitaan alivalinnaksi. - getSubSelectionStyles menetelmä toimitetaan senhetkisen alivalitun elementin kanssa matriisina CustomVisualSubSelection , ja sen odotetaan palauttavan joko objektin SubSelectionStyles tai undefined.

On olemassa kolme alivalintatyyliluokkaa, jotka kattavat useimmat skenaariot:

  • Teksti
  • Numeerinen teksti
  • Muoto

Jokainen SubSelectionStyles objekti tarjoaa käyttäjälle erilaisen käyttökokemuksen elementin tyylin muokkaamista varten.

getSubSelectionShortcuts

Visualisoinnin on otettava käyttöön getSubSelectionShortcuts -menetelmä, jotta käyttäjälle saadaan enemmän vaihtoehtoja. Tämä menetelmä palauttaa joko - tai -arvon VisualSubSelectionShortcuts undefined. Lisäksi jos SubSelectionShortcuts ne on annettu, on myös annettava niin, VisualNavigateSubSelectionShortcut että kun käyttäjä alivalitsee elementin ja muotoiluruutu on avoinna, ruutu siirtyy automaattisesti oikeaan korttiin.

Visualisoinnin tilan muokkaamiseen on useita alivalintakuvakkeita. Jokainen määrittää pikavalikosta valikkokohteen, jossa on asianmukainen selite.

Alivalinnan selvitysvalikko: On-Object-selvitysvalikossa on menetelmä, jolla käyttäjät voivat valita haluamansa alivalinnan, kun ei ole selvää, mikä visuaalinen elementti on alivalittu. Näin tapahtuu usein, kun käyttäjä alivalitsee visualisoinnin taustan. Jotta yksiselitteinen valikko esittäisiin enemmän alivalintoja, visualisoinnin on tarjottava kaikki alivalinnat -menetelmän getSubSelectables kautta.

getSubSelectables

Jos haluat määrittää alivalinnat selvitysvalikkoon, visualisoinnin on otettava käyttöön - getSubSelectables menetelmä. Tälle menetelmälle annetaan valinnainen filterType argumentti, jonka tyyppi SubSelectionStylesType on ja joka palauttaa matriisin CustomVisualSubSelection tai undefined. HTMLSubSelectionHelper Jos kohdetta käytetään alivalinnan luomiseen, HTMLSubSelectionHelper.getSubSelectables()-menetelmää voidaan käyttää alivalinnan elementtien keräämiseen DOM-toiminnosta.

Alivalinnan suora tekstin muokkaus: Objektin on-object-muotoilun avulla voit muokata suoraan alivalintaelementin tekstiä kaksoisnapsauttamalla sitä. Jos haluat tarjota suoran muokkausominaisuuden, sinun on annettava RectangleSubSelectionOutline asianmukainen cVDirectEdit-ominaisuus, johon on täytetty SubSelectableDirectEdit-objekti. Ääriviiva voidaan joko antaa mukautettuna ääriviivana tai, jos käytät HTMLSubSelectionHelper -määritettä, voit käyttää sitä SubSelectableDirectEdit . (Katso HTMLSubSelectionHelper-kohteen tarjoamat määritteet)

Suoran muokkauksen lisäämistä tiettyyn arvopisteeseen (valitsimien avulla) ei vielä tueta.

FormattingId-liittymä

Seuraavia liittymiä käytetään viittaamaan subSelection pikakuvakkeisiin ja tyyleihin.

interface FormattingId {
            objectName: string;
            propertyName: string;
            selector?: powerbi.data.Selector;
        }
  • objectName: objektin nimi, joka on määritetty capabilities.json.
  • propertyName: objektin ominaisuuden nimi capabilities.json esitetyllä tavalla.
  • selector: jos arvopisteellä on selectionId, käytä selectionId.getSelector()-funktiota, tämän valitsimen on oltava sama kuin muotoilumallin osittajassa.

Esimerkit

Tässä esimerkissä luomme mukautetun visualisoinnin, jossa on kaksi objektia: colorSelector ja directEdit. Käytämme HTMLSubSelectionHelper onobjectFormatting -apuohjelmien -apuohjelmaa, jotta voimme hoitaa suurimman osan alivalintatyöstä. Katso lisätietoja kohdasta on-object-apuohjelmat.

Ensin luomme kortit muotoiluruutuun ja tarjoamme subSelectionShortcut-kortit ja tyylit kullekin alivalinnalle.

Objektien määrittäminen

Määritä objektit ja ilmoita, että visualisointi tukee OnObject-muotoilua 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,

Muotoilukorttien luominen

Luo muotoilukortteja formattingModel-apuohjelmien avulla.

Värivalitsinkortin asetukset

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

Lisää -menetelmä formattingSetting-arvoon, jotta voimme täyttää osittajat dynaamisesti colorSelector-objektille (arvopisteet).

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(),
                }));
            });
        }
    }

Välitämme valitsimen kyseiselle arvopisteelle valitsinkentässä. Tätä valitsinta käytetään, kun otetaan käyttöön OnObject-kohteen hae ohjelmointirajapinnat.

Suora muokkauskortin asetukset

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

Alivalinta-aputoiminnon määritteiden käyttäminen

Lisää määritteet HTMLSubSelectionHelper objekteihimme. Jos haluat nähdä, mitä määritteitä HTMLSubSelectionHelper tarjoaa, tutustu objektiapuohjelmien ohjeisiin.

  • DirectEdit-määritteelle:

    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-SubSelectableDirectEditAttrmäärite tarjoaa suoranMuokkaa-viitteen directEdit-jäsennykseen, joten suora muokkaus alkaa, kun käyttäjä kaksoisnapsauttaa elementtiä.

    Screenshot showing how the subselection helper works.

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

Määritä viittaukset

Yksinkertaista esimerkkejä määrittämällä seuraava liittymä:

Muistiinpano

Antamasi cardUid -sovelluksen on oltava sama kuin getFormattingModel-ohjelmointirajapinnalle annettu versio. Jos käytät esimerkiksi powerbi-visuals-utils-formattingmodel-kohdetta, anna cardUid muodossa Visual-cardName-card, jossa cardName on nimi, jonka määritit tälle kortille muotoilumallin asetuksissa. Muussa tapauksessa anna se Visual-cardUid-arvona , jonka määritit tälle kortille.

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

Luo tässä esimerkissä luettelointi objektien nimille:

const enum BarChartObjectNames {
    ColorSelector = 'colorSelector',
    DirectEdit = 'directEdit'
}
  • Viittaukset objektiin 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'
    }
};
  • Lle colorSelector:
const colorSelectorReferences: References = {
    cardUid: 'Visual-colorSelector-card',
    groupUid: 'colorSelector-group',
    fill: {
        objectName: BarChartObjectNames.ColorSelector,
        propertyName: 'fill'
    }
};

Ohjelmointirajapintojen käyttöönotto

Otetaan seuraavaksi käyttöön hae ohjelmointirajapinnat onObject-muotoilua varten ja annetaan ne visualIsoinninOnObjectFormatting:

  1. Anna konstruktorikoodissa visualOnObjectFormatting-kohteen hae-menetelmät:

    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. Ota käyttöön getSubSelection-pikakuvakkeet ja -tyyli colorSelectorille:

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

    Yllä oleva pikakuvake palauttaa pikavalikosta asianmukaisen valikkovaihtoehdon ja lisää seuraavat toiminnot:

    • VisualShortcutType.Navigate: kun käyttäjä valitsee jonkin palkeista (arvopiste) ja muotoiluruutu on avoinna, muotoiluruutu vierittää värinvalitsinkorttiin ja avaa sen
    • VisualShortcutType.Reset: lisää nollauskuvakkeen pikavalikkoon. Se on käytössä, jos täyttöväriä muutettiin.
    private getColorSelectorStyles(subSelections: CustomVisualSubSelection[]): SubSelectionStyles {
        const selector = subSelections[0].customVisualObjects[0].selectionId?.getSelector();
        return {
            type: SubSelectionStylesType.Shape,
            fill: {
                label: 'Fill',
                reference: {
                    ...colorSelectorReferences.fill,
                 selector
                },
            },
        };
    }

Kun käyttäjä napsauttaa palkkia hiiren kakkospainikkeella, näkyviin tulee seuraava:

Screenshot of user interface when a user right-clicks on a bar.

Väriä vaihdettaessa:

Screenshot of changing color.

Aliosioiden pikanäppäimet

DirectEdit-näppäimen alivalintakuvakkeiden ja -tyylien käyttöönotto:

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

Tämä pikakuvake lisää pikavalikon asianmukaisen valikkovaihtoehdon ja lisää seuraavat toiminnot:

  • VisualShortcutType.Reset: nollaa oletuskohteen pikavalikkoon, kun jokin relatedResetFormattingIds-matriisin ominaisuuksista muuttuu.
  • VisualShortcutType.Toggle: lisää Pikavalikkoon Poista-asetukset. Kun napsautat tätä, directEdit-kortin vaihtokytkin on poistettu käytöstä.
  • VisualShortcutType.Picker: Lisää pikavalikosta vaihtoehdon, joka valitaan oikealta vasemmalle, koska olemme lisänneet sijaintiosittajan directEdit-kohteen muotoilukorttiin.
  • VisualShortcutType.Navigate: Kun muotoiluruutu on avoinna ja käyttäjä valitsee directEdit-elementin , muotoiluruutu vierittää ja avaa suoranMuokkaa-kortin .
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'
            }
        }
    }

Tarjosimme tarvittavat ominaisuudet, kun lisäsimme ne muotoiluun Asetukset.

Seuraavassa kuvassa näkyy, miltä käyttöliittymä näyttää, kun napsautat directEdit-elementtiä hiiren kakkospainikkeella:

Screenshot of the direct edit interface.

Lokalisointi

Visualisoinnin tulee käsitellä lokalisointia ja antaa lokalisoituja merkkijonoja.

GitHub-resurssit

  • Kaikki objektin muotoiluliittymiä koskevat käyttöliittymät löytyvät kohdasta (linkki, joka annetaan, kun ohjelmointirajapinta julkaistaan) on-object-formatting-api.d.ts
  • Suosittelemme käyttämään kohdetta [objektiapuohjelmat], joka sisältää [HTMLSubSelectionHelper](-linkin, joka annetaan, kun ohjelmointirajapinta julkaistaan)
  • Löydät esimerkin mukautetusta visualisoinnista SampleBarChart , joka käyttää ohjelmointirajapinnan versiota 5.8.0 ja toteuttaa objektin muotoilun tuen käyttämällä objektiapuohjelmia kohteessa (linkki, joka annetaan, kun ohjelmointirajapinta on julkaistu)

Liittyvä sisältö