Integrazione del sistema di oggetti visivi di Power BIPower BI visuals system integration

Questo articolo descrive come gli oggetti visivi si integrano con Power BI e come un utente può interagire con un oggetto visivo in Power BI.The article describes how visuals integrate with Power BI and how a user can interact with a visual in Power BI.

La figura seguente illustra in che modo le azioni comuni basate sugli oggetti visivi eseguite da un utente, ad esempio la selezione di un segnalibro, vengono elaborate in Power BI.The following figure depicts how common visual-based actions that a user takes, like selecting a bookmark, are processed in Power BI.

Diagramma delle azioni su un oggetto visivo di Power BI

Aggiornamenti degli oggetti visivi da Power BIVisuals get updates from Power BI

Un oggetto visivo chiama un metodo update per ottenere gli aggiornamenti da Power BI.A visual calls an update method to get updates from Power BI. Il metodo update contiene in genere la logica principale dell'oggetto visivo ed è responsabile del rendering di un grafico o della visualizzazione dei dati.The update method usually contains the main logic of the visual and is responsible for rendering a chart or visualizing data.

Gli aggiornamenti vengono attivati quando l'oggetto visivo chiama il metodo update.Updates are triggered when the visual calls the update method.

Modelli di azione e di aggiornamentoAction and update patterns

Le azioni e i successivi aggiornamenti degli oggetti visivi di Power BI si verificano sulla base di uno dei tre modelli seguenti:Actions and subsequent updates in Power BI visuals occur in one of these three patterns:

  • L'utente interagisce con un oggetto visivo tramite Power BI.User interacts with a visual through Power BI.
  • L'utente interagisce direttamente con l'oggetto visivo.User interacts with the visual directly.
  • L'oggetto visivo interagisce con Power BI.Visual interacts with Power BI.

L'utente interagisce con un oggetto visivo tramite Power BIUser interacts with a visual through Power BI

  • Un utente apre il pannello delle proprietà dell'oggetto visivo.A user opens the visual's properties panel.

    Quando un utente apre il pannello delle proprietà dell'oggetto visivo, Power BI recupera gli oggetti e le proprietà supportati dal file capabilities.json dell'oggetto visivo.When a user opens the visual's properties panel, Power BI fetches supported objects and properties from the visual's capabilities.json file. Per ricevere i valori effettivi delle proprietà, Power BI chiama il metodo enumerateObjectInstances dell'oggetto visivo.To receive actual values of properties, Power BI calls the enumerateObjectInstances method of the visual. L'oggetto visivo restituisce i valori effettivi delle proprietà.The visual returns actual values of properties.

    Per altre informazioni, vedere Funzionalità e proprietà degli oggetti visivi di Power BI.For more information, see Capabilities and properties of Power BI visuals.

  • Un utente modifica un proprietà dell'oggetto visivo nel pannello di formattazione.A user changes a property of the visual in the format panel.

    Quando un utente modifica il valore di una proprietà nel pannello di formattazione, Power BI chiama il metodo update dell'oggetto visivo.When a user changes the value of a property in the format panel, Power BI calls the update method of the visual. Power BI passa il nuovo oggetto options al metodo update.Power BI passes in the new options object to the update method. Gli oggetti contengono i nuovi valori.The objects contain the new values.

    Per altre informazioni, vedere Oggetti e proprietà.For more information, see Objects and properties of Power BI visuals.

  • Un utente ridimensiona l'oggetto visivo.A user resizes the visual.

    Quando un utente modifica le dimensioni di un oggetto visivo, Power BI chiama il metodo update con il nuovo oggetto options.When a user changes the size of a visual, Power BI calls the update method with the new options object. Gli oggetti options includono gli oggetti viewport annidati che contengono i nuovi valori di larghezza e altezza dell'oggetto visivo.The options objects have nested viewport objects that contain the new width and height of the visual.

  • Un utente applica un filtro a livello di report, pagina oppure oggetto visivo.A user applies a filter at the report, page, or visual level.

    Power BI filtra i dati in base alle condizioni di filtro.Power BI filters data based on filter conditions. Power BI chiama il metodo update dell'oggetto visivo per aggiornare l'oggetto visivo con i nuovi dati.Power BI calls the update method of the visual to update the visual with new data.

    L'oggetto visivo ottiene un nuovo aggiornamento degli oggetti options quando in uno degli oggetti annidati sono presenti nuovi dati.The visual gets a new update of the options objects when there's new data in one of the nested objects. La modalità di aggiornamento dipende dalla configurazione del mapping delle viste dati dell'oggetto visivo.How the update occurs depends on the data view mapping configuration of the visual.

    Per altre informazioni, vedere Mapping di viste dati in oggetti visivi di Power BI.For more information, see Understand data view mapping in Power BI visuals.

  • Un utente seleziona un punto dati in un altro oggetto visivo del report.A user selects a data point in another visual in the report.

    Quando un utente seleziona un punto dati in un altro oggetto visivo nel report, Power BI filtra o evidenzia i punti dati selezionati e chiama il metodo update dell'oggetto visivo.When a user selects a data point in another visual in the report, Power BI filters or highlights the selected data points and calls the visual's update method. L'oggetto visivo ottiene i nuovi dati filtrati o gli stessi dati con una matrice di evidenziazioni.The visual gets new filtered data, or it gets the same data with an array of highlights.

    Per altre informazioni,, vedere Evidenziare i punti dati in oggetti visivi di Power BI.For more information, see Highlight data points in Power BI visuals.

  • Un utente seleziona un segnalibro nel pannello dei segnalibri del report.A user selects a bookmark in the bookmarks panel of the report.

    Quando un utente seleziona un segnalibro nel pannello dei segnalibri del report, può verificarsi una delle due azioni seguenti:When a user selects a bookmark in the report's bookmarks panel, one of two actions can occur:

    • Power BI chiama una funzione che viene passata e registrata dal metodo registerOnSelectionCallback.Power BI calls a function that's passed and registered by the registerOnSelectionCallback method. La funzione di callback ottiene le matrici delle selezioni per il segnalibro corrispondente.The callback function gets arrays of selections for the corresponding bookmark.

    • Power BI chiama il metodo update con un oggetto filter corrispondente all'interno dell'oggetto options.Power BI calls the update method with a corresponding filter object inside the options object.

    In entrambi i casi l'oggetto visivo deve modificare lo stato in base alle selezioni ricevute o all'oggetto filter.In either case, the visual must change its state according to the received selections or filter object.

    Per altre informazioni sui segnalibri e sui filtri, vedere API dei filtri degli oggetti visivi negli oggetti visivi di Power BI.For more information about bookmarks and filters, see Visual Filters API in Power BI visuals.

