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.

Goal

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 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
• Agregar 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

<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>

<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.

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>
    )
  }
}

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.

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

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. Implementar 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 aplicación de lienzo nueva desde cero

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. Establezca 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 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 desencadenante 1.

   Esperado: el control de texto alterna entre visible y oculto

2. Presione Evento desencadenante 2.

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

Usar en una aplicación basada en modelo

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 a su aplicación basada en formulario.
   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.

Pasar carga útil en eventos

Como se describe en Definición de un evento para aplicaciones basadas en modelo, puede pasar carga útil en eventos en aplicaciones basadas en modelos. Puede modificar este ejemplo de la siguiente manera para ver cómo funciona.

Pasar carga útil con evento

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

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

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 útil 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

/* 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);

/* 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 muestra SampleControl1 Evento personalizado 1: Hola del evento 1 en el primer campo.

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: una ventana emergente muestra SampleControl2 Evento personalizado 1: Hola del 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)