视觉对象 API

所有视觉对象都以实现 IVisual 接口的类开头。 只要有一个实现 IVisual 接口的类，你就可以按需命名这个类。

备注

视觉对象类名称必须与 pbiviz.json 文件中的 visualClassName 相同。

视觉对象类应实现以下方法，如以下示例所示：

• constructor，一个初始化视觉对象状态的标准构造函数

• update，用于更新视觉对象的数据

• getFormattingModel，返回填充属性窗格（格式设置选项）的格式设置模型，可根据需要在窗格中修改这些属性

• destroy，一个用于清理的标准析构函数

TypeScript复制

class MyVisual implements IVisual {    
    constructor(options: VisualConstructorOptions) {        //one time setup code goes here (called once)
    }    
    public update(options: VisualUpdateOptions): void {        //code to update your visual goes here (called on all view or data changes)
    }    public getFormattingModel(): FormattingModel {        // returns modern format pane formatting model that contain all format pane components and properties (called on opening format and analytics pane or on editing format properties)
    }    
    public destroy(): void {        //one time cleanup code goes here (called once)
    }
}

构造函数

在实例化视觉对象时，将调用视觉对象类的 constructor。 它可用于视觉对象所需的任何设置操作。

TypeScript复制

constructor(options: VisualConstructorOptions)

VisualConstructorOptions

• element: HTMLElement，对将包含视觉对象的 DOM 元素的引用

• host: IVisualHost，可用于与视觉对象主机 (Power BI) 进行交互的属性和服务的集合

  IVisualHost 包含以下服务：

• createSelectionIdBuilder，生成并存储视觉对象中可选项目的元数据

• createSelectionManager，创建用于在选择状态更改时通知视觉对象主机的通信桥，具体请参阅选择 API。

• createLocalizationManager，生成一个管理器来帮助进行本地化

• allowInteractions: boolean，一个布尔标志，用于确定视觉对象是否是交互式的

• applyJsonFilter，应用特定的筛选器类型，请参阅筛选器 API

• persistProperties，允许用户创建持久设置并将其与视觉对象定义一起保存，使其在下次重载时可用

• eventService，返回一个事件服务来支持 Render 事件

• storageService，返回一个服务，以帮助在视觉对象中使用本地存储

• authenticationService，生成一个服务以帮助用户进行身份验证

• tooltipService，返回一个工具提示服务，以帮助在视觉对象中使用工具提示

• launchUrl，帮助在下一个选项卡中启动 URL

• locale，返回一个区域设置字符串，请参阅本地化

• instanceId，返回一个字符串来识别当前的视觉对象实例

• colorPalette，返回为数据应用颜色所需的 colorPalette

• fetchMoreData，支持使用超过标准限制（1000 行）的数据，请参阅提取更多数据

• switchFocusModeState，帮助更改焦点模式状态

  TypeScript复制

  export interface IVisualHost extends extensibility.IVisualHost {
       createSelectionIdBuilder: () => visuals.ISelectionIdBuilder;
       : () => ISelectionManager;
       colorPalette: ISandboxExtendedColorPalette;
       persistProperties: (changes: VisualObjectInstancesToPersist) => void;
       applyJsonFilter: (filter: IFilter[] | IFilter, objectName: string, propertyName: string, action: FilterAction) => void;
       tooltipService: ITooltipService;
       telemetry: ITelemetryService;
       authenticationService: IAuthenticationService;
       locale: string;
       allowInteractions: boolean;
       launchUrl: (url: string) => void;
       fetchMoreData: () => boolean;
       instanceId: string;
       refreshHostData: () => void;
       createLocalizationManager: () => ILocalizationManager;
       storageService: ILocalVisualStorageService;
       eventService: IVisualEventService;
       switchFocusModeState: (on: boolean) => void;
  }
  

update

所有视觉对象都必须实现一个公共更新方法，每当数据或主机环境发生变化时，就会调用该方法。

TypeScript复制

public update(options: VisualUpdateOptions): void

VisualUpdateOptions

• viewport: IViewport，应在其中呈现视觉对象的视区的尺寸

• dataViews: DataView[]，它是包含呈现视觉对象所需的所有数据的数据视图对象（视觉对象通常使用 DataView 下的分类属性）

• type: VisualUpdateType，它是用于指示要更新的数据类型 (Data | Resize | ViewMode | Style | ResizeEnd) 的标志

• viewMode: ViewMode，它是用于指示视觉对象的视图模式 (View | Edit | InFocusEdit) 的标志

• editMode: EditMode，它是用于指示视觉对象的编辑模式（“默认” | “高级”）的标志（如果视觉对象支持 AdvancedEditMode，则它应仅在“editMode”设置为“高级”时，呈现其高级 UI 控件，请参阅 AdvancedEditMode）

• operationKind?: VisualDataChangeOperationKind，它是用于指示数据更改类型（“创建” | “追加”）的标志

• jsonFilters?: IFilter[]，应用 json 筛选器的集合

• isInFocus?: boolean，指示视觉对象是否处于焦点模式的标志

getFormattingModel（可选）

每次打开属性窗格或用户编辑窗格中的任何属性时，都会调用此方法。 它返回 FormattingModel，其中包含关于属性窗格设计、层次结构、属性和最新格式值的所有信息。

TypeScript复制

getFormattingModel(): visuals.FormattingModel;

destroy（可选）

卸载视觉对象时，将调用销毁函数，该函数可用于清理任务，例如删除事件侦听器。

TypeScript复制

public destroy(): void

提示

Power BI 通常不调用 destroy，因为删除包含视觉对象的整个 IFrame 更快。