API de objeto visual

  • Artículo

Todos los objetos visuales empiezan con una clase que implementa la interfaz IVisual. Puede asignar cualquier nombre a la clase siempre que haya exactamente una clase que implemente la interfaz IVisual.

Nota

El nombre de la clase visual debe ser el mismo que visualClassName en el archivo pbiviz.json.

La clase del objeto visual debe implementar los siguientes métodos, como se muestra en este ejemplo:

  • constructor: un constructor estándar que inicializa el estado del objeto visual.
  • update: actualiza los datos del objeto visual.
  • getFormattingModel, devuelve un modelo de formato que rellena el panel de propiedades (opciones de formato) donde puede modificar las propiedades según sea necesario
  • destroy: un destructor estándar para la limpieza.
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

Se llama a constructor de la clase del objeto visual cuando se crea una instancia del objeto visual. Se puede usar para cualquier operación de configuración que el objeto visual necesite.

constructor(options: VisualConstructorOptions)

VisualConstructorOptions

Estas interfaces se actualizan con cada nueva versión de API. Para obtener el formato de interfaz más actualizado, vaya a nuestro repositorio de GitHub.

En la lista siguiente se describen algunas de las propiedades de la interfaz de VisualConstructorOptions:

  • element: HTMLElement: referencia al elemento DOM que contiene el objeto visual.

  • host: IVisualHost: una colección de propiedades y servicios que se pueden usar para interactuar con el host del objeto visual (Power BI).

    IVisualHost contiene los servicios siguientes:

    • createSelectionIdBuilder: genera y almacena los metadatos de los elementos seleccionables en el objeto visual.
    • createSelectionManager: crea el puente de comunicación que se usa para notificar al host del objeto visual los cambios en el estado de selección (vea API de selección).
    • hostCapabilities
    • refreshHostData
    • downloadService: devuelve información ampliada sobre los resultados de la descarga.
    • eventService: devuelve información sobre los eventos de representación.
    • hostEnv
    • displayWarningIcon: devuelve un mensaje de error o de advertencia.
    • licenseManager: devuelve información de licencia.
    • createLocalizationManager: genera un administrador para ayudar con la localización.
    • applyJsonFilter: aplica tipos de filtros específicos. Consulte Filter API.
    • applyCustomSort: admite opciones de ordenación personalizadas.
    • acquireAADTokenService: devuelve información de autenticación de Microsoft Entra ID.
    • webAccessService: devuelve el estado del permiso para acceder a recursos remotos.
    • openModalDialog: devuelve un cuadro de diálogo.
    • persistProperties: permite a los usuarios crear una configuración persistente y guardarla junto con la definición del objeto visual, de modo que esté disponible en la recarga siguiente.
    • eventService: devuelve un servicio de eventos para admitir eventos Representar.
    • storageService: devuelve un servicio para ayudar a usar el almacenamiento local en el objeto visual.
    • storageV2Service: devuelve un servicio para ayudar a usar la versión 2 del almacenamiento local en el objeto visual.
    • tooltipService: devuelve un servicio de información sobre herramientas para ayudarle a usar información sobre herramientas en el objeto visual.
    • telemetry
    • drill
    • launchUrl: ayuda a lanzar la dirección URL en la pestaña siguiente.
    • authenticationService: devuelve un token de Microsoft Entra ID.
    • locale: devuelve una cadena de configuración regional (consulte Localización).
    • instanceId: devuelve una cadena para identificar la instancia del objeto visual actual.
    • colorPalette: devuelve el colorPalette que se necesita para aplicar colores a los datos.
    • fetchMoreData: admite el uso de más datos que el límite estándar (1000 filas). Consulte Captura de más datos.
    • switchFocusModeState: ayuda a cambiar el estado del modo de enfoque.

update

Todos los objetos visuales deben implementar un método public update al que se llama cada vez que hay un cambio en los datos o en el entorno de host.

public update(options: VisualUpdateOptions): void

VisualUpdateOptions

  • viewport: IViewport: dimensiones de la ventanilla en la que se debe representar el objeto visual.
  • dataViews: DataView[]: objeto de vista de datos que contiene todos los datos necesarios para representar el objeto visual (generalmente, el objeto visual usa la propiedad de categoría en DataView).
  • type: VisualUpdateType: marcas que indican los tipos de datos que se actualizan (Data | Resize | ViewMode | Style | ResizeEnd).
  • viewMode: ViewMode: marcas que indican el modo de vista del objeto visual (View | Edit | InFocusEdit).
  • editMode: EditMode: marca que indica el modo de edición del objeto visual (Default | Advanced) (si el objeto visual admite AdvancedEditMode, debe representar sus controles de interfaz de usuario avanzados solo cuando editMode está establecido en Advanced; vea AdvancedEditMode).
  • operationKind?: VisualDataChangeOperationKind: marca que indica el tipo de cambio de datos (Create | Append).
  • jsonFilters?: IFilter[]: colección de filtros json aplicados.
  • isInFocus?: boolean: marca para indicar si el objeto visual está en modo de enfoque o no.

getFormattingModel (opcional)

Se llama a este método una vez cada vez que se abre el panel de propiedades o el usuario edita cualquiera de las propiedades del panel. Devuelve FormattingModel con toda la información sobre el diseño del panel de propiedades, la jerarquía, las propiedades y los últimos valores de formato.

getFormattingModel(): visuals.FormattingModel;

destroy (opcional)

Se llama a la función destroy cuando el objeto visual se descarga y se puede usar para realizar tareas de limpieza, como quitar clientes de escucha de eventos.

public destroy(): void

Sugerencia

Por lo general, Power BI no llama a destroy porque es más rápido quitar todo el IFrame que contiene el objeto visual.

Contenido relacionado