Utils on-object — вспомогательный вспомогательный объект подселектора (предварительная версия)

Это HTMLSubSelectionHelper позволяет пользовательскому визуальному элементу Power BI выдавать вложенные выборы в Power BI, получать и отрисовывать контуры.

HTMLSubSelectionHelper — вспомогательный класс, предназначенный для упрощения создания и последующего управления структурами подселектора. Он содержит методы для поиска вложенных элементов.

Utils экспортирует классы и атрибуты CSS, что упрощает определение и обслуживание вложенных выборов визуального элемента.

Примечание.

Используйте версию 6.0.1 или более позднюю версию utils.

Чтобы определить вложенные элементы, необходимо также добавить класс к каждому нужному элементу.

Класс CSS	Характер использования	Обязательное поле
subselectable	Предоставляет селектор для `HTMLSubSelectionHelper` поиска возможных вложенных выборов	yes

Чтобы определить вложенные выборы для визуального элемента, существует несколько атрибутов, которые необходимо добавить в нужные элементы.

Имя атрибута	Атрибут	Характер использования	Обязательное поле	Тип	Пример
SubSelectableDisplayNameAttribute	имя объекта data-sub-selection-display-name	Укажите локализованную строку для отображаемого имени выбранного элемента.	yes	строка	data-sub-selection-display-name="Visual Title"
SubSelectableObjectNameAttribute	data-sub-selection-object-name	Укажите имя объекта для связывания с сочетаниями сочетаний клавиш и стилем вложенного выбора.	yes	строка	data-sub-selection-object-name="title"
SubSelectableTypeAttribute	тип выбора данных	Укажите тип выбранного вложенного стиля	yes	SubSelectionStylesType	data-sub-selection-type="1"
SubSelectableDirectEdit	data-sub-selection-direct-edit	Предоставление прямых ссылок на редактирование текста, включая CardUID, GroupUID и ориентацию текстового поля	no	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	Укажите логическое значение для вложенных элементов, которые не должны отображать структуру	no	boolean	data-sub-selection-hide-outline="true"
SubSelectableRestrictingElementAttribute	элемент data-sub-selection-restricting-element	Используется для указания элемента, который будет ограничен, контуров и типа ограничения (закрепления или клипа)	no	SubSelectionOutlineRestrictionType	data-sub-selection-restricting-element="1"
SubSelectableSubSelectedAttribute	выбран элемент data-sub-selection-sub-selected	Укажите, выбран ли вложенный выбор.	Нет, помощник назначает его элементам при необходимости.	Логический	data-subselection-sub-selected="true"

Режим форматирования

Когда визуальный элемент входит в режим форматирования, необходимо отключить интерактивность для визуального элемента, так как мы ожидаем, что пользователь выберет визуальный и визуальный элемент, чтобы инициировать форматирование.

Общедоступные методы HTMLSubSelectionHelper

В HTMLSubSelectionHelper нем есть некоторые общедоступные методы, которые можно использовать, но есть два основных метода, и вспомогательный выполняет остальные.

Два метода: setFormatMode и updateOutlinesFromSubSelections.

К общедоступным методам вспомогательного средства относятся следующие:

createHtmlSubselectionHelper(args: HtmlSubselectionHelperArgs): HtmlSubSelectionHelper — это статический метод, который принимает args типа HtmlSubselectionHelperArgs и возвращает экземпляр HTMLSubSelectionHelper.
setFormatMode(isFormatMode: boolean): void— этот метод задает режим формата для HTMLSubSelectionHelper, если isFormatMode имеет значение true, вспомогательный помощник присоединяет соответствующие прослушиватели событий к элементу узла, чтобы включить функциональные возможности режима форматирования (вложенные выборы, контуры отрисовки).
getSubSelectionSourceFromEvent(event: PointerEvent): HtmlSubSelectionSource или undefined — возвращает HtmlSubSelectionSource объект, созданный в соответствии с параметром события.
onVisualScroll(): void — указывает htmlSubSelectionHelper, что прокрутка в настоящее время происходит. Прокрутка должна удалять контуры до завершения прокрутки.
updateElementOutlines(elements: HTMLElement[], видимость: SubSelectionOutlineVisibility, suppressRender: boolean = false): SubSelectionRegionOutlineId[] — обновите контуры (и отправляет их в Power BI для отрисовки) элементов.
clearHoveredOutline(): void — этот метод очищает наведенные контуры, если они существуют.
updateRegionOutlines(regionOutlines: HelperSubSelectionRegionOutline[], suppressRender: boolean = false): void — обновление и выдает заданные контуры для отрисовки.
getElementsFromSubSelections(subSelections: CustomVisualSubSelection[]): HTMLElement[] — заданные вложенные элементы выбора, этот метод возвращает соответствующие элементы HTMLElements.
updateOutlinesFromSubSelections(subSelections: CustomVisualSubSelection[], clearExistingOutlines?: boolean, suppressRender?: boolean?: void — обновляет и отрисовывает контуры для заданного подселекция относительно подавления и очисткиExistingOutlines.
hideAllOutlines(suppressRender: boolean = false): void — скрытие всех контуров относительно подавленияRender.
getAllSubSelectables(filterType?: SubSelectionStylesType): CustomVisualSubSelection[] — возвращает все вложенные значения в соответствии с фильтром.
createVisualSubSelectionForSingleObject(createVisualSubSelectionArgs: CreateVisualSubSelectionFromObjectArgs): CustomVisualSubSelection — создание объекта CustomVisualSubSelection из объекта createVisualSubSelectionArgs.
setDataForElement(el: HTMLElement | SVGElement, данные: 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),
            });
    ….
}

В методе обновления визуального элемента добавьте следующий код, чтобы обновить контуры подсезелекции, обновите состояние режима форматирования и отключите взаимодействие, которое не предназначено для 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);
         }
 …
}

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2025-12-15