Interfejs API podwybierz (wersja zapoznawcza)
Formatowanie obiektu umożliwia użytkownikom szybkie i łatwe modyfikowanie formatu wizualizacji przez bezpośrednie wybranie elementów, które mają zostać zmodyfikowane. Po wybraniu elementu okienko formatowania automatycznie przechodzi i rozwija określone ustawienie formatowania dla wybranego elementu. W ramach formatowania obiektów usługa podwyborcza służy do wysyłania wyborów podrzędnych i konspektu do usługi Power BI.
Jak używać interfejsu API wyboru podrzędnego
Usługa SubSelection udostępnia dwie metody:
Podselekcja
Wysyła podwyborcz dla usługi Power BI do użycia, gdy użytkownik wybierze element, który zezwala na wybory podrzędne.
subSelect(args: visuals.CustomVisualSubSelection | undefined): void
CustomVisualSubSelection
interface CustomVisualSubSelection {
customVisualObjects: CustomVisualObject[];
displayName: string;
subSelectionType: SubSelectionStylesType;
selectionOrigin: SubSelectionOrigin;
/** Whether to show the UI for this sub-selection, like formatting context menus and toolbar */
showUI: boolean;
/** If immediate direct edit should be triggered, the ID of the sub-selection outline to edit */
immediateDirectEdit?: string;
metadata?: unknown;
}
interface CustomVisualObject {
objectName: string;
selectionId: powerbi.visuals.ISelectionId | undefined;
}
Ta metoda ma następujące parametry:
- customVisualObjects: tablica zawierająca
customVisualObjectsobiekt , objectName obiektu powinna być taka sama jak ta zadeklarowana w capabilities.json i selectionId dla wybranego punktu danych, jeśli istnieje. - displayName: nazwa wyświetlana powinna być zlokalizowana, jeśli wizualizacja obsługuje lokalizację.
- subSelectionType: typ podwybierz (kształt, tekst lub tekst liczbowy).
- selectionOrigin: współrzędne podselekcyjnego elementu.
- showUI: czy pokazać interfejs użytkownika dla tej podwybierz, na przykład formatowanie menu kontekstowych i paska narzędzi.
- immediateDirectEdit: jeśli powinna zostać wyzwolona natychmiastowa bezpośrednia edycja, identyfikator konspektu podwybór do edycji.
Jeśli nie używasz programu HTMLSubSelectionHelper, musisz zarządzać wyborami podrzędnymi.
Przykład podwybierz
W tym przykładzie dodajemy odbiornik zdarzeń do elementu hosta dla zdarzeń kliknięcie prawym przyciskiem myszy, zdarzenia menu kontekstowego.
constructor(options: VisualConstructorOptions) {
this.hostElement = options.element;
this.subSelectionService = options.host.subSelectionService;
….
}
public update(options: VisualUpdateOptions) {
if (options.formatMode) {
// remove event listeners which are irrelevant for format mode.
…
this.hostElement.addEventListener('click', this.handleFormatModeClick);
this.hostElement.addEventListener('contextmenu', this.handleFormatModeContextMenu);
} else {
this.hostElement.removeEventListener('click', this.handleFormatModeClick);
this.hostElement.removeEventListener('contextmenu', this.handleFormatModeContextMenu);
…
// add event listeners which are irrelevant for format mode
}
}
private handleFormatModeClick(event: MouseEvent): void {
this.subSelectFromEvent(event, true /**showUI */);
}
private handleFormatModeContextMenu(event: MouseEvent): void {
this.subSelectFromEvent(event, false);
}
private subSelectFromEvent(event: MouseEvent, showUI: boolean): void {
//find the element which was selected and fill the needed fields
const cVObject: powerbi.visuals.CustomVisualObject = {
objectName: 'myObject',//the object name that is relevant to the clicked element
selectionId: undefined
};
const subSelection: CustomVisualSubSelection = {
customVisualObjects: [cVObject],
displayName: 'myObject',
selectionOrigin: {
x: event.clientX,
y: event.clientY
},
subSelectionType: SubSelectionStylesType.Shape,// choose the relevant type
showUI
};
this.subSelectionService.subSelect(subSelection);
}
updateRegionOutlines
Ta metoda wysyła konspekty do usługi Power BI w celu renderowania. Użyj jej w update metodzie wizualizacji, ponieważ usługa Power BI wysyła podwybór, który wizualizacja wysłała wcześniej. Można go również użyć, gdy chcesz renderować konspekt dla elementu aktywowanego.
updateRegionOutlines(outlines: visuals.SubSelectionRegionOutline[]): void
SubSelectionRegionOutline
interface SubSelectionRegionOutline {
id: string;
visibility: SubSelectionOutlineVisibility; // controls visibility for outlines
outline: SubSelectionOutline;
}
Jeśli nie używasz HTMLSubSelectionHelperelementu , musisz ręcznie zarządzać konspektami i ich stanem (jeśli są aktywne, zatrzymane lub niewidoczne).
Przykład konspektu dotyczący regionu aktualizacji
W tym przykładzie przyjęto założenie, że mamy obiekt o nazwie myObjecti chcemy renderować kontur prostokąta po umieszczeniu wskaźnika myszy na odpowiednim elemenie. W poprzednim przykładzie użyjemy kodu dla parametru subSelect.
W aktualizacji musimy również dodać odbiornik zdarzeń dla pointerover zdarzenia.
Chcemy zarządzać naszymi konspektami przy użyciu rekordu.
private subSelectionRegionOutlines: Record<string, SubSelectionRegionOutline > = {};
public update(options: VisualUpdateOptions) {
if (options.formatMode) {
// remove event listeners which are irrelevant for format mode.
…
this.hostElement.addEventListener('click', this.handleFormatModeClick);
this.hostElement.addEventListener('contextmenu', this.handleFormatModeContextMenu);
this.hostElement.addEventListener('pointerover', this.handleFormatModePointerOver);
} else {
this.hostElement.removeEventListener('click', this.handleFormatModeClick);
this.hostElement.removeEventListener('contextmenu', this.handleFormatModeContextMenu);
this.hostElement.removeEventListener('pointerover', this.handleFormatModePointerOver);
…
// add event listeners which are irrelevant for format mode
}
}
private handleFormatModePointerOver(event: MouseEvent): void {
// use the event to extract the element that was hovered.
// in this example we assume that we found the element and it is related to object called myObject.
// we need to clear previously hovered outlines before rendering
const regionOutlines = getValues(this.subSelectionRegionOutlines);
const hoveredOutline = regionOutlines.find(outline => outline.visibility === SubSelectionOutlineVisibility.Hover);
if (hoveredOutline) {
this.subSelectionRegionOutlines[hoveredOutline.id] = {
...this.subSelectionRegionOutlines[hoveredOutline.id],
visibility: powerbi.visuals.SubSelectionOutlineVisibility.None
};
}
// now we will build the outline for myObject relevant element.
let element: HTMLElement;// assume we found the relevant element.
const domRect = element.getBoundingClientRect();
const { x, y, width, height } = domRect;
const outline: powerbi.visuals.RectangleSubSelectionOutline = {
height,
width,
x,
y,
type: powerbi.visuals.SubSelectionOutlineType.Rectangle,
};
const regionOutline: powerbi.visuals.SubSelectionRegionOutline = {
id: 'myObject',
visibility: powerbi.visuals.SubSelectionOutlineVisibility.Hover,
outline
};
this.subSelectionRegionOutlines[regionOutline.id] = regionOutline;
this.renderOutlines();
// you need to remove the hovered outline when the element is not hovered anymore
}
private renderOutlines(): void {
const regionOutlines = getValues(this.subSelectionRegionOutlines);
this.subSelectionService.updateRegionOutlines(regionOutlines);
}