Развертывание расширения в SharePoint (Hello World, часть 3)

Статья
03/21/2023

В этой статье рассказывается, как развернуть настройщик заполнителей SharePoint Framework (SPFx) в SharePoint и проверить, работает ли он на современных страницах SharePoint.

Перед началом работы необходимо выполнить процедуры, описанные в следующих статьях:

Вы также можете следовать этому руководству, посмотрев видео на канале YouTube сообщества платформы Microsoft 365 (PnP):

Существует несколько способов развертывания ваших расширений SPFx и их активации на сайтах SharePoint. Правильный вариант зависит от требований бизнеса и поставленных целей. Основные параметры:

После установки решения активируйте расширение на определенных сайтах, используя опцию активации на основе платформы компонентов. Это единственная модель, которая поддерживает активы уровня сайта, созданные или развернутые при активации решения.
Используйте вариант развертывания на уровня клиента и активируйте расширение на определенных сайтах, доступных API SharePoint и интерфейсах.
Используйте вариант развертывания на уровне клиента для расширений из каталога приложения. Эта возможность поддерживается в SharePoint Framework с версии 1.6.

Упаковка настройщика приложения «Hello World»

В этом примере мы активируем расширение на одном сайте. Это означает, что мы будем использовать активацию на основе платформы компонентов при установке решения на сайте.

В окне консоли перейдите в каталог проекта расширения, созданного при работе со статьей Создание первого расширения SharePoint Framework (Hello World, часть 1).
```
cd app-extension
```
Если команда gulp serve все еще выполняется, остановите ее, нажав клавиши CTRL+C.

В отличие от работы в режиме отладки, чтобы использовать расширение на современных страницах SharePoint, вам потребуется развернуть и зарегистрировать расширение в SharePoint в области Семейство веб-сайтов, Сайт или Список. Место и тип активности настройщика приложения определяются областью. В данном сценарии мы зарегистрируем настройщик заполнителей, используя область Семейство веб-сайтов.

Прежде чем упаковать решение, нам необходимо включить код для автоматизации активации решения при установке его на сайте. В данном случае мы воспользуемся элементами платформы компонентов, чтобы выполнить эти действия в пакете решения, но вы можете связать настройщик заполнителей с сайтом SharePoint, используя интерфейсы REST SharePoint или CSOM при подготовке сайта к работе.
Установите пакет решения на нужном сайте, где он должен быть установлен, чтобы разрешить выполнение манифеста расширения.
Свяжите настройщик заполнителей с запланированной областью. Это можно сделать программным путем с помощью API REST SharePoint или CSOM или с помощью платформы компонентов в пакете решения SharePoint Framework. Указанные ниже свойства необходимо сопоставить в объекте UserCustomAction на уровне семейства веб-сайтов, сайта или списка.
- ClientSideComponentId: это идентификатор (GUID) расширения SPFx, установленного в каталоге приложений.
- ClientSideComponentProperties — это необязательный параметр, с помощью которого можно предоставлять свойства для экземпляра расширения SPFx.
Вы можете требовать добавления вашего расширения на сайт, используя параметр skipFeatureDeployment в файле ./config/package-solution.json. Даже если вы не требуете установки решения на сайте, вам нужно связать идентификатор ClientSideComponentId с конкретными объектами, чтобы расширение было видимым.

Проверка наличия определений SharePoint в существующем файле elements.xml

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

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

Проверьте существующую XML-структуру в файле elements.xml. Свойство ClientSideComponentId было обновлено на основе уникального ИД настройщика приложений, определенного в файле ./src/extensions/helloWorld/HelloWorldApplicationCustomizer.manifest.json.

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

Для определения настройщика заполнителей в конфигурации используется конкретное расположение объекта ClientSideExtension.ApplicationCustomizer. Так как по умолчанию этот файл elements.xml сопоставлен с компонентом с областью Web, это действие CustomAction будет автоматически добавлено в свойство Web.UserCustomAction на сайте, на котором устанавливается решение.

Убедитесь, что конфигурация соответствует изменениям, внесенным в свойства настройщика приложений. Задайте для свойства ClientSideComponentProperties следующую строку JSON в кодировке HTML, которая содержит значения свойств:

{&quot;Top&quot;:&quot;Top area of the page&quot;,&quot;Bottom&quot;:&quot;Bottom area in the page&quot;}

