Partilhar via

API de subseleção (visualização)

  • Artigo

A formatação no objeto permite que os usuários modifiquem rápida e facilmente o formato dos elementos visuais, selecionando diretamente os elementos que desejam modificar. Quando um elemento é selecionado, o painel de formato navega automaticamente e expande a configuração de formatação específica para o elemento selecionado. Como parte da formatação no objeto, o serviço de subseleção é usado para enviar subseleções e contornos para o Power BI.

Como usar a API de subseleção

O Serviço de Subseleção fornece dois métodos:

subSelecionar

Envia a subseleção para o Power BI usar quando um usuário seleciona um elemento que permite subseleções.

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 tem os seguintes parâmetros:

  • customVisualObjects: uma matriz que contém customVisualObjects, o objectName do objeto deve ser o mesmo que o declarado no capabilities.json e o selectionId para o ponto de dados selecionado, se existir.
  • displayName: o nome para exibição deve ser localizado se o visual suportar a localização.
  • subSelectionType: o tipo da subseleção (forma, texto ou texto numérico).
  • selectionOrigin: as coordenadas do elemento subselecionado.
  • showUI: Se deseja mostrar a interface do usuário para essa subseleção, como formatar menus de contexto e barra de ferramentas.
  • immediateDirectEdit: Se a edição direta imediata deve ser acionada, a ID do contorno de subseleção a ser editado.

Se você não usar o HTMLSubSelectionHelper, precisará gerenciar as subseleções.

Exemplo de subseleção

Neste exemplo, adicionamos um ouvinte de eventos ao elemento host, para os eventos do menu de contexto do botão direito do mouse.

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

updateRegionEsboços

Esse método envia contornos para o Power BI para renderizar. Use-o no método do visual, pois é para lá que o update Power BI envia a subseleção que o visual enviou anteriormente. Você também pode usá-lo quando quiser renderizar uma estrutura de tópicos para um elemento pairado.

updateRegionOutlines(outlines: visuals.SubSelectionRegionOutline[]): void

SubSelectionRegionOutline
interface SubSelectionRegionOutline {
            id: string;
            visibility: SubSelectionOutlineVisibility; // controls visibility for outlines
            outline: SubSelectionOutline;
        }

Se você não usar o HTMLSubSelectionHelper, terá que gerenciar manualmente os contornos e seu estado (se eles estiverem ativos, pairados ou não visíveis).

Exemplo de contornos de região de atualização

Neste exemplo, assumimos que temos um objeto chamado myObject, e queremos renderizar um contorno de retângulo quando o elemento relevante estiver pairado. Usamos o código no exemplo anterior para subSelect.

Na atualização, também precisamos adicionar um ouvinte de eventos para o pointerover evento.

Queremos gerir os nossos esboços utilizando um Record.

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

Conteúdos relacionados