Создание первого расширения с набором команд ListView

Статья
04/08/2023

Расширения — это клиентские компоненты, которые выполняются в контексте страницы SharePoint. Расширения можно развернуть в SharePoint Online, и для их создания можно использовать современные средства и библиотеки JavaScript.

Вы можете выполнить следующие действия, просмотрев видео на канале Microsoft 365 Platform Communtiy (PnP) YouTube:

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

Создайте каталог проекта в любом расположении.
```
md command-extension
```
Перейдите к каталогу проекта.
```
cd command-extension
```
Создайте расширение HelloWorld, запустив генератор Yeoman для SharePoint.
```
yo @microsoft/sharepoint
```
При появлении запроса введите следующие значения (выберите вариант по умолчанию для всех запросов, не перечисленных ниже).
- Как называется ваше решение?: command-extension
- Какой тип клиентского компонента нужно создать?: Расширение
- Какой тип клиентского расширения нужно создать? Набор команд ListView
- Как называется набор команд? HelloWorld
На этом этапе Yeoman устанавливает необходимые зависимости и формирует шаблон файлов решения вместе с расширением HelloWorld. Это обычно занимает 1–3 минуты.
Далее введите в консоли приведенную ниже команду, чтобы запустить Visual Studio Code.
```
code .
```
Откройте файл ./src/extensions/helloWorld/HelloWorldCommandSet.manifest.json .

Этот файл определяет тип расширения и уникальный идентификатор id для расширения. Этот уникальный идентификатор понадобится позже при отладке и развертывании расширения в SharePoint.
```
{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx/command-set-extension-manifest.schema.json",

  "id": "95688e19-faea-4ef1-8394-489bed1de2b4",
  "alias": "HelloWorldCommandSet",
  "componentType": "Extension",
  "extensionType": "ListViewCommandSet",

  "version": "*",
  "manifestVersion": 2,

  "requiresCustomScript": false,

  "items": {
    "COMMAND_1": {
      "title": { "default": "Command One" },
      "iconImageUrl": "icons/request.png",
      "type": "command"
    },
    "COMMAND_2": {
      "title": { "default": "Command Two" },
      "iconImageUrl": "icons/cancel.png",
      "type": "command"
    }
  }
}
```
Обратите внимание на фактические определения команд в файле манифеста. Это фактические кнопки, которые предоставляются в зависимости от целевого объекта регистрации. В шаблоне по умолчанию находятся две разные кнопки: Command One и Command Two.

Примечание.

Изображения не ссылаются должным образом, если вы не ссылаетесь на них из абсолютных расположений в CDN в манифесте.

Написание кода ListView Command Set

Откройте файл ./src/extensions/helloWorld/HelloWorldCommandSet.ts.

Обратите внимание, что базовый класс для набора команд ListView импортирован из пакета @microsoft/sp-listview-extensibility, который содержит код SharePoint Framework (SPFx), необходимый для набора команд ListView.

import { override } from '@microsoft/decorators';
import { Log } from '@microsoft/sp-core-library';
import {
  BaseListViewCommandSet,
  Command,
  IListViewCommandSetListViewUpdatedParameters,
  IListViewCommandSetExecuteEventParameters
} from '@microsoft/sp-listview-extensibility';
import { Dialog } from '@microsoft/sp-dialog';

Поведение пользовательских кнопок содержится в методах onListViewUpdated() и OnExecute() .

Событие onListViewUpdated() возникает отдельно для каждой команды (например, элемента меню) каждый раз, когда в ListView происходит изменение, и пользовательский интерфейс необходимо повторно отобразить. Параметр event функции представляет сведения о отрисовываемой команде. Обработчик может использовать эти сведения для настройки заголовка или настройки видимости, например, если команда должна отображаться только при выборе определенного количества элементов в представлении списка. Это реализация по умолчанию.

При использовании метода tryGetCommand()возвращается объект Command, представляющий собой представление команды, отображаемой в пользовательском интерфейсе. Вы можете изменить его значения, например title, или visible, чтобы изменить элемент пользовательского интерфейса. SPFx использует эти сведения при повторной отрисовке команд. Эти объекты сохраняют состояние от последней отрисовки, поэтому, если для команды задано значение visible = false, она остается невидимой, пока не будет возвращена в .visible = true

@override
public onListViewUpdated(event: IListViewCommandSetListViewUpdatedParameters): void {
  const compareOneCommand: Command = this.tryGetCommand('COMMAND_1');
  if (compareOneCommand) {
    // This command should be hidden unless exactly one row is selected.
    compareOneCommand.visible = event.selectedRows.length === 1;
  }
}

