Подготовка ресурсов SharePoint из клиентской веб-части SharePoint

Статья
04/08/2023

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

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

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

Создание проекта веб-части

Создайте каталог проекта в удобном для вас расположении:
```
md asset-deployment-webpart
```
Перейдите к каталогу проекта:
```
cd asset-deployment-webpart
```
Создайте клиентскую веб-часть с помощью генератора Yeoman для SharePoint:
```
yo @microsoft/sharepoint
```
При появлении запроса введите следующие значения (выберите вариант по умолчанию для всех запросов, не перечисленных ниже).

Как называется ваше решение?: asset-deployment-webpart
Какой тип клиентского компонента нужно создать?: WebPart
Как называется ваша веб-часть?: AssetDeployment
Какой шаблон вы хотите использовать?: Платформа JavaScript отсутствует

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

Чтобы открыть проект веб-части в Visual Studio Code, выполните следующее:
```
code .
```

Создание структуры папок для ресурсов SharePoint

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

Создайте папку sharepoint в корневой папке решения.
Создайте папку assets в новой папке sharepoint.

Структура решения должна быть примерно такой, как на следующем рисунке:

Создание файлов платформы компонентов для начального развертывания

Чтобы подготовить ресурсы SharePoint для сайтов с элементами платформы компонентов, необходимо создать нужные XML-файлы в папке ресурсов. Пакеты решений SharePoint Framework поддерживают следующие элементы:

поля и столбцы сайтов;
типы контента;
экземпляры списков;
экземпляры списков с особой схемой.

Добавление файла element.xml для определений SharePoint

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

Создайте файл elements.xml в папке sharepoint\assets.

Скопируйте следующую структуру XML в файл elements.xml:

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">

    <Field ID="{060E50AC-E9C1-4D3C-B1F9-DE0BCAC300F6}"
            Name="SPFxAmount"
            DisplayName="Amount"
            Type="Currency"
            Decimals="2"
            Min="0"
            Required="FALSE"
            Group="SPFx Columns" />

    <Field ID="{943E7530-5E2B-4C02-8259-CCD93A9ECB18}"
            Name="SPFxCostCenter"
            DisplayName="Cost Center"
            Type="Choice"
            Required="FALSE"
            Group="SPFx Columns">
        <CHOICES>
        <CHOICE>Administration</CHOICE>
        <CHOICE>Information</CHOICE>
        <CHOICE>Facilities</CHOICE>
        <CHOICE>Operations</CHOICE>
        <CHOICE>Sales</CHOICE>
        <CHOICE>Marketing</CHOICE>
        </CHOICES>
    </Field>

    <ContentType ID="0x010042D0C1C200A14B6887742B6344675C8B"
            Name="Cost Center"
            Group="SPFx Content Types"
            Description="Sample content types from web part solution">
        <FieldRefs>
            <FieldRef ID="{060E50AC-E9C1-4D3C-B1F9-DE0BCAC300F6}" />
            <FieldRef ID="{943E7530-5E2B-4C02-8259-CCD93A9ECB18}" />
        </FieldRefs>
    </ContentType>

    <ListInstance
            CustomSchema="schema.xml"
            FeatureId="00bfea71-de22-43b2-a848-c05709900100"
            Title="SPFx List"
            Description="SPFx List"
            TemplateType="100"
            Url="Lists/SPFxList">
    </ListInstance>

</Elements>

Существует несколько аспектов, которые следует учитывать при использовании этого XML:

Выполняется подготовка двух полей для сайта, типа контента и экземпляра списка с настраиваемой схемой.
В определениях используется стандартная схема Feature Framework, хорошо знакомая разработчикам решений для SharePoint.
Добавляемый тип контента ссылается на настраиваемые поля.
Мы используем атрибут CustomSchema в элементе ListInstance, чтобы определить файл schema.xml для списка. Так в основе списка по-прежнему будет лежать стандартный шаблон (в данном случае — обычный настраиваемый список 100), но мы можем создать альтернативное определение во время начальной подготовки.
При подготовке экземпляров списка с использованием компонентов необходимо предоставить идентификатор компонента, связанного с определением конкретного списка. Используя атрибут FeatureId, нужно предоставить идентификатор компонента, содержащего определение списка. Например, при подготовке экземпляра настраиваемого списка атрибуту FeatureId должно быть присвоено значение {00bfea71-de22-43b2-a848-c05709900100}.

