Tutorial: Definir um evento personalizado em um componente

[Este tópico faz parte da documentação de pré-lançamento e está sujeito a alterações.]

Neste tutorial, você criará um componente de código que usa eventos personalizados e o testará usando aplicativos baseados em tela e modelos. Saiba mais sobre a visualização de eventos personalizados.

Goal

As etapas neste tutorial orientam você a criar um componente de código com dois botões que geram eventos diferentes para o aplicativo de hospedagem que pode reagir. Você definirá dois eventos: customEvent1 e customEvent2. Em seguida, o componente de código expõe dois botões que fazem com que esses eventos ocorram.

Aplicativo de Tela

O aplicativo de tela usa expressões do Power Fx nesses eventos para alternar as propriedades visíveis e de modo de exibição de um controle:

Aplicativo baseado em modelo

O aplicativo controlado por modelo usa o JavaScript do lado do cliente para mostrar um alerta quando os respectivos eventos ocorrem.

Pré-requisitos

Você já deve saber como:

• Criar e construir um componente de código
• Empacotar um componente de código
• Adicionar componentes de código a um aplicativo controlado por modelos
• Adicionar componentes a um aplicativo de tela

Criar um novo controle

1. Crie um novo componente usando este comando:

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

2. Editar o manifesto para adicionar os novos 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

EventSample\HelloWorld.tsx No arquivo de controle, defina dois eventos na interface e associe os eventos a dois botões diferentes. Atualize também a importação para incluir DefaultButton, conforme mostram as alterações a seguir.

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 updateview método

Em EventSample\Index.ts, modifique o método updateView para adicionar manipuladores para os dois eventos de botão. Esses manipuladores adicionam os dois eventos definidos no manifesto aos eventos no contexto passado para o controle.

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

Como de costume, você precisa concluir estas etapas para usar este controle:

1. Criar e compilar o componente de código
2. Empacote o componente de código
3. Implante o componente de código.

Usar em um aplicativo de tela

Para usar esse controle em um aplicativo de tela, você precisa:

1. Criar um novo aplicativo de tela em branco

2. Adicionar o novo componente ao aplicativo de tela

3. Adicione um novo controle. Este exemplo usa um controle de texto.

   

4. Adicione duas variáveis globais ao aplicativo: isVisible e canEdit.

5. Defina canEdit na propriedade DisplayMode do controle de texto.

   

6. Defina isVisible na propriedade Visible do controle de texto.

   

7. Defina ações personalizadas no novo controle personalizado para atualizar as isVisible variáveis e canEdit quando os botões forem clicados.

   

   Event	Expressão do Power FX
   customEvent1	If(isVisible, Set (isVisible, false), Set (isVisible, true))
   customEvent2	If(canEdit = DisplayMode.Edit, Set(canEdit, DisplayMode.Disabled), Set (canEdit, DisplayMode.Edit))

Testar o aplicativo de tela

1. Pressione Evento de gatilho 1.

   Esperado: o controle de texto alterna entre visível e oculto

2. Pressione Trigger event 2.

   Esperado: o controle de texto alterna entre editável e somente leitura.

Usar em um aplicativo baseado em modelo

1. Crie um novo recurso Web JavaScript para ser executado no onLoad evento de um formulário. Esse script associa dois manipuladores de eventos aos novos eventos dos controles ao carregar o formulário.

   /* 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. Conclua as seguintes etapas como você normalmente faz:

   1. Carregue seu novo arquivo JavaScript como um recurso da Web.
   2. Adicione o componente ao formulário controlado pelo modelo.
   3. Associe o webresource ao formulário.

3. Configure o evento On Load , conforme mostrado na imagem a seguir:

   

4. Teste seu aplicativo.

   Quando você vai até o formulário e pressiona Acionar evento 1, um alerta é exibido SampleControl1 Custom Event 1. Quando você pressiona Acionar evento 2, um alerta SampleControl1 Custom Event 2é exibido.

Passando conteúdo em eventos

Conforme descrito na definição de um evento para aplicativos controlados por modelos, você pode passar conteúdo em eventos em aplicativos controlados por modelos. Você pode modificar este exemplo da maneira a seguir para ver como isso funciona.

Enviar carga útil com o evento

Altere o EventSample\index.ts para que os eventos passem o payload da mensagem e, no segundo evento, também passem uma função de callback que altera uma variável 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
   );
}

Then:

1. Recompile e implante o componente.

2. Adicione outro campo ao formulário usado antes e defina-o para usar o novo componente.

   

Usar o conteúdo no manipulador de eventos

Atualize a onLoad função para definir os manipuladores de eventos nos controles personalizados para reagir a eventos de ambos os controles e também para usar os parâmetros que estão sendo passados

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

Testar o aplicativo controlado por modelos

1. Navegue até o formulário.

2. Pressione Trigger event 1 no primeiro campo.

   Esperado: uma janela pop-up exibe SampleControl1 Custom Event 1: Olá do evento 1 no primeiro campo.

3. Pressione Trigger event 2 no campo primeiro.

   Esperado: um pop-up exibe SampleControl1 Custom Event 2: Olá do evento 2 no primeiro campo, seguido de um alerta do primeiro controle informando A ação padrão do Evento 2 NÃO foi impedida

4. Pressione Trigger event 1 no campo second.

   Esperado: um pop-up exibe o Evento Personalizado SampleControl2 1: Olá do evento 1 no segundo campo.

5. Pressione Evento de acionamento 2 no segundo campo.

   Esperado: um pop-up exibe SampleControl2 Custom Event 2: Olá do evento 2 no segundo campo, seguido de um alerta do segundo controle que diz A ação padrão do Evento 2 foi impedida

Artigos relacionados

Definir Eventos (versão prévia)