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

Статья
04/08/2023

Клиентские веб-части — это клиентские компоненты, выполняемые в контексте страницы 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!  |
#######  ##|   /   '-----------------------------------'
###     /##|(@)
###########|
**=+####!

Важно!

NPM может выводить предупреждения и сообщения об ошибках во время установки зависимостей при запуске команды npm install. Эти сообщения об ошибках журналов & можно игнорировать.

NPM может выводить сообщение о запуске команды npm audit в конце процесса. Не запускайте эту команду, так как она будет обновлять пакеты и вложенные зависимости, которые, возможно, не были проверены SharePoint Framework.

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

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

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

В примерах и инструкциях, приведенных в документации по 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-сертификату разработки, который входит в цепочку инструментов в локальной среде. Это необходимо для того, чтобы ваш браузер доверял сертификату.

Важно!

Необходимо установить доверие к сертификату разработчика. Это одноразовый процесс, который требуется только при запуске первого проекта SharePoint Framework на новой рабочей станции. Вам не нужно повторять этот процесс для каждого проекта SharePoint Framework.

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

Обновите 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.

Совет

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

gulp serve --nobrowser

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

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

gulp serve

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

Примечание.

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

Если вы по-прежнему испытываете проблемы, см. статью SharePoint Framework: известные проблемы и часто задаваемые вопросы

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, запущенная локально

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

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

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

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

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

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

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

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

В консоли остановите локальный веб-сервер и завершите процесс. Нажмите клавиши CTRL+C в Windows или macOS.
Введите следующую команду, чтобы открыть проект веб-части в VS Code (или используйте другой редактор):
```
code .
```

Примечание.

Если при выполнении этой команды возникла ошибка, задайте команду code в PATH.

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 настраиваемой.

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

Прокрутите страницу до верхней части файла и добавьте в раздел импорта из @microsoft/sp-property-pane:
```
PropertyPaneCheckbox,
PropertyPaneDropdown,
PropertyPaneToggle
```
Полный раздел импорта выглядит следующим образом:
```
import {
  IPropertyPaneConfiguration,
  PropertyPaneTextField,
  PropertyPaneCheckbox,
  PropertyPaneDropdown,
  PropertyPaneToggle
} from '@microsoft/sp-property-pane';
```
Обновите свойства веб-части, включив новые. При этом будут сопоставлены соответствующие поля и типизированные объекты.

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

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

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

Замените метод 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'
            })
          ]
          }
        ]
      }
    ]
  };
}

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

Найдите следующую строку:
```
<div>Web part property value: ${escape(this.properties.description)}</div>
```
Добавьте следующую строку сразу после ранее упоминаемой строки:
```
${escape(this.properties.test)}
${this.properties.test1}
${escape(this.properties.test2)}
${this.properties.test3}
```
Чтобы задать значение по умолчанию для этих свойств, необходимо обновить контейнер свойств properties манифеста веб-части.

Откройте 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, если вы используете этот редактор). Можете переходить к следующей статье, не останавливая ее.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Дополнительные ресурсы