オブジェクト上のユーティリティ - 副選択ヘルパー (プレビュー)

HTMLSubSelectionHelper を使うと、Power BI カスタム ビジュアルで簡単に Power BI に副選択を出力し、枠線を取得してレンダリングできます。

HTMLSubSelectionHelper は、副選択の枠線の作成とその後の管理を容易にすることを目的としたヘルパー クラスです。 これには、副選択可能な要素を見つけるためのメソッドが含まれています。

ユーティリティによって CSS クラスと属性がエクスポートされるので、視覚化で簡単に副選択を定義して管理できます。

副選択可能な要素を定義するには、必要な各要素にクラスを追加する必要もあります。

視覚化の副選択を定義するには、目的の要素にいくつかの属性を追加する必要があります。

書式モード

視覚化が書式モードになるときは、視覚化の対話機能を無効にする必要があります。ユーザーが視覚化および視覚化要素を選択して、書式設定を開始することが想定されるためです。

HTMLSubSelectionHelper のパブリック メソッド

HTMLSubSelectionHelper には使用できるパブリック メソッドがいくつかありますが、主要なメソッドは 2 つであり、残りの処理はヘルパーが行います。

その 2 つのメソッドは、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 を実装します。以下のコードはビジュアル コードのものです。 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