Usar herramientas de desarrollo para crear objetos visuales personalizadosUse developer tools to create custom visuals

Los objetos visuales personalizados le permiten satisfacer las necesidades de los usuarios y adaptarse al diseño de su aplicación.Custom visuals allow you to meet your users' needs and match your app's design. Descubra cómo crear un objeto visual personalizado para Power BI con las herramientas de desarrollo.Learn how to create a custom visual for Power BI using the developer tools.

Nota

Puede usar este documento para comenzar.You can use this document to get up and running. Para obtener información detallada, consulte la información de referencia del repositorio de Git Power BI Visuals (Objetos visuales de Power BI).For more in-depth information, see the reference information within the Power BI Visuals git repo.

RequisitosRequirements

Instalar NodeJS y las herramientas de Power BIInstall NodeJS and the Power BI tools

Para crear un objeto visual personalizado, debe instalar NodeJS.In order to create a custom visual, you will need to install NodeJS. Se necesita NodeJS para ejecutar las herramientas de línea de comandos.NodeJS is required to run the command line tools.

  1. Descargue e instale NodeJS.Download and install NodeJS. Se requiere la versión 4.0 o posterior, pero se recomienda tener la versión 5.0 o posterior.Version 4.0 or later is required but it is recommended to have 5.0 or later.

  2. Instale las herramientas de línea de comandos.Install the command line tools. Ejecute el siguiente comando desde un símbolo del sistema.Run the following command from a command prompt.

     npm install -g powerbi-visuals-tools
    
  3. Ejecute el siguiente comando sin parámetros para confirmar que se han instalado las herramientas.You can confirm that the tools are installed by running the following command without any parameters.

     pbiviz
    

    Debería ver el resultado de la ayuda.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
     

Configuración del certificado de servidorServer Certificate setup

Para habilitar una vista previa dinámica del objeto visual, se necesita un servidor https de confianza.To enable a live preview of your visual, a trusted https server is needed. Antes de comenzar, debe instalar un certificado SSL que permitirá que se carguen los activos del objeto visual en el explorador web.Before you can start, you will need to install an SSL certificate which will allow visual assets to load in your web browser.

Nota

Se trata de una configuración única de la estación de trabajo del desarrollador.This is a one-time setup for your developer workstation.

Para crear un certificado, ejecute el siguiente comando.To create a certificate, run the following command.

pbiviz --create-cert

Nota

Debería ver un mensaje indicándole la ruta de acceso de ubicación del certificado y una frase de contraseña recién generada.You should see a message telling you the location path to the certificate and a newly generated Passphrase.

Para instalar el certificado, ejecute el siguiente comando.To install the certificate, run the following command.

pbiviz --install-cert

Nota

Debería ver un mensaje indicándole que use su frase de contraseña recién generada para instalar un certificado PFX.You should see a message telling you to use your newly generated Passphrase to install a PFX certificate.

SO WindowsWindows OS

  1. Seleccione Instalar certificado...Select Install Certificate....

  2. Seleccione Usuario actual y después seleccione Siguiente.Select Current User and then select Next.

  3. Seleccione Colocar todos los certificados en el siguiente almacén y seleccione Examinar....Select Place all certificate in the following store and select Browse....

  4. Seleccione Entidades de certificación raíz de confianza y luego seleccione Aceptar.Select Trusted Root Certification Authorities and then select OK. Seleccione Siguiente.Select Next.

  5. Seleccione Finalizar.Select Finish.

  6. Seleccione en el cuadro de diálogo de advertencia de seguridad.Select Yes on the security warning dialog.

  7. Cierre los exploradores que tenga abiertos.Close any browsers that you have open.

Nota

Si no se reconoce el certificado, deberá reiniciar el equipo.If the certificate is not recognized, you may need to restart your computer.

OSXOSX

  1. Si el candado de la parte superior izquierda está bloqueado, selecciónelo para desbloquearlo.If the lock in the upper left is locked, select it to unlock. Busque localhost y haga doble clic en el certificado.Search for localhost and double click on the certificate.

  2. Seleccione Confiar siempre y cierre la ventana.Select Always Trust and close the window.

  3. Escriba el nombre de usuario y contraseña.Enter your username and password. Seleccione Actualizar configuración.Select Update Settings.

  4. Cierre los exploradores que tenga abiertos.Close any browsers that you have open.

Nota

Si no se reconoce el certificado, deberá reiniciar el equipo.If the certificate is not recognized, you may need to restart your computer.

Habilitar la vista previa dinámica del objeto visual de desarrolladorEnable live preview of developer visual

