Tutorial: Adición de opciones de formato al objeto visual Circle Card

Al crear un objeto visual, puede agregar opciones para personalizar sus propiedades. Algunos de los elementos a los que se puede aplicar formato personalizado son los siguientes:

• Título
• Fondo
• Borde
• Shadow
• Colores

En este tutorial aprenderá a:

Requisito previo

En este tutorial se explica cómo agregar propiedades de formato comunes a un objeto visual. Se usará el objeto visual Circle Card como ejemplo. Se agregará la capacidad de cambiar el color y el grosor del círculo. Si no tiene la carpeta de proyecto Circle Card que ha creado en ese tutorial, repítalo antes de continuar.

Adición de opciones de formato

1. En PowerShell, vaya a la carpeta del proyecto Circle card e inicie el objeto visual Circle card. Su objeto visual ahora se ejecuta mientras está hospedado en el equipo.

   pbiviz start
   

2. En Power BI, seleccione la página Formato.

   Debería ver un mensaje que dice: Las opciones de formato no están disponibles para este objeto visual.

   

   Si aquí ve opciones de formato pero no puede cambiarlas, vaya a Adición de opciones de formato personalizado para personalizarlas.

3. Abra el archivo capabilities.json en Visual Studio Code.

4. Antes de la matriz dataViewMappings, agregue objects (después de la línea 8).

   "objects": {},
   

   

5. Guarde el archivo capabilities.json.

6. En Power BI, vuelva a revisar las opciones de formato.

   Nota

   Si no ve el cambio de opciones de formato, seleccione Reload Custom Visual (Recargar objeto visual personalizado).

   

7. Establezca la opción Title (Título) en Off (Desactivar). Tenga en cuenta que el objeto visual ya no muestra el nombre de medida en la esquina superior izquierda.

   

   

Adición de opciones de formato personalizadas

Ahora se agregará un nuevo grupo denominado color para configurar el color y el ancho del círculo.

1. Para detener el objeto visual personalizado, escriba Ctrl+C en PowerShell.

2. En Visual Studio Code, en el archivo capabilities.json, inserte el siguiente fragmento de JSON en el objeto que tiene la etiqueta objects.

       {
           "circle": {
               "displayName": "Circle",
               "properties": {
                   "circleColor": {
                       "displayName": "Color",
                       "description": "The fill color of the circle.",
                       "type": {
                           "fill": {
                               "solid": {
                                   "color": true
                               }
                           }
                       }
                   },
                   "circleThickness": {
                       "displayName": "Thickness",
                       "description": "The circle thickness.",
                       "type": {
                           "numeric": true
                       }
                   }
               }
           }
       }
   

   En el fragmento de JSON se describe un grupo denominado circle, que consta de dos variables: circleColor y circleThickness.

   

3. Guarde el archivo capabilities.json.

4. En el panel Explorador, vaya a la carpeta src y, después, seleccione settings.ts. Este archivo representa la configuración para el objeto visual de inicio.

5. En el archivo settings.ts, reemplace las dos clases por el código siguiente.

   export class CircleSettings {
       public circleColor: string = "white";
       public circleThickness: number = 2;
   }
   export class VisualSettings extends DataViewObjectsParser {
       public circle: CircleSettings = new CircleSettings();
   }
   

   

   Este módulo define las dos clases. La clase CircleSettings define dos propiedades con nombres que coinciden con los objetos definidos en el archivo capabilities.json (circleColor y circleThickness), y también establece valores predeterminados. La clase VisualSettings hereda la clase DataViewObjectParser y agrega una propiedad llamada circle, que coincide con el objeto definido en el archivo capabilities.json, y devuelve una instancia de CircleSettings.

6. Guarde el archivo settings.ts.

7. Abra el archivo visual.ts .

8. En el archivo visual.ts, importe VisualSettings, VisualObjectInstanceEnumeration y EnumerateVisualObjectInstancesOptions:

   import { VisualSettings } from "./settings";
   import VisualObjectInstanceEnumeration = powerbi.VisualObjectInstanceEnumeration;
   import EnumerateVisualObjectInstancesOptions = powerbi.EnumerateVisualObjectInstancesOptions;
   

   y en la clase Visual, agregue la siguiente propiedad:

   private visualSettings: VisualSettings;
   

   Esta propiedad almacena una referencia al objeto VisualSettings, que describe la configuración visual.

   

