Crear el primer componente

En este tutorial, demostramos cómo crear un componente de código de control deslizante lineal que permite a los usuarios cambiar los valores numéricos utilizando un control deslizante visual en lugar de escribir los valores en la columna.

Nota

¿No está seguro de entidad frente a tabla? Vea Desarrolladores: comprender la terminología en Microsoft Dataverse.

Los siguientes pasos son necesarios para crear un componente de código deslizante lineal:

Requisitos previos

Para este tutorial, necesita instalar los siguientes componentes:

  1. Visual Studio Code (VSCode) (Asegúrese de que la opción Agregar a PATH esté seleccionada)
  2. node.js (Se recomienda la versión LTS)
  3. Microsoft Power Platform CLI (Utilice la extensión Visual Studio Code o el instalador MSI)
  4. Herramientas .NET Build instalando una de las siguientes: (Como mínimo, seleccione la carga de trabajo .NET build tools.)

Nota

Es posible que prefiera utilizar el .NET 5.x SDK en lugar de las herramientas de compilación para Visual Studio. En este caso, en lugar de usar msbuild usaría dotnet build.

Sugerencia

También se recomienda instalar git para control de código fuente.

Crear un nuevo proyecto de componente

Para crear un nuevo proyecto:

  1. Abra una ventana del símbolo del sistema. Cree una nueva carpeta para el proyecto usando el comando siguiente:

     mkdir LinearInput
    
  2. Abra su carpeta LinearInput dentro de Visual Studio Code. La forma más rápida de comenzar es usando cd LinearInput y luego ejecutando code . desde el símbolo del sistema una vez que esté en el directorio del proyecto. Este comando abre el proyecto de componente en Visual Studio Code.

  3. Abra una nueva terminal en Visual Studio Code usando Terminal -> Nueva terminal.

  4. En el símbolo de sistema de la terminal, cree un nuevo proyecto de componente pasando los parámetros básicos usando el comando.

     pac pcf init --namespace SampleNamespace --name LinearInputControl --template field
    
  5. El comando anterior también ejecuta el comando npm install para que configure las herramientas de creación del proyecto.

    Running 'npm install' for you...
    

    Nota

    Si recibe el error The term 'npm' is not recognized as the name of a cmdlet, function, script file, or operable program., asegúrese de haber instalado todos los requisitos previos, específicamente node.js (Se recomienda la versión LTS) y el resto de prerrequisitos.

  6. Después de instalar npm, tendrá que generar el archivo ManifestDesignTypes.d.ts en este directorio usando el comando siguiente."

    npm run refreshTypes
    

Implementar el manifiesto

El manifiesto de control es un archivo XML que contiene los metadatos del componente de código. También define el comportamiento del componente de código. En este tutorial, este archivo de manifiesto se crea en la subcarpeta LinearInputControl. Cuando abra el archivo ControlManifest.Input.xml en Visual Studio Code, observará que el archivo de manifiesto está predefinido con algunas propiedades. Más información: Manifiesto.

