Перенос пунктов меню "Изменение блока управления" (ECB) в расширения SharePoint Framework

  • Статья

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

В этом руководстве описано, как перенести устаревшие "классические" настройки в текущую модель: SharePoint Framework расширения.

Сначала рассмотрим доступные разработчикам варианты для создания расширений SharePoint Framework.

  • Настройщик приложений. Расширьте встроенный "современный" пользовательский интерфейс SharePoint, добавив пользовательские элементы HTML и клиентский код в заранее определенные заполнители на "современных" страницах. Дополнительные сведения о настройщиках приложений см. в разделе Создание первого расширения SharePoint Framework (Hello World, часть 1)
  • Набор команд. добавляет пользовательские пункты меню ECB и настраиваемые кнопки на панель команд или в представление списка или библиотеки. С этими командами можно связать любое действие на стороне клиента. Дополнительные сведения о наборах команд см. в разделе Создание первого расширения набора команд ListView.
  • Настройщик полей. Настройте отображение поля в представлении списка, используя настраиваемые элементы HTML и клиентский код. Дополнительные сведения о настройщиках полей см. в разделе Создание первого расширения настройщика полей.

Наиболее полезное в нашем контексте расширение — набор команд.

Предположим, что у вас есть CustomAction в SharePoint Online элемент пользовательского меню ECB для документов в библиотеке. Назначение пункта меню ECB — открытие настраиваемой страницы с предоставлением идентификаторов списка и выбранного в текущий момент пункта в строке запроса целевой страницы.

В следующем фрагменте кода вы увидите XML-код, определяющий CustomAction с помощью SharePoint Feature Framework.

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <CustomAction
      Id="OpenDetailsPageWithItemReference"
      Title="Show Details"
      Description="Opens a new page with further details about the currently selected item"
      Sequence="1001"
      RegistrationType="List"
      RegistrationId="101"
      Location="EditControlBlock">
    <UrlAction Url="ShowDetails.aspx?ID={ItemId}&amp;List={ListId}" />
  </CustomAction>
</Elements>

Как видите, файл элементов признаков определяет элемент типа CustomAction для добавления нового элемента в EditControlBlock расположение (то есть ECB) для любого документа в любой библиотеке (RegistrationType is List and RegistrationId is 101).

На приведенном ниже рисунке представлены выходные данные вышеописанного дополнительного действия в представлении списка для библиотеки.

Пользовательский нижний колонтитул на классической странице

Обратите внимание на то, что настраиваемый элемент ECB в SharePoint Feature Framework работает и в "современном" списке. Если не использовать код JavaScript, то дополнительное действие для списков будет работать и в "современных" списках.

Ниже описано, как перенести старое решение в SharePoint Framework.

Создание решения SharePoint Framework

  1. С помощью консоли создайте папку для проекта:

    md spfx-ecb-extension

  2. Перейдите в папку проекта:

    cd spfx-ecb-extension

  3. Создайте веб-часть решения SharePoint Framework, запустив генератор SharePoint Yeoman.

    yo @microsoft/sharepoint

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

    • Как называется ваше решение?: spfx-ecb-extension
    • Какие базовые пакеты нужно выбрать как целевые для ваших компонентов? Только SharePoint Online (последняя версия)
    • Какой тип клиентского компонента нужно создать?: Расширение
    • Какой тип клиентского расширения нужно создать? Набор команд ListView
    • Как называется набор команд? CustomECB

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

  5. Запустите Visual Studio Code (или другой редактор кода) и начните разработку решения. Чтобы запустить Visual Studio Code, можно выполнить приведенный ниже оператор.

    code .

Определение нового элемента ECB

