Использование настраиваемых диалоговых окон с расширениями SharePoint Framework

Вы можете использовать настраиваемые диалоговые окна, доступные в пакете @microsoft/sp-dialog, в контексте расширений SharePoint Framework или клиентских веб-частей.

В этой статье описываются создание настраиваемого диалогового окна и его использование в контексте расширения ListView Command Set.

Пример кода, рассматриваемый в этой статье, можно найти в репозитории sp-dev-fx-extensions.

Важно!

В этом руководстве предполагается, что вы настроили среду разработки в соответствии с разделом Настройка среды разработки.

Создание проекта

1. Создайте новый каталог для своего проекта и измените текущую папку на этот каталог.

2. Создайте новый проект, запустив генератор Yeoman для SharePoint из созданного вами нового каталога:

   yo @microsoft/sharepoint
   

3. При появлении запроса введите следующие значения (выберите вариант по умолчанию для всех запросов, не перечисленных ниже).

   • Какой тип клиентского компонента нужно создать? Расширение
   • Какой тип клиентского расширения нужно создать? Набор команд ListView
   • Как называется набор команд? DialogDemo

   После этого Yeoman устанавливает необходимые зависимости и формирует шаблоны файлов решения. Это может занять несколько минут.

4. После завершения начального скаффолдинга введите указанную ниже команду, чтобы установить Office UI Fabric для своего решения:

   npm install office-ui-fabric-react  --save
   

5. Откройте папку проекта в редакторе кода. В этой статье в инструкциях и на снимках экрана используется Visual Studio Code, но вы можете использовать любой другой редактор. Чтобы открыть папку в Visual Studio Code, выполните следующую команду в консоли:

   code .
   

Изменение манифеста расширения

В манифесте расширения настройте для расширения только одну кнопку. В редакторе кода откройте файл ./src/extensions/dialogDemo/DialogDemoCommandSet.manifest.json . Замените раздел команд следующим кодом JSON:

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

Создание настраиваемого диалогового окна

1. Создайте файл с именем ColorPickerDialog.tsx в папке ./src/extensions/dialogDemo/.

2. Добавьте приведенные ниже операторы импорта в начале нового файла. Вы создаете настраиваемое диалоговое окно с помощью компонентов Office UI Fabric React, поэтому реализация будет основана на 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. Добавьте приведенное ниже определение интерфейса сразу после операторов импорта. Оно будет использоваться для передачи сведений и функций между расширением ListView Command Set и настраиваемым диалоговым окном.

   interface IColorPickerDialogContentProps {
     message: string;
     close: () => void;
     submit: (color: IColor) => void;
     defaultColor?: IColor;
   }
   

4. Добавьте приведенный ниже класс сразу после определения интерфейса. Этот класс React отвечает за отрисовку пользовательского интерфейса в настраиваемом диалоговом окне. Обратите внимание, что мы используем компоненты Office UI Fabric React для фактической отрисовки и просто передаем необходимые свойства.

   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. Добавьте приведенное ниже определение класса для настраиваемого диалогового окна под только что добавленным классом ColorPickerDialogContent. Это фактическое настраиваемое диалоговое окно, которое вызывается по нажатию кнопки "Набор команд ListView" и наследуется от объекта 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();
     }
   }
   

Связывание диалогового окна с нажатием кнопки "Набор команд ListView"

Чтобы связать настраиваемое диалоговое окно с набором команд ListView, добавьте код инициализации диалогового окна в операцию нажатия кнопки.

1. В редакторе кода откройте файл DialogDemoCommandSet.ts из папки ./src/extensions/dialogDemo/.

2. Добавьте следующие операторы импорта под имеющимся оператором импорта strings. Они предназначены для использования настраиваемого диалогового окна в контексте набора команд ListView и использования типа IColor для передачи и получения цветов из диалогового окна.

   import ColorPickerDialog from './ColorPickerDialog';
   import { IColor } from 'office-ui-fabric-react/lib/Color';
   

3. Добавьте следующее _colorCode определение переменной над функцией onInit в DialogDemoCommandSet классе . Используется для хранения результата диалогового окна выбора цвета.

   private _colorCode: IColor;
   

4. Обновите функцию onExecute следующим образом. Этот код выполняет следующие действия:

   • инициализирует настраиваемое диалоговое окно;
   • передает сообщение, используемое в качестве заголовка диалогового окна;
   • передает код цвета диалогового окна со стандартным значением, если оно еще не задано;
   • показывает настраиваемое диалоговое окно;
   • получает и сохраняет значение, возвращаемое диалоговым окном;
   • показывает полученное значение в стандартном диалоговом окне с помощью функции 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');
     }
   }
   

Тестирование диалогового окна в клиенте

1. Откройте файл serve.json в папке ./config/ и обновите в нем текущие параметры. Этот файл призван упростить отладку расширений SharePoint Framework. Вы можете обновить содержимое файла в соответствии с данными клиента и сайта, на котором будет тестироваться расширение. В первую очередь следует изменить значение свойства pageUrl в определении JSON так, чтобы оно соответствовало вашему клиенту.

2. Измените свойство pageUrl так, чтобы оно указывало на URL-адрес списка, в котором нужно тестировать функции диалогового окна.

     "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."
             }
           }
         }
       },
   

   Примечание.

   Уникальный идентификатор расширения автоматически обновляется для этого файла во время первоначального формирования шаблонов. Если вы обновляете свойства, которые используются расширением, следует обновить файл serve.json, прежде чем приступать к отладке.

3. Вернитесь к консоли и выполните следующую команду:

   gulp serve
   

Начнется упаковка решения, а полученный манифест станет доступен по адресу localhost. В соответствии с конфигурацией из файла serve.json в браузере также откроется определенный URL-адрес, а параметры запроса будут автоматически заданы согласно конфигурации решения.

1. Согласитесь на загрузку манифестов отладки, нажав кнопку Загрузить скрипты отладки при появлении соответствующего запроса.

   

   Обратите внимание, что новая кнопка не отображается на панели инструментов по умолчанию, так как стандартное решение требует выбора одного элемента списка. Если список или библиотека не содержит элементов, создайте элемент или отправьте документ.

2. Выберите элемент из списка или библиотеки. Обратите внимание, что на панели инструментов появится кнопка с текстом Open Custom Dialog (Открыть настраиваемое диалоговое окно).

   

3. Нажмите кнопку Open Custom Dialog (Открыть настраиваемое диалоговое окно), чтобы настраиваемое диалоговое окно отобразилось в представлении списка.

   

4. Выберите цвет в палитре и нажмите кнопку ОК, чтобы проверить, как код возвращает вызывающей стороне выбранное значение, которое затем отображается в стандартном диалоговом окне предупреждения.

   

   Примечание.

   Если вы обнаружили ошибку в документации или SharePoint Framework, сообщите о ней разработчикам SharePoint, указав в списке проблем для репозитория sp-dev-docs. Заранее спасибо!

См. также

• Обзор расширений SharePoint Framework