API de subselección (versión preliminar)
El formato en el objeto permite a los usuarios modificar rápida y fácilmente el formato de los objetos visuales seleccionando directamente los elementos que quieren modificar. Cuando se selecciona un elemento, el panel de formato navega automáticamente y expande la configuración de formato específica del elemento seleccionado. Como parte del formato en el objeto, el servicio de subselección se usa para enviar subselecciones y esquemas a Power BI.
Uso de la API de subselección
El servicio de subselección proporciona dos métodos:
subSelect
Envía la subselección para que Power BI la use cuando un usuario seleccione un elemento que permite las subselecciones.
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;
}
Este método tiene los siguientes parámetros:
- customVisualObjects: una matriz que contiene
customVisualObjects, el objectName del objeto debe ser el mismo que el declarado en el capabilities.json y el selectionId para el punto de datos seleccionado, si existe. - displayName: el nombre para mostrar debe localizarse si el objeto visual admite la localización.
- subSelectionType: el tipo de la subselección (forma, texto o texto numérico).
- selectionOrigin: las coordenadas del elemento subseleccionado.
- showUI: indica si se va a mostrar la interfaz de usuario para esta subselección, como el formato de menús contextuales y la barra de herramientas.
- immediateDirectEdit: si se debe desencadenar la edición directa inmediata, el identificador del esquema de la subselección que se va a editar.
Si no usa HTMLSubSelectionHelper, debe administrar las subselecciones.
Ejemplo de subselección
En este ejemplo, agregamos un agente de escucha de eventos al elemento host para los eventos del menú contextual y del clic derecho.
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
Este método envía esquemas a Power BI para representar. Úselo en el método update del objeto visual, ya que es donde Power BI envía la subselección que el objeto visual envió anteriormente. También puede usarlo cuando quiera representar un esquema para un elemento desplazado.
updateRegionOutlines(outlines: visuals.SubSelectionRegionOutline[]): void
SubSelectionRegionOutline
interface SubSelectionRegionOutline {
id: string;
visibility: SubSelectionOutlineVisibility; // controls visibility for outlines
outline: SubSelectionOutline;
}
Si no usa el HTMLSubSelectionHelper, debe administrar manualmente los esquemas y su estado (si están activos, se mantiene el puntero o no visibles).
Ejemplo de esquemas de la región de actualización
En este ejemplo se supone que tenemos un objeto denominado myObject y queremos representar un esquema de rectángulo cuando se mantiene el puntero sobre el elemento correspondiente. Usamos el código del ejemplo anterior para la subselección.
En la actualización, también es necesario agregar un agente de escucha de eventos para el evento pointerover.
Queremos administrar nuestros esquemas mediante un registro.
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);
}