Tutoriel : Définir un événement personnalisé dans un composant

[Cette rubrique fait partie de la documentation en version préliminaire et peut faire l’objet de modifications.]

Dans ce tutoriel, vous allez créer un composant de code qui utilise des événements personnalisés et le tester à l’aide de canevas et d’applications basées sur des modèles. En savoir plus sur l’aperçu des événements personnalisés.

Objectif

Les étapes décrites dans ce tutoriel vous guident pour créer un composant de code avec deux boutons qui déclenchent des événements différents pour l’application d’hébergement. Vous allez définir deux événements : customEvent1 et customEvent2. Ensuite, le composant de code expose deux boutons qui provoquent l’exécution de ces événements.

Application canevas

L'application canevas utilise des expressions Power Fx sur ces événements pour basculer les propriétés de visibilité et de mode d'affichage d'un contrôle.

Application basée sur un modèle

L’application pilotée par modèle utilise JavaScript côté client pour afficher une alerte lorsque les événements respectifs se produisent.

Prerequisites

Vous devez déjà savoir comment :

• Créer et générer un composant de code
• Empaqueter un composant de code
• Ajouter des composants de code à une application basée sur des modèles
• Ajouter des composants à une application canevas

Créer un contrôle

1. Créez un composant à l’aide de cette commande :

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

2. Modifier le manifeste pour ajouter les nouveaux événements

Avant

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

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

Définir des événements

Dans le EventSample\HelloWorld.tsx fichier de contrôle, définissez deux événements dans l’interface et liez les événements à deux boutons différents. Mettez également à jour l'importation pour inclure DefaultButton comme le montrent les modifications suivantes.

Avant

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

Aprè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>
  );
};

Modifier updateview la méthode

Dans EventSample\Index.ts, modifiez la méthode updateView pour ajouter des gestionnaires pour les deux événements de bouton. Ces gestionnaires ajoutent les deux événements définis dans le manifeste aux événements dans le contexte passé au contrôle.

Avant

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

Aprè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
   );
}

Générer et empaqueter

Comme d’habitude, vous devez effectuer ces étapes pour utiliser ce contrôle :

1. Créer et générer le composant de code
2. Créer un package de composant de code
3. Déployer le composant de code

Utiliser dans une application canevas

Pour utiliser ce contrôle dans une application canevas, vous devez :

1. Créer une nouvelle application Canvas vide

2. Ajouter le nouveau composant à l’application canevas

3. Ajoutez un nouveau contrôle. Cet exemple utilise un contrôle de texte.

   

4. Ajoutez deux variables globales à l’application : isVisible et canEdit.

5. Affectez canEdit à la propriété DisplayMode du contrôle de texte.

   

6. Définissez isVisible sur la propriété Visible du contrôle de texte.

   

7. Définissez des actions personnalisées sur le nouveau contrôle personnalisé pour mettre à jour les variables isVisible et canEdit lorsque les boutons sont cliqués.

   

   Événement	Expression Power FX
   customEvent1	If(isVisible, Set (isVisible, false), Set (isVisible, true))
   customEvent2	If(canEdit = DisplayMode.Edit, Set(canEdit, DisplayMode.Disabled), Set (canEdit, DisplayMode.Edit))

Tester l'application canvas

1. Appuyez sur Déclencher l'événement 1.

   Attendu : le contrôle de texte permute entre Visible et Masqué

2. Déclenchez l'événement 2.

   Attendu : le contrôle de texte permute entre Modifiable et Lecture seule.

Utiliser dans une application pilotée par modèle

Note

Ces étapes font référence aux instructions décrites dans La procédure pas à pas : écrire votre premier script client.

1. Créez une ressource web JavaScript à exécuter sur l’événement onLoad d’un formulaire. Ce script lie deux gestionnaires d’événements aux nouveaux événements pour les contrôles lors du chargement du formulaire.

   /* 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. Effectuez les étapes suivantes comme vous le faites normalement :

   1. Chargez votre nouveau fichier JavaScript en tant que ressource web.
   2. Ajoutez le composant au formulaire piloté par modèle.
   3. Associez la ressource web au formulaire.

3. Configurez l’événement On Load comme indiqué dans l’image suivante :

   

4. Testez votre application.

   Lorsque vous accédez au formulaire et appuyez sur l’événement Déclencheur 1, une alerte s’affiche SampleControl1 Custom Event 1. Lorsque vous appuyez sur l’événement Déclencheur 2, une alerte s’affiche SampleControl1 Custom Event 2.

Passage d’une charge utile dans les événements

Comme décrit dans Définition d’un événement pour les applications basées sur des modèles, vous pouvez transmettre la charge utile dans les événements dans les applications basées sur des modèles. Vous pouvez modifier cet exemple de la façon suivante pour voir comment cela fonctionne.

Transmettre la charge de données avec un événement

Modifiez EventSample\index.ts afin que les événements transmettent une charge utile de message et, dans le deuxième événement, transmettent également une fonction de rappel qui modifie une variable interne.

Avant

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

Aprè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
   );
}

Ensuite :

1. Regénérer et déployer le composant.

2. Ajoutez un autre champ au formulaire utilisé avant et définissez-le pour utiliser le nouveau composant.

   

Utiliser la charge utile dans le gestionnaire d’événements

Mettez à jour la onLoad fonction pour définir les gestionnaires d’événements sur les contrôles personnalisés afin de réagir aux événements des deux contrôles et pour utiliser les paramètres passés

Avant

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

Aprè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);

Tester l’application pilotée par modèle

1. Accédez au formulaire.

2. Appuyez sur déclencher l'événement 1 dans le premier champ.

   Attendu : une fenêtre contextuelle affiche SampleControl1 Custom Event 1 : Hello from event 1 sur le premier champ.

3. Appuyez sur Déclencher l'événement 2 dans le premier champ.

   Attendu : une fenêtre contextuelle affiche SampleControl1 Événement personnalisé 2 : Bonjour de l’événement 2 dans le premier champ, suivi d’une alerte du premier contrôle indiquant Valeur par défaut de l’événement 2 NON empêchée

4. Appuyez sur Déclencher l’événement 1 dans le second champ.

   Attendu : une fenêtre contextuelle affiche SampleControl2 Événement personnalisé 1 : Bonjour de l’événement 1 dans le second champ.

5. Appuyez sur Déclencher l’événement 2 dans le second champ.

   Attendu : une fenêtre contextuelle affiche Événement personnalisé 2 SampleControl2 : Bonjour de l’événement 2 dans le second champ, suivi d’une alerte du second contrôle indiquant Valeur par défaut de l’événement 2 empêchée

Articles connexes

Définir des événements (préversion)