Дополнительные сведения о схеме манифеста компонента см. в статье Использование компонентов в SharePoint Foundation.

Добавление файла schema.xml для определения структуры списка

Выполняя предыдущий шаг, мы ссылались на файл schema.xml в атрибуте CustomSchema элемента ListInstance, поэтому необходимо включить этот файл в наш пакет.

Создайте файл schema.xml в папке sharepoint\assets.

Скопируйте приведенную ниже структуру XML в файл schema.xml.

<List xmlns:ows="Microsoft SharePoint" Title="Basic List" EnableContentTypes="TRUE" FolderCreation="FALSE" Direction="$Resources:Direction;" Url="Lists/Basic List" BaseType="0" xmlns="http://schemas.microsoft.com/sharepoint/">
  <MetaData>
    <ContentTypes>
      <ContentTypeRef ID="0x010042D0C1C200A14B6887742B6344675C8B" />
    </ContentTypes>
    <Fields></Fields>
    <Views>
      <View BaseViewID="1" Type="HTML" WebPartZoneID="Main" DisplayName="$Resources:core,objectiv_schema_mwsidcamlidC24;" DefaultView="TRUE" MobileView="TRUE" MobileDefaultView="TRUE" SetupPath="pages\viewpage.aspx" ImageUrl="/_layouts/images/generic.png" Url="AllItems.aspx">
        <XslLink Default="TRUE">main.xsl</XslLink>
        <JSLink>clienttemplates.js</JSLink>
        <RowLimit Paged="TRUE">30</RowLimit>
        <Toolbar Type="Standard" />
        <ViewFields>
          <FieldRef Name="LinkTitle"></FieldRef>
          <FieldRef Name="SPFxAmount"></FieldRef>
          <FieldRef Name="SPFxCostCenter"></FieldRef>
        </ViewFields>
        <Query>
          <OrderBy>
            <FieldRef Name="ID" />
          </OrderBy>
        </Query>
      </View>
    </Views>
    <Forms>
      <Form Type="DisplayForm" Url="DispForm.aspx" SetupPath="pages\form.aspx" WebPartZoneID="Main" />
      <Form Type="EditForm" Url="EditForm.aspx" SetupPath="pages\form.aspx" WebPartZoneID="Main" />
      <Form Type="NewForm" Url="NewForm.aspx" SetupPath="pages\form.aspx" WebPartZoneID="Main" />
    </Forms>
  </MetaData>
</List>

Существует несколько аспектов, которые следует учитывать при использовании этого XML:

Элемент ContentTypeRef ссылается на настраиваемый тип контента, развертываемый с помощью файла elements.xml.
Настраиваемые поля SPFxAmount и SPFxCostCenter ссылаются на элемент FieldRef.

Дополнительные сведения о схеме Schema.xml см. в статье Общие сведения о файлах Schema.xml.

Проверка использования определений в конвейере сборки

На этом этапе мы создали файлы для подготовки ресурсов SharePoint с помощью схемы компонентов из решения при развертывании. Следующим шагом является включение их в файл *.sppkg пакета SharePoint.

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

В файле package-solution.json определяются метаданные пакета, как показано в следующем фрагменте кода:

Убедитесь, что новые файлы платформы компонентов включены в пакет SharePoint.

Включите определение компонента платформы компонентов в пакет решения. Добавьте определение JSON для нужного компонента в структуру решения, как показано во фрагменте кода ниже.