Чтобы воспроизвести такое поведение пункта меню ECB, созданного с помощью SharePoint Feature Framework, нужно реализовать такую же логику с помощью клиентского кода в новом решении SharePoint Framework. Чтобы выполнить эту задачу, сделайте следующее:

  1. Откройте файл ./src/extensions/customEcb/CustomEcbCommandSet.manifest.json. Скопируйте значение свойства id и сохраните его в надежном месте, так как оно понадобится вам позже.

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

    {
  "$schema": "https://developer.microsoft.com/json-schemas/spfx/command-set-extension-manifest.schema.json",

  "id": "5d3bac4c-e040-44ed-ab43-464490d22762",
  "alias": "CustomEcbCommandSet",
  "componentType": "Extension",
  "extensionType": "ListViewCommandSet",

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

  "requiresCustomScript": false,

  "items": {
    "ShowDetails": {
      "title": {
        "default": "Show Details"
      },
      "type": "command"
    }
  }
}

  3. Откройте файл ./src/extensions/customEcb/CustomEcbCommandSet.ts и измените содержимое в соответствии со следующим фрагментом кода:

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

import * as strings from 'CustomEcbCommandSetStrings';

export interface ICustomEcbCommandSetProperties {
  targetUrl: string;
}

export default class CustomEcbCommandSet extends BaseListViewCommandSet<ICustomEcbCommandSetProperties> {

  @override
  public onInit(): Promise<void> {
    return Promise.resolve();
  }

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

  @override
  public onExecute(event: IListViewCommandSetExecuteEventParameters): void {
    switch (event.itemId) {
      case 'ShowDetails':

        const itemId: number = event.selectedRows[0].getValueByName("ID");
        const listId: Guid = this.context.pageContext.list.id;

        window.location.replace(`${this.properties.targetUrl}?ID=${itemId}&List=${listId}`);

        break;
      default:
        throw new Error('Unknown command');
    }
  }
}

    Обратите внимание на оператор import в самом начале файла. Он ссылается на тип Guid, который будет использоваться для хранения идентификатора текущего списка.

    Интерфейс ICustomEcbCommandSetProperties объявляет одно свойство с именем targetUrl , которое можно использовать для предоставления URL-адреса целевой страницы, открываемой при выборе пункта меню ECB.

    Переопределенный метод onExecute() выполняет дополнительное действие. Обратите внимание на фрагмент кода, считывающий идентификатор выбранного элемента из аргумента event, а также идентификатор исходного списка из объекта pageContext.

    Наконец, обратите внимание на переопределение метода onListViewUpdated(), который по умолчанию включал команду ShowDetails, только если выбран один элемент.

    Перенаправление на целевой URL-адрес выполняется с помощью классического кода JavaScript и функции window.location.replace(). В методе можно написать любой код onExecute() TypeScript. В качестве примера можно использовать платформу диалоговых окон SharePoint Framework, чтобы открыть новое диалоговое окно и взаимодействовать с пользователями.

    Примечание.

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

    На приведенном ниже рисунке показан результат.

    Набор команд ECB в

Тестирование решения в режиме отладки

  1. Вернитесь в окно консоли и выполните приведенную ниже команду, чтобы выполнить сборку и запустить локальный сервер Node.js для размещения решения.

    gulp serve --nobrowser

  2. Теперь откройте любой браузер и перейдите к "современной" библиотеке на любом "современном" сайте группы. Добавьте приведенные ниже параметры строки запроса к URL-адресу страницы AllItems.aspx.

    ?loadSpfx=true&debugManifestsFile=https://localhost:4321/temp/manifests.js&customActions={"6c5b8ee9-43ba-4cdf-a106-04857c8307be":{"location":"ClientSideExtension.ListViewCommandSet.ContextMenu","properties":{"targetUrl":"ShowDetail.aspx"}}}

    В приведенной выше строке запроса замените GUID на сохраненное ранее значение id из файла CustomEcbCommandSet.manifest.json.

    Кроме того, существует location свойство, которое принимает значение ClientSideExtension.ListViewCommandSet.ContextMenu, которое указывает SPFx на отображение набора команд в качестве элемента меню ECB. Ниже представлены допустимые значения свойства location.

    • ClientSideExtension.ListViewCommandSet.ContextMenu: контекстное меню элементов.
    • ClientSideExtension.ListViewCommandSet.CommandBar — меню верхнего уровня для набора команд в списке или библиотеке.
    • ClientSideExtension.ListViewCommandSet: контекстное меню и панель команд (соответствует SPUserCustomAction.Location="CommandUI.Ribbon").

    В строке запроса есть свойство с именем properties , которое представляет сериализацию JSON объекта типа ICustomEcbCommandSetProperties , который является типом настраиваемых свойств, запрошенных настраиваемым набором команд для отрисовки.

    При выполнении запроса страницы появится запрос разрешения на запуск кода с домена localhost (окно с заголовком "Разрешить скрипты отладки?"). Если вы хотите отладить и протестировать решение локально, необходимо разрешить загрузку скриптов отладки.

    Примечание.

    Либо можно создавать записи конфигурации службы в файле config/serve.json проекта для автоматизации создания параметров строки запроса отладки, как описано в этом документе: Отладка решений SharePoint Framework на современных страницах SharePoint

