Перенос настроек веб-части редактора скриптов в SharePoint Framework
SharePoint Framework — это модель, с помощью которой можно создавать настройки SharePoint. Если вы создавали клиентские решения SharePoint с помощью веб-части редактора скриптов, возможно, вы хотите узнать о преимуществах переноса этих решений на SharePoint Framework.
В этой статье рассматриваются преимущества переноса клиентских настроек на платформу SharePoint Framework и представлен ряд факторов, которые следует учитывать при его планировании.
Примечание.
Информация в этой статье применима к настройкам, созданным с помощью веб-частей редактора контента и редактора скриптов. Любое упоминание веб-части "редактор скриптов" относится и к веб-части "редактор контента", и к веб-части "редактор скриптов".
Преимущества переноса клиентских настроек на платформу SharePoint Framework
Платформа SharePoint Framework была создана с нуля как модель разработки для SharePoint с ориентацией на клиентскую разработку. В первую очередь она предоставляет возможности расширения современных сайтов групп, но настройки на платформе SharePoint Framework также совместимы с классическим интерфейсом SharePoint. Создавая настройки с помощью SharePoint Framework, вы получите ряд преимуществ, которыми не обладает ни одна другая модель разработки для SharePoint, доступная на данный момент.
Возможность использования на всех устройствах
Современный пользовательский интерфейс SharePoint обеспечивает встроенную поддержку доступа к данным, хранящимся в SharePoint, с любого устройства. Кроме того, он поддерживает мобильное приложение SharePoint. Решения, созданные с помощью SharePoint Framework, органично вписываются в современный интерфейс SharePoint. Кроме того, их можно использовать на различных устройствах и в мобильном приложении SharePoint. Так как решения SharePoint Framework совместимы с классическим интерфейсом SharePoint, их можно использовать в организациях, которые еще не перешли на современный интерфейс.
Надежность и готовность к будущему
Раньше разработчики модифицировали SharePoint путем присоединения к определенным элементам модели DOM в пользовательском интерфейсе. С помощью этого подхода они могли менять стандартный пользовательский интерфейс или предоставлять дополнительные функции пользователям. Тем не менее в таких решениях часто возникали ошибки. Так как модель DOM для страниц SharePoint никогда не рассматривалась как платформа для расширения, каждое ее изменение приводило к ошибкам в зависящих от нее решениях.
SharePoint Framework предоставляет разработчикам стандартизованный API и точки расширяемости для создания клиентских решений и предоставления дополнительных возможностей пользователям. С помощью SharePoint Framework разработчики могут создавать решения поддерживаемым современным способом, не беспокоясь о том, как будущие изменения пользовательского интерфейса SharePoint повлияют на решение.
Удобство доступа к данным в SharePoint и Office 365
Корпорация Майкрософт постоянно расширяет возможности SharePoint и Office 365. По мере того как организации все чаще используют обе платформы, разработчикам становится все более важно использовать информацию и аналитические сведения, хранящиеся в Office 365 для создания многофункциональных решений. Одна из задач SharePoint Framework — помочь разработчикам подключаться к различным API SharePoint и Office 365.
Возможность настройки решений пользователями
Клиентские решения, созданные с помощью внедрения скриптов, часто не предлагают конечным пользователям простой способ настроить их в соответствии с их потребностями. Настроить такое решение можно было только путем изменения его кода или с помощью специального пользовательского интерфейса, созданного исключительно для этой цели.
Клиентские веб-части SharePoint Framework можно настраивать с помощью стандартной области свойств, знакомой пользователям, которые уже работали с классическими веб-частями. Создавая клиентские веб-части, разработчики могут выбирать между реактивной областью свойств (она выбрана по умолчанию), где каждое изменение свойства веб-части непосредственно влияет на ее текст, и нереактивной областью свойств, в которой изменения свойств веб-части необходимо применять в явном виде.
Работа на сайтах без скриптов
Чтобы помочь организациям управлять настройками, корпорация Майкрософт добавила возможность работы без скриптов в SharePoint Online. Если в клиенте или определенном семействе веб-сайтов установлен флаг работы без скриптов, то модификации, для которых вставляются и внедряются скрипты, отключаются.
Так как клиентские веб-части SharePoint Framework развертываются через каталог приложений с предварительным утверждением, их разрешается использовать на сайтах без скриптов. По умолчанию на современных сайтах групп включен параметр работы без скриптов, поэтому на этих сайтах невозможно внедрять скрипты. Следовательно, использование SharePoint Framework — единственный поддерживаемый способ создания клиентских настроек на современных сайтах групп.
Сходство между решениями SharePoint Framework и настройками веб-части редактор скриптов
Хотя в основе новой модели разработки используется новая цепочка инструментов, SharePoint Framework решения похожи на настройки веб-части редактора скриптов, созданные ранее. Так как они основаны на одних и тех же понятиях, вам будет проще перенести их на новую платформу SharePoint Framework.
Выполнение в составе страницы
Подобно настройкам, встроенным в веб-части редактора скриптов, решения SharePoint Framework являются частью страницы. Благодаря этому у таких решений есть доступ к модели DOM страницы и возможность взаимодействовать с другими компонентами на этой странице. Кроме того, это помогает разработчикам создавать решения, которые адаптируются к различным форм-факторам, в которых может отображаться страница SharePoint, включая мобильное приложение SharePoint.
В отличие от надстроек SharePoint, клиентские веб-части SharePoint Framework не изолируются в объекте iframe. Как следствие, все ресурсы, доступные той или иной клиентской веб-части, также доступны другим элементам страницы. Это важно учитывать при создании решений, использующих неявный поток OAuth с маркерами доступа носителя либо файлы cookie или хранилище браузера для хранения конфиденциальной информации. Так как клиентские веб-части работают в составе страницы, другим элементам этой страницы также доступны все эти ресурсы.
Создание веб-части с помощью любой библиотеки
При создании настроек с помощью веб-части редактора скриптов вы могли использовать такие библиотеки, как jQuery и Knockout, чтобы ваши настройки были более динамичными и лучше реагировали на действия пользователя. При создании клиентских веб-частей SharePoint Framework вы можете совершенствовать свои решения с помощью любой клиентской библиотеки, как и раньше. Еще одно преимущество SharePoint Framework — изоляция скрипта. Несмотря на то что веб-часть выполняется в составе страницы, ее скрипт упаковывается в виде модуля, который, к примеру, позволяет различным веб-частям на одной странице использовать разные версии jQuery, не конфликтуя друг с другом. Благодаря этой полезной функции вы можете сосредоточиться на коммерческой ценности решения, а не на технических особенностях миграции и компромиссах, связанных с функциональностью.
Запуск от имени текущего пользователя
В настройках, созданных с помощью веб-части редактора скриптов, для связи с SharePoint достаточно было вызвать его API. Клиентское решение работало в браузере в контексте текущего пользователя, а благодаря автоматической отправке с запросом файла cookie для аутентификации решение могло подключаться к SharePoint напрямую. Для связи с SharePoint не требовалась дополнительная аутентификация, как, например, при использовании надстроек SharePoint. Такой же механизм применяется к настройкам на платформе SharePoint Framework, которые также работают в контексте текущего пользователя, поэтому для связи с SharePoint им не требуется дополнительная аутентификация.
Использование клиентского кода
Решения веб-частей SharePoint Framework и редактора скриптов выполняются в браузере и могут содержать только код JavaScript на стороне клиента. Клиентские решения имеют ряд ограничений, например не повышать разрешения в SharePoint или обращаться к внешним API, которые не поддерживают взаимодействие между источниками (CORS) или проверку подлинности с использованием неявного потока OAuth. В таких случаях клиентское решение может использовать удаленный API на стороне сервера для выполнения необходимой операции и возврата результатов клиенту.
Размещение решения в SharePoint
Одним из преимуществ создания настроек SharePoint с помощью веб-части редактора скриптов было то, что их код можно было размещать в обычной библиотеке документов SharePoint. По сравнению с надстройками SharePoint для этого требовалось меньше инфраструктуры, а размещать решение было проще. Кроме того, организации могли использовать разрешения SharePoint для управления доступом к файлам решения.
Хотя размещение решений SharePoint Framework в сети CDN имеет ряд преимуществ, оно необязательно, и вы можете разместить код решений в обычной библиотеке документов SharePoint. SharePoint Framework пакеты (файлы *.sppkg), развернутые в каталоге приложений, указывают URL-адрес, по которому SharePoint Framework может найти код решения. Этот URL-адрес может быть каким угодно, при условии что пользователь, просматривающий страницу с веб-частью, может скачать скрипт из указанного расположения.
Office 365 позволяет публиковать файлы из определенной библиотеки документов SharePoint в сети CDN. Общедоступные сети CDN Office 365 сочетают в себе преимущества использования сетей CDN и простоту размещения файлов с кодом в библиотеке документов SharePoint. Если общедоступность файлов с кодом не является проблемой для организации, рекомендуем использовать общедоступную сеть CDN Office 365.
Различия между решениями SharePoint Framework и настройками веб-части редактора скриптов
Настройки SharePoint, созданные с помощью SharePoint Framework и веб-части редактора скриптов, похожи между собой. Все они выполняются в составе страницы в контексте текущего пользователя и создаются с помощью клиентского кода JavaScript. Однако существует несколько значительных различий, которые могут повлиять на принятие решений, связанных с архитектурой, и которые следует учитывать при разработке решения.
Работа на сайтах без скриптов
При создании клиентских настроек с помощью веб-части редактора скриптов нужно было учитывать, является ли сайт, на котором будет применяться настройка, сайтом без скриптов. приходилось либо просить администратора отключить параметр работы без скриптов, либо создавать решение по-другому, например с помощью модели надстроек.
Решения SharePoint Framework развертываются через каталог приложений с предварительным утверждением, поэтому на них не распространяются ограничения работы без скриптов. Эти решения работают на всех сайтах.
Развертывание и обновление через ИТ-отдел
Созданием настроек SharePoint с помощью веб-части редактора скриптов занимались в основном разработчики-любители. Располагая только разрешениями владельца сайта, разработчики-любители могли создавать привлекательные настройки SharePoint, представляющие коммерческую ценность. Каждый раз, когда требуется обновить настройку, пользователи с необходимыми разрешениями могут применять обновления к файлам скриптов решения. При этом изменения сразу становятся видны всем пользователям.
Решения веб-частей редактора скриптов затрудняют отслеживание используемых настроек и места их использования ит-организациям. Кроме того, организациям не могут определить, какие внешние скрипты используются в их интрасети, и получить доступ к их данным.
SharePoint Framework возвращает контроль ИТ-отделам. Развертывание решений SharePoint Framework и управление ими выполняются централизованно через каталог приложений, поэтому представители организации могут изучить решение, прежде чем развертывать его. Кроме того, все обновления также развертываются через каталог приложений, позволяя организациям проверять и утверждать их перед развертыванием.
Стандартизация пользовательского интерфейса
При создании настроек с помощью веб-части редактора скриптов разработчикам-любителям полностью принадлежала соответствующая модель DOM. Не существовало никаких рекомендаций касательно пользовательского интерфейса и работы таких настроек. Как следствие, разные разработчики создавали настройки по-разному, в результате чего пользовательский интерфейс становился несогласованным.
Одна из задач SharePoint Framework — стандартизировать клиентские настройки в отношении развертывания, обслуживания и пользовательского интерфейса. С помощью Office UI Fabric разработчики могут без труда сделать так, чтобы их решения выглядели и работали как неотъемлемая часть SharePoint, что повышает их привлекательность для пользователей. Цепочка инструментов SharePoint Framework создает файлы пакетов для решений, которые развертываются в каталоге приложений, и пакеты скриптов, которые развертываются в выбранном вами расположении. Все решения структурируются и управляются одним способом.
Не меняйте модель DOM вне настройки
В прошлом веб-части редактора скриптов часто использовались для изменения фрагментов страниц, например добавления кнопок на панель инструментов либо изменения заголовка или фирменной символики страницы. Такие настройки зависели от наличия определенных элементов модели DOM. Следовательно, при каждом обновлении пользовательского интерфейса SharePoint существовала опасность того, что такая настройка перестанет работать.
В SharePoint Framework доступен более структурированный и надежный подход к настройке SharePoint. Вместо того чтобы использовать определенные элементы модели DOM для настройки SharePoint, SharePoint Framework предоставляет разработчикам общедоступный API, с помощью которого они могут расширять SharePoint. SharePoint Framework поддерживает только клиентские веб-части, но рассматривается возможность добавления других форматов, таких как JSLink и настраиваемые действия пользователей, чтобы разработчики могли реализовывать наиболее распространенные сценарии с помощью SharePoint Framework.
Распространение в виде пакетов
Клиентские модификации SharePoint часто использовали списки и библиотеки SharePoint для хранения своих данных. При сборке с помощью веб-части редактора скриптов не было простого способа автоматической подготовки необходимых предварительных требований. Для развертывания той же модификации на другом сайте часто требовалось скопировать веб-часть, а также правильно воссоздать и обеспечить функционирование хранилища необходимых данных.
Решения SharePoint Framework распространяются в виде пакетов, которые могут автоматически подготавливать необходимые компоненты, такие как поля, типы контента и списки. Разработчики, создающие пакет, могут указывать артефакты, необходимые решению. Указанные артефакты создаются при установке решения на сайте. Это значительно упрощает развертывание решения на нескольких сайтах и управление им.
Использование TypeScript для создания надежных и простых в обслуживании решений
При создании настроек с помощью веб-части редактора скриптов разработчики-любители часто использовали обычный код JavaScript. Зачастую в таких решениях не были предусмотрены автоматические проверки, что могло приводить к ошибкам при рефакторинге.
На платформе SharePoint Framework разработчики могут использовать систему типов TypeScript при создании решений. Благодаря системе типов вы можете находить ошибки во время разработки, а не во время выполнения. Кроме того, рефакторинг стал проще, так как TypeScript защищает изменения кода. Так как любой код JavaScript является допустимым кодом TypeScript, переход не вызовет особых затруднений. Вы можете перенести обычный код JavaScript в TypeScript, постепенно расширяя возможности поддержки решения.
Ненадежный объект spPageContextInfo
Раньше при создании клиентских настроек для разных сайтов разработчики использовали объект JavaScript spPageContextInfo, чтобы получать сведения о текущей странице, сайте или пользователе. С помощью этого объекта было легко сделать решение пригодным для использования на разных сайтах в SharePoint, не используя фиксированные URL-адреса.
Объект spPageContextInfo все еще присутствует на классических страницах SharePoint, но он ненадежен при использовании с современными страницами и библиотеками SharePoint. При создании решений на платформе SharePoint Framework разработчикам рекомендуется использовать объект [IWebPartContext.pageContext](/javascript/api/sp-webpart-base/iwebpartcontext), который содержит контекстные сведения для определенного решения.
Отсутствие доступа к объектной модели JavaScript SharePoint по умолчанию
При создании клиентских модификаций для классического пользовательского интерфейса SharePoint многие разработчики применяли объектную модель JavaScript (JSOM) для взаимодействия с SharePoint. Модель JSOM предоставляла функцию IntelliSense и удобный доступ к API SharePoint подобно клиентской объектной модели (CSOM). На классических страницах SharePoint основной компонент модели JSOM по умолчанию присутствовал на странице, а разработчики могли загружать дополнительные компоненты, например для взаимодействия со службой поиска SharePoint.
Современный пользовательский интерфейс SharePoint по умолчанию не включает модель SharePoint JSOM. Разработчики могут загружать ее самостоятельно, но рекомендуем использовать вместо нее REST API. Модель REST более универсальна и поддерживается в различных клиентских библиотеках, таких как jQuery, Angular и React.
Корпорация Майкрософт больше не занимается разработкой модели JSOM. Если вы предпочитаете работать с API, вместо этого можно использовать корневую библиотеку JavaScript для SharePoint Patterns and Practices, предоставляющую удобный API и определения типов TypeScript.
Перенос настроек в SharePoint Framework
Перенос существующих настроек веб-части редактора скриптов в SharePoint Framework предоставляет ряд преимуществ как для пользователей, так и для разработчиков. Вы можете либо повторно использовать как можно больше существующих сценариев, либо полностью переписать настройку.
Повторное использование существующих сценариев
При переносе существующих настроек веб-части редактора скриптов в SharePoint Framework вы можете использовать существующие сценарии. Несмотря на то, что SharePoint Framework ориентирована на TypeScript, вы можете использовать обычный код JavaScript и постепенно преобразовывать его в TypeScript. Для краткосрочной поддержки определенного решения или в условиях ограниченного бюджета этого может быть достаточно.
В решении SharePoint Framework не всегда можно повторно использовать существующие скрипты. Например, решения SharePoint Framework упаковываются в виде модулей JavaScript и асинхронно загружаются на странице. Некоторые библиотеки JavaScript некорректно работают, если ссылаться на них из модуля, а на некоторые необходимо ссылаться определенным способом. Кроме того, использование событий страниц (например, onload()) или функции jQuery ready() может привести к нежелательным результатам.
Учитывая разнообразие библиотек JavaScript, сложно сказать заранее, можно ли будет использовать существующие сценарии в решении SharePoint Framework или все-таки придется переписывать их. Единственный способ узнать это — пробовать перемещать разные компоненты в решение SharePoint Framework и проверять их работу.
Повторное создание настройки
Если вам потребуются дополнительные возможности SharePoint Framework или долгосрочная поддержка решения либо окажется, что существующие скрипты невозможно использовать в SharePoint Framework, то необходимо полностью переписать настройку. Хотя это дороже, чем использовать существующие скрипты, в долгосрочной перспективе это более эффективно. Такое решение будет лучше работать, и его будет проще обслуживать и использовать.
Переписывая существующую настройку веб-части редактора скриптов для SharePoint Framework, для начала следует задуматься о нужных функциях. Для реализации пользовательского интерфейса советуем использовать Office UI Fabric, чтобы решение выглядело как неотъемлемая часть SharePoint. Для определенных компонентов, таких как диаграммы и ползунки, следует искать современные библиотеки, которые распространяются в виде модулей и включают определения типов TypeScript. Так вам будет легче внедрить компонент в решение.
Невозможно однозначно сказать, какой компонент лучше всего подходит для того или иного сценария, но SharePoint Framework поддерживает все наиболее популярные сценарии, и вы сможете преобразовать существующие клиентские настройки в полноценные решения SharePoint Framework.
Советы по миграции
Существует несколько общих шаблонов преобразования настроек веб-части редактора скриптов для SharePoint Framework.
Перемещение существующего кода в SharePoint Framework
Настройки SharePoint, созданные с помощью веб-части редактора скриптов, обычно состоят из разметки HTML, включенной в веб-часть, и одной или нескольких ссылок на файлы JavaScript. При преобразовании существующих настроек в решение SharePoint Framework, скорее всего, потребуется переместить разметку HTML из веб-части редактора скриптов в метод render() клиентской веб-части SharePoint Framework. Ссылки на внешние скрипты будут заменены ссылками в свойстве externals в файле ./config/config.json. Необходимо скопировать внутренние скрипты в исходную папку веб-части, а затем сослаться на них из класса веб-части с помощью операторов require().
Ссылки на функции в файлах скриптов
Чтобы ссылаться на функции из файлов скриптов, необходимо определить эти функции как экспортированные. Допустим, у вас есть файл JavaScript, который вы хотите использовать в клиентской веб-части SharePoint Framework:
var greeting = function() {
alert('How are you doing?');
return false;
}
Чтобы иметь возможность вызвать функцию greeting из класса веб-части, необходимо изменить содержимое файла JavaScript на следующее:
var greeting = function() {
alert('How are you doing?');
return false;
}
module.exports = {
greeting: greeting
};
Затем вы сможете сослаться на скрипт в классе веб-части и вызвать функцию greeting:
public render(): void {
this.domElement.innerHTML = `<input type="button" value="Click me"/>`;
const myScript = <any> require('./my-script.js');
this.domElement.querySelector('input').addEventListener('click', myScript.greeting);
}
Выполнение вызовов AJAX
Многие клиентские настройки используют библиотеку jQuery для выполнения запросов AJAX из-за ее простоты и совместимости с разными браузерами. Если вы используете jQuery только из-за этого, то вы можете совершать вызовы AJAX с помощью стандартного клиента HTTP, входящего в состав SharePoint Framework.
В SharePoint Framework есть два клиента HTTP: SPHttpClient, предназначенный для отправки запросов REST API SharePoint, и HttpClient, предназначенный для отправки веб-запросов других REST API. Вот как выполнить вызов, используя SPHttpClient для получения заголовка текущего сайта SharePoint:
this.context.spHttpClient.get(`${this.context.pageContext.web.absoluteUrl}/_api/web?$select=Title`,
SPHttpClient.configurations.v1,
{
headers: {
'Accept': 'application/json;odata=nometadata',
'odata-version': ''
}
})
.then((response: SPHttpClientResponse): Promise<{Title: string}> => {
return response.json();
})
.then((web: {Title: string}): void => {
// web.Title
}, (error: any): void => {
// error
});