{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/package-solution.schema.json",
  "solution": {
    //...
    "version": "1.0.0.0",
    "includeClientSideAssets": true,
    "isDomainIsolated": false,
    // >>> START
    //     add the following to the package-solution.json file
    "features": [{
      "title": "asset-deployment-webpart-client-side-solution",
      "description": "asset-deployment-webpart-client-side-solution",
      "id": "00000000-0000-0000-0000-000000000000",     // <-- Update new GUID
      "version": "1.0.0.0",
      "assets": {
        "elementManifests": [
          "elements.xml"
        ],
        "elementFiles":[
          "schema.xml"
        ]
      }
    }]
    // <<< END
  },
  "paths": {
    "zippedPackage": "solution/asset-deployment-webpart.sppkg"
  }
}

Существует несколько аспектов, которые следует учитывать при использовании этого XML:

Убедитесь, что вы определили уникальный GUID для свойства id внутри свойства feature.
Технически можно иметь несколько компонентов в пакете, потому что свойство features является массивом. Однако это не рекомендуется.
elements.xml указан в elementManifests, чтобы быть правильно упакованным для определения компонента в роли файл манифеста элемента.
Определение может включать несколько файлов element.xml, которые будут выполняться в том же порядке, в котором они упоминаются в определении JSON. Как правило, не рекомендуется использовать несколько файлов element.xml, так как это сильно усложняет разработку. Вы можете определить все необходимые ресурсы в файле element.xml.

Развертывание и тестирование подготовки ресурсов

Все готово к развертыванию решения в SharePoint. Так как мы подготавливаем ресурсы непосредственно на сайтах SharePoint при установке решения, эту возможность невозможно протестировать в локальной или сетевой версии Workbench.

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

Вернитесь к Visual Studio Code стороне и разверните папку sharepoint/solution/debug, которая содержит необработанные структуры XML, которые будут включены в фактический пакет *.sppkg.
Разверните пакет, созданный в каталоге приложений.

В браузере перейдите в каталог приложений клиента.
Отправьте или перетащите файл asset-deployment-webpart.sppkg из папки sharepoint/solution в каталог приложений. Откроется диалоговое окно для подтверждения доверия клиентскому решению.

Примечание.

SharePoint проверяет опубликованный пакет при развертывании. Диалоговое окно для подтверждения доверия отображается, если пакет является действительным для развертывания. Вы также можете просмотреть состояние этой проверки в столбце Допустимый пакет приложения каталога приложений.
Перейдите на тот сайт, где требуется проверить подготовку ресурсов SharePoint. Это может быть любое семейство веб-сайтов в клиенте, где развернут пакет решения.
Нажмите значок шестеренки на верхней панели навигации справа и выберите Добавить приложение, чтобы перейти на страницу "Приложения".
В поле Поиск введите deployment, а затем нажмите клавишу ВВОД, чтобы отфильтровать приложения.
Выберите приложение asset-deployment-webpart-client-side-solution, чтобы установить его на сайте. После установки обновите страницу, нажав клавишу F5. Обратите внимание на то, что при развертывании пакета решения на сайте был подготовлен настраиваемый список SPFx List.
Выберите SPFx List, чтобы перейти к списку. Обратите внимание на то, что настраиваемые поля Amount (Количество) и Cost Center (Место возникновения затрат) отображаются в списке по умолчанию.

Определение действий по обновлению для новой версии

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

Решения SharePoint Framework поддерживают следующие определения действий Feature Framework по обновлению:

ApplyElementManifest
AddContentTypeField

Дополнительные сведения об определениях действий Feature Framework по обновлению см. в статье Процедура обновления надстроек SharePoint.

Добавление нового файла element.xml для новой версии

Вернитесь к своему решению в Visual Studio Code.
Создайте файл elements-v2.xml в папке sharepoint\assets

Скопируйте указанную структуру XML в файл elements-v2.xml, в котором определяется новый подготавливаемый список SharePoint под названием New List (Новый список).

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <ListInstance
    FeatureId="00bfea71-de22-43b2-a848-c05709900100"
    Title="New List"
    Description="New list provisioned from v2"
    TemplateType="100"
    Url="Lists/NewList">
  </ListInstance>
</Elements>

Важно!

Не изменяйте GUID в этом XML-файле. Это указывает на GUID, в котором определен тип списка.