Метод onExecute() определяет, что происходит при выполнении команды (например, выбран пункт меню). В реализации по умолчанию отображаются различные сообщения в зависимости от выбранной кнопки.

@override
public onExecute(event: IListViewCommandSetExecuteEventParameters): void {
  switch (event.itemId) {
    case 'COMMAND_1':
      Dialog.alert(`${this.properties.sampleTextOne}`);
      break;
    case 'COMMAND_2':
      Dialog.alert(`${this.properties.sampleTextTwo}`);
      break;
    default:
      throw new Error('Unknown command');
  }
}

Отладка набора команд ListView

В настоящее время для проверки расширений SharePoint Framework нельзя использовать локальную версию Workbench. Вам потребуется протестировать и разработать их непосредственно на динамическом сайте SharePoint Online. Для этого не нужно развертывать модификацию в каталоге приложений, что делает процесс отладки простым и эффективным.

Перейдите к любому списку SharePoint на сайте SharePoint Online с помощью современного интерфейса или создайте новый список. Скопируйте URL-адрес списка в буфер обмена, так как он потребуется нам на следующем этапе.

Так как расширение ListView Command Set размещено с использованием localhost и запущено, с помощью определенных параметров запроса отладки мы можем выполнить код в представлении списка.

Откройте файл ./config/serve.json . pageUrl Обновите атрибуты, чтобы они соответствовали URL-адресу списка, в котором требуется протестировать решение. После редактирования файл serve.json должен выглядеть примерно так:

{
  "$schema": "https://developer.microsoft.com/json-schemas/core-build/serve.schema.json",
  "port": 4321,
  "https": true,
  "serveConfigurations": {
    "default": {
      "pageUrl": "https://sppnp.sharepoint.com/sites/Group/Lists/Orders/AllItems.aspx",
      "customActions": {
        "bf232d1d-279c-465e-a6e4-359cb4957377": {
          "location": "ClientSideExtension.ListViewCommandSet.CommandBar",
          "properties": {
            "sampleTextOne": "One item is selected in the list",
            "sampleTextTwo": "This command is always visible."
          }
        }
      }
    },
    "helloWorld": {
      "pageUrl": "https://sppnp.sharepoint.com/sites/Group/Lists/Orders/AllItems.aspx",
      "customActions": {
        "bf232d1d-279c-465e-a6e4-359cb4957377": {
          "location": "ClientSideExtension.ListViewCommandSet.CommandBar",
          "properties": {
            "sampleTextOne": "One item is selected in the list",
            "sampleTextTwo": "This command is always visible."
          }
        }
      }
    }
  }
}

Скомпилируйте код и разместите скомпилированные файлы на локальном компьютере, выполнив следующую команду:
```
gulp serve
```
Когда компиляция кода завершится без ошибок, полученный манифест будет доступен в https://localhost:4321.

Это также запустит браузер по умолчанию в URL-адресе, определенном в файле ./config/serve.json . Обратите внимание, что по крайней мере в Windows вы можете определять, какое окно браузера будет использоваться, активировав предпочтительное окно перед выполнением этой команды.
Согласитесь на загрузку манифестов отладки, нажав кнопку Загрузить скрипты отладки при появлении соответствующего запроса.
Обратите внимание на то, что на панели инструментов появилась новая кнопка — Command Two (Команда вторая). Нажмите эту кнопку, чтобы увидеть текст, предоставленный как свойство для свойства sampleTextTwo.
Код не позволяет отображаться кнопке Command One (Команда первая), пока в библиотеке документов не будет выбрана одна строка. Отправьте документ в библиотеку или создайте его там и подтвердите, что вторая кнопка видима.
Нажмите кнопку Command Two (Команда вторая), чтобы увидеть, как работает элемент управления диалоговым окном, который используется в выходных данных, по умолчанию получаемых при скаффолдинге решения, когда в качестве типа расширения выбирается ListView Command Set.

Дополнительные сведения о параметрах serve.json

customActions: имитирует пользовательское действие. Вы можете задать множество свойств для этого объекта CustomAction, определяющих внешний вид и расположение кнопки. Мы расскажем о них позже.
- GUID: GUID расширения.
- Location: где отображаются команды. Возможные значения:
  - ClientSideExtension.ListViewCommandSet.ContextMenu: контекстное меню элементов.
  - ClientSideExtension.ListViewCommandSet.CommandBar: Меню верхнего уровня для набора команд в списке или библиотеке.
  - ClientSideExtension.ListViewCommandSet: контекстное меню и панель команд (соответствует SPUserCustomAction.Location="CommandUI.Ribbon").
