Condividi tramite

Integrazione del sistema di oggetti visivi di Power BI

  • Articolo

L’articolo descrive l’API per gli oggetti visivi e il modo in cui Power BI gestisce le interazioni tra l'utente, l'oggetto visivo e l'host.

Le azioni e gli aggiornamenti successivi in Power BI possono essere avviati manualmente o automaticamente. Tipi di aggiornamento:

La figura seguente illustra in che modo le azioni comuni basate sugli oggetti visivi, ad esempio la selezione di un segnalibro, vengono elaborate in Power BI.

Diagramma del processo degli oggetti visivi di Power BI.

Interagire con un oggetto visivo tramite Power BI

È possibile aggiornare un oggetto visivo con Power BI come segue:

  • Aprire il pannello delle proprietà dell'oggetto visivo.

    Quando si apre il pannello delle proprietà dell'oggetto visivo, Power BI recupera gli oggetti e le proprietà supportati dal file capabilities.json dell'oggetto visivo. Per ricevere i valori effettivi delle proprietà, Power BI chiama il metodo getFormattingModel dell'oggetto visivo (le API precedenti alla versione 5.0 chiamano invece enumerateObjectInstances). L'API restituisce componenti del modello del riquadro di formato moderno, proprietà e valori effettivi.

    Per altre informazioni, vedere Funzionalità e proprietà degli oggetti visivi di Power BI.

  • Personalizzare i titoli, gli sfondi, le etichette e le legende delle visualizzazioni.

    Quando un utente modifica il valore di una proprietà nel pannello di formattazione, Power BI chiama il metodo update. Power BI passa il nuovo oggetto options al metodo update e gli oggetti contengono i nuovi valori.

    Per altre informazioni, vedere Oggetti e proprietà.

  • Ridimensionare l'oggetto visivo.

    Quando un utente modifica le dimensioni di un oggetto visivo, Power BI chiama il metodo update e passa il nuovo oggetto options. Gli oggetti options includono gli oggetti viewport annidati che contengono i nuovi valori di larghezza e altezza dell'oggetto visivo.

  • Applicare un filtro a livello di report, pagina oppure oggetto visivo.

    Power BI filtra i dati in base alle condizioni di filtro. Power BI chiama il metodo update dell'oggetto visivo per aggiornare l'oggetto visivo con i nuovi dati.

    L'oggetto visivo ottiene un nuovo aggiornamento degli oggetti options quando in uno degli oggetti annidati sono presenti nuovi dati. La modalità di aggiornamento dipende dalla configurazione del mapping delle viste dati dell'oggetto visivo.

    Per altre informazioni, vedere Mapping di viste dati in oggetti visivi di Power BI.

  • Selezionare un punto dati in un altro oggetto visivo del report.

    Quando si 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. L'oggetto visivo ottiene i nuovi dati filtrati o gli stessi dati con una matrice di evidenziazioni.

    Per altre informazioni, vedere Evidenziare i punti dati in oggetti visivi di Power BI.

  • Selezionare un segnalibro nel pannello Segnalibri del report.

    Quando si seleziona un segnalibro nel pannello Segnalibri, si verifica una delle due situazioni seguenti:

    • Power BI chiama una funzione che viene passata e registrata dal metodo registerOnSelectionCallback. La funzione di callback ottiene le matrici delle selezioni per il segnalibro corrispondente.

    • Power BI chiama il metodo update con un oggetto filter corrispondente all'interno dell'oggetto options.

      In entrambi i casi, l'oggetto visivo cambia lo stato in base alle selezioni ricevute o all'oggetto filter.

      Per altre informazioni sui segnalibri e sui filtri, vedere API dei filtri degli oggetti visivi negli oggetti visivi di Power BI.

Interagire direttamente con l'oggetto visivo

È possibile interagire direttamente con l'oggetto visivo anche per aggiornarlo:

  • Passare il puntatore del mouse su un elemento dati.

    Un oggetto visivo può visualizzare più informazioni su un punto dati tramite l'API delle descrizioni comando di Power BI. Quando si 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. L'oggetto visivo può visualizzare una descrizione comando standard oppure una descrizione comando della pagina del report.

    Per altre informazioni, vedere Aggiungere descrizioni comando agli oggetti visivi di Power BI.

  • Modificare le proprietà dell’oggetto visivo, ad esempio espandendo una struttura ad albero, e l'oggetto visivo salva il nuovo stato nelle proprietà dell’oggetto visivo.

    Un oggetto visivo può salvare i valori delle proprietà tramite l'API Power BI. Quando ad esempio si interagisce con l'oggetto visivo e l'oggetto visivo deve salvare o aggiornare i valori delle proprietà, l'oggetto visivo può chiamare il metodo persistProperties.

  • Selezionare un URL.

    Per impostazione predefinita, un oggetto visivo non può aprire direttamente un URL. Per aprire un URL in una nuova scheda, l'oggetto visivo può chiamare il metodo launchUrl e passare l'URL come parametro.

    Per altre informazioni, vedere Creare un URL di avvio.

  • Applicare un filtro tramite l'oggetto visivo.

    Un oggetto visivo può chiamare il metodo applyJsonFilter e passare le condizioni per filtrare i dati in altri oggetti visivi. Sono disponibili diversi tipi di filtri, inclusi i filtri di tipo base, avanzato e tupla.

    Per altre informazioni, vedere API dei filtri degli oggetti visivi negli oggetti visivi di Power BI.

  • Selezionare gli elementi nell'oggetto visivo.

    Per altre informazioni sulle selezioni in un oggetto visivo di Power BI, vedere Aggiungere interattività negli oggetti visivi usando le selezioni degli oggetti visivi di Power BI.

Un oggetto visivo interagisce con Power BI

In alcuni casi l'oggetto visivo avvia la comunicazione con l'host di Power BI senza alcun input da parte dell'utente:

  • Un oggetto visivo richiede più dati a Power BI.

    Un oggetto visivo elabora una parte dei dati per volta. Il metodo API fetchMoreData richiede il frammento successivo dei dati nel modello semantico.

    Per altre informazioni, vedere Recuperare altri dati da Power BI.

  • Viene attivato il servizio eventi.

    Power BI può esportare un report in formato PDF o inviare un report tramite posta elettronica (applicabile solo agli oggetti visivi certificati). 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.

    Per altre informazioni, vedere Esportare report da Power BI in PDF.

    Per informazioni sul servizio eventi, vedere Eseguire il rendering degli eventi negli oggetti visivi di Power BI.

Contenuto correlato

Sono disponibili altre informazioni sulla creazione di visualizzazioni e la relativa aggiunta a Microsoft AppSource. Vedere i seguenti articoli: