다음을 통해 공유

개체 유틸리티 - 하위 선택 도우미(미리 보기)

  • 아티클

이 HTMLSubSelectionHelper는 Power BI 사용자 지정 시각적 개체가 하위 선택을 Power BI로 내보내고 윤곽선을 가져오고 렌더링하는 쉬운 방법을 제공합니다.

HTMLSubSelectionHelper는 하위 선택 윤곽선의 생성 및 후속 관리를 용이하게 하는 도우미 클래스입니다. 여기에는 하위 선택 가능 요소를 찾는 메서드가 포함되어 있습니다.

유틸리티는 CSS 클래스와 특성을 내보내 시각적 개체가 하위 선택을 더 쉽게 정의하고 유지 관리할 수 있도록 합니다.

참고 항목

유틸리티 버전 6.0.1 이상을 사용합니다.

하위 선택 가능 요소를 정의하려면 원하는 각 요소에 클래스를 추가해야 합니다.

CSS 클래스 목적 Required
subselectable 하위 선택 가능 요소를 찾기 위해 HTMLSubSelectionHelper에 선택기 제공 예

시각적 개체에 대한 하위 선택을 정의하기 위해 원하는 요소에 추가해야 하는 몇 가지 특성이 있습니다.

특성 이름 특성 목적 필수 Type 예시
SubSelectableDisplayNameAttribute data-sub-selection-display-name 하위 선택 요소의 표시 이름에 지역화된 문자열 제공 예 string data-sub-selection-display-name="Visual Title"
SubSelectableObjectNameAttribute data-sub-selection-object-name 하위 선택 바로 가기 및 스타일과 연결할 개체 이름 제공 예 string data-sub-selection-object-name="title"
SubSelectableTypeAttribute data-sub-selection-type 하위 선택 스타일의 형식 제공 예 SubSelectionStylesType data-sub-selection-type="1"
SubSelectableDirectEdit data-sub-selection-direct-edit CardUID, GroupUID 및 텍스트 상자의 방향을 포함하여 직접 텍스트 편집 참조 제공 아니요 SubSelectableDirectEdit를 문자열로 제공해야 함 data-sub-selection-direct-edit="{"reference":{"cardUid":"Visual-title","groupUid":"title-text","sliceUid":"title-text-text"},"style":0}"
SubSelectableHideOutlineAttribute data-sub-selection-hide-outline 윤곽선이 표시되지 않아야 하는 하위 선택 가능 요소에 대한 부울 값 제공 아니요 부울 값 data-sub-selection-hide-outline="true"
SubSelectableRestrictingElementAttribute data-sub-selection-restricting-element 제한되는 요소, 윤곽선 및 제한 유형(클램프 또는 클립)을 나타내는 데 사용 아니요 SubSelectionOutlineRestrictionType data-sub-selection-restricting-element="1"
SubSelectableSubSelectedAttribute data-sub-selection-sub-selected 하위 선택 가능 항목이 선택되었는지 여부 표시 아니요, 필요한 경우 도우미가 이를 요소에 할당합니다. Boolean data-subselection-sub-selected="true"

서식 모드

시각적 개체가 서식 모드로 전환되면 사용자가 서식을 시작할 시각적 개체와 시각적 요소를 선택해야 하므로 시각적 개체에 대한 대화형 작업을 비활성화해야 합니다.

HTMLSubSelectionHelper public methods

HTMLSubSelectionHelper에는 사용자가 사용할 수 있는 몇 가지 공용 메서드가 있지만, 주요 메서드는 두 가지이며 도우미가 나머지를 수행합니다.

두 메서드는 setFormatMode 및 updateOutlinesFromSubSelections입니다.

