Partilhar via

Utils no objeto - auxiliar de subseleção (visualização)

  • Artigo

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

HTMLSubSelectionHelper é uma classe auxiliar destinada a facilitar a criação e subsequente gestão de esboços de subseleção. Ele contém métodos para encontrar elementos subselecionáveis.

O utils exporta classes e atributos CSS, tornando mais fácil para o visual definir e manter subseleções.

Nota

Use a versão 6.0.1 ou superior dos utils.

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

Classe CSS Propósito Necessário
subselecionável Fornece um seletor para o HTMLSubSelectionHelper para encontrar possíveis subseleções sim

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

Nome do Atributo Atributo Propósito Necessá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="Título visual"
SubSelectableObjectNameAttribute data-sub-selection-object-name Fornecer um nome de objeto para associar a atalhos e estilo de subseleção sim string data-sub-selection-object-name="título"
SubSelectableTypeAttribute tipo de subseleção de dados Forneça o tipo do estilo subselecionado sim SubSelectionStylesType data-sub-selection-type="1"
SubSelecionávelDirectEdit data-sub-selection-direct-edit Forneça 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 dados-sub-seleção-ocultar-contorno Fornecer um valor booleano para elementos subselecionáveis que não devem ter um contorno mostrado não boolean data-sub-selection-hide-outline="verdadeiro"
SubSelectableRestrictingElementAttribute data-sub-selection-restricting-element Usado para indicar o elemento que será restrito, os contornos e o tipo de restrição (grampo ou clipe) não SubSelectionOutlineRestrictionType data-sub-selection-restricting-element="1"
SubSelectableSubSelectedAttribute dados-sub-seleção-sub-selecionados Indicar se o subselecionável está selecionado ou não Não, o ajudante atribui-o aos elementos quando necessário Boolean data-subselection-sub-selected="verdadeiro"

Modo de formato

Quando o visual entra no modo de formato, é necessário desativar 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 existem dois métodos principais e o ajudante faz o resto.

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

Os métodos públicos do ajudante 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 - Este 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 (subseleção, contornos de renderização).

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

  • 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[] - atualiza os contornos (e os emite para o Power BI a serem renderizados) dos elementos.

  • clearHoveredOutline(): void - Este método limpa contornos pairados se eles existirem.

  • updateRegionOutlines(regionOutlines: HelperSubSelectionRegionOutline[], suppressRender: boolean = false): void - update e emite os contornos fornecidos para ser renderizado.

  • getElementsFromSubSelections(subSelections: CustomVisualSubSelection[]): HTMLElement[] - dado subSelections, este método retorna os HTMLElements relevantes.

  • updateOutlinesFromSubSelections(subSelections: CustomVisualSubSelection[], clearExistingOutlines?: boolean, suppressRender?: boolean): void - atualiza e renderiza os contornos para a subSelection dada com relação a suppressRender e clearExistingOutlines.

  • hideAllOutlines(suppressRender: boolean = false): void - oculte todos os contornos em relação a suppressRender.

  • getAllSubSelectables(filterType?: SubSelectionStylesType): CustomVisualSubSelection[] - retorna todos os subSelectables de acordo com o filterType.

  • createVisualSubSelectionForSingleObject(createVisualSubSelectionArgs: CreateVisualSubSelectionFromObjectArgs): CustomVisualSubSelection - crie 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,
}

SubSelecionávelDirectEdit

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 este 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 pairado 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 seguinte código para atualizar os contornos da subSeselection, atualize o estado do modo de formato para o e desative as interações que não são para o modo de formato se o HTMLSubSelectionHelper 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údos relacionados