Utilisation de boîtes de dialogue personnalisées avec des extensions SharePoint Framework

Vous pouvez utiliser des boîtes de dialogue personnalisées, disponibles dans le package @microsoft/sp-dialog, dans le cadre d’extensions SharePoint Framework ou de composants WebPart côté client.

Cet article indique comment créer une boîte de dialogue personnalisée et comment l’utiliser dans le cadre d’une extension de jeu de commandes ListView.

Vous pouvez accéder à l’exemple de code sur lequel est basé cet article dans le référentiel sp-dev-fx-extensions.

Important

Ce didacticiel suppose que vous avez configuré votre environnement de développement comme expliqué dans Configurer votre environnement de développement.

Créer un projet

  1. Créez un répertoire de projet pour votre projet et remplacez votre dossier actuel par ce répertoire.

  2. Créez un projet en exécutant le générateur SharePoint Yeoman à partir du nouveau répertoire que vous avez créé :

    yo @microsoft/sharepoint
    
  3. Lorsque vous y êtes invité, entrez les valeurs suivantes (sélectionnez l’option par défaut pour toutes les invites qui ne sont pas mentionnées ci-dessous):

    • Quel type de composant côté client voulez-vous créer? Extension
    • Quel type d’extension côté client créer ? Jeu de commandes ListView
    • Quel est le nom de votre jeu de commandes? DialogDemo

    À ce stade, Yeoman installe les dépendances requises et génère automatiquement les fichiers solution. Cette opération peut prendre quelques minutes.

  4. Lorsque la structure initiale est terminée, entrez ce qui suit pour installer Office avec Fabric dans votre solution :

    npm install office-ui-fabric-react  --save
    
  5. Ouvrez le dossier de votre projet dans votre éditeur de code. Dans cet article, Visual Studio Code est utilisé dans les étapes et les captures d’écran, mais vous pouvez utiliser un autre éditeur si vous le souhaitez. Pour ouvrir le dossier dans Visual Studio Code, utilisez la commande suivante dans la console :

    code .
    

Modifier le manifeste d’extension

Dans le manifeste d’extension, configurez l’extension pour avoir un seul bouton. Dans l’éditeur de code, ouvrez le fichier ./src/extensions/dialogDemo/DialogDemoCommandSet.manifest.json. Remplacez la section de commandes avec le JSON suivant :

{
  //...
  "items": {
    "COMMAND_1": {
      "title": { "default": "Open Custom Dialog" },
      "iconImageUrl": "icons/request.png",
      "type": "command"
    }
  }
}