Нам также потребуется определение фактических действий Feature Framework по обновлению, поэтому создайте файл upgrade-actions-v2.xml в папке sharepoint\assets.
Скопируйте следующую структуру XML в файл upgrade-actions-v2.xml: Обратите внимание на то, что ссылка на GUID компонента в пути указывает на автоматически созданную папку, вложенную в папку sharepoint/solution/debug, и зависит от конкретного решения. Этот GUID также совпадает с идентификатором GUID компонента, который мы определили в файле package-solution.json.
```
<ApplyElementManifests>
  <ElementManifest Location="{feature-guid}\elements-v2.xml" />
</ApplyElementManifests>
```

Важно!

{feature-guid} должен соответствовать GUID компонента, добавленного в файл package-solution.json.

Развертывание новой версии в SharePoint

Далее нам нужно обновить версию решения и версию компонента, ответственного за подготовку ресурсов.

Важно!

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

Откройте файл package-solution.json из папки config и замените значения версий решения и компонента на 2.0.0.0.
Кроме того, необходимо включить файл elements-v2.xml в раздел elementManifest и добавить элемент upgradeActions с указателем на новый файл upgrade-actions-v2.xml.

Ниже полностью представлен файл package-solution.json с необходимыми изменениями. Обратите внимание, что идентификаторы в вашем решении могут слегка отличаться от представленных здесь, так что сосредоточьтесь только на добавлении недостающих элементов.
```
{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/package-solution.schema.json",
  "solution": {
    //...
    "version": "2.0.0.0",
    "includeClientSideAssets": true,
    "isDomainIsolated": false,
    "features": [{
      "title": "asset-deployment-webpart-client-side-solution",
      "description": "asset-deployment-webpart-client-side-solution",
      "id": "{feature-guid}",
      "version": "2.0.0.0",
      "assets": {
        "elementManifests": [
          "elements.xml",
          "elements-v2.xml"
        ],
        "elementFiles":[
          "schema.xml"
        ],
        "upgradeActions":[
          "upgrade-actions-v2.xml"
        ]
      }
    }]
    //...
  }
}
```
Важно!

Обратите внимание на то, что мы также добавили файл elements-v2.xml в раздел elementManifest. Благодаря этому при установке пакета версии 2.0 на чистом сайте результат будет таким же, как и при обновлении пакетов.
Чтобы повторно упаковать клиентское решение, содержащее веб-часть, и получить базовую структуру, готовую к упаковке, выполните в окне консоли указанную команду.
```
gulp bundle
```
Выполните следующую команду, чтобы создать пакет решения:
```
gulp package-solution
```
Эта команда создает новую версию пакета решения в папке sharepoint/solution. Обратите внимание: заглянув в папку sharepoint/solution/debug, можно легко убедиться, что обновленные XML-файлы включены в пакет решения.
Далее необходимо развернуть новую версию, созданную в каталоге приложений. Перейдите в каталог приложений вашего клиента.
Отправьте или перетащите файл asset-deployment-webpart.sppkg из папки sharepoint/solution в каталог приложений. SharePoint предложит вам подтвердить переопределение текущей версии.
Выберите Заменить, чтобы добавить последнюю версию в каталог приложений.
Выберите Развернуть для подтверждения доверия к последней версии.

Обратите внимание на то, что в столбце Версия приложения для решения asset-deployment-webpart-client-side-solution теперь отображается значение 2.0.0.0.

Обновление существующего экземпляра на сайте

Когда пакет в каталоге приложений обновлен, можно перейти к сайту с контентом SharePoint и обновить существующий экземпляр.

Перейдите на сайт, где вы развернули первую версию решения SharePoint Framework.
Перейдите на страницу Содержимое сайта.
Выберите Сведения в контекстном меню решения asset-deployment-webpart-client-side-solution.

Вы увидите текущие сведения об установленном решении SharePoint Framework. На этой странице теперь также отображается текст Доступна новая версия этого приложения. Получите ее сейчас.
Нажмите кнопку ПОЛУЧИТЬ, чтобы приступить к обновлению пакета.

Если вы перейдете в классический интерфейс, то увидите больше сведений о действии обновления, применяемом к решению SharePoint Framework.

Примечание.

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

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

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