9. En la clase Visual, agregue el método siguiente antes del método update. Este método se usa para rellenar las opciones de formato.

   public enumerateObjectInstances(options: EnumerateVisualObjectInstancesOptions): VisualObjectInstanceEnumeration {
       const settings: VisualSettings = this.visualSettings || <VisualSettings>VisualSettings.getDefault();
       return VisualSettings.enumerateObjectInstances(settings, options);
   }
   

   Este método se usa para rellenar las opciones de formato.

   

10. En el método update, después de la declaración de la variable radius, agregue el código siguiente.

    this.visualSettings = VisualSettings.parse<VisualSettings>(dataView);
    
    this.visualSettings.circle.circleThickness = Math.max(0, this.visualSettings.circle.circleThickness);
    this.visualSettings.circle.circleThickness = Math.min(10, this.visualSettings.circle.circleThickness);
    

    Este código recupera las opciones de formato. Ajusta cualquier valor pasado a la propiedad circleThickness, convirtiéndolo en 0 si es negativo, o en 10 si es mayor de 10.

    

11. En el elemento circle, modifique los valores pasados al estilo de relleno y al estilo de ancho de trazo, como se muestra a continuación:

    this.visualSettings.circle.circleColor
    

    this.visualSettings.circle.circleThickness
    

    

12. Guarde el archivo visual.ts.

13. En PowerShell, inicie el objeto visual.

    pbiviz start
    

14. En Power BI, la barra de herramientas flotante sobre el objeto visual, seleccione Activar recarga automática.

    

15. En las opciones de formato del objeto visual, expanda Circle.

    

    Modifique las opciones de color y grosor.

    Modifique la opción de grosor a un valor inferior a cero y un valor superior a 10. A continuación, observe que el objeto visual actualiza el valor a un mínimo o máximo tolerable.

Empaquetado del objeto visual personalizado

Ahora que ha terminado el objeto visual y está listo para usarse, es momento de empaquetarlo. Un objeto visual empaquetado se puede importar a informes de Power BI u ofrecerlo para que otros usuarios lo puedan utilizar y disfrutar.

En esta sección, aprenderá a

• Escribir valores de propiedad para el proyecto de objeto visual personalizado en el archivo pbiviz.json.
• Actualizar el archivo de icono (icon.png).
• Por último, empaquetar el objeto visual personalizado.

Edición de los valores de propiedad del objeto visual

1. Para detener el objeto visual personalizado, escriba Ctrl+C en PowerShell.

2. Abra el archivo pbiviz.json en Visual Studio Code.

3. En el objeto visual, modifique la propiedad displayName en Circle Card.

   En el panel Visualizaciones, al mantener el cursor sobre el icono, se muestra el nombre.

   

4. En la propiedad description, escriba el texto siguiente.

   Muestra el valor de medida con formato dentro de un círculo

5. Rellene supportUrl y gitHubUrl para el objeto visual.

   Ejemplo:

   {
       "supportUrl": "https://community.powerbi.com",
       "gitHubUrl": "https://github.com/microsoft/PowerBI-visuals-circlecard"
   }
   

6. Escriba los detalles en el objeto author.

7. Guarde el archivo pbiviz.json.

Actualización del icono

1. En el objeto assets del archivo pbiviz.json, observe que el documento define una ruta de acceso a un icono. El icono es la imagen que aparece en el panel Visualizaciones. Debe ser un archivo PNG, 20 píxeles por 20 píxeles.

2. En el Explorador de Windows, copie el archivo icon.png y péguelo para reemplazar el archivo predeterminado ubicado en la carpeta assets.

3. En Visual Studio Code, en el panel Explorador, expanda la carpeta assets y, después, seleccione el archivo icon.png.

4. Revise el icono.

   

Empaquetar el objeto visual.

1. En Visual Studio Code, asegúrese de que se guardan todos los archivos.

2. Para empaquetar el objeto visual personalizado, escriba el comando siguiente en PowerShell.

   pbiviz package
   

Este comando crea un archivo pbiviz en el directorio dist/ del proyecto del objeto visual y sobrescribe cualquier archivo pbiviz anterior.

El paquete contiene todo lo necesario para importar el objeto visual personalizado en el servicio Power BI o en un informe de Power BI Desktop. Ha empaquetado el objeto visual personalizado y está listo para usarse.

Importación de objetos visuales personalizados

Ya está listo para importar el objeto visual personalizado Circle Card para poder usarlo en los informes. Siga las instrucciones de Importación de un archivo de objeto visual desde el equipo local a Power BI para importar el archivo circleCard.pbivizdesde la carpeta dist al informe de Power BI.

Depuración

Para obtener sugerencias sobre cómo depurar el objeto visual personalizado, consulte la guía de depuración.

Pasos siguientes