Créer une boîte de dialogue personnalisée

  1. Créez un fichier appelé ColorPickerDialog.tsx dans le dossier ./src/extensions/dialogDemo/.

  2. Ajoutez les instructions d’importation suivantes en haut du nouveau fichier créé. Comme vous créez votre boîte de dialogue personnalisée à l’aide des composants d’Office UI Fabric React, l’implémentation s’opère dans React.

    import * as React from 'react';
    import * as ReactDOM from 'react-dom';
    import { BaseDialog, IDialogConfiguration } from '@microsoft/sp-dialog';
    import { PrimaryButton, DefaultButton } from 'office-ui-fabric-react/lib/Button';
    import { ColorPicker } from 'office-ui-fabric-react/lib/ColorPicker';
    import { DialogFooter, DialogContent } from 'office-ui-fabric-react/lib/Dialog';
    import { IColor } from 'office-ui-fabric-react/lib/Color';
    
  3. Ajoutez la définition de l’interface suivante juste en dessous des instructions d’importation. Celle-ci va transmettre des informations et des fonctions entre votre extension de jeu de commandes ListView et votre boîte de dialogue personnalisée.

    interface IColorPickerDialogContentProps {
      message: string;
      close: () => void;
      submit: (color: IColor) => void;
      defaultColor?: IColor;
    }
    
  4. Ajoutez la classe suivante juste en dessous de la définition de l’interface. Cette classe React a pour rôle d’afficher les expériences d’interface utilisateur dans la boîte de dialogue personnalisée. Notez que vous utilisez les composants d’Office UI Fabric React pour le rendu réel et que vous transmettez simplement les propriétés nécessaires.

    class ColorPickerDialogContent extends React.Component<IColorPickerDialogContentProps, {}> {
      private _pickedColor: IColor;
    
      constructor(props) {
        super(props);
        // Default Color
        this._pickedColor = props.defaultColor || { hex: 'FFFFFF', str: '', r: null, g: null, b: null, h: null, s: null, v: null };
      }
    
      public render(): JSX.Element {
        return <DialogContent
        title='Color Picker'
        subText={this.props.message}
        onDismiss={this.props.close}
        showCloseButton={true}
        >
        <ColorPicker color={this._pickedColor} onChange={this._onColorChange} />
        <DialogFooter>
            <DefaultButton text='Cancel' title='Cancel' onClick={this.props.close} />
            <PrimaryButton text='OK' title='OK' onClick={() => { this.props.submit(this._pickedColor); }} />
        </DialogFooter>
        </DialogContent>;
      }
    
      private _onColorChange = (ev: React.SyntheticEvent<HTMLElement, Event>, color: IColor) => {
        this._pickedColor = color;
      }
    }
    
  5. Ajoutez la définition de la classe suivante pour votre boîte de dialogue personnalisée en dessous de la classe ColorPickerDialogContent que vous venez d’ajouter. Il s’agit de la boîte de dialogue personnalisée réelle qui est appelée suite à l’action de clic sur le jeu de commandes ListView et héritée de l’élément BaseDialog.

    export default class ColorPickerDialog extends BaseDialog {
      public message: string;
      public colorCode: IColor;
    
      public render(): void {
        ReactDOM.render(<ColorPickerDialogContent
        close={ this.close }
        message={ this.message }
        defaultColor={ this.colorCode }
        submit={ this._submit }
        />, this.domElement);
      }
    
      public getConfig(): IDialogConfiguration {
        return { isBlocking: false };
      }
    
      protected onAfterClose(): void {
        super.onAfterClose();
    
        // Clean up the element for the next dialog
        ReactDOM.unmountComponentAtNode(this.domElement);
      }
    
      private _submit = (color: IColor) => {
        this.colorCode = color;
        this.close();
      }
    }
    

Association de la boîte de dialogue à l’action de clic sur le jeu de commandes ListView

Pour associer la boîte de dialogue personnalisée au jeu de commandes ListView personnalisé, ajoutez le code permettant de lancer la boîte de dialogue lors de l’opération de clic du bouton.

  1. Dans l’éditeur de code, ouvrez le fichier DialogDemoCommandSet.ts à partir du dossier ./src/extensions/dialogDemo/.

  2. Ajoutez les instructions d’importation suivantes sous l'importation de chaînes existantes. Elles sont destinées à l’utilisation de la boîte de dialogue personnalisée dans le contexte de votre groupe de commandes ListView et à l’utilisation du type IColor pour transférer les couleurs vers et à partir de notre boîte de dialogue.

    import ColorPickerDialog from './ColorPickerDialog';
    import { IColor } from 'office-ui-fabric-react/lib/Color';
    
  3. Ajoutez la définition de la variable _colorCode suivante au-dessus de la fonction onInit dans la classe DialogDemoCommandSet. Cela permet de stocker le résultat de boîte de dialogue de sélection des couleurs.

    private _colorCode: IColor;
    
  4. Mettez à jour la fonction onExecute comme suit. Ce code effectue les opérations suivantes :

    • Lancer la boîte de dialogue personnalisée.
    • Transmettre un message pour la boîte de dialogue qui est utilisé comme titre.
    • Transmettre un code de couleur pour la boîte de dialogue avec une valeur par défaut, s’il n’a pas encore été défini.
    • Afficher la boîte de dialogue personnalisée.
    • Recevoir et stocker la valeur de retour à partir de la boîte de dialogue.
    • Afficher la valeur reçue dans une boîte de dialogue par défaut à l’aide de la fonction Dialog.alert().
    @override
    public onExecute(event: IListViewCommandSetExecuteEventParameters): void {
      switch (event.itemId) {
        case 'COMMAND_1':
          Dialog.alert(`${this.properties.sampleTextOne}`);
          const dialog: ColorPickerDialog = new ColorPickerDialog();
          dialog.message = 'Pick a color:';
          // Use 'FFFFFF' as the default color for first usage
          let defaultColor : IColor = { hex: 'FFFFFF', str: '', r: null, g: null, b: null, h: null, s: null, v: null };
          dialog.colorCode = this._colorCode|| defaultColor;
          dialog.show().then(() => {
            this._colorCode = dialog.colorCode;
            Dialog.alert(`Picked color: ${dialog.colorCode.hex}`);
          });
          break;
        default:
          throw new Error('Unknown command');
      }
    }
    

Test de la boîte de dialogue dans votre client

  1. Ouvrez le fichier serve.json dans le dossier ./config/ et mettez à jour les paramètres actuels du fichier. Ce fichier permet de faciliter le débogage dans les extensions SharePoint Framework. Vous pouvez mettre à jour le contenu du fichier de sorte que les détails de votre propre client correspondent aux détails du site où vous voulez tester votre extension. La valeur clé à mettre à jour est la propriété pageUrl dans la définition JSON pour la faire correspondre à votre propre client.

  2. Mettez à jour pageUrl de sorte à pointer vers une URL de liste dans laquelle tester la fonctionnalité de boîte de dialogue.

      "serveConfigurations": {
        "default": {
          "pageUrl": "https://yourtenantname.sharepoint.com/Shared%20Documents/Forms/AllItems.aspx",
          "customActions": {
            "9b98b919-fe5e-4758-ac91-6d62e582c4fe": {
              "location": "ClientSideExtension.ListViewCommandSet.CommandBar",
              "properties": {
                "sampleTextOne": "One item is selected in the list",
                "sampleTextTwo": "This command is always visible."
              }
            }
          }
        },
    

    Notes

    L’identificateur unique de votre extension est automatiquement mis à jour sur ce fichier pendant la génération automatique initiale de modèles. Si vous mettez à jour les propriétés utilisées par votre extension, mettez à jour serve.json avant de commencer le débogage.

  3. Revenez à la console et exécutez la commande suivante :

    gulp serve
    

Ceci démarre le regroupement de votre solution et traite le manifeste obtenu à partir de l’adresse localhost. En raison de la configuration dans le fichier serve.json, cette commande ouvre également un navigateur dans l’URL spécifique et définit automatiquement des paramètres de requête en fonction de la configuration de la solution.

  1. Acceptez le chargement des manifestes de débogage en sélectionnant Charger les scripts de débogage lorsque vous y êtes invité.

    Avertissement Autoriser les scripts de débogage

    Notez que le nouveau bouton n’est pas visible dans la barre d’outils par défaut, car la solution par défaut exige que vous sélectionniez un élément dans la liste. Si la liste ou la bibliothèque ne contient aucun élément, créez un élément ou téléchargez un document.

  2. Sélectionnez un élément dans la liste ou la bibliothèque. Le bouton Ouvrir la boîte de dialogue personnalisée apparaît dans la barre d’outils.

    Bouton Ouvrir la boîte de dialogue personnalisée visible dans la barre d’outils

  3. Cliquez sur le bouton Ouvrir la boîte de dialogue personnalisée pour afficher votre boîte de dialogue personnalisée dans l’affichage de liste.

    Sélecteur de couleurs affiché en mode boîte de dialogue

  4. Sélectionnez une couleur dans le Sélecteur de couleurs, puis sélectionnez OK pour tester la façon dont le code renvoie la valeur sélectionnée à l’appelant. La sélection s’affiche ensuite à l’aide de la boîte de dialogue d’alerte par défaut.

    Boîte de dialogue contenant les détails de couleur sélectionnée

    Notes

    Si vous trouvez un problème dans la documentation ou dans SharePoint Framework, signalez-le aux ingénieurs SharePoint en utilisant la liste des problèmes dans le référentiel sp-dev-docs. Nous vous remercions par avance pour vos commentaires.

Voir aussi