Share via

视觉对象 API

  • 项目

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

注意

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

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

  • constructor - 一个初始化视觉对象状态的标准构造函数
  • update - 用于更新视觉对象的数据
  • getFormattingModel，返回填充属性窗格（格式设置选项）的格式设置模型，可根据需要在窗格中修改这些属性
  • destroy - 一个用于清理的标准析构函数
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。 它可用于视觉对象所需的任何设置操作。

constructor(options: VisualConstructorOptions)

VisualConstructorOptions

这些接口使用每个新的 API 版本进行更新。 有关最新的接口格式，请转到 GitHub 存储库。

以下列表描述了 VisualConstructorOptions 接口的部分属性：

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

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

    IVisualHost 包含以下服务：

    • createSelectionIdBuilder - 生成并存储视觉对象中可选项目的元数据
    • createSelectionManager - 创建用于在选择状态更改时通知视觉对象主机的通信桥，具体请参阅选择 API。
    • hostCapabilities
    • refreshHostData
    • downloadService - 返回下载的扩展结果信息。
    • eventService - 返回有关呈现事件的信息。
    • hostEnv
    • displayWarningIcon - 返回错误或警告消息。
    • licenseManager - 返回许可证信息。
    • createLocalizationManager - 生成一个管理器来帮助进行本地化
    • applyJsonFilter - 应用特定的筛选器类型。 请参阅筛选器 API
    • applyCustomSort - 允许自定义排序选项。
    • acquireAADTokenService - 返回 Microsoft Entra ID 身份验证信息。
    • webAccessService - 返回访问远程资源的权限状态。
    • openModalDialog - 返回对话框。
    • persistProperties - 允许用户创建持久设置并将其与视觉对象定义一起保存，使其在下次重载时可用
    • eventService - 返回一个事件服务来支持 Render 事件
    • storageService - 返回一个服务，以帮助在视觉对象中使用本地存储
    • storageV2Service - 返回一个服务，以帮助在视觉对象中使用本地存储版本 2
    • tooltipService - 返回一个工具提示服务，以帮助在视觉对象中使用工具提示
    • telemetry
    • drill
    • launchUrl - 帮助在下一个选项卡中启动 URL
    • authenticationService - 返回 Microsoft Entra ID 令牌。
    • locale - 返回一个区域设置字符串，请参阅本地化
    • instanceId - 返回一个字符串来识别当前的视觉对象实例
    • colorPalette - 返回为数据应用颜色所需的 colorPalette
    • fetchMoreData - 支持使用超过标准限制（1000 行）的数据 请参阅提取更多数据
    • switchFocusModeState - 帮助更改焦点模式状态

update

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

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 - 其中包含关于属性窗格设计、层次结构、属性和最新格式值的所有信息。

getFormattingModel(): visuals.FormattingModel;

destroy（可选）

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

public destroy(): void

提示

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

相关内容