Создание первой клиентской веб-части SharePoint (Hello World, часть 1)

Клиентские веб-части — это клиентские компоненты, выполняемые в контексте страницы SharePoint. Клиентские веб-части можно развернуть в средах SharePoint, поддерживающих SharePoint Framework. Для их создания можно также использовать современные веб-платформы, инструменты и библиотеки JavaScript.

Поддержка клиентских веб-частей:

• Создание при помощи HTML и JavaScript.
• Как SharePoint Online, так и локальные среды.

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

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

Создайте новый каталог для своего проекта и измените текущую папку на этот каталог.

Создайте новый проект, запустив генератор Yeoman для SharePoint из созданного вами нового каталога:

yo @microsoft/sharepoint

Генератор Yeoman для SharePoint предложит вам ответить на ряд вопросов. Для всех вопросов, за исключением приведенных ниже, примите параметры по умолчанию:

• Какой тип клиентского компонента нужно создать?: WebPart
• Как называется веб-часть?: HelloWorld
• Какой шаблон следует использовать?: Без платформы

На этом этапе Yeoman создает шаблон проекта (файлы папок & ) и устанавливает необходимые зависимости, запустив npm install. Это обычно занимает 1–3 минуты в зависимости от скорости интернет-соединения.

Когда шаблон проекта будет сформирован, а зависимости установлены, Yeoman выведет сообщение об успехе операции примерно такого содержания:

_=+#####!
###########|       .-----------------------------------.
###/    (##|(@)    |          Congratulations!         |
###  ######|   \   |   Solution webpart-1 is created.  |
###/   /###|   (@) |  Run gulp serve to play with it!  |
#######  ##|   /   '-----------------------------------'
###     /##|(@)
###########|
**=+####!

Сведения об устранении неполадок см. в статье Известные проблемы.

Использование удобного редактора кода

Так как клиентские решения SharePoint созданы с помощью HTML и TypeScript, для разработки веб-части можно использовать любой редактор кода, который поддерживает клиентское программирование, например:

• Visual Studio Code;
• Atom;
• Webstorm

