Общие сведения о настройке надстроек Office

  • 7 мин

Платформа надстроек Office позволяет выполнить настройку вашей надстройки. В этом модуле вы узнаете, как настроить надстройку путем сохранения состояния и использования Fluent UI и Microsoft Graph. Изучив этот модуль, вы сможете настраивать надстройки Office с помощью сохраненного состояния, Fluent UI и Microsoft Graph.

Общие сведения о способах сохранения состояния и параметров

Платформа надстроек Office предоставляет несколько способов сохранения состояния и параметров надстройки. Какой из них использовать, зависит от приложений Office, которые вы планируете поддерживать, и от типа надстройки, которую собираетесь разрабатывать.

Способы сохранения состояния и параметров

API JavaScript для Office предоставляет объекты, позволяющие сохранять состояние надстройки в сеансах пользователей. В следующей таблице перечислены доступные варианты, а также поддерживаемые типы надстроек и ведущих приложений Office.

Объект API Office Поддерживаемые типы надстроек Поддерживаемые ведущие приложения Office Сведения о хранилище
CustomProperties MailApp Outlook Данные элементов сохраняются в сообщениях или встречах, с которыми работает надстройка.*
CustomXmlParts TaskPaneApp Excel (API JavaScript для Excel для определенных узлов),
Word (общий API JavaScript для Office)		 Данные хранятся в пользовательской XML-части документа или книги.
RoamingSettings MailApp Outlook Данные хранятся в почтовом ящике Exchange пользователя и связаны с конкретной надстройкой.*
Settings ContentApp, TaskPaneApp Excel, PowerPoint, Word Данные хранятся в документе, книге или презентации, с которой работает надстройка.*

*Данные, хранимые в парах "имя-значение" в контейнере свойств

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

Важно!

Не храните пароли и конфиденциальные персональные данные на устройстве пользователя.

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

При создании надстройки необходимо учитывать множество факторов проектирования пользовательского интерфейса. Fluent UI предоставляет элементы с фирменным оформлением Office, чтобы ваша надстройка выглядела как естественное расширение Office.

Примечание.

Использовать UI Fabric рекомендуется, хоть это и не обязательно.

Сведения о Fluent UI

Fluent UI включает два (2) основных пакета:

  • Fabric Core — предоставляет основные элементы, такие как шрифт, значки и цвет
  • Компоненты Fabric React — содержат элементы Fabric Core, компоненты ввода, навигации и уведомлений и многое другое

Fabric Core

Fabric Core предоставляет базовые элементы оформления, которые отражают фирменный стиль Office или согласуются с ним.

Чтобы приступить к использованию Fabric Core, укажите ссылку на CSS на вашей HTML-странице, как показано в следующем коде.

<link rel="stylesheet" href="https://static2.sharepointonline.com/files/fabric/office-ui-fabric-core/9.6.1/css/fabric.min.css">

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

<i class="ms-Icon ms-font-xl ms-Icon--Table ms-fontColor-themePrimary"></i>

Компоненты Fabric

Fabric React предоставляет компоненты, обеспечивающие взаимодействие с пользователем: ввод, навигацию, уведомление и т.д. Этот пакет создан на основе Fabric Core и включает его компоненты.

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

  • Breadcrumb
  • Кнопка
  • Флажок
  • ChoiceGroup
  • Dropdown
  • Label
  • List
  • Pivot
  • TextField
  • Toggle

Совет

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

Использование Microsoft Graph в надстройках Office

Надстройка может подключаться к Microsoft Graph и получать доступ к данным пользователя, чтобы выполнять более полезные и производительные сценарии. Примеры задач:

  • Чтение файлов из OneDrive
  • Получение вложений электронной почты
  • Получение профиля пользователя.

Преимущества Microsoft Graph

REST API Microsoft Graph предоставляют надстройкам доступ к данным пользователя в таких службах, как:

  • Microsoft Entra ID
  • Службы Microsoft 365
  • Службы Enterprise Mobility + Security.
  • Службы Windows 10
  • Dynamics 365

Авторизация в Microsoft Graph

Чтобы подключиться и использовать Microsoft Graph, надстройка должна обладать следующими возможностями:

  • Проверка подлинности пользователя
  • Получение права действовать от имени пользователя

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

Надстройка может получить маркер доступа из Идентификатора Microsoft Entra, когда пользователь вошел в систему. Идентификатор Microsoft Entra не позволяет открывать страницу входа в iframe, а область задач надстройки является iframe при запуске надстройки в Office в Интернете. Таким образом, используйте API диалогового окна JavaScript для Office, чтобы отобразить форму входа в Microsoft Entra. Если надстройка содержит настраиваемые функции, которым требуется авторизация в Microsoft Graph, используйте настраиваемые функции API диалога, чтобы отобразить форму для входа.

Авторизация

Когда пользователь выполняет вход, надстройка получает маркер доступа для использования в последующих вызовах API к Microsoft Graph. Маркер доступа не может дать надстройке больше разрешений, чем есть у пользователя, как не может повысить их уровень. Как правило, у пользователей есть разрешения только на доступ к данным о себе, собственным файлам и электронной почте, а также к объектам, доступ к которым ему был предоставлен. Если надстройка получает данные Microsoft Graph о нескольких пользователях, ее могут использовать только пользователи с разрешениями уровня администратора.

В зависимости от вариантов разработки для проверки подлинности и авторизации можно использовать одну из следующих библиотек.

  • MSAL.NET, если сервер использует платформу на основе .NET (например, .NET Core или ASP.NET)
  • Серверная сторона основана на node.js: используйте Passport Microsoft Entra ID
  • msal.js, если надстройка использует неявный поток

Сводка

Платформа надстроек Office позволяет выполнить настройку вашей надстройки. В этом модуле вы узнали, как настроить надстройку путем сохранения состояния и использования Fluent UI и Microsoft Graph. Изучив этот модуль, вы сможете настраивать надстройки Office с помощью сохраненного состояния, Fluent UI и Microsoft Graph.

Настройка надстроек Office

1.

Надстройка Outlook должна хранить данные. Какие объекты JavaScript для Office может использовать разработчик надстройки?

2.

Владимир решил использовать Fluent UI в надстройке. В чем преимущество этого?

3.

Владимир подключается к Microsoft Graph в надстройке. Где надстройка должна отображать форму входа Microsoft Entra для пользователя в Office в Интернете?