Разработка надстроек Office

  • Статья

Совет

Перед прочтением этой статьи ознакомьтесь с обзором платформы надстроек Office.

Все надстройки Office построены на базе платформы надстроек Office. Для каждой создаваемой надстройки следует понять важные принципы, такие как доступность клиентского приложения и платформы, шаблоны программирования API JavaScript для Office, настройку параметров и возможностей надстройки в файле манифеста, способ разработки пользовательского интерфейса и т. д. Эти основные принципы разработки рассматриваются ниже в разделе документации Жизненный цикл разработки>Разработка. Ознакомьтесь с этими сведениями перед изучением документации для клиентского приложения, надстройку для которого вы создаете (например, Excel).

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

Надстройку Office можно создать с помощью генератора Yeoman для надстроек Office, Visual Studio или набора средств Teams.

Генератор Yeoman

Генератор Yeoman для надстроек Office можно использовать для создания проекта надстройки Office Node.js, которым можно управлять с помощью Visual Studio Code или любого другого редактора. В генераторе можно создавать надстройки Office для любой из следующих целей.

  • Excel
  • OneNote
  • Outlook
  • PowerPoint
  • Project
  • Word
  • Пользовательские функции Excel

Создайте проект с помощью HTML, CSS и JavaScript (или TypeScript) или React. Если выбрать React, вы также можете выбрать между JavaScript и Typescript. Дополнительные сведения о создании надстроек с помощью генератора см. в статье Генератор Yeoman для надстроек Office.

Visual Studio

С помощью Visual Studio можно создавать надстройки Office для Excel, Outlook, Word и PowerPoint. Проект надстройки Office создается в рамках решения Visual Studio и использует HTML, CSS и JavaScript. Дополнительные сведения о создании надстроек с помощью Visual Studio см. в статье Разработка надстроек Office с помощью Visual Studio.

Примечание.

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

  • Генератор Yeoman поддерживает для проектов надстроек Office больше типов проектов, платформ и языков по сравнению с Visual Studio.

  • Шаблоны проектов в Yeoman обновляются чаще, чем шаблоны проектов в Visual Studio.

Набор средств Teams

Набор средств Teams можно использовать для создания практически любого типа приложения Teams, термин, который включает в себя все расширения Microsoft 365, включая те, которые не расширяют приложение Teams. Дополнительные сведения о создании надстройки см. в статье Создание проектов надстроек Office с помощью набора средств Teams.

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

Надстройка Office состоит из двух частей.

  • Манифест надстройки, определяющий параметры и возможности надстройки.

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

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

Определение параметров и возможностей надстройки

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

  • метаданные, описывающие надстройку (например, ИД, версия, описание, отображаемое имя, региональные параметры по умолчанию);
  • приложения Office, в которых будет запускаться надстройка;
  • разрешения, требующиеся для надстройки;
  • способ интеграции надстройки с Office, включая создаваемые ею элементы пользовательского интерфейса (например, настраиваемая вкладка или настраиваемые кнопки на ленте);
  • расположение изображений, используемых надстройкой для фирменной символики и значков команд;
  • размеры надстройки (например, размеры для контентных надстроек, запрошенная высота для надстроек Outlook);
  • правила, определяющие, когда надстройка активируется в контексте сообщения или встречи (только для надстроек Outlook).
  • Сочетания клавиш (только для Excel).

Подробные сведения о манифесте см. в разделе Манифест надстроек Office.

Взаимодействие с содержимым в документе Office

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

Доступ к библиотеке API JavaScript для Office

Доступ к библиотеке API JavaScript для Office можно получить через сеть доставки содержимого (CDN) Office JS по адресу https://appsforoffice.microsoft.com/lib/1/hosted/office.js. Чтобы использовать API JavaScript для Office на любой из веб-страниц надстройки, требуется указать ссылку на CDN в теге <script> тега <head> страницы.

<head>
    ...
    <script src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js" type="text/javascript"></script>
</head>

Примечание.

Чтобы использовать API предварительных версий, требуется указать ссылку на предварительную версию библиотеки API JavaScript для Office в сети CDN: https://appsforoffice.microsoft.com/lib/beta/hosted/office.js.

Дополнительные сведения о доступе к библиотеке API JavaScript для Office, в том числе о способе получения функции IntelliSense, см. в статье Добавление ссылок на библиотеку API JavaScript для Office из сети доставки содержимого (CDN).

Модели API

