Поделиться через

Использование React пользовательского интерфейса Fluent в надстройках Office

Fluent UI React — это официальная интерфейсная платформа JavaScript с открытым кодом, предназначенная для создания возможностей, которые легко вписываются в широкий спектр продуктов Майкрософт, включая приложения Microsoft 365. Он обеспечивает надежные, современные, доступные компоненты на основе React, которые легко настраиваются с помощью CSS-in-JS.

Примечание.

В этой статье описывается использование React пользовательского интерфейса Fluent в контексте надстроек Office. Однако он также используется в широком спектре приложений и расширений Microsoft 365. Дополнительные сведения см. в разделах React пользовательского интерфейса Fluent и репозиторий веб-открытый код интерфейса Fluent.

В этой статье описывается, как создать надстройку, созданную с помощью React и использующая компоненты fluent UI React.

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

Вы будете использовать генератор Yeoman для надстроек Office, чтобы создать проект надстройки, использующий React.

Установка необходимых компонентов

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

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

yo office

Примечание.

При выполнении команды yo office может появиться запрос о политиках сбора данных генератора Yeoman и средств CLI надстройки Office. Используйте предоставленные сведения, чтобы ответить на запросы подходящим образом.

При появлении запроса предоставьте следующую информацию для создания проекта надстройки.

  • Выберите тип проекта: Укажите Office Add-in Task Pane project using React framework.
  • Выберите тип скрипта: Укажите или TypeScriptJavaScript.
  • Как вы хотите назвать свою надстройку? Укажите My Office Add-in.
  • Какое клиентское приложение Office должно поддерживаться? Укажите один из узлов. (На снимках экрана в этой статье используется Word. Запустить проект в первый раз проще, если выбрать Excel, PowerPointили Word. См . статью Попробовать.)

Ниже приведен пример.

Генератор Yeoman в интерфейсе командной строки с запросами и ответами.

После завершения работы мастера генератор создаст проект и установит вспомогательные компоненты Node.

Знакомство с проектом

Проект надстройки, который вы создали с помощью генератора Yeoman, содержит образец кода для простой надстройки области задач. Если вы хотите изучить компоненты проекта надстройки, откройте проект в редакторе кода и просмотрите следующие файлы. Расширения имен файлов зависят от выбранного языка. Расширения TypeScript находятся в круглых скобках. Когда вы будете готовы попробовать собственную надстройку, перейдите к следующему разделу.

  • Параметры и возможности надстройки определяются в файле ./manifest.xml или ./manifest.json в корневом каталоге проекта. Дополнительные сведения о файлеmanifest.xml см. в статье Надстройки Office с манифестом только надстройки. Дополнительные сведения о файле manifest.json см. в статье Надстройки Office с манифестом унифицированного приложения для Microsoft 365.

  • Файл ./src/taskpane/taskpane.html содержит разметку HTML для области задач и загружает библиотеку JavaScript для Office. Он также проверяет, поддерживает ли элемент управления веб-представление пользовательский интерфейс Fluent React версии 9, и отображает специальное сообщение, если это не так.

  • Файл ./src/taskpane/index.jsx (tsx) является корневым компонентом React. Он загружает React и React пользовательского интерфейса Fluent, гарантирует, что библиотека JavaScript для Office загружена, и применяет тему, определяемую Fluent.

  • Файл ./src/taskpane/office-document.js (ts) содержит код API JavaScript для Office, который упрощает взаимодействие между областью задач и клиентским приложением Office.

  • Папка ./src/taskpane/components/ содержит React файлы компонента *.jss (tsx), которые создают пользовательский интерфейс.

