Compartilhar via

API de Subseleção (versão prévia)

A formatação no objeto permite que os usuários modifiquem o formato dos visuais com rapidez e facilidade selecionando diretamente os elementos que querem modificar. Quando um elemento é selecionado, o painel de formato navega e expande automaticamente 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 ao Power BI para ser usada 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;
        }

Esse método tem os seguintes parâmetros:

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

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

Exemplo de subseleção

Nesse exemplo, adicionamos um ouvinte de evento ao elemento host, para os eventos do menu de contexto acessados com o 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);
    }

updateRegionOutlines

Esse método envia contornos para o Power BI renderizar. Use-o no método update do visual, o local para onde o Power BI envia a subseleção que o visual enviou anteriormente. Você também pode usá-lo quando quiser renderizar um contorno para um elemento visualizado ao passar o mouse.

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

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

Se não usar o HTMLSubSelectionHelper, você precisará gerenciar manualmente os contornos e seu estado (se estão ativos, são visualizados ao passar o mouse ou não estão visíveis).

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

Nesse exemplo, supomos que temos um objeto chamado myObject e queremos renderizar um contorno de retângulo quando o mouse é passado sobre o elemento relevante. Usamos o código no exemplo anterior para subselecionar.

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

Queremos gerenciar nossos contornos usando um 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);
     }

Conteúdo relacionado

  • Last updated on