物件專屬公用程式 - 子選取項目協助程式 (預覽)

HTMLSubSelectionHelper 提供一個簡便的方式，讓您的 Power BI 自訂視覺效果將子選取項目發出至 Power BI、取得和轉譯外框。

HTMLSubSelectionHelper 是協助程式類別，旨在協助建立子選取項目外框和後續管理。它包含用於尋找可子選取元素的方法。

公用程式會匯出 CSS 類別和屬性，讓視覺效果更容易定義和維護子選取項目。

注意

使用版本 6.0.1 或更高版本的公用程式。

若要定義可子選取元素，我們也必須將類別新增至每個所需的元素。

CSS 類別	目的	必要
子選取項目	提供的選取器，讓 `HTMLSubSelectionHelper` 尋找可能的子選取項目	是

若要定義視覺效果的子選取項目，需要將幾個屬性新增至所需的元素。

屬性名稱	屬性	目的	必要	類型	範例
SubSelectableDisplayNameAttribute	data-sub-selection-display-name	提供當地語系化字串作為子選取元素的顯示名稱	是	字串	data-sub-selection-display-name="Visual Title"
SubSelectableObjectNameAttribute	data-sub-selection-object-name	提供物件名稱，以與子選取項目捷徑和樣式相關聯	是	字串	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	用來指出將限制的元素、外框和限制類型 (clamp 或 clip)	否	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[] - 給定的子選取項目，此方法會傳回相關的 HTMLElements。
updateOutlinesFromSubSelections(subSelections: CustomVisualSubSelection[], clearExistingOutlines?: boolean, suppressRender?: boolean): void - 更新並轉譯與 suppressRender 和 clearExistingOutlines 相關的給定子選取項目的外框。
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
        }

若要對特定元素新增限制選項，請使用 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),
            });
    ….
}

在視覺效果的 update 方法中，新增下列程式碼來更新子選取項目的外框，更新 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