Subselection API(미리 보기)
개체 기반 서식 지정을 사용하면 사용자가 수정하려는 요소를 직접 선택하여 시각적 개체 서식을 빠르고 쉽게 수정할 수 있습니다. 요소를 선택하면 서식 창에서 선택한 요소에 대한 특정 서식 설정을 자동으로 탐색하고 확장합니다. 개체 서식 지정의 일부로 Subselection 서비스는 Subselection 및 개요를 Power BI에 보내는 데 사용됩니다.
Subselection API를 사용하는 방법
SubSelection 서비스는 다음 두 가지 메서드를 제공합니다.
subSelect
사용자가 Subselection을 허용하는 요소를 선택할 때 사용할 Power BI의 Subselection을 보냅니다.
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(을)를 포함하는 배열입니다. 개체의 objectName은 capabilities.json에서 선언된 것과 동일해야 하며 선택한 데이터 요소에 대한 selectionId(있는 경우)입니다. - displayName: 시각적 개체가 지역화를 지원하는 경우 표시 이름을 지역화해야 합니다.
- subSelectionType: Subselection(도형, 텍스트 또는 숫자 텍스트)의 형식입니다.
- selectionOrigin: Subselection 요소의 좌표입니다.
- showUI: 상황에 맞는 메뉴 및 도구 모음 서식 지정과 같이 이 Subselection에서 UI를 표시할지 여부입니다.
- immediateDirectEdit: 바로 직접 편집을 트리거해야 하는 경우 편집할 subselection 개요의 ID입니다.
HTMLSubSelectionHelper(을)를 사용하지 않는 경우 subselection을 관리해야 합니다.
Subselection 예제
이 예제에서는 마우스 오른쪽 단추로 클릭하는 상황에 맞는 메뉴 이벤트에 대한 이벤트 수신기를 호스트 요소에 추가합니다.
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는 시각적 개체가 이전에 보낸 subselection을 전송하기 때문에 시각적 개체의 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);
}