Didacticiel : Utiliser des bibliothèques dépendantes dans un composant

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

Ce didacticiel montre comment créer un composant de code pour les applications pilotées par modèle qui dépend des bibliothèques contenues dans un autre composant. En savoir plus sur la version préliminaire des bibliothèques dépendantes

Goal

Suivez les étapes de ce didacticiel pour créer un contrôle de bibliothèque et un contrôle qui en dépend. Ce didacticiel contient les étapes suivantes :

1. Générer le composant de la bibliothèque : créez un composant qui ne contient que la bibliothèque réutilisable. Pour simplifier, ce contrôle ne contient que la bibliothèque réutilisable. Il n’y a aucune raison pour qu’il ne puisse pas également fournir des fonctionnalités.
2. Générer le contrôle dépendant : créez un composant qui utilise la bibliothèque définie dans le contrôle de bibliothèque et ajoutez-le au formulaire d’une application pilotée par modèle pour vérifier son bon fonctionnement.
3. Charger la bibliothèque dépendante à la demande : développez l’exemple pour que le composant dépendant charge la ressource de la bibliothèque à la demande au lieu que l’infrastructure charge la bibliothèque lors du chargement du contrôle.

Prérequis

Vous devez déjà savoir comment :

• Créer un composant de code
• Créer un package de composant de code
• Ajouter des composants de code à une application pilotée par modèle

1. Générer le composant de bibliothèque

Ce composant ne fournit aucune fonctionnalité par lui-même. Il s’agit simplement d’un conteneur pour la bibliothèque.

La première étape consiste à créer un nouveau composant à l’aide de la commande pac pcf init :

pac pcf init -n StubLibrary -ns SampleNamespace -t field -npm

Définir la bibliothèque

1. Vous avez besoin d’un nouveau fichier de déclaration (d.ts) pour décrire les objets et les fonctions contenus dans votre bibliothèque. Créez un nouveau fichier dans le dossier racine de votre projet nommé myLib.d.ts :

   declare module 'myLib' {
     export function sayHello(): string;
   }
   

2. Nous allons exposer notre bibliothèque en tant que module UMD, et nous devons placer la variable dans la portée globale. Pour cela, nous avons besoin d’un nouveau fichier de déclaration (d.ts). Créez un nouveau fichier dans le dossier racine de votre projet nommé global.d.ts :

   /* eslint-disable no-var */
   declare global {
     var myLib: typeof import('myLib');
   }
   
   export { };
   

3. Mettez à jour tsconfig.json pour autoriser les modules UMD et le code JavaScript comme suit :

   Avant le

   {
       "extends": "./node_modules/pcf-scripts/tsconfig_base.json",
       "compilerOptions": {
           "typeRoots": ["node_modules/@types"]
       }
   }
   

   Après

   {
       "extends": "./node_modules/pcf-scripts/tsconfig_base.json",
       "compilerOptions": {
           "typeRoots": ["node_modules/@types"],
           "allowJs": true,
           "allowUmdGlobalAccess": true,
           "outDir": "dist"
       },
   }
   

Ajouter la bibliothèque

Dans votre nouveau dossier de contrôle, ajoutez un nouveau dossier pour contenir vos bibliothèques libs ; pour cet exemple, créez un nouveau fichier JavaScript. Cet exemple utilise une bibliothèque nommée myLib-v_0_0_1.js qui a une seule fonction sayHello.

// UMD module pattern
var myLib = (function (exports) {
"use strict";

function sayHello() {
   return "Hello from myLib";
}

exports.sayHello = sayHello;

return exports;
})(/** @type {import('myLib')}  */ ({}));

Ajouter des données de configuration

1. Ajoutez un fichier nommé featureconfig.json dans le dossier racine du projet.

2. Ajoutez le texte suivant au fichier featureconfig.json :

   {
     "pcfAllowCustomWebpack": "on",
     "pcfAllowLibraryResources": "on"
   }
   

   En savoir plus sur le fichier featureconfig.json

3. Ajoutez un nouveau fichier webpack.config.js dans le dossier racine de votre projet. Ces données de configuration garantissent que les bibliothèques ne sont pas regroupées avec la sortie de contrôle. Le regroupement n’est pas nécessaire, car elles sont déjà mises en package séparément lorsque vous créez le projet.

   /* eslint-disable */
   "use strict";
   
   module.exports = {
     externals: {
       "myLib": "myLib"
     },
   }
   

   En savoir plus sur le fichier webpack.config.js

4. Ajoutez une référence à la bibliothèque sous resources dans le manifeste du contrôle.

Avant le

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

Après

<resources> 
  <library name="myLib" version=">=1" order="1"> 
    <packaged_library path="libs/myLib-v_0_0_1.js" version="0.0.1" /> 
  </library> 
  <code path="index.ts" order="2"/> 
</resources> 

Ajouter la bibliothèque à la fenêtre

La dernière étape consiste à modifier le fichier index.ts du contrôle pour lier la bibliothèque à la fenêtre.

Avant le

import { IInputs, IOutputs } from "./generated/ManifestTypes";

export class StubLibrary
implements ComponentFramework.StandardControl<IInputs, IOutputs>
{
 constructor() {
   // Empty
 }

 public init(
    context: ComponentFramework.Context<IInputs>,
    notifyOutputChanged: () => void,
    state: ComponentFramework.Dictionary,
    container: HTMLDivElement
 ): void {
   // Add control initialization code
 }

 public updateView(context: ComponentFramework.Context<IInputs>): void {
   // Add code to update control view
 }

 public getOutputs(): IOutputs {
    return {};
 }

  public destroy(): void {
    // Add code to cleanup control if necessary
  }
}

Après

import * as myLib from 'myLib';
import { IInputs, IOutputs } from "./generated/ManifestTypes";

export class StubLibrary
implements ComponentFramework.StandardControl<IInputs, IOutputs>
{
 constructor() {
   // Empty
 }

 public init(
    context: ComponentFramework.Context<IInputs>,
    notifyOutputChanged: () => void,
    state: ComponentFramework.Dictionary,
    container: HTMLDivElement
 ): void {
   // Add control initialization code
 }

 public updateView(context: ComponentFramework.Context<IInputs>): void {
   // Add code to update control view
 }

 public getOutputs(): IOutputs {
    return {};
 }

  public destroy(): void {
    // Add code to cleanup control if necessary
  }
}

(function () {
   window.myLib = myLib;
})();

Le projet de la bibliothèque devrait se présenter comme suit :-

Générer et créer un package pour le composant de la bibliothèque

Pour terminer le composant de la bibliothèque, effectuez les étapes suivantes comme d’habitude :

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

2. Générer le contrôle dépendant

Maintenant que vous disposez d’un contrôle de bibliothèque, vous avez besoin d’un contrôle qui en dépende.

1. Créez un nouveau composant en utilisant cette commande :

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

2. Ajoutez un nouveau fichier de contrôle de fonctionnalité dans le dossier racine de votre projet appelé featureconfig.json contenant le texte suivant :

   {
     "pcfResourceDependency": "on"
   } 
   

3. Ajoutez la ressource dépendante dans le manifeste du contrôle.

   Utilisez le schemaName du contrôle dépendant [solution prefix]_[namespace].[control name], que vous pouvez trouver dans le fichier solution.xml du composant dépendant. Le code XML contenu dans le fichier solution.xml peut ressembler à ceci :

   <RootComponents>
     <RootComponent
      type="66"
      schemaName="samples_SampleNamespace.StubLibrary"
      behavior="0"
     />
   </RootComponents>
   

Avant le

<resources>
      <code path="index.ts"
         order="1" />
      <platform-library name="React"
         version="16.14.0" />
      <platform-library name="Fluent"
         version="9.46.2" />
</resources> 

Après

<resources>
      <dependency type="control"
         name="samples_SampleNamespace.StubLibrary"
         order="1" />
      <code path="index.ts"
         order="2" />
      <platform-library name="React"
         version="16.14.0" />
      <platform-library name="Fluent"
         version="9.46.2" />    
</resources> 

Ajouter Global.d.ts

Étant donné que la StubLibrary est exposée en tant que module UMD, nous devons placer la variable dans la portée globale. Pour cela, nous avons besoin d’un nouveau fichier de déclaration (d.ts). Créez un nouveau fichier dans le dossier racine de votre projet nommé global.d.ts :

/* eslint-disable no-var */

interface MyLib {
      sayHello(): string;
}

declare global {
      var myLib: MyLib;
}

export { };

Utiliser la fonction de la bibliothèque

Mettez à jour le fichier HelloWorld.tsx du composant afin qu’il utilise une fonction de la bibliothèque dépendante. La bibliothèque est chargée dans l’objet Window au moment de l’exécution.

Avant le

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

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 } from '@fluentui/react-components';

export interface IHelloWorldProps {
  name?: string;
}

export class HelloWorld extends React.Component<IHelloWorldProps> {
  public render(): React.ReactNode {
    return (
      <Label>
        { window.myLib.sayHello() + " from Dependency" || "Hello World"}
      </Label>
    )
  }
}

Générer et empaqueter le composant dépendant

Pour terminer le composant dépendant, effectuez les étapes suivantes comme d’habitude :

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

Ajouter le composant à un formulaire

1. Ajoutez le composant au formulaire piloté par modèle.

2. Accédez au formulaire et vous devriez voir le composant afficher le texte Hello from myLib from Dependency.

   

3. Charger la bibliothèque dépendante à la demande

Vous pouvez développer cet exemple en modifiant le composant dépendant pour qu’il charge la ressource de bibliothèque à la demande, plutôt que de demander à l’infrastructure de charger la bibliothèque lors du chargement du composant. Le comportement de chargement à la demande est utile si les bibliothèques utilisées par le contrôle sont volumineuses et augmentent le temps de chargement du formulaire.

Spécifier le comportement de chargement à la demande

Pour spécifier le comportement de chargement à la demande, modifiez le manifeste de contrôle du composant créé en 2. Créer le contrôle dépendant.

Avant le

<resources>
    <dependency type="control"
        name="samples_SampleNamespace.StubLibrary"
        order="1" />
    <code path="index.ts"
        order="2" />
    <platform-library name="React" version="16.14.0" />
    <platform-library name="Fluent" version="9.46.2" />
</resources>

Après

<platform-action action-type="afterPageLoad" />
<feature-usage>
    <uses-feature name="Utility"
        required="true" />
</feature-usage>
<resources>
    <code path="index.ts"
        order="1" />
    <dependency type="control"
        name="samples_SampleNamespace.StubLibrary"
        load-type="onDemand" />
    <platform-library name="React" version="16.14.0" />
    <platform-library name="Fluent" version="9.46.2" />  
</resources>

Modifier le composant dépendant pour charger la bibliothèque à la demande

Modifiez le fichier HelloWorld.tsx pour ajouter un état et des méthodes pour le mettre à jour une fois la dépendance chargée.

Avant le

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

export interface IHelloWorldProps {
  name?: string;
}

export class HelloWorld extends React.Component<IHelloWorldProps> {
  public render(): React.ReactNode {
    return (
      <Label>
        { window.myLib.sayHello() + " from Dependency" || "Hello World"}
      </Label>
    )
  }
}

Après

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

export interface IHelloWorldProps {
  name?: string;
}

export class HelloWorld extends React.Component<IHelloWorldProps, { loaded: boolean }> {
  constructor(props: IHelloWorldProps) {
    super(props);
    this.state = {
      loaded: false
    };
  }

  public afterPageLoad() {
    this.setState({ loaded: true });
  }

  public render(): React.ReactNode {
    return (
      <Label>
          {this.state.loaded ? window.myLib.sayHello() + " Dependency On Demand Load" : 'Loading...'}
      </Label>
    )
  }
}

Mise à jour de index.ts

Lorsque le script est chargé à la demande, vous devez apporter de légers ajustements à la façon dont le composant est créé et initialisé. Par exemple, de nouvelles variables pour les références au contexte et au conteneur pour mettre à jour l’état.

Plus important encore, ajoutez une méthode getActions pour réagir au chargement et demander le chargement du contrôle dépendant.

Avant le

import { IInputs, IOutputs } from "./generated/ManifestTypes";
import { HelloWorld, IHelloWorldProps } from "./HelloWorld";
import * as React from "react";

export class DependencyControl implements ComponentFramework.ReactControl<IInputs, IOutputs> {
    private notifyOutputChanged: () => void;

    constructor() {
        // Empty
    }

    public init(
        context: ComponentFramework.Context<IInputs>,
        notifyOutputChanged: () => void,
        state: ComponentFramework.Dictionary
    ): void {
        this.notifyOutputChanged = notifyOutputChanged;
    }

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

    public getOutputs(): IOutputs {
        return { };
    }

    public destroy(): void {
        // Add code to cleanup control if necessary
    }
}

Après

import { IInputs, IOutputs } from "./generated/ManifestTypes";
import { HelloWorld} from "./HelloWorld";
import * as React from "react";

export class DependencyControl implements ComponentFramework.ReactControl<IInputs, IOutputs> {
    private theComponent: ComponentFramework.ReactControl<IInputs, IOutputs>;
    private notifyOutputChanged: () => void;
    private context: ComponentFramework.Context<IInputs>;
    private mainContainerRef: React.RefObject<HelloWorld> = React.createRef<HelloWorld>();

    constructor() { 
        // Empty
    }

    public init(
        context: ComponentFramework.Context<IInputs>,
        notifyOutputChanged: () => void,
        state: ComponentFramework.Dictionary
    ): void {
        this.notifyOutputChanged = notifyOutputChanged;
        this.context = context;
    }

    public updateView(context: ComponentFramework.Context<IInputs>): React.ReactElement {
        return React.createElement(
            HelloWorld, {ref: this.mainContainerRef }
        );
    }

    public getOutputs(): IOutputs {
        return { };
    }

    public getActions(): {afterPageLoad: ()=>Promise<void>} {
        return {
            afterPageLoad: async () => {
                console.log("afterPageLoad");
                const loadedControl = await this.context.utils.loadDependency?.("samples_SampleNamespace.StubLibrary");
                if (loadedControl) {
                    this.mainContainerRef.current?.afterPageLoad();
                  } 
            },
        };
    }

    public destroy(): void {
        // Add code to cleanup control if necessary
    }
}

Étapes finales

1. Mettez à jour le numéro de version du contrôle dans le fichier ControlManifest.Input.xml et la version dans le fichier Solution.xml
2. Regénérez, empaquetez, déployez et publiez la solution avec le contrôle mis à jour.

Vérifier les résultats

Maintenant, lorsque la page se charge, vous voyez le contrôle se charger avec Loading....

Une fois la page chargée, le contrôle se met à jour pour afficher Hello from myLib Dependency On Demand Load.

Articles associés

Bibliothèques dépendantes (version préliminaire)