Отладка решений SharePoint Framework на современных страницах SharePoint
Создавая решения SharePoint Framework, вы можете тестировать их на современных страницах SharePoint. В случае расширений SharePoint Framework тестирование на современных страницах — единственный вариант, ведь на данный момент SharePoint Workbench не поддерживает загрузку расширений. Однако тестирование на современных страницах также можно использовать для отладки веб-частей, что полезно для разработчиков.
Важно!
Не существует технических ограничений на отладку локальных решений SharePoint Framework на современных страницах SharePoint, но следует соблюдать осторожность при ее использовании в рабочем клиенте. Эта возможность позволяет выполнять код, который не был протестирован и сверен с политиками организации, поэтому может нанести ущерб рабочим данным.
Отладка расширений SharePoint Framework на современных страницах SharePoint
В настоящее время отлаживать расширения SharePoint Framework можно только на современных страницах SharePoint. SharePoint Workbench не поддерживает тестирование расширений. В зависимости от используемой версии SharePoint Framework, отлаживать расширения на современных страницах можно несколькими способами.
Отладка расширений с помощью конфигурации обслуживания
При добавлении расширения SharePoint Framework к проекту генератор Yeoman для SharePoint Framework расширяет конфигурацию проекта. С помощью этой конфигурации можно автоматически открыть в браузере современную страницу SharePoint со всеми параметрами, необходимыми для отладки расширения на этой странице.
Как это работает
При добавлении расширения SharePoint Framework в проект генератор Yeoman для SharePoint Framework добавляет новую запись в файл config/serve.json проекта. Пример записи выглядит так:
{
"$schema": "https://developer.microsoft.com/json-schemas/spfx-build/spfx-serve.schema.json",
"port": 4321,
"https": true,
"serveConfigurations": {
"default": {
"pageUrl": "https://contoso.sharepoint.com/sites/mySite/SitePages/myPage.aspx",
"customActions": {
"d7678bd7-b58a-44fc-b9fa-a621a89edcad": {
"location": "ClientSideExtension.ApplicationCustomizer",
"properties": {
"testMessage": "Test message"
}
}
}
},
"helloWorld": {
"pageUrl": "https://contoso.sharepoint.com/sites/mySite/SitePages/myPage.aspx",
"customActions": {
"d7678bd7-b58a-44fc-b9fa-a621a89edcad": {
"location": "ClientSideExtension.ApplicationCustomizer",
"properties": {
"testMessage": "Test message"
}
}
}
}
}
}
Наряду с конфигурацией по умолчанию генератор Yeoman для SharePoint Framework создает запись для каждого расширения, добавляемого к проекту. Каждая запись содержит URL-адрес современной страницы, который следует использовать для тестирования того или иного расширения, список загружаемых расширений и список свойств для каждого расширения. Чтобы использовать определенную конфигурацию обслуживания, выполните в командной строке следующую команду:
gulp serve --config=<name>
Пример:
gulp serve --config=helloWorld
После выполнения этой команды gulp запустит браузер с современной страницей, указанной в вашей конфигурации. На странице откроется всплывающее окно с предложением подтвердить, что теперь вы будете загружать скрипты отладки.
После подтверждения загрузится страница с расширениями, указанными в конфигурации обслуживания.
Отключение сценариев отладки
По умолчанию сценарии, когда сценарии отладки включены и разрешены один раз на странице, они будут разрешены в течение всей сессии браузера. Чтобы отключить загрузку сценариев отладки без завершения сеанса браузера или ручного удаления данных сеанса, включите параметр URL-адреса reset=true в запрос.
Отладка расширений путем сборки URL-адреса отладки вручную
Если вы работаете с SharePoint Framework версии ниже 1.3.0 и хотите выполнить отладку расширения на современной странице, необходимо вручную составить URL-адрес с необходимыми параметрами. Для начала запустите локальный сервер gulp, изменив рабочий каталог в командной строке на папку проекта, а затем выполнив следующую команду:
gulp serve --nobrowser
После этого в браузере перейдите на современную страницу, где требуется тестировать расширение. После загрузки страницы скопируйте ее URL-адрес. В зависимости от типа расширения, которое требуется тестировать, к URL-адресу может потребоваться добавить разные параметры.
Отладка настройщика приложений
Для отладки настройщика приложений добавьте к URL-адресу современной страницы следующее:
Осторожностью
Отступы разрывов & строк добавлены в следующий фрагмент кода для удобства чтения. Следующий текст должен находиться в одной строке без пробелов.
?loadSPFX=true
&debugManifestsFile=https://localhost:4321/temp/manifests.js
&customActions={"<extensionId>":{
"location":"<extensionType>",
"properties":<propertiesJSON>
}}
Например:
https://contoso.sharepoint.com/sites/team-a/sitepages/news.aspx
?loadSPFX=true
&debugManifestsFile=https://localhost:4321/temp/manifests.js&customActions={
"e5625e23-5c5a-4007-a335-e6c2c3afa485":{
"location":"ClientSideExtension.ApplicationCustomizer",
"properties":{
"testMessage":"Hello as property!"
}
}
}
Ниже перечислены необходимые параметры строки запроса.
| Параметр | Описание |
|---|---|
loadSPFX=true |
Проверяет, загружена ли на странице платформа SharePoint Framework. Из соображений производительности платформа загружается, только если зарегистрировано хотя бы одно расширение. Так как компоненты еще не зарегистрированы, платформу необходимо загрузить явным образом. |
debugManifestsFile |
Указывает, что нужно загрузить компоненты, сохраненные локально. Загрузчик ищет компоненты только в каталоге приложений (для развернутого решения) и на сервере манифестов SharePoint (для системных библиотек). |
customActions |
Имитирует дополнительное действие. При развертывании и регистрации этого компонента на сайте вы создадите объект CustomAction и опишете все свойства, которые можно задать для него. |
В параметре customActions есть следующие маркеры, которые необходимо заменить:
| Маркер | Описание |
|---|---|
<extensionId> |
Используйте GUID расширения в качестве ключа, связываемого с дополнительным действием. Он должен соответствовать идентификатору расширения, указанному в файле manifest.json. |
<extensionType> |
Тип дополнительного действия. Используйте ClientSideExtension.ApplicationCustomizer для расширения "Настройщик приложений". |
<propertiesJSON> |
Необязательный объект JSON, содержащий свойства, доступные посредством элемента this.properties. |
Добавив параметры к URL-адресу, обновите страницу в браузере. На странице откроется всплывающее окно с предложением подтвердить, что теперь вы будете загружать скрипты отладки.
После подтверждения загрузится страница с расширениями, указанными в конфигурации обслуживания.
Отладка настройщика полей
Для отладки настройщика поля добавьте к URL-адресу современной страницы следующее:
Осторожностью
Отступы разрывов & строк добавлены в следующий фрагмент кода для удобства чтения. Следующий текст должен находиться в одной строке без пробелов.
?loadSPFX=true
&debugManifestsFile=https://localhost:4321/temp/manifests.js&fieldCustomizers={
"<fieldName>":{
"id":"<fieldCustomizerId>",
"properties":<propertiesJSON>
}
}
Например:
https://contoso.sharepoint.com/sites/team-a/Lists/Orders/AllItems.aspx
?loadSPFX=true
&debugManifestsFile=https://localhost:4321/temp/manifests.js
&fieldCustomizers={
"Percent":{
"id":"45a1d299-990d-4917-ba62-7cb67158be16",
"properties":{
"sampleText":"Hello!"
}
}
}
Ниже перечислены необходимые параметры строки запроса.
| Параметр | Описание |
|---|---|
loadSPFX=true |
Проверяет, загружена ли на странице платформа SharePoint Framework. Из соображений производительности платформа загружается, только если зарегистрировано хотя бы одно расширение. Так как компоненты еще не зарегистрированы, платформу необходимо загрузить явным образом. |
debugManifestsFile |
Указывает, что нужно загрузить компоненты, сохраненные локально. Загрузчик ищет компоненты только в каталоге приложений (для развернутого решения) и на сервере манифестов SharePoint (для системных библиотек). |
fieldCustomizers |
Указывает, какие поля в списке должны отрисовываться с учетом настройщика полей. Параметр ID задает GUID расширения, управляющего отрисовкой поля. Параметр properties — это необязательным текстовая строка, содержащая объект JSON, который десериализируется в this.properties для расширения. |
В параметре fieldCustomizers есть следующие маркеры, которые необходимо заменить:
| Маркер | Описание |
|---|---|
<fieldName> |
Инициализирует новый экземпляр SP.CamlQuery object (sp.js). |
<fieldCustomizerId> |
GUID расширения для настройки полей, связанный с этим полем. |
<propertiesJSON> |
Значения свойств, определенные в расширении. В этом примере sampleText является свойством, определенным с помощью расширения. |
Добавив параметры к URL-адресу, обновите страницу в браузере. На странице откроется всплывающее окно с предложением подтвердить, что теперь вы будете загружать скрипты отладки.
После подтверждения загрузится страница с расширениями, указанными в конфигурации обслуживания.
Отладка набора команд для представления списка
Для отладки набора команд представления списка добавьте к URL-адресу современной страницы следующее:
Осторожностью
Отступы разрывов & строк добавлены в следующий фрагмент кода для удобства чтения. Следующий текст должен находиться в одной строке без пробелов.
?loadSPFX=true
&debugManifestsFile=https://localhost:4321/temp/manifests.js
&customActions={"<extensionId>":{
"location":"<extensionType>",
"properties":<propertiesJSON>
}}
Например:
https://contoso.sharepoint.com/sites/team-a/Lists/Orders/AllItems.aspx
?loadSPFX=true
&debugManifestsFile=https://localhost:4321/temp/manifests.js
&customActions={"a8047e2f-30d5-40fc-b880-b2890c7c16d6":{
"location":"ClientSideExtension.ListViewCommandSet.CommandBar",
"properties":{
"sampleTextOne":"One item is selected in the list.",
"sampleTextTwo":"This command is always visible."
}
}}
Ниже перечислены необходимые параметры строки запроса.
| Параметр | Описание |
|---|---|
loadSPFX=true |
Проверяет, загружена ли на странице платформа SharePoint Framework. Из соображений производительности платформа загружается, только если зарегистрировано хотя бы одно расширение. Так как компоненты еще не зарегистрированы, платформу необходимо загрузить явным образом. |
debugManifestsFile |
Указывает, что нужно загрузить компоненты, сохраненные локально. Загрузчик ищет компоненты только в каталоге приложений (для развернутого решения) и на сервере манифестов SharePoint (для системных библиотек). |
customActions |
Имитирует дополнительное действие. Вы можете задать для этого объекта CustomAction много свойств, влияющих на внешний вид и расположение кнопки. Мы расскажем о них позже. |
В параметре customActions есть следующие маркеры, которые необходимо заменить:
| Маркер | Описание |
|---|---|
<extensionId> |
GUID расширения. |
<extensionType> |
Место, где отображаются команды. Возможные значения:ClientSideExtension.ListViewCommandSet.ContextMenu: Контекстное меню элементов.ClientSideExtension.ListViewCommandSet.CommandBar: Меню верхнего уровня для набора команд в списке или библиотеке.ClientSideExtension.ListViewCommandSet — контекстное меню и панель команд (соответствует параметру SPUserCustomAction.Location="CommandUI.Ribbon"). |
<propertiesJSON> |
Необязательный объект JSON, содержащий свойства, доступные посредством элемента this.properties. |
Добавив параметры к URL-адресу, обновите страницу в браузере. На странице откроется всплывающее окно с предложением подтвердить, что теперь вы будете загружать скрипты отладки.
После подтверждения загрузится страница с расширениями, указанными в конфигурации обслуживания.
Отладка веб-частей SharePoint Framework на современных страницах SharePoint
Чтобы тестировать локальные версии клиентских веб-частей SharePoint Framework на современных страницах SharePoint в клиенте, сначала запустите сервер gulp, изменив рабочий каталог на папку проекта и выполнив в командной строке следующую строку:
gulp serve --nobrowser
После этого в браузере перейдите на современную страницу, где требуется тестировать веб-части. После загрузки страницы добавьте к URL-адресу следующее:
?loadSPFX=true&debugManifestsFile=https://localhost:4321/temp/manifests.js
Например:
Осторожностью
Отступы разрывов & строк добавлены в следующий фрагмент кода для удобства чтения. Следующий текст должен находиться в одной строке без пробелов.
https://contoso.sharepoint.com/sites/team-a/sitepages/news.aspx
?loadSPFX=true
&debugManifestsFile=https://localhost:4321/temp/manifests.js
Страница обновится, и на ней откроется всплывающее окно с предложением подтвердить, что теперь вы будете загружать скрипты отладки.
Подтвердив, что вы хотите загружать разрабатываемые веб-части, вы можете редактировать страницу и выбирать любые локальные веб-части на панели элементов.
Дополнительные преимущества отладки веб-частей SharePoint Framework на современных страницах
Создавая веб-части SharePoint Framework, вы можете тестировать их с помощью локального рабочего места. Это не только удобно, но и эффективно. Каждый раз, когда вы меняете что-то в своем коде, локальное рабочее место автоматически обновляется, показывая последние изменения.
В некоторых случаях, например при создании веб-частей, которые связываются с SharePoint, использовать локальное рабочее место SharePoint невозможно, ведь вам требуется доступ к интерфейсам API SharePoint, которые можно вызывать только в контексте сайта SharePoint. В таких случаях вместо локального рабочего места можно использовать размещенное рабочее место SharePoint, для доступа к которому следует добавить строку /_layouts/15/workbench.aspx к URL-адресу сайта. Пример: https://contoso.sharepoint.com/sites/team-a/_layouts/15/workbench.aspx.
Ограничения пользовательского интерфейса
Для удобства рабочее место SharePoint Framework имитирует холст современных страниц SharePoint. Но это касается не всех аспектов. Ширина холста отличается, отображаются не все цвета темы, и на рабочем месте невозможно тестировать полноценный интерфейс, где веб-часть занимает всю ширину веб-браузера без горизонтальных полей и отступов.
Совместимость с другими веб-частями и расширениями
С помощью рабочего места SharePoint можно тестировать только веб-части из решения. Но что если требуется проверить работу веб-части с другими веб-частями на странице? Тестирование локального решения на современных страницах с помощью подхода, описанного в этой статье, намного эффективнее, чем упаковывание проекта, его развертывание в каталоге приложение и добавление новой веб-части на страницу.
Отладка веб-частей SharePoint Framework — альтернативный способ
Если вы создаете решение веб-части без аргумента --ship, как показано ниже,
gulp bundle
gulp package-solution
Созданные пакеты будут ссылаться на код с локального компьютера (https://localhost:4321). Можно развернуть решение в каталоге приложений обычным образом.
Затем можно запустить локальный сервер, выполнив следующее:
gulp serve --nobrowser
Теперь вы можете вернуться на сайт SharePoint, где было развернуто решение и добавить веб-части на любую страницу (современную или классическую). При этом код веб-части будет загружаться из вашей локальной среды разработки. Отладку веб-частей можно выполнять так же, как при запуске команды gulp serve с добавлением веб-части в рабочее пространство.
Этот подход следует применять только в режиме разработки. Если развернуть приложение в каталоге приложений, указывающем на локальный узел, оно не будет запускаться при неработающей среде разработки.
См. также
- Отладка решений SharePoint Framework в Visual Studio Code
- Простое тестирование веб-частей SharePoint Framework на современных страницах (Уолдек Мастикарз, Rencore)
- Тестирование и отладка решений SPFx в рабочей среде без последствий (Элио Страйф)
- Генератор Yeoman для SharePoint Framework
- Обзор SharePoint Framework