Tutorial: Definir un evento personalizado en un componente

[Este tema es documentación preliminar y está sujeto a modificaciones.]

En este tutorial, creará un componente de código que usa eventos personalizados y lo probará con aplicaciones lienzo y basadas en modelos. Más información sobre la vista previa de eventos personalizados.

Objetivo

Los pasos de este tutorial le guían para crear un componente de código con dos botones que generan diferentes eventos a los que puede reaccionar la aplicación de hospedaje. Definirá dos eventos: customEvent1 y customEvent2. A continuación, el componente de código expone dos botones que hacen que se produzcan estos eventos.

Aplicación de tipo lienzo

La aplicación de lienzo usa expresiones de Power Fx en estos eventos para alternar las propiedades de modo visible y de visualización de un control:

Aplicación basada en modelo

La aplicación basada en modelo usa el JavaScript del lado del cliente para mostrar una alerta cuando se producen los eventos respectivos.

Requisitos previos

Ya deberías saber cómo:

• Crear y generar un componente de código
• Empaquete un componente de código
• Agregar componentes de código a aplicaciones basadas en modelo
• Añadir componentes a una aplicación de lienzo

Crear un control nuevo

1. Crea un nuevo componente usando este comando:

   pac pcf init -n EventSample -ns SampleNamespace -t field -fw react -npm

2. Edite el manifiesto para agregar los nuevos eventos

Antes

<property name="sampleProperty"
   display-name-key="Property_Display_Key"
   description-key="Property_Desc_Key"
   of-type="SingleLine.Text"
   usage="bound"
   required="true" />
<resources>
   <code path="index.ts"
      order="1"/>
   <platform-library name="React"
      version="16.8.6" />
   <platform-library name="Fluent"
      version="8.29.0" />
   <css path="css/SampleEventPCF.css" order="1" />
   <resx path="strings/SampleEventPCF.1033.resx" version="1.0.0" />
</resources>

Después

<property name="sampleProperty"
   display-name-key="Property_Display_Key"
   description-key="Property_Desc_Key"
   of-type="SingleLine.Text"
   usage="bound"
   required="true" />
<event name="customEvent1"
   display-name-key="customEvent1"
   description-key="customEvent1"/>
<event name="customEvent2"
   display-name-key="customEvent2"
   description-key="customEvent2"/>
<resources>
   <code path="index.ts"
      order="1"/>
   <platform-library name="React"
      version="16.8.6" />
   <platform-library name="Fluent"
      version="8.29.0" />
   <css path="css/SampleEventPCF.css" order="1" />
   <resx path="strings/SampleEventPCF.1033.resx" version="1.0.0" />
</resources>

Definir eventos

En el archivo de control EventSample\HelloWorld.tsx, defina dos eventos en la interfaz y vincule los eventos a dos botones diferentes. Actualice también la importación para incluir DefaultButton como se muestra en los siguientes cambios.

Antes

import * as React from 'react';
import { Label } from '@fluentui/react';

export interface IHelloWorldProps {
  name?: string;
}

export class HelloWorld extends React.Component<IHelloWorldProps> {
  public render(): React.ReactNode {
    return (
      <Label>
        {this.props.name}
      </Label>
    )
  }
}

Después

import * as React from 'react';
import { Label, DefaultButton } from '@fluentui/react';

// This component renders two buttons each one will trigger an event passed via props

export interface IHelloWorldProps {
  onCustomEvent1: () => void;
  onCustomEvent2: () => void;
}

export const HelloWorld: React.FunctionComponent<IHelloWorldProps> = (props: IHelloWorldProps) => {
  return (
    <div>
      <Label>Control with event</Label>
      <DefaultButton onClick={props.onCustomEvent1}>Trigger event 1</DefaultButton>
      <DefaultButton onClick={props.onCustomEvent2}>Trigger event 2</DefaultButton>
    </div>
  );
};

Modificar el método updateview

En EventSample\Index.ts, modifique el método updateView para agregar controladores para los dos eventos de botón. Estos controladores agregan los dos eventos definidos en el manifiesto a los eventos en el contexto pasado al control.

Antes

public updateView(context: ComponentFramework.Context<IInputs>): React.ReactElement {
   const props: IHelloWorldProps = { name: 'Hello, World!' };
   return React.createElement(
      HelloWorld, props
   );
}

Después

