Usare gli strumenti di sviluppo per la creazione di oggetti visivi personalizzatiUse developer tools to create custom visuals

Gli oggetti visivi personalizzati consentono di soddisfare le esigenze degli utenti e rispettare la progettazione dell'applicazione.Custom visuals allow you to meet your users' needs and match your app's design. Ecco come creare un oggetto visivo personalizzato per Power BI usando gli strumenti di sviluppo.Learn how to create a custom visual for Power BI using the developer tools.

Nota

Leggere questo documento per iniziare a usare Power BI rapidamente.You can use this document to get up and running. Per informazioni più dettagliate, vedere le informazioni di riferimento all'interno del repository git degli oggetti visivi di Power BI.For more in-depth information, see the reference information within the Power BI Visuals git repo.

RequisitiRequirements

Installare NodeJS e gli strumenti di Power BIInstall NodeJS and the Power BI tools

Per creare un oggetto visivo personalizzato, è necessario installare NodeJS.In order to create a custom visual, you will need to install NodeJS. NodeJS è necessario per eseguire gli strumenti da riga di comando.NodeJS is required to run the command line tools.

  1. Scaricare e installare NodeJS.Download and install NodeJS. È necessaria la versione 4.0 o versioni successive, ma è consigliata la versione 5.0 o versioni successive.Version 4.0 or later is required but it is recommended to have 5.0 or later.
  2. Installare gli strumenti da riga di comando.Install the command line tools. Eseguire il comando seguente dal prompt dei comandi.Run the following command from a command prompt.

     npm install -g powerbi-visuals-tools
    
  3. È possibile confermare che gli strumenti vengano installati eseguendo il comando seguente senza parametri.You can confirm that the tools are installed by running the following command without any parameters.

     pbiviz
    

    Si otterrà l'output della guida.You should see the help output.

    
          +syyso+/
     oms/+osyhdhyso/
     ym/       /+oshddhys+/
     ym/              /+oyhddhyo+/
     ym/                     /osyhdho
     ym/                           sm+
     ym/               yddy        om+
     ym/         shho /mmmm/       om+
      /    oys/ +mmmm /mmmm/       om+
     oso  ommmh +mmmm /mmmm/       om+
    ymmmy smmmh +mmmm /mmmm/       om+
    ymmmy smmmh +mmmm /mmmm/       om+
    ymmmy smmmh +mmmm /mmmm/       om+
    +dmd+ smmmh +mmmm /mmmm/       om+
          /hmdo +mmmm /mmmm/ /so+//ym/
                /dmmh /mmmm/ /osyhhy/
                  //   dmmd
                        ++
    
        PowerBI Custom Visual Tool
    
     Usage: pbiviz [options] [command]
    
     Commands:
    
     new [name]        Create a new visual
     info              Display info about the current visual
     start             Start the current visual
     package           Package the current visual into a pbiviz file
     update [version]  Updates the api definitions and schemas in the current visual. Changes the version if specified
     help [cmd]        display help for [cmd]
    
     Options:
    
     -h, --help      output usage information
     -V, --version   output the version number
     --install-cert  Install localhost certificate
     

<a name"ssl-setup">

Installazione del certificato serverServer Certificate setup

Per abilitare l'anteprima dinamica dell'oggetto visivo, è necessario un server https attendibile.To enable a live preview of your visual, a trusted https server is needed. Prima di iniziare, è necessario installare un certificato SSL in modo da permettere il caricamento di asset visivi nel Web browser.Before you can start, you will need to install an SSL certificate which will allow visual assets to load in your web browser.

Nota

Si tratta di una singola configurazione per la workstation di sviluppo.This is a one-time setup for your developer workstation.

Per aggiungere un certificato, eseguire il comando seguente.To add a certificate, run the following command.

pbiviz --install-cert

