子选择 API（预览）
对象上格式化允许用户通过直接选择要修改的元素来快速轻松地修改视觉对象的格式。 选择元素后，格式窗格会自动导航并展开选定元素的特定格式设置。 作为对象上格式化的一部分，子选择服务用于将子选择和轮廓发送到 Power BI。
如何使用子选择 API
SubSelection 服务提供两种方法：
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的数组，对象的 objectName 应与 capabilities.json 中所声明的 objectName 及所选数据点的 selectionId（如果存在）相同。 - displayName：如果视觉对象支持本地化，则应将显示名称本地化。
- subSelectionType：子选择的类型（形状、文本或数值文本）。
- selectionOrigin：子选择元素的坐标。
- showUI：是否显示此子选择的 UI，如格式化上下文菜单和工具栏。
- immediateDirectEdit：如果应触发立即直接编辑，则显示要编辑的子选择轮廓的 ID。
如果不使用 HTMLSubSelectionHelper，则需要管理子选择。
子选择示例
在本例中，我们为右键单击上下文菜单事件向 host 元素添加事件侦听器。
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 进行呈现。 在视觉对象的 update 方法中使用它，因为 Power BI 在该处发送视觉对象之前发送的子选择。 想要呈现悬停元素的轮廓时，也可以使用它。
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);
}