副選択 API (プレビュー)
オブジェクト上の書式設定では、ユーザーは変更する要素を直接選択することで、ビジュアルの形式をすばやく簡単に変更できます。 ある要素が選択されると、書式設定ウィンドウでは、その選択された要素の特定の書式設定が自動的に表示され、展開されます。 オブジェクト上の書式設定の一環として、副選択サービスが使用され、副選択と枠線が Power BI に送信されます。
副選択 API を使用する方法
副選択サービスからは、次の 2 つのメソッドが提供されます。
subSelect
副選択を許可する要素をユーザーが選択すると、Power BI で使用される副選択が送信されます。
subSelect(args: visuals.CustomVisualSubSelection | undefined): void
CustomVisualSubSelection
interface CustomVisualSubSelection {
customVisualObjects: CustomVisualObject[];
displayName: string;
subSelectionType: SubSelectionStylesType;
selectionOrigin: SubSelectionOrigin;
/** Whether to show the UI for this sub-selection, like formatting context menus and toolbar */
showUI: boolean;
/** If immediate direct edit should be triggered, the ID of the sub-selection outline to edit */
immediateDirectEdit?: string;
metadata?: unknown;
}
interface CustomVisualObject {
objectName: string;
selectionId: powerbi.visuals.ISelectionId | undefined;
}
このメソッドには次のパラメーターがあります。
- customVisualObjects:
customVisualObjects、capabilities.json で宣言されている名前と同じにする必要があるオブジェクトの objectName、存在する場合、選択されたデータの selectionId が含まれる配列。 - displayName: ビジュアルでローカライゼーションがサポートされている場合、表示名はローカライズする必要があります。
- subSelectionType: 副選択の型 (図形、テキスト、または数値テキスト)。
- selectionOrigin: 副選択された要素の座標。
- showUI: 書式設定のコンテキスト メニューやツール バーなど、この副選択に UI を表示するかどうか。
- immediateDirectEdit: 即時の直接編集をトリガーする必要がある場合、編集する副選択枠線の ID。
HTMLSubSelectionHelper を使用しない場合、副選択を管理する必要があります。
副選択の例
この例では、右クリックのコンテキスト メニュー イベントのために、ホスト要素にイベント リスナーを追加します。
constructor(options: VisualConstructorOptions) {
this.hostElement = options.element;
this.subSelectionService = options.host.subSelectionService;
….
}
public update(options: VisualUpdateOptions) {
if (options.formatMode) {
// remove event listeners which are irrelevant for format mode.
…
this.hostElement.addEventListener('click', this.handleFormatModeClick);
this.hostElement.addEventListener('contextmenu', this.handleFormatModeContextMenu);
} else {
this.hostElement.removeEventListener('click', this.handleFormatModeClick);
this.hostElement.removeEventListener('contextmenu', this.handleFormatModeContextMenu);
…
// add event listeners which are irrelevant for format mode
}
}
private handleFormatModeClick(event: MouseEvent): void {
this.subSelectFromEvent(event, true /**showUI */);
}
private handleFormatModeContextMenu(event: MouseEvent): void {
this.subSelectFromEvent(event, false);
}
private subSelectFromEvent(event: MouseEvent, showUI: boolean): void {
//find the element which was selected and fill the needed fields
const cVObject: powerbi.visuals.CustomVisualObject = {
objectName: 'myObject',//the object name that is relevant to the clicked element
selectionId: undefined
};
const subSelection: CustomVisualSubSelection = {
customVisualObjects: [cVObject],
displayName: 'myObject',
selectionOrigin: {
x: event.clientX,
y: event.clientY
},
subSelectionType: SubSelectionStylesType.Shape,// choose the relevant type
showUI
};
this.subSelectionService.subSelect(subSelection);
}
updateRegionOutlines
このメソッドでは、レンダリングのために枠線が Power BI に送信されます。 ビジュアルから前に送信された副選択が Power BI によって送信される場所であるため、ビジュアルの update メソッドでそれを使用します。 ホバーされた要素の枠線をレンダリングするときもそれを使用できます。
updateRegionOutlines(outlines: visuals.SubSelectionRegionOutline[]): void
SubSelectionRegionOutline
interface SubSelectionRegionOutline {
id: string;
visibility: SubSelectionOutlineVisibility; // controls visibility for outlines
outline: SubSelectionOutline;
}
HTMLSubSelectionHelper を使用しない場合、枠線とその状態 (アクティブ、ホバー、非表示の場合) は手動で管理する必要があります。
リージョン枠線例のアップデート
この例では、myObject というオブジェクトがあり、関連する要素がホバーされたとき、四角の枠線をレンダリングするものと想定しています。 前の例のコードを subSelect に使用します。
このアップデートでは、pointerover イベントのイベント リスナーを追加する必要もあります。
レコードを使用した枠線の管理を考えています。
private subSelectionRegionOutlines: Record<string, SubSelectionRegionOutline > = {};
public update(options: VisualUpdateOptions) {
if (options.formatMode) {
// remove event listeners which are irrelevant for format mode.
…
this.hostElement.addEventListener('click', this.handleFormatModeClick);
this.hostElement.addEventListener('contextmenu', this.handleFormatModeContextMenu);
this.hostElement.addEventListener('pointerover', this.handleFormatModePointerOver);
} else {
this.hostElement.removeEventListener('click', this.handleFormatModeClick);
this.hostElement.removeEventListener('contextmenu', this.handleFormatModeContextMenu);
this.hostElement.removeEventListener('pointerover', this.handleFormatModePointerOver);
…
// add event listeners which are irrelevant for format mode
}
}
private handleFormatModePointerOver(event: MouseEvent): void {
// use the event to extract the element that was hovered.
// in this example we assume that we found the element and it is related to object called myObject.
// we need to clear previously hovered outlines before rendering
const regionOutlines = getValues(this.subSelectionRegionOutlines);
const hoveredOutline = regionOutlines.find(outline => outline.visibility === SubSelectionOutlineVisibility.Hover);
if (hoveredOutline) {
this.subSelectionRegionOutlines[hoveredOutline.id] = {
...this.subSelectionRegionOutlines[hoveredOutline.id],
visibility: powerbi.visuals.SubSelectionOutlineVisibility.None
};
}
// now we will build the outline for myObject relevant element.
let element: HTMLElement;// assume we found the relevant element.
const domRect = element.getBoundingClientRect();
const { x, y, width, height } = domRect;
const outline: powerbi.visuals.RectangleSubSelectionOutline = {
height,
width,
x,
y,
type: powerbi.visuals.SubSelectionOutlineType.Rectangle,
};
const regionOutline: powerbi.visuals.SubSelectionRegionOutline = {
id: 'myObject',
visibility: powerbi.visuals.SubSelectionOutlineVisibility.Hover,
outline
};
this.subSelectionRegionOutlines[regionOutline.id] = regionOutline;
this.renderOutlines();
// you need to remove the hovered outline when the element is not hovered anymore
}
private renderOutlines(): void {
const regionOutlines = getValues(this.subSelectionRegionOutlines);
this.subSelectionService.updateRegionOutlines(regionOutlines);
}