public updateView(context: ComponentFramework.Context<IInputs>): React.ReactElement {
   const props: IHelloWorldProps = {
      onCustomEvent1: ()=> {
            context.events.customEvent1()
      },
      onCustomEvent2: () => {
            context.events.customEvent2()
      }
   };
   return React.createElement(
      HelloWorld, props
   );
}

Compilar y empaquetar

Como de costumbre, debe completar estos pasos para usar este control:

1. Crear y generar el componente de código
2. Empaquete el componente de código
3. Implemente el componente de código.

Usar en una aplicación de lienzo

Para usar este control en una aplicación de lienzo, necesita:

1. Crear una nueva aplicación de lienzo en blanco

2. Agregar el componente nuevo a la aplicación de lienzo

3. Agregar un control nuevo. En este ejemplo se usa un control de texto.

   

4. Agregue dos variables globales a la aplicación: isVisible y canEdit.

5. Establezca canEdit a la propiedad DisplayMode del control de texto.

   

6. Asigne isVisible a la propiedad Visible del control de texto.

   

7. Establezca acciones personalizadas en el nuevo control personalizado para actualizar las variables isVisible y canEdit cuando se hace clic en los botones.

   

   Evento	Expresión de Power Fx
   customEvent1	If(isVisible, Set (isVisible, false), Set (isVisible, true))
   customEvent2	If(canEdit = DisplayMode.Edit, Set(canEdit, DisplayMode.Disabled), Set (canEdit, DisplayMode.Edit))

Pruebe la aplicación de lienzo

1. Presione Evento de activación 1.

   Esperado: el control de texto alterna entre visible y oculto

2. Presione Evento desencadenador 2.

   Esperado: el control de texto alterna entre editable y de solo lectura.

Usar en una aplicación basada en los modelos

Nota

Estos pasos hacen referencia a las instrucciones descritas en Tutorial: Escribir el primer script de cliente.

1. Cree un nuevo recurso web de JavaScript para ejecutar en el evento onLoad de un formulario. Este script vincula dos controladores de eventos a los nuevos eventos para los controles al cargar el formulario.

   /* eslint-disable */
   "use strict";
   
   var MyScriptsNameSpace = window.MyScriptsNameSpace || {};
   (function () {
   
   const controlName1 = "cr116_personid";
   
   this.onLoad = function (executionContext) {
      const formContext = executionContext.getFormContext();
   
      const sampleControl1 = formContext.getControl(controlName1);
      sampleControl1.addEventHandler("customEvent1", this.onSampleControl1CustomEvent1);
      sampleControl1.addEventHandler("customEvent2", this.onSampleControl1CustomEvent2);
   };
   
   this.onSampleControl1CustomEvent1 = function (params) {
      alert(`SampleControl1 Custom Event 1`);
   }.bind(this);
   
   this.onSampleControl1CustomEvent2 = function (params) {
      alert(`SampleControl1 Custom Event 2`);
   }.bind(this);
   
   }).call(MyScriptsNameSpace);
   

2. Complete los pasos siguientes como hace normalmente:

   1. Cargue su nuevo archivo de JavaScript como un recurso web.
   2. Agregue el componente al formulario basado en modelos.
   3. Asocie el recurso web al formulario.

3. Configure el evento On Load como aparece en la imagen siguiente:

   

4. Probar la aplicación.

   Cuando navegue al formulario y presione Efecto desencadenante 1, se muestra una alerta SampleControl1 Custom Event 1. Al pulsar Efecto desencadenante 2, se muestra una alerta SampleControl1 Custom Event 2.

Transmitir carga útil en los eventos

Como se describe en Definir un evento para aplicaciones basadas en modelo, puede pasar datos de carga en los eventos de las aplicaciones basadas en modelo. Puede modificar este ejemplo de la siguiente manera para ver cómo funciona.

Enviar carga útil con el evento

Cambie el EventSample\index.ts para que los eventos pasen un mensaje como carga útil y, en el segundo evento, también pasen una función de devolución de llamada que cambie una variable interna

Antes

public updateView(context: ComponentFramework.Context<IInputs>): React.ReactElement {
   const props: IHelloWorldProps = {
      onCustomEvent1: ()=> {
            context.events.customEvent1()
      },
      onCustomEvent2: () => {
            context.events.customEvent2()
      }
   };
   return React.createElement(
      HelloWorld, props
   );
}

Después