Para habilitar una vista previa dinámica de su objeto visual personalizado, siga estos pasos.To enable a live preview of your custom visual, follow these steps. Esto permite que el objeto visual se use en el servicio Power BI al editar informes.This allows the visual to be used within the Power BI service when editing reports.

  1. Vaya a app.powerbi.com e inicie sesión.Browse and sign into app.powerbi.com.

  2. Seleccione el icono de engranaje y después seleccione Configuración.Select the gear icon and then select Settings.

  3. Seleccione Desarrollador y luego seleccione Habilitar objeto visual de desarrollador para realizar pruebas.Select Developer and then select Enable developer visual for testing.

  4. Seleccione el Objeto visual de desarrollador en el panel Visualización.Select the Developer Visual in the Visualization pane.

    Nota

    Esto requiere que se ejecute pbiviz start desde la carpeta del objeto visual en el equipo de desarrollo.This requires that you have run pbiviz start from the visual folder on your development machine. Para obtener más información sobre cómo crear el objeto visual, consulte Crear un nuevo objeto visual en este artículo.For more information on creating your visual, see Create a new visual in this article.

  5. Seleccione el objeto visual en el lienzo del informe.Select the visual in the report canvas. Puede enlazar datos de la misma forma que otros objetos visuales.You can bind data in the same way you do other visuals.

Ahora puede comenzar a desarrollar el objeto visual.You can now begin developing your visual.

Crear un nuevo objeto visualCreate a new visual

Para crear un nuevo proyecto de objeto visual, ejecute el comando siguiente.You can create a new visual project by running the following command.

pbiviz new MyVisualName

Puede reemplazar MyVisualName por el nombre que quiera darle al objeto visual.You can replace MyVisualName with the name you want to give the visual. Se puede cambiar más adelante si modifica los campos name y displayName del archivo pbiviz.json generado.This can be changed later by modifying the name and displayName fields within the generated pbiviz.json file.

Este comando creará una nueva carpeta en el directorio en el que se ha ejecutado el comando.This command will create a new folder in the direct where the command was run. Generará una plantilla de inicio básica para el objeto visual.It will generate a basic starter template for your visual. Una vez completado el comando, puede abrir el directorio y usar su editor favorito para empezar a trabajar en el nuevo objeto visual.Once the command completes, you can open the directory and use your favorite editor to start working on your new visual.

Probar el objeto visual en Power BITesting your visual in Power BI

Puede probar el objeto visual en el servicio Power BI en informes y paneles.You can test your visual within the Power BI service within reports and dashboards.

Ejecutar el objeto visualRunning your visual

Puede ejecutar el objeto visual de la siguiente forma.You can run your visual by doing the following.

  1. Abra un símbolo del sistema.Open a prompt.

  2. Cambie el directorio para que sea la carpeta del objeto visual.Change your directory to be your visual folder. Esta es la carpeta que contiene el archivo pbiviz.json.This is the folder that contains the pbiviz.json file.

  3. Ejecute el siguiente comando.Run the following command.

    pbiviz start
    

Si se encuentra en una ubicación incorrecta, verá un error similar al siguiente.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)

Ver el objeto visual en Power BIViewing your visual in Power BI

Para ver el objeto visual en un informe, vaya a ese informe y seleccione el objeto visual en el panel Visualizaciones.To view your visual in a report, go to that report and select the visual within the Visualizations pane.

Nota

Debe ejecutar el comando pbiviz start antes de hacerlo, como se describe en la sección Ejecutar el objeto visual.You must run the pbiviz start command before doing this as discribed in the Running your visual section.

Verá la plantilla de inicio del objeto visual.You will then see the starter template for the visual.

Elemento de la barra de herramientasToolbar item DescripciónDescription
Actualizar objeto visualRefresh visual Actualice el objeto visual de forma manual si la recarga automática está deshabilitada.Manually refresh the visual if auto reload is disabled.
Activar recarga automáticaToggle auto reload Cuando está activada, el objeto visual se actualizará de forma automática cada vez que guarde el archivo.When turned on, the visual will automatically update every time you save your visual file.
Mostrar vista de datosShow dataview Muestra la vista de datos subyacente del objeto visual para la depuraciónShows the visual's underlying data view for debugging
Obtener ayudaGet help Documentación en GitHubDocumentation within GitHub
Enviar comentariosSend feedback Háganos saber si hay alguna forma en la que podemos mejorar la experiencia.Let us know if there is anyway we can improve the experience! (Se necesita una cuenta de GitHub)(Requires GitHub account)

Empaquetar el objeto visual para usar en Power BI Desktop y distribuirloPackage your visual for use in Power BI Desktop and distribution

Para poder cargar el objeto visual en Power BI Desktop o compartirlo con la comunidad en la galería de Power BI Visual, debe generar un archivo 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.

