Создание первого расширения для настройки полей

Статья
12/14/2023

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

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

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

Создайте каталог проекта в любом расположении.
```
md field-extension
```
Перейдите к каталогу проекта.
```
cd field-extension
```
Создайте расширение HelloWorld, запустив генератор Yeoman для SharePoint.
```
yo @microsoft/sharepoint
```
При появлении запроса введите следующие значения (выберите вариант по умолчанию для всех запросов, не перечисленных ниже).
- Как называется ваше решение?: field-extension
- Какой тип клиентского компонента нужно создать?: Расширение
- Какой тип клиентского расширения нужно создать? Настройщик полей
- Как называется настройщик полей? HelloWorld
- Какой шаблон вы хотите использовать?: нет Платформы JavaScript
На этом этапе Yeoman устанавливает необходимые зависимости и формирует шаблон файлов решения вместе с расширением HelloWorld. Это может занять несколько минут.
Введите в консоли приведенную ниже команду, чтобы запустить Visual Studio Code.
```
code .
```
Примечание.

Так как клиентское решение SharePoint основано на HTML и TypeScript, для разработки расширения можно использовать любой редактор кода, поддерживающий клиентскую разработку.
Откройте файл ./src/extensions/helloWorld/HelloWorldFieldCustomizer.manifest.json .

Этот файл определяет тип расширения и уникальный идентификатор id для расширения. Этот уникальный идентификатор понадобится позже при отладке и развертывании расширения в SharePoint.

Написание кода настройщика полей

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

Обратите внимание, что базовый класс для настройщика полей импортируется из пакета sp-listview-extensibility, который содержит код платформы SharePoint Framework, необходимый для настройщика полей.

import { Log } from '@microsoft/sp-core-library';
import { override } from '@microsoft/decorators';
import {
  BaseFieldCustomizer,
  IFieldCustomizerCellEventParameters
} from '@microsoft/sp-listview-extensibility';

Логика для настройщика полей содержится в методах onInit(), onRenderCell()и onDisposeCell() .

onInit() — это место, где вы будете выполнять настройку, необходимую для расширения. Это событие происходит после назначения классов this.context и this.properties, но до создания модели DOM страницы. Как и в случае с веб-частями, возвращает обещание, onInit() которое можно использовать для выполнения асинхронных операций; onRenderCell() не вызывается до тех пор, пока обещание не будет разрешено. Если вам оно не надо, просто верните Promise.resolve<void>();.
onRenderCell() Возникает при отрисовки каждой ячейки. Он предоставляет event.domElement HTML-элемент, где код может записать его содержимое.
onDisposeCell() происходит непосредственно перед удалением event.cellDiv . Его можно использовать для освобождения ресурсов, которые были выделены во время отображения поля. Например, если подключить onRenderCell() к элементу Reach, для его освобождения необходимо использовать onDisposeCell(), в противном случае произойдет утечка ресурсов.

Ниже приведено содержимое onRenderCell() и onDisposeCell() в решении по умолчанию.

@override
public onRenderCell(event: IFieldCustomizerCellEventParameters): void {
  // Use this method to perform your custom cell rendering.
  const text: string = `${this.properties.sampleText}: ${event.fieldValue}`;

  event.domElement.innerText = text;

  event.domElement.classList.add(styles.cell);
}

@override
public onDisposeCell(event: IFieldCustomizerCellEventParameters): void {
  super.onDisposeCell(event);
}

Отладка настройщика полей

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

Чтобы протестировать расширение, необходимо сначала создать поле для тестирования настройщика. Перейдите на сайт в клиенте SharePoint Online, на котором вы хотите проверить настройщика полей.
Перейдите на страницу Site Contents (Содержание сайта).
На панели инструментов выберите Создать, а затем выберите Список.
Создайте список под названием Заказы и нажмите кнопку Создать.
+ Выберите знак, а затем выберите Число, чтобы создать новое поле Число для списка.
Для имени поля выберите Процент, а затем выберите Сохранить.
Добавьте несколько элементов с разными числами в поле процента. Мы изменим отрисовку далее в этом руководстве, поэтому различные числа будут представлены по-разному в зависимости от вашей пользовательской реализации.
В Visual Studio Code откройте файл ./config/serve.json.

Присвойте атрибуту InternalFieldName значение Percent для имени поля, которое мы создали. pageUrl Обновите атрибуты, чтобы они соответствовали URL-адресу списка, созданного на этапах предварительного просмотра. После внесения изменений файл serve.json должен выглядеть следующим образом:
```
{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/spfx-serve.schema.json",
  "port": 4321,
  "https": true,
  "serveConfigurations": {
    "default": {
      "pageUrl": "https://sppnp.sharepoint.com/sites/Group/Lists/Orders/AllItems.aspx",
      "fieldCustomizers": {
        "Percent": {
          "id": "b909e395-f714-421f-94e0-d638dafeb210",
            "properties": {
            "sampleText": "Value"
          }
        }
      }
    },
    "helloWorld": {
      "pageUrl": "https://sppnp.sharepoint.com/sites/Group/Lists/Orders/AllItems.aspx",
      "fieldCustomizers": {
        "Percent": {
          "id": "b909e395-f714-421f-94e0-d638dafeb210",
          "properties": {
            "sampleText": "Value"
          }
        }
      }
    }
  }
}
```
Примечание.

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

