Compartilhar via

Utilitários no objeto – auxiliar de subseleção (versão prévia)

O HTMLSubSelectionHelper fornece uma maneira fácil para seu visual personalizado do Power BI emitir subseleções para o Power BI, obter e renderizar estruturas de tópicos.

HTMLSubSelectionHelper é uma classe auxiliar destinada a facilitar a criação e o gerenciamento subsequente de estruturas de tópicos de subseleção. Ele contém métodos para localizar elementos subelecionáveis.

Os utilitários exportam classes CSS e atributos facilitando a definição e manutenção de subseleções do visual.

Observação

Use a versão 6.0.1 ou superior dos utilitários.

Para definir elementos subelecionáveis, também precisamos adicionar uma classe a cada elemento desejado.

Classe CSS Finalidade Obrigatório
subselecionável Fornece um seletor para que HTMLSubSelectionHelper localize possíveis subseleções sim

Para definir as subseleções para o visual, há alguns atributos que precisam ser adicionados aos elementos desejados.

Nome do atributo Atributo Finalidade Obrigatório Tipo Exemplo
SubSelectableDisplayNameAttribute data-sub-selection-display-name Fornecer uma cadeia de caracteres localizada para o nome de exibição do elemento subselecionado sim string data-sub-selection-display-name="Visual Title"
SubSelectableObjectNameAttribute data-sub-selection-object-name Fornecer um nome de objeto para associar a atalhos de subseleção e estilo sim string data-sub-selection-object-name="title"
SubSelectableTypeAttribute data-sub-selection-type Fornecer o tipo do estilo subselecionado sim SubSelectionStylesType data-sub-selection-type="1"
SubSelectableDirectEdit data-sub-selection-direct-edit Fornecer referências de edição de texto direto, incluindo CardUID, GroupUID e a orientação da caixa de texto não SubSelectableDirectEdit deve ser fornecido como uma cadeia de caracteres data-sub-selection-direct-edit="{"reference":{"cardUid":"Visual-title","groupUid":"title-text","sliceUid":"title-text-text"},"style":0}"
SubSelectableHideOutlineAttribute data-sub-selection-hide-outline Fornecer um valor booliano para elementos subelecionáveis que não devem ter uma estrutura de tópicos mostrada não boolean data-sub-selection-hide-outline="true"
SubSelectableRestrictingElementAttribute data-sub-selection-restricting-element Usado para indicar o elemento que será restrito, as estruturas de tópicos e o tipo de restrição (grampo ou clipe) não SubSelectionOutlineRestrictionType data-sub-selection-restricting-element="1"
SubSelectableSubSelectedAttribute data-sub-selection-sub-selected Indicar se o subselecionável está selecionado ou não Não, o auxiliar o atribui aos elementos quando necessário Booliano data-subselection-sub-selected="true"

Modo de formato

Quando o visual entra no modo de formato, você precisa desabilitar a interatividade para o visual, pois esperamos que o usuário selecione o elemento visual e visual para iniciar a formatação.

Métodos públicos HTMLSubSelectionHelper

O HTMLSubSelectionHelper tem alguns métodos públicos que você pode usar, mas há dois métodos principais e o auxiliar faz o restante.

Os dois métodos são setFormatMode e updateOutlinesFromSubSelections.