public updateView(context: ComponentFramework.Context<IInputs>): React.ReactElement {
   const props: IHelloWorldProps = {
      onCustomEvent1: () => {
            // Trigger event with a string as payload 
            context.events.customEvent1("Hello from event 1")
      },
      onCustomEvent2: () => {
            let defaultPrevented = false;
            // Trigger event with a payload object and a preventDefault function
            context.events.customEvent2({ message: "Hello from event 2", preventDefault: () => { defaultPrevented = true } })

            // Check if the event was prevented
            if (defaultPrevented) {
               alert("Event 2 prevented default!");
            } else {
               alert("Event 2 default NOT prevented");
            }
      }
   };
   return React.createElement(
      HelloWorld, props
   );
}

A continuación:

1. Reconstruya e implemente el componente.

2. Agregue otro campo al formulario utilizado anteriormente y configúrelo también para usar el nuevo componente.

   

Usar la carga en el controlador de eventos

Actualice la función onLoad para configurar los controladores de eventos en los controles personalizados para reaccionar a los eventos de ambos controles y también para hacer uso de los parámetros que se pasan

Antes

/* eslint-disable */
"use strict";

var MyScriptsNameSpace = window.MyScriptsNameSpace || {};
(function () {

const controlName1 = "cr116_personid";

this.onLoad = function (executionContext) {
   const formContext = executionContext.getFormContext();

   const sampleControl1 = formContext.getControl(controlName1);
   sampleControl1.addEventHandler("customEvent1", this.onSampleControl1CustomEvent1);
   sampleControl1.addEventHandler("customEvent2", this.onSampleControl1CustomEvent2);
};

this.onSampleControl1CustomEvent1 = function (params) {
   alert(`SampleControl1 Custom Event 1`);
}.bind(this);

this.onSampleControl1CustomEvent2 = function (params) {
   alert(`SampleControl1 Custom Event 2`);
}.bind(this);

}).call(MyScriptsNameSpace);

Después

/* eslint-disable */
"use strict";

var MyScriptsNameSpace = window.MyScriptsNameSpace || {};
(function () {

const controlName1 = "cr116_personid";
const controlName2 = "cr116_haircolor";

this.onLoad = function (executionContext) {
   const formContext = executionContext.getFormContext();

   const sampleControl1 = formContext.getControl(controlName1);
   sampleControl1.addEventHandler("customEvent1", this.onSampleControl1CustomEvent1);
   sampleControl1.addEventHandler("customEvent2", this.onSampleControl1CustomEvent2);

   const sampleControl2 = formContext.getControl(controlName2);
   if (sampleControl2) {
      sampleControl2.addEventHandler("customEvent1", this.onSampleControl2CustomEvent1);
      sampleControl2.addEventHandler("customEvent2", this.onSampleControl2CustomEvent2);
   }
};

this.onSampleControl1CustomEvent1 = function (params) {
   alert(`SampleControl1 Custom Event 1: ${params.message}`);
}.bind(this);

this.onSampleControl1CustomEvent2 = function (params) {
   alert(`SampleControl1 Custom Event 2: ${params.message}`);
}.bind(this);

this.onSampleControl2CustomEvent1 = function (params) {
   alert(`SampleControl2 Custom Event 1: ${params}`);
}

this.onSampleControl2CustomEvent2 = function (params) {
   alert(`SampleControl2 Custom Event 2: ${params.message}`);
   // prevent the default action for the event
   params.preventDefault();
}*/
}).call(MyScriptsNameSpace);

Pruebe las aplicaciones basadas en modelos

1. Navegue al formulario.

2. Presione Efecto desencadenante 1 en el primer campo.

   Esperado: Una ventana emergente aparece en el primer campo con SampleControl1 Evento personalizado 1: Hola desde el evento 1.

3. Presione Efecto desencadenante 2 en el primer campo.

   Esperado: se muestra una ventana emergente SampleControl1 Evento personalizado 2: Hola desde el evento 2 en el primer campo seguido de una alerta del primer control que indica que el evento 2 predeterminado NO se ha impedido

4. Presione Efecto desencadenante 1 en el segundo campo.

   Esperado: Se muestra una ventana emergente con SampleControl2 Evento personalizado 1: Hola desde el evento 1 en el segundo campo.

5. Presione Efecto desencadenante 2 en el segundo campo.

   Esperado: se muestra una ventana emergente SampleControl2 Evento personalizado 2: Hola desde el evento 2 en el segundo campo seguido de una alerta del segundo control que indica que el evento 2 predeterminado se ha impedido

Artículos relacionados

Definir eventos (versión preliminar)