Realice cambios en el archivo de manifiesto predefinido, como se muestra aquí:

  1. El nodo control define el espacio de nombres, la versión y el nombre para mostrar del componente de código. Ahora, defina cada propiedad del nodo control como se muestra aquí:

    • espacio de nombres: Espacio de nombres del componente de código.

    • Constructor: Constructor del componente de código.

    • Versión: Versión del componente. Cada vez que actualice el componente, deberá actualizar la versión para ver los últimos cambios en tiempo de ejecución.

    • display-name-key: Nombre del componente de código que se muestra en la interfaz de usuario.

    • description-name-key: Descripción del componente de código que se muestra en la interfaz de usuario.

    • control-type: tipo de componente de código. Solo se admiten tipos estándar de componentes de código.

      <?xml version="1.0" encoding="utf-8" ?>
      <manifest>
      <control namespace="SampleNamespace" constructor="LinearInputControl" version="1.1.0" display-name-key="LinearInputControl_Display_Key" description-key="LinearInputControl_Desc_Key" control-type="standard">
      
  2. El nodo propiedades define las propiedades del componente de código, como l definición del tipo de datos de la columna. El nodo de la propiedad se especifica como elemento secundario bajo el elemento control. Defina el nodo propiedad como se muestra aquí:

    • name: Nombre de la propiedad.

    • display-name-key: Nombre para mostrar de la propiedad que se muestra en la interfaz de usuario.

    • description-name-key: Descripción de la propiedad que se muestra en la interfaz de usuario.

    • of-type-group: el of-type-group se utiliza cuando se desean tener más de dos columnas de tipo de datos. Agregue el elemento of-type-group como elemento del mismo nivel que el elemento property del manifiesto. El of-type-group especifica el valor de componente y puede contener valores enteros, de divisa, punto flotante, o decimales.

    • uso: Tiene dos propiedades, bound e input. Las propiedades vinculadas están vinculadas solo al valor de la columna. Las propiedades de entrada están vinculadas a una columna o permiten un valor estático.

    • requerida: Define si la propiedad es requerida o no

      <property name="controlValue" display-name-key="controlValue_Display_Key" description-key="controlValue_Desc_Key" of-type-group="numbers" usage="bound" required="true" />
      
  3. El nodo resources define la visualización del componente de código. Contiene todos los recursos que crean la visualización y el diseño del componente de código. El código se especifica como elemento secundario bajo el elemento recursos. Defina los recursos como se muestra aquí:

    • code: Hace referencia a la ruta de acceso donde se ubican todos los archivos de recursos.

      <resources>
         <code path="index.ts" order="1" />
         <css path="css/LinearInputControl.css" order="1" />
      </resources>
      

      El archivo de manifiesto general ser de este tipo:

      <?xml version="1.0" encoding="utf-8" ?>
      <manifest>
        <control namespace="SampleNamespace" constructor="LinearInputControl" version="1.1.0" display-name-key="LinearInputControl_Display_Key" description-key="LinearInputControl_Desc_Key" control-type="standard">
            <type-group name="numbers">
               <type>Whole.None</type>
               <type>Currency</type>
               <type>FP</type>
               <type>Decimal</type>
            </type-group>
            <property name="controlValue" display-name-key="controlValue_Display_Key" description-key="controlValue_Desc_Key" of-type-group="numbers" usage="bound" required="true" />
          <resources>
            <code path="index.ts" order="1" />
            <css path="css/LinearInputControl.css" order="1" />
          </resources>
        </control>
      </manifest>
      
  4. Guarde los cambios en el archivo ControlManifest.Input.xml.

Implementar lógica del componente

El siguiente paso después de implementar el archivo de manifiesto es implementar la lógica de componente con TypeScript. La lógica de componente se debe implementar en el archivo index.ts. Cuando abre el archivo index.ts en el Visual Studio Code, notará que las cuatro funciones esenciales están predefinidas. Ahora, implementemos la lógica para el componente de código.

  1. Abra el archivo index.ts en el editor de código que prefiera.
  2. Actualice la clase LinearInputControl con el siguiente código:
import { IInputs, IOutputs } from "./generated/ManifestTypes";

export class LinearInputControl implements ComponentFramework.StandardControl<IInputs, IOutputs> {
   private _value: number;
   private _notifyOutputChanged: () => void;
   private labelElement: HTMLLabelElement;
   private inputElement: HTMLInputElement;
   private _container: HTMLDivElement;
   private _context: ComponentFramework.Context<IInputs>;
   private _refreshData: EventListenerOrEventListenerObject;

   public init(context: ComponentFramework.Context<IInputs>, notifyOutputChanged: () => void, state: ComponentFramework.Dictionary, container: HTMLDivElement): void {
      this._context = context;
      this._container = document.createElement("div");
      this._notifyOutputChanged = notifyOutputChanged;
      this._refreshData = this.refreshData.bind(this);

      // creating HTML elements for the input type range and binding it to the function which refreshes the control data
      this.inputElement = document.createElement("input");
      this.inputElement.setAttribute("type", "range");
      this.inputElement.addEventListener("input", this._refreshData);

      //setting the max and min values for the control.
      this.inputElement.setAttribute("min", "1");
      this.inputElement.setAttribute("max", "1000");
      this.inputElement.setAttribute("class", "linearslider");
      this.inputElement.setAttribute("id", "linearrangeinput");

      // creating a HTML label element that shows the value that is set on the linear range control
      this.labelElement = document.createElement("label");
      this.labelElement.setAttribute("class", "LinearRangeLabel");
      this.labelElement.setAttribute("id", "lrclabel");

      // retrieving the latest value from the control and setting it to the HTMl elements.
      this._value = context.parameters.controlValue.raw!;
      this.inputElement.setAttribute("value", context.parameters.controlValue.formatted ? context.parameters.controlValue.formatted : "0");
      this.labelElement.innerHTML = context.parameters.controlValue.formatted ? context.parameters.controlValue.formatted : "0";

      // appending the HTML elements to the control's HTML container element.
      this._container.appendChild(this.inputElement);
      this._container.appendChild(this.labelElement);
      container.appendChild(this._container);
   }