- Properties: необязательный объект JSON, содержащий свойства, доступные this.properties через элемент .

Улучшение отрисовки ListView Command Set

Решение по умолчанию использует новый API диалоговых окон, позволяющий легко выводить модальные диалоговые окна с помощью кода. Далее мы слегка изменим интерфейс по умолчанию, чтобы показать варианты использования API диалоговых окон.

Вернитесь в Visual Studio Code (или в предпочитаемый редактор).
Откройте файл ./src/extensions/helloWorld/HelloWorldCommandSet.ts .

Обновите onExecute() метод следующим образом:

@override
public onExecute(event: IListViewCommandSetExecuteEventParameters): void {
  switch (event.itemId) {
    case 'COMMAND_1':
      Dialog.alert(`Clicked ${strings.Command1}`);
      break;
    case 'COMMAND_2':
      Dialog.prompt(`Clicked ${strings.Command2}. Enter something to alert:`).then((value: string) => {
        Dialog.alert(value);
      });
      break;
    default:
      throw new Error('Unknown command');
  }
}

В окне консоли не должно быть исключений. Если решение еще не запущено в localhost, выполните следующую команду:
```
gulp serve
```
Согласитесь на загрузку манифестов отладки, нажав кнопку Загрузить скрипты отладки при появлении соответствующего запроса.

На панели инструментов есть те же кнопки, но вы заметите, что если нажимать их по отдельности, их поведение меняется. Теперь мы используем новый API диалоговых окон, который можно легко применять к решениям даже в случае самых сложных сценариев.

Добавление набора команд ListView в пакет решения для развертывания

Вернитесь к решению в Visual Studio Code (или другом редакторе, который вы используете).
Откройте файл ./sharepoint/assets/elements.xml.

Запишите следующую структуру XML в файл elements.xml: Свойство ClientSideComponentId обновлено до уникального идентификатора набора команд ListView, доступного в файле ./src/extensions/helloWorld/HelloWorldCommandSet.manifest.json .

Обратите внимание на то, что мы используем определенное значение расположения ClientSideExtension.ListViewCommandSet.CommandBar, чтобы определить, что это расширение ListView Command Set, которое должно отображаться на панели команд. Мы также определяем RegistrationId для 100 и как ListRegistrationType, чтобы автоматически связать это пользовательское действие с универсальными списками. ClientSideComponentProperties позволяет создавать конфигурации для определенных экземпляров. В этом случае мы используем свойства по умолчанию — sampleTextOne и sampleTextTwo.

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
    <CustomAction
        Title="SPFxListViewCommandSet"
        RegistrationId="100"
        RegistrationType="List"
        Location="ClientSideExtension.ListViewCommandSet.CommandBar"
        ClientSideComponentId="5fc73e12-8085-4a4b-8743-f6d02ffe1240"
        ClientSideComponentProperties="{&quot;sampleTextOne&quot;:&quot;One item is selected in the list.&quot;, &quot;sampleTextTwo&quot;:&quot;This command is always visible.&quot;}">
    </CustomAction>
</Elements>

Примечание.

При запуске с localhost настраиваемое действие будет работать как в списках, так и в библиотеках документов, но не будет развернуто один раз, если elements.xml не будет обновлен. RegistrationId=100 будет только сопутствовать дополнительному действию со списками, а НЕ библиотеками документов.

Чтобы связать пользовательское действие с библиотеками документов, RegistrationId необходимо задать значение 101. Если вы хотите, чтобы действие работало как со списками, так и с библиотеками документов, в файлelements.xml необходимо добавить еще одно CustomAction действие.

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
    <CustomAction
        Title="SPFxListViewCommandSet"
        RegistrationId="100"
        RegistrationType="List"
        Location="ClientSideExtension.ListViewCommandSet.CommandBar"
        ClientSideComponentId="5fc73e12-8085-4a4b-8743-f6d02ffe1240"
        ClientSideComponentProperties="{&quot;sampleTextOne&quot;:&quot;One item is selected in the list.&quot;, &quot;sampleTextTwo&quot;:&quot;This command is always visible.&quot;}">
    </CustomAction>
    <CustomAction
        Title="SPFxListViewCommandSet"
        RegistrationId="101"
        RegistrationType="List"
        Location="ClientSideExtension.ListViewCommandSet.CommandBar"
        ClientSideComponentId="5fc73e12-8085-4a4b-8743-f6d02ffe1240"
        ClientSideComponentProperties="{&quot;sampleTextOne&quot;:&quot;One item is selected in the list.&quot;, &quot;sampleTextTwo&quot;:&quot;This command is always visible.&quot;}">
    </CustomAction>