Os métodos públicos do auxiliar incluem:

  • createHtmlSubselectionHelper(args: HtmlSubselectionHelperArgs): HtmlSubSelectionHelper – este é um método estático que usa args do tipo HtmlSubselectionHelperArgs e retorna uma instância de HTMLSubSelectionHelper.

  • setFormatMode(isFormatMode: boolean): void - Esse método define o modo de formato para o HTMLSubSelectionHelper, se isFormatMode for true, o auxiliar anexará ouvintes de eventos relevantes ao elemento host para habilitar a funcionalidade do modo de formato (subeleção, estruturas de tópicos de renderização).

  • getSubSelectionSourceFromEvent(event: PointerEvent): HtmlSubSelectionSource ou undefined – retorna um objeto HtmlSubSelectionSource criado de acordo com o parâmetro de evento.

  • onVisualScroll(): void - Indica ao HTMLSubSelectionHelper que a rolagem está ocorrendo no momento. A rolagem deve remover os contornos até que a rolagem seja concluída.

  • updateElementOutlines(elements: HTMLElement[], visibility: SubSelectionOutlineVisibility, suppressRender: boolean = false): SubSelectionRegionOutlineId[] – atualize as estruturas de tópicos (e emite-as para o Power BI a ser renderizado) dos elementos.

  • clearHoveredOutline(): void - Esse método limpa os contornos focalizados se eles existirem.

  • updateRegionOutlines(regionOutlines: HelperSubSelectionRegionOutline[], suppressRender: boolean = false): void - update and emits the given outlines to get rendered.

  • getElementsFromSubSelections(subSelections: CustomVisualSubSelection[]): HTMLElement[] – determinadas subSeleções, esse método retorna os HTMLElements relevantes.

  • updateOutlinesFromSubSelections(subSelections: CustomVisualSubSelection[], clearExistingOutlines?: boolean, suppressRender?: booleano): void - atualiza e renderiza os contornos da subSeleção fornecida em relação a suppressRender e clearExistingOutlines.

  • hideAllOutlines(suppressRender: boolean = false): void - oculta todas as estruturas de tópicos em relação ao suppressRender.

  • getAllSubSelectables(filterType?: SubSelectionStylesType): CustomVisualSubSelection[] – retorna todos os subSelecionáveis de acordo com o filterType.

  • createVisualSubSelectionForSingleObject(createVisualSubSelectionArgs: CreateVisualSubSelectionFromObjectArgs): CustomVisualSubSelection - cria o objeto CustomVisualSubSelection a partir do createVisualSubSelectionArgs.

  • setDataForElement(el: HTMLElement | SVGElement, data: SubSelectionElementData): void - um método estático que define dados para os elementos.

  • getDataForElement(el: HTMLElement | SVGElement): SubSelectionElementData - um método estático que obtém o associado atribuído anteriormente usando setDataForElement.

HtmlSubselectionHelperArgs

interface HtmlSubselectionHelperArgs {
    /** Element which contains the items that can be sub-selected */
    hostElement: HTMLElement; // The host element, the helper will attach the listeners to this element
    subSelectionService: powerbi.extensibility.IVisualSubSelectionService;// subSelectionService which is provided in powerbi-visuals-api
    selectionIdCallback?: ((e: HTMLElement) => ISelectionId);// a callback that gets the selectionId for the specific element
    customOutlineCallback?: ((subSelection: CustomVisualSubSelection) => SubSelectionRegionOutlineFragment[]);// a callback to get custom outline for the specific subSelection
    customElementCallback?: ((subSelection: CustomVisualSubSelection) => HTMLElement[]);
    subSelectionMetadataCallback?: ((subSelectionElement: HTMLElement) => unknown);// a callback to attatch any meta data to the subSelection.
}

SubSelectionStylesType

const enum SubSelectionStylesType {
            None = 0,
            Text = 1,
            NumericText = 2,
            Shape = 3,
}

SubSelectableDirectEdit

interface SubSelectableDirectEdit {
            reference: SliceFormattingModelReference;
            style: SubSelectableDirectEditStyle;
            displayValue?: string;
}

SubSelectionOutlineRestrictionType

const enum SubSelectionOutlineRestrictionType {
            /**
             * A clamping element will adjust the outline to prevent it from extending beyond
             * the restricting element.
             */
            Clamp,
            /**
             * A clipping element will make parts of the outline not visible if the outline extends beyond the
             * restricting element's bounds. 
             */
            Clip
        }

Para adicionar opções de restrição a um elemento específico, use o HTMLSubSelectionHelper setDataForElement com esse tipo de dados, o auxiliar usa os dados para atualizar os contornos:

interface SubSelectionElementData {
    outlineRestrictionOptions?: SubSelectionOutlineRestrictionOptions;
}

/** Options used to indicate if a restricting element should allow outlines more space to
  * generate by adding padding or if the restricting element should constrict the outline more
  * by adding a margin.
  */
export interface SubSelectionOutlineRestrictionOptions {
        padding?: IOffset;
        margin?: IOffset;
  }

Exemplo

Neste exemplo, implementamos customOutlineCallback e selectionIdCallback: o código a seguir está no Visual Code. Temos um objeto no visual chamado arcElement. Queremos renderizar a estrutura de tópicos quando o elemento estiver focalizado ou subselecionado.

import ISelectionId = powerbi.visuals.ISelectionId;

const enum BarChartObjectNames {
    ArcElement = 'arcElement',
    ColorSelector = 'colorSelector',
    …..
}

private ArcOutlines(subSelection: CustomVisualSubSelection): powerbi.visuals.SubSelectionRegionOutlineFragment[] {
        const outlines: powerbi.visuals.SubSelectionRegionOutlineFragment[] = []
        if (subSelection?.customVisualObjects[0].objectName === BarChartObjectNames.ArcElement) {
            const outline: powerbi.visuals.ArcSubSelectionOutline = {
                type: powerbi.visuals.SubSelectionOutlineType.Arc,
                center: { x: this.arcCenterX, y: this.arcCenterY },
                startAngle: this.arcStartAngle,
                endAngle: this.arcEndAngle,
                innerRadius: this.arcInnerRadius,
                outerRadius: this.arcOuterRadius
            };
            outlines.push({
                id: BarChartObjectNames.ArcElement,
                outline
            });
            return outlines;
        }
    }

public selectionIdCallback(e: Element): ISelectionId {
        const elementType: string = d3.select(e).attr(SubSelectableObjectNameAttribute);
        switch (elementType) {
            case BarChartObjectNames.ColorSelector:
                const datum = d3.select<Element, BarChartDataPoint>(e).datum();
                return datum.selectionId;
            default:
                return undefined;
        }
    }

Importe o HtmlSubSelectionHelper:

import { HtmlSubSelectionHelper } from 'powerbi-visuals-utils-onobjectutils';

No código do construtor, crie o HTMLSubSelectionHelper:

constructor(options: VisualConstructorOptions) {
    …….
    this.subSelectionHelper = HtmlSubSelectionHelper.createHtmlSubselectionHelper({
                hostElement: options.element,
                subSelectionService: options.host.subSelectionService,
                selectionIdCallback: (e) => this.selectionIdCallback(e),
                customOutlineCallback: (e) => this.ArcOutlines(e),
            });
    ….
}

No método de atualização do visual, adicione o código a seguir para atualizar os contornos da subSeseleção, atualize o estado do modo de formato para HTMLSubSelectionHelper e desabilite as interações que não são para o modo de formato se o modo de formato estiver ativado:

public update(options: VisualUpdateOptions) {
 …
 
 if (this.formatMode) {// disabling interaction with the visual data in format mode
             barSelectionMerged.on('click', null);
             this.svg.on('click', null);
             this.svg.on('contextmenu', null);
         } else {
             this.handleBarClick(barSelectionMerged);
             this.handleClick(barSelectionMerged);
             this.handleContextMenu();
         }
         this.subSelectionHelper.setFormatMode(options.formatMode);
         const shouldUpdateSubSelection = options.type & powerbi.VisualUpdateType.Data
             || options.type & powerbi.VisualUpdateType.Resize
             || options.type & powerbi.VisualUpdateType.FormattingSubSelectionChange;
         if (this.formatMode && shouldUpdateSubSelection) {
             this.subSelectionHelper.updateOutlinesFromSubSelections(options.subSelections, true);
         }
 …
}

Conteúdo relacionado

  • Last updated on