   public refreshData(evt: Event): void {
      this._value = (this.inputElement.value as any) as number;
      this.labelElement.innerHTML = this.inputElement.value;
      this._notifyOutputChanged();
   }

   public updateView(context: ComponentFramework.Context<IInputs>): void {
      // storing the latest context from the control.
      this._value = context.parameters.controlValue.raw!;
      this._context = context;
      this.inputElement.setAttribute("value", context.parameters.controlValue.formatted ? context.parameters.controlValue.formatted : "");
      this.labelElement.innerHTML = context.parameters.controlValue.formatted ? context.parameters.controlValue.formatted : "";
   }

   public getOutputs(): IOutputs {
      return {
         controlValue: this._value
      };
   }

   public destroy(): void {
      this.inputElement.removeEventListener("input", this._refreshData);
   }
}
  1. Guarde los cambios en el archivo index.ts.

Agregar estilo al componente de código

Los programadores y proveedores de aplicaciones pueden definir el diseño para representar sus componentes de código visualmente usando CSS. CSS permite que los desarrolladores describan la presentación de componentes de código, incluidos estilo, colores, diseños, y fuentes. El método init del componente de entrada lineal crea un elemento de entrada y establece el atributo de clase en linearslider. El estilo para la clase linearslider se define en un archivo CSS aparte. Recursos de componente adicionales como CSS se pueden incluir con el componente de código para admitir otras personalizaciones.

Importante

Cuando implemente estilos en sus componentes de código mediante CSS, asegúrese de que el ámbito de CSS es el control. Para ello, use las clases CSS generadas automáticamente y aplíqueselas al elemento DIV del contenedor para el componente. Si el código CSS tiene un ámbito global, es probable que rompa el estilo existente del formulario o la pantalla donde se representa el componente de código. Si usa un marco de trabajo CSS de terceros, debe usar una versión que ya tenga espacio de nombres o, de lo contrario, encapsular ese marco en un espacio de nombres, ya sea manualmente o mediante un preprocesador de CSS.

  1. Cree una nueva subcarpeta css en la carpeta LinearInputControl.

  2. Cree un nuevo archivo LinearInputControl.css en la subcarpeta css.

  3. Agregue el siguiente contenido de estilo al archivo LinearInputControl.css:

    .SampleNamespace\.LinearInputControl input[type=range].linearslider {   
       margin: 1px 0;   
       background:transparent;
       -webkit-appearance:none;
       width:100%;padding:0;
       height:24px;
       -webkit-tap-highlight-color:transparent
    }
    .SampleNamespace\.LinearInputControl input[type=range].linearslider:focus {
       outline: none;
    }
    .SampleNamespace\.LinearInputControl input[type=range].linearslider::-webkit-slider-runnable-track {   
       background: #666;
       height:2px;
       cursor:pointer
    }   
    .SampleNamespace\.LinearInputControl input[type=range].linearslider::-webkit-slider-thumb {   
       background: #666;   
       border:0 solid #f00;
       height:24px;
       width:10px;
       border-radius:48px;
       cursor:pointer;
       opacity:1;
       -webkit-appearance:none;
       margin-top:-12px
    }    
    .SampleNamespace\.LinearInputControl input[type=range].linearslider::-moz-range-track {   
       background: #666;   
       height:2px;
       cursor:pointer  
    }   
    .SampleNamespace\.LinearInputControl input[type=range].linearslider::-moz-range-thumb {   
       background: #666;   
       border:0 solid #f00;
       height:24px;
       width:10px;
       border-radius:48px;
       cursor:pointer;
       opacity:1;
       -webkit-appearance:none;
       margin-top:-12px
    }   
    .SampleNamespace\.LinearInputControl input[type=range].linearslider::-ms-track {   
       background: #666;   
       height:2px;
       cursor:pointer  
    }    
    .SampleNamespace\.LinearInputControl input[type=range].linearslider::-ms-thumb {   
       background: #666;   
       border:0 solid #f00;
       height:24px;
       width:10px;
       border-radius:48px;
       cursor:pointer;
       opacity:1;
       -webkit-appearance:none;
    }
    
  4. Guarde el archivo LinearInputControl.css.

  5. Tenga en cuenta que el archivo ControlManifest.Input.xml incluye el archivo de recurso CSS en el elemento de recursos.

    <resources> 
      <code path="index.ts" order="1"/> 
      <css path="css/LinearInputControl.css" order="1"/> 
    </resources> 
    