Sistema operativo WindowsWindows OS

  1. Selezionare Installa certificato....Select Install Certificate....

  2. Selezionare Utente corrente, quindi scegliere Avanti.Select Current User and then select Next.

  3. Selezionare Colloca tutti i certificati nel seguente archivio e quindi selezionare Sfoglia....Select Place all certificate in the following store and select Browse....
  4. Selezionare Autorità di certificazione radice disponibile nell'elenco locale e quindi selezionare OK.Select Trusted Root Certification Authorities and then select OK. Fare clic su Avanti.Select Next.

  5. Fare clic su Fine.Select Finish.

  6. Selezionare nella finestra di dialogo dell'avviso di sicurezza.Select Yes on the security warning dialog.

  7. Chiudere qualsiasi browser aperto.Close any browsers that you have open.

Nota

Se il certificato non viene riconosciuto, potrebbe essere necessario riavviare il computer.If the certificate is not recognized, you may need to restart your computer.

OSXOSX

  1. Se il lucchetto in alto a sinistra è bloccato, selezionarlo per sbloccarlo.If the lock in the upper left is locked, select it to unlock. Cercare localhost e fare doppio clic sul certificato.Search for localhost and double click on the certificate.

  2. Selezionare Considera sempre attendibile e chiudere la finestra.Select Always Trust and close the window.

  3. Immettere il nome utente e password.Enter your username and password. Selezionare Impostazioni aggiornamento.Select Update Settings.

  4. Chiudere qualsiasi browser aperto.Close any browsers that you have open.

Nota

Se il certificato non viene riconosciuto, potrebbe essere necessario riavviare il computer.If the certificate is not recognized, you may need to restart your computer.

Abilitare l'anteprima dinamica dell'oggetto visivo della modalità sviluppatoreEnable live preview of developer visual

Per abilitare un'anteprima dinamica dell'oggetto visivo personalizzato, seguire questi passaggi.To enable a live preview of your custom visual, follow these steps. In questo modo l'oggetto visivo verrà usato all'interno del servizio Power BI durante la modifica di report.This allows the visual to be used within the Power BI service when editing reports.

  1. Passare ad app.powerbi.com ed eseguire l'accesso.Browse and sign into app.powerbi.com.
  2. Selezionare l'icona dell'ingranaggio e quindi selezionare Impostazioni.Select the gear icon and then select Settings.

  3. Selezionare Sviluppatore e quindi selezionare Abilita oggetto visivo per sviluppatori per il test.Select Developer and then select Enable developer visual for testing.

  4. Selezionare Oggetto visivo della modalità sviluppatore nel riquadro Visualizzazione.Select the Developer Visual in the Visualization pane.

    Nota

    Questa operazione richiede che sia stato eseguito pbiviz start dalla cartella dell'oggetto visivo nel computer di sviluppo.This requires that you have run pbiviz start from the visual folder on your development machine. Per altre informazioni su come creare l'oggetto visivo, vedere Creare un nuovo oggetto visivo in questo articolo.For more information on creating your visual, see Create a new visual in this article.

  5. Selezionare l'oggetto visivo nell'area di disegno report.Select the visual in the report canvas. È possibile associare i dati nello stesso modo in cui si associano altri oggetti visivi.You can bind data in the same way you do other visuals.

È ora possibile iniziare lo sviluppo dell'oggetto visivo.You can now begin developing your visual.

Creare un nuovo oggetto visivoCreate a new visual

È possibile creare un nuovo progetto di oggetto visivo eseguendo il comando seguente.You can create a new visual project by running the following command.

pbiviz new My Visual name

È possibile sostituire My Visual Name con il nome che si vuole assegnare all'oggetto visivo.You can replace My Visual Name with the name you want to give the visual. È possibile cambiarlo in un secondo momento modificando i campi name e displayName all'interno del file pbiviz.json generato.This can be changed later by modifying the name and displayName fields within the generated pbiviz.json file.

Questo comando crea una nuova cartella nella directory in cui è stato eseguito il comando.This command will create a new folder in the direct where the command was run. Verrà generato un modello iniziale di base per l'oggetto visivo.It will generate a basic starter template for your visual. Al termine dell'esecuzione del comando, è possibile aprire la directory e usare l'editor preferito per iniziare a elaborare il nuovo oggetto visivo.Once the command completes, you can open the directory and use your favorite editor to start working on your new visual.