</Elements>

Допустимые значения расположений, которые можно использовать с набором команд ListView:

ClientSideExtension.ListViewCommandSet.CommandBar: панель инструментов списка или библиотеки
ClientSideExtension.ListViewCommandSet.ContextMenu: контекстное меню для элементов списка или библиотеки
ClientSideExtension.ListViewCommandSet: регистрация команд на панели инструментов и в контекстном меню

Убедитесь, что определения учитываются на этапе сборки.

Откройте файл ./config/package-solution.json.

В файле package-solution.json определяются метаданные пакета, как показано в следующем фрагменте кода. Чтобы обеспечить учет element.xml файла при создании пакета решения, шаблон по умолчанию для этого файла обновляется, чтобы включить дополнительные сведения об определении компонента. Это определение компонента используется для подготовки и выполнения файлаelements.xml .

Примечание.

Вы можете использовать ClientSideInstance.xml для автоматической развертки ваших расширений на всех сайтах вашего клиента. Дополнительные сведения вокруг этого параметра см. с статье Развертывание расширений SharePoint Framework для всего клиента. Так как это решение умышленно настроено не для использования в масштабах всего клиента, при активации решения в каталоге приложений этот XML-файл игнорируется.

{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/package-solution.schema.json",
  "solution": {
    "name": "command-extension-client-side-solution",
    "id": "0abe5c73-1655-49d3-922b-7a47dd70e151",
    "version": "1.0.0.0",
    "includeClientSideAssets": true,
    "isDomainIsolated": false,
    "features": [
      {
        "title": "Application Extension - Deployment of custom action.",
        "description": "Deploys a custom action with ClientSideComponentId association",
        "id": "25f8df47-61f2-4d75-bfe2-8d614f775219",
        "version": "1.0.0.0",
        "assets": {
          "elementManifests": [
            "elements.xml",
            "clientsideinstance.xml"
          ]
        }
      }
    ]
  },
  "paths": {
    "zippedPackage": "solution/command-extension.sppkg"
  }
}

Развертывание расширения в SharePoint Online

Теперь мы готовы развернуть решение на сайте SharePoint и автоматически сопоставить действие CustomAction на уровне сайта.

Так как решения будут по умолчанию использовать возможность упаковки ресурсов, ваши файлы JavaScript и другие активы будут автоматически упаковываться в sppkg файл, а затем автоматически используются из CDN Office 365 или из семейства веб-сайтов каталога приложений.

Чтобы упаковать клиентское решение, содержащее расширение, и получить базовую структуру, готовую к упаковке, в окне консоли введите указанную ниже команду.
```
gulp bundle --ship
```
Затем выполните следующую команду, чтобы создать пакет решения:
```
gulp package-solution --ship
```
Команда создает следующий пакет: ./sharepoint/solution/command-extension.sppkg :
Разверните пакет, созданный в каталоге приложений. Для этого перейдите в каталог приложений клиента и откройте библиотеку Приложения для SharePoint.
Отправьте папку ./sharepoint/solution/command-extension.sppkg в каталог приложений. В SharePoint откроется диалоговое окно с запросом на подтверждение доверия клиентскому решению.
Нажмите кнопку Развернуть.
Перейдите на тот сайт, где требуется проверить подготовку ресурсов SharePoint. Это может быть любое семейство веб-сайтов в клиенте, где развернут пакет решения.
Щелкните значок шестеренки на верхней панели навигации справа, а затем выберите Добавить приложение , чтобы перейти на страницу приложения.
В поле Поиск введите extension и нажмите клавишу ВВОД, чтобы отфильтровать приложения.
Выберите приложение command-extension-client-side-solution, чтобы установить решение на сайте. После завершения установки.
Когда приложение будет успешно установлено, нажмите кнопку Создать на панели инструментов страницы Содержимое сайта и выберите Список.
Укажите имя Sample (Пример) и нажмите кнопку Создать.

Обратите внимание, что кнопки Command One (Команда первая) и Command Two (Команда вторая) отрисовываются на панели инструментов в соответствии с изменениями набора команд ListView. Обратите внимание на то, что расширение также отображении автоматически для любых готовых списков, а не только для новых.

Поделиться через

Создание первого расширения с набором команд ListView

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

Написание кода ListView Command Set

Отладка набора команд ListView

Дополнительные сведения о параметрах serve.json

Улучшение отрисовки ListView Command Set

Добавление набора команд ListView в пакет решения для развертывания

Убедитесь, что определения учитываются на этапе сборки.

Развертывание расширения в SharePoint Online

См. также

Дополнительные ресурсы