对象上 utils - 子选择帮助程序（预览版）

HTMLSubSelectionHelper 为 Power BI 自定义视觉对象提供了一种简便的方法，可用于向 Power BI 发送子选择、获取和呈现轮廓。

HTMLSubSelectionHelper 是一个帮助程序类，用于帮助创建和后续管理子选择轮廓。 它包含用于查找可子选择元素的方法。

utils 导出 CSS 类和属性，使视觉对象更容易定义和维护子选择。

注意

使用 utils 版本 6.0.1 或更高版本。

若要定义可子选择的元素，还需要向每个所需元素添加一个类。

CSS	用途	必须
可子选择	为 HTMLSubSelectionHelper 提供选择器以查找可能的子选择	是

若要为视觉对象定义子选择，需要向所需元素添加一些属性。

属性名称	Attribute	用途	必须	类型	示例
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	为不应显示轮廓的可子选择元素提供布尔值	否	boolean	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	指示是否选择了可子选择项	否，帮助程序在需要时将其分配给元素	布尔	data-subselection-sub-selected="true"

格式模式

当视觉对象进入格式模式时，需要禁用视觉对象的交互性，因为我们希望用户选择视觉对象和视觉对象元素来启动格式设置。

HTMLSubSelectionHelper 公共方法

可以使用 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 返回所有可子选择对象。

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

若要向特定元素添加限制选项，HTMLSubSelectionHelpersetDataForElement请使用此数据类型，帮助程序使用数据来更新大纲：

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

在视觉对象的 update 方法中添加以下代码来更新 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);
         }
 …
}

相关内容

• 子选择 API
• 对象上格式设置 API