Упаковка и размещение решения

Если вы довольны результатом, упакуйте решение и разместите его в настоящей инфраструктуре.

Прежде чем собирать пакет, необходимо объявить XML-файл Feature Framework для подготовки расширения.

Обзор элементов Feature Framework

  1. В редакторе кода откройте вложенную папку /sharepoint/assets папки решения и измените файлelements.xml . В приведенном ниже фрагменте кода показано, как должен выглядеть файл.

    <?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
    <CustomAction
        Title="CustomEcb"
        RegistrationId="101"
        RegistrationType="List"
        Location="ClientSideExtension.ListViewCommandSet.ContextMenu"
        ClientSideComponentId="6c5b8ee9-43ba-4cdf-a106-04857c8307be"
        ClientSideComponentProperties="{&quot;targetUrl&quot;:&quot;ShowDetails.aspx&quot;}">
    </CustomAction>
</Elements>

    Как видите, он напоминает файл SharePoint Feature Framework из "классической" модели, но использует атрибут ClientSideComponentId для обращения к id настраиваемого расширения, а также атрибут ClientSideComponentProperties для настройки специальных свойств конфигурации, необходимых расширению.

  2. Откройте файл ./config/package-solution.json в решении. В файле можно увидеть ссылку на файлelements.xml в assets разделе.

    {
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/package-solution.schema.json",
  "solution": {
    "name": "spfx-ecb-extension-client-side-solution",
    "id": "b8ff6fdf-16e9-4434-9fdb-eac6c5f948ee",
    "version": "1.0.2.0",
    "features": [
      {
        "title": "Custom ECB Menu Item.",
        "description": "Deploys a custom ECB menu item sample extension",
        "id": "f30a744c-6f30-4ccc-a428-125a290b5233",
        "version": "1.0.0.0",
        "assets": {
          "elementManifests": [
            "elements.xml"
          ]
        }
      }
    ]
  },
  "paths": {
    "zippedPackage": "solution/spfx-ecb-extension.sppkg"
  }
}

Пакет, упаковка и развертывание компонента SharePoint Framework

Подготовьте и разверните решение для клиента SharePoint Online:

  1. Выполните приведенную ниже задачу, чтобы создать пакет решения. При этом создается сборка выпуска проекта:

    gulp bundle --ship

  2. Выполните приведенную ниже задачу, чтобы упаковать решение. Эта команда создает пакет *.sppkg в папке sharepoint/solution .

    gulp package-solution --ship

  3. Добавьте или перетащите новый пакет клиентского решения в каталог приложений в клиенте и нажмите кнопку Развернуть.

Установка и запуск решения

  1. Откройте браузер и перейдите на любой "современный" сайт.

  2. Перейдите на страницу Содержимое сайта и добавьте новое приложение.

  3. Выберите Из вашей организации, чтобы просмотреть решения, доступные в каталоге приложений.

  4. Выберите решение spfx-ecb-extension-client-side-solution и установите его на целевом сайте.

    Добавление решения на сайт

  5. После завершения установки приложения откройте библиотеку Документы на сайте. Выбрав один документ, вы увидите пользовательский пункт меню ECB в действии.

Наслаждайтесь новым настраиваемым пунктом меню ECB, созданным с помощью расширений SharePoint Framework!

См. также