Это запустит браузер по умолчанию и загрузит страницу, определенную в файле serve.json .
Согласитесь на загрузку манифестов отладки, нажав кнопку Загрузить скрипты отладки при появлении соответствующего запроса.

Обратите внимание, что значения столбца Процент теперь представляются с дополнительной строкой префикса Value:, которая предоставляется в качестве свойства для настройщика полей.

Улучшение отображения настройщика полей

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

Откройте файл ./src/extensions/helloWorld/HelloWorldFieldCustomizer.module.scss и обновите определение стиля следующим образом.
```
.HelloWorld {
  .cell {
    display: inline-block;
  }
  .full {
    background-color: #e5e5e5;
    width: 100px;
  }
}
```

Откройте файл ./src/extensions/helloWorld/HelloWorldFieldCustomizer.ts и обновите onRenderCell() метод следующим образом.

@override
public onRenderCell(event: IFieldCustomizerCellEventParameters): void {
  event.domElement.classList.add(styles.cell);
  event.domElement.innerHTML = `
    <div class='${styles.HelloWorld}'>
        <div class='${styles.full}'>
        <div style='width: ${event.fieldValue}px; background:#0094ff; color:#c0c0c0'>
            &nbsp; ${event.fieldValue}
        </div>
        </div>
    </div>`;
}

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

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

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

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

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

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

Примечание.

PnP PowerShell — это решение с открытым исходным кодом, поддержка которого предоставляется активным сообществом. Для инструментов с открытым исходным кодом не существует соглашения об уровне обслуживания в отношении поддержки корпорацией Майкрософт.

Просмотрите файл elements.xml

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

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

Просмотрите XML-код в этом файле. Свойство ClientSideComponentId автоматически обновлено до уникального идентификатора настройщика полей, доступного в файле ./src/extensions/helloWorld/HelloWorldFieldCustomizer.manifest.json . Вам потребуется настроить этот файл в соответствии с типом поля и сведениями.

Примечание.

Дополнительные сведения о XML-схеме Feature Framework см. в статье Справочник по схеме SharePoint.

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <Field ID="{060E50AC-E9C1-3D3C-B1F9-DE0BCAC200F6}"
          Name="SPFxPercentage"
          DisplayName="Percentage"
          Type="Number"
          Min="0"
          Required="FALSE"
          Group="SPFx Columns"
          ClientSideComponentId="7e7a4262-d02b-49bf-bfcb-e6ef1716aaef">
  </Field>
</Elements>

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

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

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

Также обратите внимание, что includeClientSideAssets атрибут имеет значение true. Это означает, что ресурсы JavaScript будут включены в файл *.sppkg :

{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/package-solution.schema.json",
  "solution": {
    "name": "field-extension-client-side-solution",
    "id": "80c04d1b-dca7-4d0a-86c0-9aedf904704f",
    "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": "b27507b9-7c2a-4398-8946-7438571f16f6",
        "version": "1.0.0.0",
        "assets": {
          "elementManifests": [
            "elements.xml"
          ]
        }
      }
    ]
  },
  "paths": {
    "zippedPackage": "solution/field-extension.sppkg"
  }
}

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

Теперь вы готовы развернуть решение на сайте SharePoint и автоматически включить сопоставление полей в поле. Мы будем использовать параметр --ship с этой упаковкой, чтобы все ресурсы автоматически упаковылись в пакет решения.

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

Обратите внимание, что SharePoint отображает диалоговое окно доверия и предлагает доверять клиентскому решению с SharePoint Online в качестве домена. Ресурсы будут автоматически размещаться из URL-адреса каталога приложений или из общедоступной сети CDN Майкрософт 365 в зависимости от параметров клиента.
Нажмите кнопку Развернуть.
Перейдите на тот сайт, где требуется проверить подготовку ресурсов SharePoint. Это может быть любое семейство веб-сайтов в клиенте, где развернут пакет решения.
Щелкните значок шестеренки на верхней панели навигации справа и выберите Добавить приложение.
В поле Поиск введите поле и нажмите клавишу ВВОД , чтобы отфильтровать приложения.
Выберите приложение field-extension-client-side-solution, чтобы установить решение на сайте. После завершения установки обновите страницу.
После установки решения нажмите кнопку Создать на панели инструментов страницы Содержимое сайта и выберите Список.
Создайте список под названием Счета.
Создав список, на странице одержимое сайта выберите Параметры из меню нового списка.
Выберите Столбцы>Добавить из существующих столбцов сайта.
Выберите поле SpFx ColumnsPercentage (Процентстолбцов> SPFx), подготовленное из пакета решения, и нажмите кнопку ОК.
Выберите только что созданный список Счета. Добавьте в столбец "Процент" несколько новых элементов с разными значениями, чтобы увидеть, как поле отрисовывается без параметров запроса отладки.

Отрисовка поля без параметров запроса отладки

Публикация приложения не зависит от типа расширения.