Проверка

  1. Перейдите к корневой папке проекта.

    cd "My Office Add-in"

  2. Выполните указанные ниже действия, чтобы запустить локальный веб-сервер и загрузить неопубликованную надстройку.

    Примечание.

    • Надстройки Office должны использовать HTTPS, а не HTTP, даже во время разработки. Если после выполнения одной из следующих команд вам будет предложено установить сертификат, примите запрос на установку сертификата, который предоставляет генератор Yeoman. Кроме того, вам может потребоваться запустить командную строку или терминал с правами администратора, чтобы внести изменения.

    • Если вы впервые разрабатываете надстройку Office на компьютере, в командной строке может появиться запрос на предоставление Microsoft Edge WebView исключения замыкания на себя ("Разрешить замыкания на себя локальный узел для Microsoft Edge WebView?"). При появлении запроса введите Y , чтобы разрешить исключение. Обратите внимание, что вам потребуются права администратора, чтобы разрешить исключение. После этого вам не следует запрашивать исключение при загрузке неопубликованных надстроек Office в будущем (если вы не удалите исключение с компьютера). Дополнительные сведения см. в разделе "Не удается открыть эту надстройку из localhost" при загрузке надстройки Office или с помощью Fiddler.

      Запрос в командной строке, чтобы разрешить Microsoft Edge WebView исключения замыкания на себя.

    • При первом использовании генератора Yeoman для разработки надстройки Office браузер по умолчанию открывает окно, в котором вам будет предложено войти в учетную запись Microsoft 365. Если окно входа не отображается и возникает ошибка загрузки неопубликованных приложений или времени ожидания входа, выполните команду atk auth login m365.

    Совет

    Если вы тестируете надстройку на компьютере Mac, перед продолжением выполните указанную ниже команду. После выполнения этой команды запустится локальный веб-сервер.

    npm run dev-server

    • Чтобы протестировать надстройку, выполните следующую команду в корневом каталоге проекта. Запустится локальный веб-сервер и откроется ведущее приложение Office с загруженной надстройкой.

      npm start

      Примечание.

      Если вы тестируете надстройку в Outlook, npm start она загружается неопубликованно как в классический, так и в веб-клиенты Outlook. Дополнительные сведения о загрузке неопубликованных надстроек в Outlook см. в разделе Загрузка неопубликованных надстроек Outlook для тестирования.

    • Чтобы протестировать надстройку в Excel, Word или PowerPoint в Интернете, выполните следующую команду в корневом каталоге проекта. После выполнения этой команды запустится локальный веб-сервер. Замените "{url}" на URL-адрес документа Word в OneDrive или библиотеке SharePoint, для которой у вас есть разрешения.

      Примечание.

      Если вы разрабатываете на компьютере Mac, заключите в одинарные {url} кавычки. Не делайте этого в Windows.

      npm run start -- web --document {url}

      Ниже приведены примеры.

      • npm run start -- web --document https://contoso.sharepoint.com/:t:/g/EZGxP7ksiE5DuxvY638G798BpuhwluxCMfF1WZQj3VYhYQ?e=F4QM1R
      • npm run start -- web --document https://1drv.ms/x/s!jkcH7spkM4EGgcZUgqthk4IK3NOypVw?e=Z6G1qp
      • npm run start -- web --document https://contoso-my.sharepoint-df.com/:t:/p/user/EQda453DNTpFnl1bFPhOVR0BwlrzetbXvnaRYii2lDr_oQ?e=RSccmNP

      Если надстройка не загружает неопубликованное приложение в документе, вручную загрузите ее, следуя инструкциям в разделе Ручная загрузка неопубликованных надстроек для Office в Интернете.

    Примечание.

    Если вы впервые загружаете неопубликованную надстройку Office на компьютере (или впервые за месяц), сначала вам будет предложено удалить старый сертификат, а затем установить новый. Примите оба запроса.

  3. Появится запрос Остановить при загрузке WebView . Нажмите OK.

  4. Если область задач "Моя надстройка Office" еще не открыта, перейдите на вкладку Главная , а затем нажмите кнопку Показать область задач на ленте, чтобы открыть область задач надстройки.

    Примечание.

    Если вы тестируете надстройку в Outlook, создайте новое сообщение. Затем перейдите на вкладку Сообщение и выберите показать область задач на ленте, чтобы открыть область задач надстройки.

  5. Введите текст в текстовое поле и нажмите кнопку Вставить текст.

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

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

    npm stop

Переход на пользовательский интерфейс Fluent React версии 9

Если у вас есть надстройка, которая реализует более раннюю версию React пользовательского интерфейса Fluent, рекомендуется выполнить переход на Fluent UI версии 9. Рекомендации по процессу миграции см. в статье Приступая к миграции на версию 9.

Устранение неполадок

  • Автоматическое npm install выполнение шага Yo Office может завершиться ошибкой. Если при попытке запустить npm startвы видите ошибки , перейдите в только что созданную папку проекта в командной строке и вручную запустите npm install. Дополнительные сведения о Yo Office см. в статье Создание проектов надстроек Office с помощью генератора Yeoman.

  • При запуске npm install генератора Yeoman или проекта могут отображаться предупреждения. В большинстве случаев эти предупреждения можно игнорировать. Иногда зависимости становятся устаревшими, а их замена не поддерживается другими пакетами, от которых зависит проект. Если вы хотите устранить эти предупреждения, используйте npm-check-updates средство .

    • В командной строке в корневом каталоге проекта выполните команду npm i -g npm-check-updates. При этом средство устанавливается глобально.
    • Запустите ncu -u. Он предоставляет отчет обо всех пакетах и о том, какие версии они будут обновлены.
    • Выполните команду npm install , чтобы обновить все пакеты.

    Дополнительные сведения о предупреждениях при запуске npm installсм. в разделе Предупреждения и зависимости в мире Node.js и npm.

  • Если кнопка надстройки не отображается на ленте (например, Показать область задач), нажмите кнопку Надстройки на вкладке Главная ленты, а затем выберите тестовую надстройку.

См. также

  • Last updated on