В примерах и инструкциях, приведенных в документации по SharePoint Framework, используется Visual Studio Code. Visual Studio Code (VS Code) — мощный редактор исходного кода от корпорации Майкрософт, который занимает мало места на диске и работает на компьютере. VS Code доступен для Windows, macOS и Linux. Он изначально поддерживает JavaScript, TypeScript, Node.js, а также предусматривает использование богатой экосистемы расширений для других языков (например, C++, C#, Python, PHP).

Просмотр веб-части

Вы можете просмотреть и протестировать свою клиентскую веб-часть в размещенной в SharePoint рабочей области без развертывания решения в SharePoint. Для этого нужно запустить локальный веб-сервер, с которого размещенная рабочая область сможет загрузить файлы, с помощью задачи gulp serve.

Клиентская цепочка инструментов по умолчанию использует конечные точки HTTPS. Часть процесса Настройка среды разработки включает настройку доверия к SSL-сертификату разработки, который входит в цепочку инструментов в локальной среде. Это необходимо для того, чтобы ваш браузер доверял сертификату.

Обновите URL-адрес размещенной рабочей области вашего проекта

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

• Найдите и откройте в проекте файл ./config/serve.json.

• Найдите свойство initialPage:

  {
    "$schema": "https://developer.microsoft.com/json-schemas/core-build/serve.schema.json",
    "port": 4321,
    "https": true,
    "initialPage": "https://enter-your-SharePoint-site/_layouts/workbench.aspx"
  }
  

• Измените домен enter-your-SharePoint-site на URL-адрес клиента SharePoint и сайта, который вы хотите использовать для тестирования. Пример: https://contoso.sharepoint.com/sites/devsite/_layouts/workbench.aspx.

gulp serve --nobrowser

Запуск локального веб-сервера & , запуск размещенной рабочей среды

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

gulp serve

Эта команда выполняет ряд задач Gulp, позволяющих создать и запустить локальный веб-сервер, на котором размещены конечные точки localhost:4321 и localhost:5432. После этого будет открыт браузер по умолчанию и загружены веб-части из локальной среды разработки для предварительного просмотра в размещенной рабочей области.

gulp serve
Build target: DEBUG
[12:13:24] Using gulpfile d:\pnp\helloworld-webpart\gulpfile.js
[12:13:24] Starting 'serve'...
[12:13:24] Starting gulp
[12:13:24] Starting subtask 'spfx-serve'...
[12:13:24] [spfx-serve] To load your scripts, use this query string: ?debug=true&noredir=true&debugManifestsFile=https://localhost:4321/temp/manifests.js
[12:13:25] Starting server...
[12:13:25] Finished subtask 'spfx-serve' after 1.24 s
[12:13:25] Starting subtask 'pre-copy'...
[12:13:26] Finished subtask 'pre-copy' after 533 ms
[12:13:26] Starting subtask 'copy-static-assets'...
[12:13:26] Starting subtask 'sass'...
[12:13:26] Server started https://localhost:4321
[12:13:26] LiveReload started on port 35729
[12:13:26] Running server
[12:13:26] Opening https://sppnp.sharepoint.com/_layouts/workbench.aspx using the default OS app

Инструменты клиентской разработки SharePoint используют Gulp как средство запуска таких задач по сборке, как:

• перекомпиляция файлов TypeScript в JavaScript;
• компиляция файлов SASS в CSS;
• добавление в пакет и минификация файлов JavaScript и CSS;

VS Code поддерживает Gulp и другие средства запуска задач. Нажмите клавиши CTRL+SHIFT+B в Windows или CMD+SHIFT+B в macOS для отладки и просмотра веб-части.

SharePoint Workbench — это рабочая область конструирования для разработчиков, которая позволяет быстро просматривать и проверять веб-части, не развертывая их в SharePoint. SharePoint Workbench включает клиентскую страницу и клиентский холст, на которых можно добавлять, удалять и проверять веб-части, которые находятся в разработке.

Предварительный просмотр и тестирование веб-части с помощью SharePoint Workbench

1. Чтобы добавить веб-часть HelloWorld, выберите значок добавления (этот значок появляется, когда вы наводите курсор мыши на раздел, как показано на изображении выше). Откроется панель элементов со списком веб-частей, которые можно добавить. Список включает веб-часть HelloWorld, а также другие веб-части, доступные локально в среде разработки.

   

2. Выберите пункт HelloWorld, чтобы добавить эту веб-часть на страницу.

   

   Поздравляем! Вы только что добавили свою первую клиентскую веб-часть на клиентскую страницу.

3. Выберите значок карандаша в крайнем левом углу веб-части, чтобы открыть панель свойств веб-части.

   

   На панели свойств можно задавать свойства для настройки веб-части. Панель свойств запускается на стороне клиента и имеет одинаковый дизайн для всех веб-частей SharePoint.

4. Измените текст в поле Описание на текст Клиентские веб-части — это великолепно!

   Обратите внимание, что при вводе текст в веб-части также меняется.

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

Структура проекта веб-части

Анализ структуры проекта веб-части с помощью Visual Studio Code

1. В консоли остановите локальный веб-сервер и завершите процесс. Нажмите клавиши CTRL+C в Windows или macOS.

2. Введите следующую команду, чтобы открыть проект веб-части в VS Code (или используйте другой редактор):

   code .
   

TypeScript — это основной язык для создания клиентских веб-частей SharePoint. TypeScript — это типизированное надмножество JavaScript, которое компилируется в обычный JavaScript. Клиентские средства разработки SharePoint создаются с помощью классов, модулей и интерфейсов TypeScript, помогая разработчикам создавать надежные клиентские веб-части.

Ниже приведены некоторые ключевые файлы в проекте.

Класс веб-части

HelloWorldWebPart.ts в папке src\webparts\helloworld определяет основную точку входа для веб-части. Класс веб-части HelloWorldWebPart расширяет класс BaseClientSideWebPart. Чтобы клиентская веб-часть была допустимой, она должна расширять класс BaseClientSideWebPart.

Класс BaseClientSideWebPart обеспечивает минимальную функциональность, необходимую для создания веб-части. Он также предоставляет много параметров для проверки и доступа к свойствам, доступным только для чтения (например, displayMode), другим свойствам веб-частей, контексту веб-частей, а также свойствам instanceId и domElement.

Обратите внимание, что класс веб-части определяется как принимающий свойство типа IHelloWorldWebPartProps.

Тип свойства определяется как интерфейс перед классом HelloWorldWebPart в файле HelloWorldWebPart.ts.

export interface IHelloWorldWebPartProps {
  description: string;
}

С помощью этого определения свойства задаются типы настраиваемых свойств для веб-части. Дополнительные сведения см. в разделе, посвященном области свойств, ниже.

Метод отрисовки веб-части

Элемент DOM, в котором должна отрисовываться веб-часть, доступен в методе render(). Этот метод используется для отрисовки веб-части в этом элементе DOM. В веб-части HelloWorld элемент DOM присвоен переменной DIV.

public render(): void {
  this.domElement.innerHTML = `
  <section class="${styles.helloWorld} ${!!this.context.sdks.microsoftTeams ? styles.teams : ''}">
    <div class="${styles.welcome}">
      <img alt="" src="${this._isDarkTheme ? require('./assets/welcome-dark.png') : require('./assets/welcome-light.png')}" class="${styles.welcomeImage}" />
      <h2>Well done, ${escape(this.context.pageContext.user.displayName)}!</h2>
      <div>${this._environmentMessage}</div>
      <div>Web part property value: <strong>${escape(this.properties.description)}</strong></div>
    </div>
    <div>
      <h3>Welcome to SharePoint Framework!</h3>
      <p>
      The SharePoint Framework (SPFx) is a extensibility model for Microsoft Viva, Microsoft Teams and SharePoint. It's the easiest way to extend Microsoft 365 with automatic Single Sign On, automatic hosting and industry standard tooling.
      </p>
      <h4>Learn more about SPFx development:</h4>
        <ul class="${styles.links}">
          <li><a href="https://aka.ms/spfx" target="_blank">SharePoint Framework Overview</a></li>
          <li><a href="https://aka.ms/spfx-yeoman-graph" target="_blank">Use Microsoft Graph in your solution</a></li>
          <li><a href="https://aka.ms/spfx-yeoman-teams" target="_blank">Build for Microsoft Teams using SharePoint Framework</a></li>
          <li><a href="https://aka.ms/spfx-yeoman-viva" target="_blank">Build for Microsoft Viva Connections using SharePoint Framework</a></li>
          <li><a href="https://aka.ms/spfx-yeoman-store" target="_blank">Publish SharePoint Framework applications to the marketplace</a></li>
          <li><a href="https://aka.ms/spfx-yeoman-api" target="_blank">SharePoint Framework API reference</a></li>
          <li><a href="https://aka.ms/m365pnp" target="_blank">Microsoft 365 Developer Community</a></li>
        </ul>
    </div>
  </section>`;
}

Эта модель достаточно гибкая — в элемент DOM можно загружать веб-части, созданные на любой платформе JavaScript.

Настройка области свойств веб-части

Область свойств определяется в классе HelloWorldWebPart. Область свойств нужно настраивать в свойстве getPropertyPaneConfiguration.

Когда свойства заданы, вы можете получить к ним доступ в веб-части, используя строку this.properties.<property-value>, как показано в примере с методом render():

<div>Web part property value: <strong>${escape(this.properties.description)}</strong></div>

Обратите внимание, что мы выполняем управляющий код HTML для значения свойства, чтобы убедиться, что строка является допустимой. Дополнительные сведения о работе с областью свойств и типами ее полей см. в статье Сделайте клиентскую веб-часть SharePoint настраиваемой.

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

1. Прокрутите страницу до верхней части файла и добавьте в раздел импорта из @microsoft/sp-property-pane:

   PropertyPaneCheckbox,
   PropertyPaneDropdown,
   PropertyPaneToggle
   

   Полный раздел импорта выглядит следующим образом:

   import {
     IPropertyPaneConfiguration,
     PropertyPaneTextField,
     PropertyPaneCheckbox,
     PropertyPaneDropdown,
     PropertyPaneToggle
   } from '@microsoft/sp-property-pane';
   

2. Обновите свойства веб-части, включив новые. При этом будут сопоставлены соответствующие поля и типизированные объекты.

3. Замените интерфейс IHelloWorldWebPartProps на приведенный ниже код.

   export interface IHelloWorldWebPartProps {
     description: string;
     test: string;
     test1: boolean;
     test2: string;
     test3: boolean;
   }
   

4. Сохраните файл.

5. Замените метод getPropertyPaneConfiguration() на указанный ниже код, который добавляет новые поля области свойств и сопоставляет их с соответствующими типизированными объектами.

   protected getPropertyPaneConfiguration(): IPropertyPaneConfiguration {
     return {
       pages: [
         {
           header: {
             description: strings.PropertyPaneDescription
           },
           groups: [
             {
               groupName: strings.BasicGroupName,
               groupFields: [
               PropertyPaneTextField('description', {
                 label: 'Description'
               }),
               PropertyPaneTextField('test', {
                 label: 'Multi-line Text Field',
                 multiline: true
               }),
               PropertyPaneCheckbox('test1', {
                 text: 'Checkbox'
               }),
               PropertyPaneDropdown('test2', {
                 label: 'Dropdown',
                 options: [
                   { key: '1', text: 'One' },
                   { key: '2', text: 'Two' },
                   { key: '3', text: 'Three' },
                   { key: '4', text: 'Four' }
                 ]}),
               PropertyPaneToggle('test3', {
                 label: 'Toggle',
                 onText: 'On',
                 offText: 'Off'
               })
             ]
             }
           ]
         }
       ]
     };
   }
   

6. После добавления свойств веб-части к ним можно получить доступ так же, как к свойству description ранее.

   Найдите следующую строку:

   <div>Web part property value: <strong>${escape(this.properties.description)}</strong></div>
   

   Добавьте следующую строку сразу после ранее упоминаемой строки:

   <p>${escape(this.properties.test)}</p>
   <p>${this.properties.test1}</p>
   <p>${escape(this.properties.test2)}</p>
   <p>${this.properties.test3}</p>
   

   Чтобы задать значение по умолчанию для этих свойств, необходимо обновить контейнер свойств properties манифеста веб-части.

7. Откройте HelloWorldWebPart.manifest.json и замените properties на следующий код:

   "properties": {
     "description": "HelloWorld",
     "test": "Multi-line text field",
     "test1": true,
     "test2": "2",
     "test3": true
   }
   

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

Манифест веб-части

Файл HelloWorldWebPart.manifest.json определяет метаданные веб-части, такие как версия, идентификатор, отображаемое имя, значок и описание. Все веб-части должны содержать этот манифест.

{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx/client-side-web-part-manifest.schema.json",
  "id": "fbcf2c6a-7df9-414c-b3f5-37cab6bb1280",
  "alias": "HelloWorldWebPart",
  "componentType": "WebPart",

  // The "*" signifies that the version should be taken from the package.json
  "version": "*",
  "manifestVersion": 2,

  // If true, the component can only be installed on sites where Custom Script is allowed.
  // Components that allow authors to embed arbitrary script code should set this to true.
  // https://support.office.com/article/Turn-scripting-capabilities-on-or-off-1f2c515f-5d7e-448a-9fd7-835da935584f
  "requiresCustomScript": false,
  "supportedHosts": ["SharePointWebPart", "TeamsPersonalApp", "TeamsTab", "SharePointFullPage"],

  "preconfiguredEntries": [{
    "groupId": "5c03119e-3074-46fd-976b-c60198311f70", // Other
    "group": { "default": "Other" },
    "title": { "default": "HelloWorld" },
    "description": { "default": "HelloWorld description" },
    "officeFabricIconFontName": "Page",
    "properties": {
      "description": "HelloWorld",
      "test": "Multi-line text field",
      "test1": true,
      "test2": "2",
      "test3": true
    }
  }]
}

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

gulp serve

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

Поздравляем с запуском вашей первой веб-части Hello World!

Теперь, когда веб-часть работает, вы можете продолжить ее разработку, ознакомившись со статьей Подключение веб-части к SharePoint. В ней рассказывается, как добавить в веб-часть Hello World возможность взаимодействия с REST API для списков SharePoint. Обратите внимание, что команда gulp serve по-прежнему запущена в окне консоли (или в Visual Studio Code, если вы используете этот редактор). Можете переходить к следующей статье, не останавливая ее.