Puede empaquetar el objeto visual de la siguiente forma.You can package your visual by doing the following.

  1. Abra un símbolo del sistema.Open a prompt.

  2. Cambie el directorio para que sea la carpeta del objeto visual.Change your directory to be your visual folder. Esta es la carpeta que contiene el archivo pbiviz.json.This is the folder that contains the pbiviz.json file.

  3. Ejecute el siguiente comando.Run the following command.

    pbiviz package
    

Este comando creará un pbiviz en el directorio dist/ del proyecto del objeto visual.This command will create a pbiviz in the dist/ directory of your visual project. Si ya hay un archivo pbiviz, se sobrescribirá.If there is already a pbiviz file present, it will be overwritten.

Actualizar la versión de la API de los objetos visualesUpdating the visuals API version

Al crear un objeto visual mediante pbiviz new, se copia en el directorio del objeto visual una copia de las definiciones de tipo de API y los esquemas de JSON adecuados.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. Puede usar el comando pbiviz update para actualizar estos archivos si es necesario.You can use the pbiviz update command to update these files if needed. Esto puede ser útil si lanzamos una corrección de una versión anterior de la API o si quiere actualizar a la última versión de la API.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.

Actualizar la versión existente de la APIUpdating your existing API version

Si se lanza una actualización de una API existente, puede obtener la última versión mediante el procedimiento siguiente.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

Esto descargará las herramientas más recientes de npm, que incluyen los esquemas y definiciones de tipo actualizados.This will download the latest tools from npm which include the updated type definitions and schemas. Mediante pbiviz update, sobrescribirá la propiedad apiVersion en el archivo pbiviz.json con la última versión.Using pbiviz update will overwrite the apiVersion property in your pbiviz.json fiel with the latest version.

Actualizar a una versión diferente de la APIUpgrading to a different API version

Puede actualizar a una versión diferente de la API si sigue los mismos pasos que se han mencionado anteriormente.You can update to a different API version by using the same steps as mentioned above. Puede especificar explícitamente la versión de la API que quiere usar.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

Esto actualizará el objeto visual a la versión 1.2.0 de la API.This would update yoru visual to API version 1.2.0. Puede reemplazar 1.2.0 con cualquier versión que quiera usar.You can replace 1.2.0 with whatever version your wanting to use.

Advertencia

La versión predeterminada de la API que usan las herramientas siempre será la versión estable de la API.The default API version used by the tools will always be the stable version of the API. Las versiones posteriores a la versión predeterminada de la API son inestables y están sujetas a cambios.Any versions later than the default API version are unstable and subject to change. Pueden tener un comportamiento inesperado y comportarse de forma diferente en el servicio Power BI y Power BI Desktop.They may have unexpected behaviors and behave differently between the Power BI service and Power BI Desktop. Para ver la versión actual de la API estable, consulte el registro de cambios.For the current stable API version, see the change log. Para obtener más información sobre las versiones preliminares, consulte el mapa de ruta.For more information about pre-release versions, see the roadmap.

Dentro del proyecto del objeto visualInside the visual project

El proyecto del objeto visual es la carpeta que se crea al ejecutar el comando pbiviz new.Your visual project is the folder that gets created when you run the pbiviz new command.

Estructura de archivosFile structure

Item (Elemento)Item DescripciónDescription
assets/assets/ Se usa para almacenar los activos del objeto visual (icono, capturas de pantalla, etc.).Used to store visual assets (icon, screenshots, etc).
dist/dist/ Al ejecutar pbiviz package, se generará aquí el archivo pbiviz.When you run pbiviz package, the pbiviz file will be generated here.
src/src/ Código de TypeScript para el objeto visual.Typescript code for your visual.
style/style/ Estilos de Less para el objeto visual.Less styles for your visual.
.gitignore.gitignore Indica a Git que omita los archivos a los que no se les debe realizar el seguimiento en el repositorio.Tells git to ignore files that shouldn't be tracked in the repository.
capabilities.jsoncapabilities.json Se usa para definir las capacidades del objeto visual.Used to define the capabilities of your visual.
package.jsonpackage.json Lo usa npm para administrar los módulos.Used by npm to manage modules.
pbiviz.jsonpbiviz.json Archivo de configuración principal.Main configuration file.
tsconfig.jsontsconfig.json Configuración de compilador de TypeScript.Typescript compiler settings. Obtenga más información sobre tsconfig.json.Learn more about tsconfig.json.

pbiviz.jsonpbiviz.json

Este es el archivo de configuración principal del objeto visual.This file is the main configuration file for your visual. Contiene metadatos, así como información sobre los archivos, necesarios para compilar el objeto visual.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 
}

Origen del objeto visual (TypeScript)Visual source (TypeScript)

El código del objeto visual debe escribirse en TypeScript, que es un superconjunto de JavaScript que admite características más avanzadas y acceso anticipado a la funcionalidad de 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.