Nota

Power Apps component framework usa el concepto de implementar recursos web String(resx) que se usa para administrar las cadenas localizadas mostradas en cualquier interfaz de usuario. Más información: String(Resx) recursos web. Vea la muestra de la API de localización, para aprender cómo localizar componentes de código usando recursos web resx.

Crear sus componentes de código

Después de terminar de agregar manifiesto, lógica de componentes y estilo, compile los componentes del código con el comando:

npm run build

La generación crea un archivo de declaración de tipo TypeScript actualizado en la carpeta LinearInputControl/generated. El componente se compila en la carpeta out/controls/LinearInputControl. Los artefactos de compilación incluyen:

  • bundle.js – Código origen del componente agrupado.
  • ControlManifest.xml – Archivo de manifiesto del componente real que se carga en la organización de Microsoft Dataverse.

Depurar el componente de código

Una vez que termine de implementar la lógica del componente de código, ejecute el siguiente comando de iniciar el proceso de depuración. Más información: Depurar componentes de código

npm start watch

Empaquetar componentes de código

Siga estos pasos para crear e importar un archivo de solución:

  1. Cree una nueva carpeta Solutions dentro de la carpeta LinearInputControl y vaya a la carpeta.

  2. Cree un nuevo proyecto de solución en la carpeta LinearInputControl usando el comando siguiente:

      pac solution init --publisher-name Samples --publisher-prefix samples 
    

    Nota

    Los valores publisher-name y publisher-prefix deben ser los mismos que un editor de soluciones existente o uno nuevo que desee crear en su entorno de destino.

  3. Cuando se crea el nuevo proyecto de solución, debe hacer referencia a la ubicación donde se ubica el componente creado. Puede agregar la referencia usando el comando siguiente:

     pac solution add-reference --path ..\
    

    Nota

    La ruta provista aquí está relacionada con la actual carpeta Solutions que se creó debajo de la carpeta LinearInputControl. También puede proporcionar una ruta absoluta.

  4. Para generar un archivo zip del proyecto de la solución, cuando esté dentro del directorio del proyecto de la solución cdsproj, use el comando siguiente:

    msbuild /t:restore
    

    O si ha instalado .NET 5 SDK:

    dotnet build
    
  5. Ejecute de nuevo el siguiente comando:

    msbuild
    

    Nota

    Si recibe el error Missing required tool: MSBuild.exe/dotnet.exe. Agregue MSBuild.exe/dotnet.exe en la variable de entorno Path o use Developer Command Prompt for Visual Studio Code. Como se menciona en los Requisitos previos, debe instalar las herramientas de compilación .NET.

    Sugerencia

    Verá el mensaje No utilice la función eval o sus equivalentes funcionales, cuando crea el archivo de solución con el comando msbuild y lo importa a Dataverse y ejecuta el comprobador de soluciones. Vuelva a crear el archivo de la solución usando el comando msbuild/property:configuration=Release y vuelva a importar la solución a Dataverse y ejecute el comprobador de soluciones. Más información: Depurar componentes de código.

  6. El archivo zip generado de la solución se encuentra en la carpeta Solution\bin\debug.

  7. Importe manualmente la solución en Dataverse con el portal web una vez que el archivo zip esté listo o usando automáticamente la herramienta de compilación de Microsoft Power Platform.

Nota

Publicar manualmente las personalizaciones si está importanto una solución no administrada.

Agregar componentes código en aplicaciones basadas en modelo

Para agregar un componente de código como un componente de entrada lineal, siga los pasos mencionados en el artículo Agregar componentes a columnas y tablas.

Agregar componentes de código a una aplicación de lienzo

Para agregar los componentes del código a una aplicación de lienzo, siga los pasos del artículo Agregar componentes de código a una aplicación de lienzo.

Agregar componentes de código a un portal

Para agregar el componente de código a un portal, siga los pasos del artículo Usar componentes de código en portales.

Consultar también

Descargar componentes de ejemplo
Más información sobre Power Apps component framework
Actualizar componentes existentes de Power Apps component framework
Microsoft Power Platform Build Tools
Referencia de la API de Power Apps component framework
Información general sobre Power Apps component framework
Depurar componentes de código

Nota

¿Puede indicarnos sus preferencias de idioma de documentación? Realice una breve encuesta. (tenga en cuenta que esta encuesta está en inglés)

La encuesta durará unos siete minutos. No se recopilan datos personales (declaración de privacidad).