Может быть воспользоваться файлом ClientSideInstance.xml в папке с ресурсами?

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

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

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

Совет

Дополнительные сведения см. в разделе Развертывание клиентом расширений SharePoint Framework.

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

В файле ./config/package-solution.json определяются метаданные пакета. Чтобы обеспечить учет elements.xml файла во время упаковки решения, шаблон по умолчанию включает необходимую конфигурацию для определения определения компонента Feature Framework в пакете решения.

Исходное свойство elementManifests в файле ./config/package-solution.json выглядит так:

"assets": {
  "elementManifests": [
    "elements.xml",
    "clientsideinstance.xml"
  ]
}

Удалите запись для clientsideinstance.xml в разделе elementManifests, так как нам это не требуется в данном обучающем курсе.

"assets": {
  "elementManifests": [
    "elements.xml"
  ]
}

После внесения необходимых изменений файл ./config/package-solution.json теперь выглядит примерно так, как в следующем примере:

{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/package-solution.schema.json",
  "solution": {
    "name": "app-extension-client-side-solution",
    "id": "65e15d73-515b-4d57-8c92-66ba5890c7b4",
    "version": "1.0.0.0",
    "includeClientSideAssets": true,
    "skipFeatureDeployment": true,
    "isDomainIsolated": false,
    "developer": {
      "name": "",
      "websiteUrl": "",
      "privacyUrl": "",
      "termsOfUseUrl": "",
      "mpnId": "Undefined-1.14.0"
    },
    "metadata": {
      "shortDescription": {
        "default": "app-extension description"
      },
      "longDescription": {
        "default": "app-extension description"
      },
      "screenshotPaths": [],
      "videoUrl": "",
      "categories": []
    },
    "features": [
      {
        "title": "Application Extension - Deployment of custom action",
        "description": "Deploys a custom action with ClientSideComponentId association",
        "id": "41b490c7-49f7-4db4-b7ea-c632d0fb9785",
        "version": "1.0.0.0",
        "assets": {
          "elementManifests": [
            "elements.xml"
          ]
        }
      }
    ]
  },
  "paths": {
    "zippedPackage": "solution/app-extension.sppkg"
  }
}

Развертывание расширения в SharePoint Online и локальное размещение кода JavaScript

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

Чтобы упаковать клиентское решение, содержащее расширение, и получить базовую структуру, готовую к упаковке, в окне консоли введите указанную ниже команду.
```
gulp bundle
```
Затем выполните следующую команду, чтобы создать пакет решения:
```
gulp package-solution
```
Эта команда создает следующий пакет: ./sharepoint/solution/app-extension.sppkg.
Теперь необходимо развернуть пакет в каталоге приложений. Перейдите в каталог приложений клиента и отправьте или перетащите файл ./sharepoint/solution/app-extension.sppkg в список Приложения для SharePoint. В SharePoint отобразится панель с запросом на включение клиентского решения.

Мы не изменяли URL-адреса для размещения решения в этом развертывании, поэтому по-прежнему используется URL-адрес https://localhost:4321.
Выберите переключатель Включить только это приложение, а затем нажмите кнопку Включить приложение.
Назад в консоль и убедитесь, что решение запущено. Если он не запущен, выполните следующую команду в папке решения:
```
gulp serve --nobrowser
```
Перейдите на тот сайт, где требуется проверить подготовку ресурсов SharePoint. Это может быть любое семейство веб-сайтов в клиенте, где развернут пакет решения.
Щелкните значок с изображением шестеренки на верхней панели навигации справа и выберите команду Добавить приложение. Откроется страница "Приложения".
В поле Поиск введите приложение, а затем нажмите клавишу ВВОД, чтобы отфильтровать приложения.
Выберите приложение app-extension-client-side-solution, чтобы установить решение на сайте. После завершения установки вернитесь на сайт, на котором установлено приложение.

Теперь верхний и нижний колонтитулы будут отрисовываться так же, как и при использовании параметров запроса отладки.

Дальнейшие действия

Поздравляем, вы развернули расширение из каталога приложений на современной странице SharePoint!

Из следующей статьи Размещение расширения в сети доставки содержимого Office 365 (Hello World, часть 4) вы узнаете, как развернуть ресурсы расширения в сети CDN и загружать их оттуда.

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