도우미의 공용 메서드는 다음과 같습니다.

  • createHtmlSubselectionHelper(args: HtmlSubselectionHelperArgs): HtmlSubSelectionHelper - HtmlSubselectionHelperArgs 형식의 인수를 사용하고 HTMLSubSelectionHelper 인스턴스를 반환하는 정적 메서드입니다.

  • setFormatMode(isFormatMode: boolean): void - 이 메서드는 HTMLSubSelectionHelper에 대한 서식 모드를 설정합니다. isFormatMode가 true이면 도우미는 관련 이벤트 수신기를 호스트 요소에 연결하여 서식 모드 기능(하위 선택, 윤곽선 렌더링)을 활성화합니다.

  • getSubSelectionSourceFromEvent(event: PointerEvent): HtmlSubSelectionSource 또는 undefined - 이벤트 매개변수에 따라 빌드된 HtmlSubSelectionSource 개체를 반환합니다.

  • onVisualScroll(): void - 현재 스크롤하고 있음을 HTMLSubSelectionHelper에 나타냅니다. 스크롤은 스크롤이 완료될 때까지 윤곽선을 제거해야 합니다.

  • updateElementOutlines(elements: HTMLElement[], visibility: SubSelectionOutlineVisibility, suppressRender: boolean = false): SubSelectionRegionOutlineId[] - 요소의 윤곽선을 업데이트하고, 렌더링할 Power BI로 내보냅니다.

  • clearHoveredOutline(): void - 이 메서드는 마우스로 가리킨 윤곽선이 있는 경우 이를 지웁니다.

  • updateRegionOutlines(regionOutlines: HelperSubSelectionRegionOutline[], suppressRender: boolean = false): void - 렌더링하도록 지정된 윤곽선을 업데이트하고 내보냅니다.

  • getElementsFromSubSelections(subSelections: CustomVisualSubSelection[]): HTMLElement[] - subSelections가 주어지면 이 메소드는 관련 HTMLElements를 반환합니다.

  • updateOutlinesFromSubSelections(subSelections: CustomVisualSubSelection[], clearExistingOutlines?: boolean, suppressRender?: boolean): void - suppressRender 및 clearExistingOutlines와 관련하여 지정된 subSelection의 윤곽선을 업데이트하고 렌더링합니다.

  • hideAllOutlines(suppressRender: boolean = false): void - suppressRender와 관련된 모든 윤곽선을 숨깁니다.

  • getAllSubSelectables(filterType?: SubSelectionStylesType): CustomVisualSubSelection[] - filterType에 따라 모든 subSelectables를 반환합니다.

  • createVisualSubSelectionForSingleObject(createVisualSubSelectionArgs: CreateVisualSubSelectionFromObjectArgs): CustomVisualSubSelection - createVisualSubSelectionArgs에서 CustomVisualSubSelection 개체를 만듭니다.

  • setDataForElement(el: HTMLElement | SVGElement, data: SubSelectionElementData): void - 요소에 대한 데이터를 설정하는 정적 메서드입니다.

  • getDataForElement(el: HTMLElement | SVGElement): SubSelectionElementData - 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
        }

특정 요소에 제한 옵션을 추가하려면 이 데이터 형식의 HTMLSubSelectionHelper setDataForElement를 사용하면 도우미가 데이터를 사용하여 윤곽선을 업데이트합니다.

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

예시

이 예에서는 customOutlineCallback 및 selectionIdCallback을 구현합니다. 다음 코드는 Visual Code에 있습니다. 시각적 개체에 arcElement라는 개체가 있습니다. 요소를 마우스로 가리키거나 하위 선택할 때 윤곽선을 렌더링하려고 합니다.

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

HtmlSubSelectionHelper를 가져옵니다.

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

생성자 코드에서 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),
            });
    ….
}

시각적 개체의 업데이트 메서드에서 다음 코드를 추가하여 subSeselection의 윤곽선을 업데이트하고, HTMLSubSelectionHelper에 대한 서식 모드의 상태를 업데이트하고, 서식 모드가 활성화되어 있을 때 서식 모드가 아닌 상호 작용을 비활성화합니다.

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

관련 콘텐츠