Test dell'oggetto visivo in Power BITesting your visual in Power BI

È possibile testare l'oggetto visivo nel servizio Power BI all'interno di rapporti e dashboard.You can test your visual within the Power BI service within reports and dashboards.

Esecuzione dell'oggetto visivoRunning your visual

È possibile eseguire l'oggetto visivo effettuando le operazioni seguenti.You can run your visual by doing the following.

  1. Aprire un prompt dei comandi.Open a prompt.
  2. Modificare la directory nella cartella dell'oggetto visivo,Change your directory to be your visual folder. che contiene il file pbiviz.json.This is the folder that contains the pbiviz.json file.
  3. Eseguire il comando seguente.Run the following command.

    pbiviz start
    

Se si è nella posizione errata, verrà visualizzato un errore simile al seguente.If you are in the wrong location, you will see an error similar to the following.

    error  LOAD ERROR Error: pbiviz.json not found. You must be in the root of a visual project to run this command.
        at e (C:\Users\[user]\AppData\Roaming\npm\node_modules\powerbi-visuals-tools\lib\VisualPackage.js:67:35)
        at Function.loadVisualPackage (C:\Users\[user]\AppData\Roaming\npm\node_modules\powerbi-visuals-tools\lib\VisualPackage.js:62:16)
        at Object.<anonymous> (C:\Users\[user]\AppData\Roaming\npm\node_modules\powerbi-visuals-tools\bin\pbiviz-start.js:43:15)
        at Module._compile (module.js:556:32)
        at Object.Module._extensions..js (module.js:565:10)
        at Module.load (module.js:473:32)
        at tryModuleLoad (module.js:432:12)
        at Function.Module._load (module.js:424:3)
        at Module.runMain (module.js:590:10)
        at run (bootstrap_node.js:394:7)

Visualizzazione dell'oggetto visivo in Power BIViewing your visual in Power BI

Per visualizzare l'oggetto visivo in un report, passare a tale report e selezionare l'oggetto visivo all'interno del riquadro Visualizzazioni.To view your visual in a report, go to that report and select the visual within the Visualizations pane.

Nota

È necessario eseguire il comando pbiviz start prima di procedere come descritto nella sezione Esecuzione dell'oggetto visivo.You must run the pbiviz start command before doing this as discribed in the Running your visual section.

Verrà quindi visualizzato il modello iniziale per l'oggetto visivo.You will then see the starter template for the visual.

Elemento di barra degli strumentiToolbar item DescrizioneDescription
Refresh visual (Aggiorna oggetto visivo)Refresh visual Aggiornare manualmente l'oggetto visivo se il ricaricamento automatico è disabilitato.Manually refresh the visual if auto reload is disabled.
Attiva/Disattiva ricaricamento automaticoToggle auto reload Quando attivato, l'oggetto visivo verrà automaticamente aggiornato ogni volta che si salva il file dell'oggetto visivo.When turned on, the visual will automatically update every time you save your visual file.
Mostra vista datiShow dataview Mostra la visualizzazione dati sottostante dell'oggetto visivo per il debugShows the visual's underlying data view for debugging
GuidaGet help Documentazione in GitHubDocumentation within GitHub
Invia commenti e suggerimentiSend feedback Segnalare se è possibile migliorare ulteriormente l'esperienza.Let us know if there is anyway we can improve the experience! (Richiede un account GitHub)(Requires GitHub account)

Creare pacchetti di oggetti visivi da usare in Power BI Desktop e per la distribuzionePackage your visual for use in Power BI Desktop and distribution

Prima di caricare l'oggetto visivo in Power BI Desktop o condividerlo con la community nella Raccolta oggetti visivi di Power BI, sarà necessario generare un file pbiviz.Before you can load your visual into Power BI Desktop, or share it with the community in the Power BI Visual gallery, you'll need to generate a pbiviz file.

È possibile creare un pacchetto per l'oggetto visivo effettuando le operazioni seguenti.You can package your visual by doing the following.

  1. Aprire un prompt dei comandi.Open a prompt.
  2. Modificare la directory nella cartella dell'oggetto visivo,Change your directory to be your visual folder. che contiene il file pbiviz.json.This is the folder that contains the pbiviz.json file.
  3. Eseguire il comando seguente.Run the following command.

    pbiviz package
    

Questo comando crea un file pbiviz nella directory dist/ del progetto di oggetto visivo.This command will create a pbiviz in the dist/ directory of your visual project. Se esiste già un file pbiviz, verrà sovrascritto.If there is already a pbiviz file present, it will be overwritten.

Aggiornamento della versione dell'API degli oggetti visiviUpdating the visuals API version

Quando si crea un oggetto visivo usando pbiviz new, una copia delle definizioni di tipo API e degli schemi JSON appropriati viene aggiunta alla directory dell'oggetto visivo.When you create a visual using pbiviz new, a copy of the appropriate API type definitions and json schemas are copied into your visual's directory. È possibile usare il comando pbiviz update per aggiornare questi file, se necessario.You can use the pbiviz update command to update these files if needed. Può essere utile se si rilascia una correzione per una versione precedente dell'API o se si vuole eseguire l'aggiornamento alla versione dell'API più recente.This can be useful if we release a fix for a past API version or if you want to update to the latest API version.

Aggiornamento della versione dell'API esistenteUpdating your existing API version

Se viene rilasciato un aggiornamento per un'API esistente, è possibile ottenere la versione più recente eseguendo le operazioni seguenti.If we release an update to an existing API, you can get the latest version by doing the following.

#Update your version of pbiviz
npm install -g powerbi-visuals-tools

#Run update from the root of your visual project, where pbiviz.json is located
pbiviz update

Verranno scaricati gli strumenti più recenti da npm che includono le definizioni di tipo e gli schemi aggiornati.This will download the latest tools from npm which include the updated type definitions and schemas. Se si usa pbiviz update verrà sovrascritta la proprietà apiVersion nel file pbiviz.json con la versione più recente.Using pbiviz update will overwrite the apiVersion property in your pbiviz.json fiel with the latest version.

Aggiornamento a una versione diversa dell'APIUpgrading to a different API version

È possibile aggiornare a una versione diversa dell'API usando gli stessi passaggi indicati in precedenza.You can update to a different API version by using the same steps as mentioned above. È possibile specificare in modo esplicito la versione dell'API da usare.You can explicitly specify the API version you want to use.

#Update your version of pbiviz
npm install -g powerbi-visuals-tools

#Run update from the root of your visual project, where pbiviz.json is located
pbiviz update 1.2.0

In questo modo l'oggetto visivo verrà aggiornato alla versione dell'API 1.2.0.This would update yoru visual to API version 1.2.0. È possibile sostituire 1.2.0 con qualsiasi versione che si vuole usare.You can replace 1.2.0 with whatever version your wanting to use.

Avviso

La versione dell'API predefinita usata dagli strumenti sarà sempre la versione stabile dell'API.The default API version used by the tools will always be the stable version of the API. Tutte le versioni successive alla versione dell'API predefinita sono instabili e soggette a modifiche.Any versions later than the default API version are unstable and subject to change. Possono presentare comportamenti imprevisti e si comportano in modo diverso tra il servizio Power BI e Power BI Desktop.They may have unexpected behaviors and behave differently between the Power BI service and Power BI Desktop. Per la versione dell'API stabile corrente, vedere il log delle modifiche.For the current stable API version, see the change log. Per altre informazioni sulle versioni non definitive, vedere le funzionalità previste.For more information about pre-release versions, see the roadmap.

All'interno del progetto di oggetto visivoInside the visual project

Il progetto di oggetto visivo è la cartella che viene creata quando si esegue il comando pbiviz new.Your visual project is the folder that gets created when you run the pbiviz new command.

Struttura di fileFile structure

ElementoItem DescrizioneDescription
assets/assets/ Usato per archiviare gli asset visivi (icona, schermate e così via).Used to store visual assets (icon, screenshots, etc).
dist/dist/ Quando si esegue pbiviz package, verrà generato il file pbiviz qui.When you run pbiviz package, the pbiviz file will be generated here.
src/src/ Codice TypeScript per l'oggetto visivo.Typescript code for your visual.
style/style/ Stili Less per l'oggetto visivo.Less styles for your visual.
.gitignore.gitignore Indica di ignorare i file che non devono essere rilevati nel repository git.Tells git to ignore files that shouldn't be tracked in the repository.
capabilities.jsoncapabilities.json Usato per definire le funzionalità dell'oggetto visivo.Used to define the capabilities of your visual.
package.jsonpackage.json Usato da npm per gestire i moduli.Used by npm to manage modules.
pbiviz.jsonpbiviz.json File di configurazione principale.Main configuration file.
tsconfig.jsontsconfig.json Impostazioni del servizio di compilazione TypeScript.Typescript compiler settings. Altre informazioni su tsconfig.Learn more about tsconfig.json.

pbiviz.jsonpbiviz.json

Questo file è il file di configurazione principale per l'oggetto visivo.This file is the main configuration file for your visual. Contiene i metadati, nonché informazioni sui file, necessari per compilare l'oggetto visivo.It contains metadata, as well as information about your files, needed to build your visual.

{
    "visual": {
        "name": "myVisual", // internal visual name (should not contain spaces)
        "displayName": "My Visual!", // visual name displayed to user (used in gallery)
        "guid": "PBI_CV_xxxxxxx", // a unique id for this visual MUST BE UNIQUE
        "visualClassName": "Visual" // the entry class for your visual
        "version": "1.0.0", // visual version. Should be semantic version (increment if you update the visual)
        "description": "", // description used in gallery
        "supportUrl": "", // url to where users can get support for this visual
        "gitHubUrl": "" // url to the source in github (if applicable)
    },
    "apiVersion": "1.0.0", //API version this visual was created with
    "author": {
        "name": "", // your name
        "email": "" // your e-mail
    },
    "assets": {
        "icon": "assets/icon.png" // relative path to your icon file (20x20 png)
    },
    "style": "style/visual.less", // relative path to your less file
    "capabilities": "capabilities.json" // relative path to your capabilities definition 
}

Origine oggetto visivo (TypeScript)Visual source (TypeScript)

Il codice dell'oggetto visivo deve essere scritto in TypeScript, cioè un soprainsieme di JavaScript che supporta caratteristiche più avanzate e l'accesso anticipato alla funzionalità ES6/ES7.Visual code should be written in TypeScript, which is a superset of JavaScript that support more advanced features and early access to ES6/ES7 functionality.

Tutti i file TypeScript devono essere archiviati nella directory src/ e aggiunti alla matrice files in tsconfig.json.All TypeScript files should be stored in the src/ directory and added to the files array in tsconfig.json. Ciò consente al servizio di compilazione di TypeScript di caricarli nell'ordine preferito.This allows the TypeScript compiler to load them and in what order.

Quando viene compilato l'oggetto visivo, tutto il linguaggio TypeScript verrà compilato in un singolo file JavaScript.When your visual is built, all of the TypeScript will be compiled into a single JavaScript file. Ciò consente di fare riferimento agli elementi esportati da altri file senza dover eseguire require manualmente finché entrambi i file saranno elencati in tsconfig.This allows you to reference exported elements from other files without needing to manually require them as long as both files are listed in the tsconfig.

È possibile creare il numero di file e classi necessario per creare l'oggetto visivo.You can create as many files and classes as you need to create your visual.

Altre informazioni su TypeScript.Learn more about TypeScript.

Stile di oggetto visivo (Less)Visual style (Less)

L'applicazione di stili visivi viene gestita usando i fogli di stile CSS.Visual styling is handled using cascading style sheets (CSS). Per praticità, verrà usato il servizio di pre-compilazione Less che supporta alcune funzionalità avanzate, ad esempio la nidificazione, le variabili, le combinazioni, le condizioni, i cicli e così via. Se non si vuole usare nessuna di queste funzionalità, è possibile scrivere semplicemente fogli di stile CSS normali nel file di Less.For your convience, we use the Less pre-compiler which supports some advanced features such as nesting, variables, mixins, conditions, loops, etc. If you don't want to use any of these features, you can just write plain CSS in the Less file.

Tutti i file di Less devono essere archiviati nella directory style/.All Less files should be stored in the style/ directory. Verrà caricato il file specificato nel campo style all'interno del file pbiviz.json.The file specified under the style field within your pbiviz.json file will be loaded. Eventuali file aggiuntivi devono essere caricati usando @import.Any additional files should be loaded using @import.

Altre informazioni su Less.Learn more about Less.

DebugDebugging

Per suggerimenti sul debug dell'oggetto visivo personalizzato, vedere la guida al debug.For tips about debugging your custom visual, see the debugging guide.

Inviare l'oggetto visivo ad AppSourceSubmit your visual to AppSource

È possibile elencare l'oggetto visivo per consentirne l'uso da parte di altri utenti ma inviandolo ad AppSource.You can list your visual for others to use but submitting it to AppSource. Per altre informazioni su questo processo, vedere Pubblicare oggetti visivi personalizzati in AppSource.For more information on this process, see publish custom visuals to AppSource.

Risoluzione dei problemiTroubleshooting

Comando Pbiviz non trovato (o errori simili)Pbiviz command not found (or similar errors)

Se si esegue pbiviz nella riga di comando / del terminal, verrà visualizzata la finestra della Guida in linea.If you run pbiviz in your terminal / command line, you should see the help screen. In caso contrario, l'installazione non è stata eseguita correttamente.If not, it is not installed correctly. Assicurarsi di avere almeno la versione 4.0 di NodeJS installata.Make sure you have at least the 4.0 version of NodeJS installed.

Per altre informazioni, vedere Installare NodeJS e gli strumenti di Power BI.For more information, see Install NodeJS and the Power BI tools...

Non è possibile trovare l'oggetto visivo di debug nella scheda VisualizzazioniCannot find the debug visual in the Visualizations tab

L'oggetto visivo di debug all'interno della scheda Visualizzazioni ha l'aspetto di un'icona di prompt dei comandi.The debug visual looks like a prompt icon within the Visualizations tab.

Se non è visualizzata, verificare che sia stata abilitata nelle impostazioni di Power BI.If you don't see it, make sure you have enabled it within the Power BI settings.

Nota

L'oggetto visivo di debug è attualmente disponibile solo nel servizio Power BI e non in Power BI Desktop o nell'app per dispositivi mobili.The debug visual is currently only available in the Power BI service and not in Power BI Desktop or the mobile app. L'oggetto visivo in pacchetto continuerà a funzionare ovunque.The packaged visual will still work everywhere.

Per altre informazioni, vedere Abilitare l'anteprima dinamica dell'oggetto visivo della modalità sviluppatore.For more information, see Enable live preview of developer visual...

Non è possibile contattare il server dell'oggetto visivoCan't contact visual server

Eseguire il server dell'oggetto visivo con il comando pbiviz start nella riga di comando / del terminal dalla radice del progetto di oggetto visivo.Run the visual server with the command pbiviz start in your terminal / command line from the root of your visual project. Se il server è in esecuzione, è probabile che i certificati SSL non siano stati installati correttamente.If the server is running, it is likely that your SSL vertificates weren't installed correctly.

Per altre informazioni, vedere Esecuzione dell'oggetto visivo oppure Installazione del certificato server.For more information, see Running your visual or Server certificate setup.

Passaggi successiviNext steps

Visualizzazioni in Power BIVisualizations in Power BI
Visualizzazioni personalizzate in Power BICustom Visualizations in Power BI
Pubblicare oggetti visivi personalizzati in Office StorePublish custom visuals to the Office store
TypeScriptTypeScript
Less CSSLess CSS

Altre domande?More questions? Provare a rivolgersi alla community di Power BITry asking the Power BI Community