API JavaScript для Office включает две модели:

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

    Эта модель API использует обещания и позволяет указывать несколько операций в каждом запросе, отправляемом в приложение Office. Подобные пакетные операции могут значительно повысить производительность надстроек для веб-приложений Office. API для конкретных приложений появились в Office 2016.

    Примечание.

    Существует также API приложения для Visio, но его можно использовать только на страницах SharePoint Online для взаимодействия со схемами Visio, внедренными в страницу. Веб-надстройки Office не поддерживаются в Visio.

    Дополнительные сведения об этой модели API см. в статье Использование модели API для конкретного приложения.

  • Общие API-интерфейсы можно использовать для доступа к таким компонентам, как пользовательский интерфейс, диалоговые окна и параметры клиентов, общие для нескольких типов приложений Office. Эта модель API использует обратные вызовы, позволяющие указывать только одну операцию в каждом запросе, отправляемом в приложение Office. Общие API появились в Office 2013 и могут использоваться для взаимодействия с любыми поддерживаемыми приложениями Office. Подробнее об объектной модели общих API, включающей API для взаимодействия с Outlook, PowerPoint и Project, см. в статье Объектная модель общих API JavaScript.

Примечание.

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

Наборы обязательных элементов API

Наборы обязательных элементов — это именованные группы элементов API. Наборы обязательных элементов могут относиться к конкретному приложению Office, например набор обязательных элементов ExcelApi 1.7 (набор API, который можно использовать только в Excel), или быть общими для нескольких приложений, например набор обязательных элементов DialogApi 1.1 (набор API, который можно использовать в любом приложение Office, поддерживающем API диалоговых окон).

Используя наборы обязательных элементов, надстройка может определять, поддерживает ли приложение Office необходимые элементы API. Дополнительные сведения об этом см. в статье Указание приложений Office и обязательных элементов API.

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

Изучение API с помощью Script Lab

Script Lab — это надстройка, позволяющая изучать API JavaScript для Office и выполнять фрагменты кода при работе в программах Office, таких как Excel или Word. Она доступна бесплатно в AppSource и является полезным инструментом для добавления в набор средств разработки при создании прототипов и проверке нужных функций в надстройке. В Script Lab можно получить доступ к библиотеке встроенных примеров, чтобы быстро испытать API или использовать пример в качестве отправной точки для собственного кода.

В следующем 1-минутном видео показана надстройка Script Lab в действии.

Короткое видео, в котором показано, как Script Lab работает в Excel, Word и PowerPoint.

Дополнительные сведения о Script Lab см. в статье Изучение API JavaScript для Office с помощью Script Lab.

Настройка интерфейса пользователя Office

Надстройка Office может расширить пользовательский интерфейс Office с помощью команд надстройки и контейнеров HTML, таких как области задач, контентные надстройки и диалоговые окна.

  • Команды надстроек можно использовать для добавления настраиваемой вкладки, настраиваемых кнопок и меню на стандартную ленту в Office или для расширения стандартного контекстного меню, отображающегося при щелчке правой кнопкой мыши по тексту в документе Office или объекту в Excel. Когда пользователи выбирают команду надстройки, они запускают задачу, определяемую этой командой надстройки, например выполнение кода JavaScript, открытие области задач или запуск диалогового окна.

  • Контейнеры HTML, такие как области задач, контентные надстройки и диалоговые окна можно использовать для отображения настраиваемого пользовательского интерфейса и предоставления дополнительных функций в приложении Office. Содержимое и функции каждой области задач, контентной надстройки или диалогового окна зависят от указанной вами веб-страницы. Эти веб-страницы могут использовать API JavaScript для Office с целью взаимодействия с содержимым в документе Office, в котором запущена надстройка, а также могут выполнять другие типовые действия веб-страниц, например вызовы внешних веб-служб, упрощение проверки подлинности пользователей и т. д.

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

Схема с командами надстроек на ленте, областью задач и диалоговым окном / надстройкой содержимого в документе Office.

Дополнительные сведения о расширении пользовательского интерфейса Office и разработке интерфейса надстройки см. в статье Элементы пользовательского интерфейса Office для надстроек Office.

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

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

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

Вы можете быстро создать простую надстройку для Excel, OneNote, Outlook, PowerPoint, Project или Word с помощью 5-минутного краткого руководства по началу работы. Если вы уже ознакомились с кратким руководством и хотите создать более сложную надстройку, воспользуйтесь учебником.

Дополнительные сведения

Ознакомьтесь с этой документацией, чтобы узнать больше о разработке, тестировании и публикации надстроек Office.

Совет

При создании любой надстройки вы можете использовать информацию из раздела Жизненный цикл разработки этой документации, а также сведения из разделов для определенных приложений, соответствующих типу создаваемой надстройки (например, Excel).

См. также