Todos los archivos de TypeScript deben almacenarse en el directorio src/ y agregarse a la matriz files en tsconfig.json.All TypeScript files should be stored in the src/ directory and added to the files array in tsconfig.json. Esto permite que el compilador de TypeScript los cargue y determine en qué orden.This allows the TypeScript compiler to load them and in what order.

Cuando se crea el objeto visual, todo el TypeScript se compilará en un único archivo de JavaScript.When your visual is built, all of the TypeScript will be compiled into a single JavaScript file. Esto le permite hacer referencia a los elementos exportados desde otros archivos sin necesidad de requerirlos manualmente mediante require siempre que ambos archivos se muestren en 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.

Puede crear tantos archivos y clases como necesite para crear el objeto visual.You can create as many files and classes as you need to create your visual.

Obtenga más información sobre TypeScript.Learn more about TypeScript.

Estilo de objeto visual (Less)Visual style (Less)

La aplicación de estilos de objeto visual se administra mediante hojas de estilos CSS.Visual styling is handled using cascading style sheets (CSS). Para su comodidad, usamos el precompilador Less, que admite algunas características avanzadas (por ejemplo, el anidamiento, variables, mixins, condiciones, bucles, etc.). Si no quiere usar ninguna de estas características, puede escribir CSS plano en el archivo de 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.

Todos los archivos de Less deben estar almacenados en el directorio style/.All Less files should be stored in the style/ directory. Se cargará el archivo especificado en el campo style del archivo pbiviz.json.The file specified under the style field within your pbiviz.json file will be loaded. Los archivos adicionales se deben cargar mediante @import.Any additional files should be loaded using @import.

Obtenga más información sobre Less.Learn more about Less.

DepuraciónDebugging

Para obtener sugerencias sobre cómo depurar el objeto visual personalizado, consulte la guía de depuración.For tips about debugging your custom visual, see the debugging guide.

Envío de un objeto visual a AppSourceSubmit your visual to AppSource

Puede enumerar los objetos visuales para que los usen otras personas y enviarlos a AppSource.You can list your visual for others to use but submitting it to AppSource. Para más información acerca de este proceso, consulte Publicación de objetos visuales personalizados en la Tienda Office.For more information on this process, see publish custom visuals to AppSource.

Solución de problemasTroubleshooting

No se ha encontrado el comando de pbiviz (o errores similares)Pbiviz command not found (or similar errors)

Si ejecuta pbiviz en la terminal o línea de comandos, verá la pantalla de ayuda.If you run pbiviz in your terminal / command line, you should see the help screen. De lo contrario, no está instalado correctamente.If not, it is not installed correctly. Asegúrese de que tiene instalada al menos la versión 4.0 de NodeJS.Make sure you have at least the 4.0 version of NodeJS installed.

Para obtener más información, consulte Instalar NodeJS y las herramientas de Power BI...For more information, see Install NodeJS and the Power BI tools...

No se puede encontrar el objeto visual de depuración en la pestaña VisualizacionesCannot find the debug visual in the Visualizations tab

El objeto visual de depuración es similar a un icono de símbolo del sistema en la pestaña Visualizaciones.The debug visual looks like a prompt icon within the Visualizations tab.

Si no lo ve, asegúrese de que lo ha habilitado en la configuración de Power BI.If you don't see it, make sure you have enabled it within the Power BI settings.

Nota

Actualmente, el objeto visual de depuración solo está disponible en el servicio Power BI y no está en Power BI Desktop ni en la aplicación móvil.The debug visual is currently only available in the Power BI service and not in Power BI Desktop or the mobile app. El objeto visual empaquetado seguirá funcionando en todas partes.The packaged visual will still work everywhere.

Para obtener más información, consulte Habilitar la vista previa dinámica del objeto visual de desarrollador...For more information, see Enable live preview of developer visual...

No puede ponerse en contacto con el servidor del objeto visualCan't contact visual server

Ejecute el servidor del objeto visual con el comando pbiviz start en la terminal o línea de comandos desde la raíz del proyecto del objeto visual.Run the visual server with the command pbiviz start in your terminal / command line from the root of your visual project. Si el servidor se está ejecutando, es probable que los certificados SSL no se hayan instalado correctamente.If the server is running, it is likely that your SSL vertificates weren't installed correctly.

Para obtener más información, consulte Ejecutar el objeto visual o Configuración del certificado de servidor.For more information, see Running your visual or Server certificate setup.

Pasos siguientesNext steps

Visualizaciones en Power BIVisualizations in Power BI
Visualizaciones personalizadas en Power BICustom Visualizations in Power BI
Publicación de objetos visuales personalizados en la Tienda OfficePublish custom visuals to the Office store
TypeScriptTypeScript
Less CSSLess CSS

¿Tiene más preguntas?More questions? Pruebe a preguntar a la comunidad de Power BITry asking the Power BI Community