L'utente interagisce direttamente con l'oggetto visivoUser interacts with the visual directly

  • Un utente passa il puntatore del mouse su un elemento dati.A user hovers the mouse over a data element.

    Un oggetto visivo può visualizzare più informazioni su un punto dati tramite l'API delle descrizioni comando di Power BI.A visual can display more information about a data point through the Power BI Tooltips API. Quando un utente passa il puntatore del mouse su un elemento dell'oggetto visivo, l'oggetto visivo può gestire l'evento e visualizzare i dati relativi all'elemento descrizione comando associato.When a user hovers the mouse over a visual element, the visual can handle the event and display data about the associated tooltip element. L'oggetto visivo può visualizzare una descrizione comando standard oppure una descrizione comando della pagina del report.The visual can display either a standard tooltip or a report page tooltip.

    Per altre informazioni, vedere Descrizioni comando negli oggetti visivi di Power BI.For more information, see Tooltips in Power BI visuals.

  • Un utente modifica le proprietà dell'oggetto visivo,A user changes visual properties. ad esempio un utente espande un albero e l'oggetto visivo salva lo stato nelle proprietà dell'oggetto visivo.(For example, a user expands a tree and the visual saves state in the visual properties.)

    Un oggetto visivo può salvare i valori delle proprietà tramite l'API Power BI.A visual can save properties values through the Power BI API. Quando ad esempio un utente interagisce con l'oggetto visivo e l'oggetto visivo deve salvare o aggiornare i valori delle proprietà, l'oggetto visivo può chiamare il metodo presistProperties.For example, when a user interacts with the visual and the visual needs to save or update properties values, the visual can call the presistProperties method.

  • Un utente seleziona un URL.A user selects a URL.

    Per impostazione predefinita, un oggetto visivo non può aprire direttamente un URL.By default, a visual can't open a URL directly. Per aprire un URL in una nuova scheda, l'oggetto visivo può invece chiamare il metodo launchUrl e passare l'URL come parametro.Instead, to open a URL in a new tab, the visual can call the launchUrl method and pass the URL as a parameter.

    Per altre informazioni, vedere Creare un URL di avvio.For more information, see Create a launch URL.

  • Un utente applica un filtro tramite l'oggetto visivo.A user applies a filter through the visual.

    Un oggetto visivo può chiamare il metodo applyJsonFilter e passare le condizioni per filtrare i dati in altri oggetti visivi.A visual can call the applyJsonFilter method and pass conditions to filter for data in other visuals. Sono disponibili diversi tipi di filtri, inclusi i filtri di tipo base, avanzato e tupla.Several types of filters are available, including Basic, Advanced, and Tuple filters.

    Per altre informazioni, vedere API dei filtri degli oggetti visivi negli oggetti visivi di Power BI.For more information, see Visual Filters API in Power BI visuals.

  • Un utente seleziona gli elementi nell'oggetto visivo.A user selects elements in the visual.

    Per altre informazioni sulle selezioni in un oggetto visivo di Power BI, vedere Aggiungere interattività usando le selezioni degli oggetti visivi di Power BI.For more information about selections in a Power BI visual, see Add interactivity by using Power BI visual selections.

Un oggetto visivo interagisce con Power BIVisual interacts with Power BI

  • Un oggetto visivo richiede più dati a Power BI.A visual requests more data from Power BI.

    Un oggetto visivo elabora una parte dei dati per volta.A visual processes data part by part. Il metodo API fetchMoreData richiede il frammento successivo dei dati nel set di dati.The fetchMoreData API method requests the next fragment of data in the dataset.

    Per altre informazioni, vedere Recuperare altri dati da Power BI.For more information, see Fetch more data from Power BI.

  • Viene attivato il servizio eventi.The event service triggers.

    Power BI può esportare un report in formato PDF o inviare un report tramite posta elettronica (applicabile solo agli oggetti visivi certificati).Power BI can export a report to PDF or send a report by e-mail (applies only to certified visuals). Per notificare a Power BI che il rendering è completato e che l'oggetto visivo è pronto per essere acquisito come PDF o messaggio di posta elettronica, l'oggetto visivo deve chiamare l'API per gli eventi di rendering.To notify Power BI that rendering is finished and that the visual is ready to be captured as PDF or e-mail, the visual should call the Rendering Events API.

    Per altre informazioni, vedere Esportare report da Power BI in PDF.For more information, see Export reports from Power BI to PDF.

    Per informazioni sul servizio eventi, vedere Eseguire il rendering degli eventi negli oggetti visivi di Power BI.To learn about the event service, see Render events in Power BI visuals.

Passaggi successiviNext steps

Sono disponibili altre informazioni sulla creazione di visualizzazioni e la relativa aggiunta a Microsoft AppSource.Interested in creating visualizations and adding them to Microsoft AppSource? Vedere i seguenti articoli:See these articles: