Интегрируем React приложение в Microsoft Office
Как можно расширить возможности MS Office с помошью кастомного расширения на JavaScript.
5К открытий5К показов
Максим Колоколов
техлид в Dunice
Для решений многих повседневных задач используются продукты Microsoft Office, такие, как Word, Excel, PowerPoint и т.д. Но не все знают, что в этих приложениях можно использовать надстройки (Add-ins), доступные из Microsoft AppSource. Эти надстройки позволяют расширить стандартный функционал Office, например, осуществлять перевод текста, искать изображения в интернете или даже планировать встречи в Starbucks. Стоит отметить, что многие современные надстройки работают с Office для iPad, Office Online и Office для Mac, а не только с традиционными настольными версиями Office для Windows.
Мне необходимо было интегрировать виджет для работы с уже существующим веб-сайтом, написанным ранее. Основные задачи надстройки можно выделить в следующие пункты:
- получение данных из открытого документа Microsoft Office в контекст виджета;
- анализ полученных данных из текущего документа, выделение ключевых слов с помощью простого NLP алгоритма (подсчет наиболее используемых слов, не считая предлогов и союзов), а также поиск по этим словам и отображение соответствующего контента (карточки с различными типами содержания: текст, изображения, видео, опросники и т.д.), посредством API уже написанного сервера;
- возможность быстрой вставки контента из результатов поиска в рабочую область документа.
Для реализации собственной надстройки Office, нам нужно подготовить два основных компонента — файл манифеста и веб-приложение.
Манифест представляет собой XML-файл, который определяет следующие параметры и возможности надстройки:
- Отображаемое имя, описание, идентификатор, версию и языковой стандарт надстройки по умолчанию.
- Способ интеграции надстройки с Office.
- Уровень разрешений и требования для доступа к данным для надстройки.
Веб-приложение — это HTML-страница, которая отображается в приложении Office. Для создания кода, который взаимодействует с документами Office, а также позволяет пользователю взаимодействовать с веб-ресурсами из приложения Office, можно применять любые технологии, как клиентские, так и серверные. В свою очередь, Microsoft предоставляет интерфейсы API JavaScript Office.js для взаимодействия с документами. Выглядит это следующим образом:
Перед началом разработки, Microsoft Office предлагает ознакомиться, и соответственно придерживаться следующих принципов оформления надстроек:
- Разрабатывайте специально для Office.
- Сосредоточьтесь на нескольких ключевых задачах.
- Содержимое важнее, чем хром (внешний вид).
- Сделайте работу с надстройкой приятной и разрешите пользователям самим выбирать, что делать.
- Поддержка всех платформ и способов ввода.
Так же Microsoft разработал Office UI Fabric — официальный front-end framework для создания интерфейсов в Office. И конечно же, рекомендует его использовать при разработке.
Написание файла манифеста
Для начала подготовим файл манифеста. На следующей схеме показана иерархия элементов, используемых для задания команд надстройки.
Весь файл манифеста разбиваем на 3 части:
- Общая информация о надстройке — тут отображается название, версия, описание надстройки и т.д, а также поддерживаемые типы платформ в нашей надстройке (доступны: Word, Excel, PowerPoint, Outlook, Project и SharePoint).
- Далее идет информационный блок для каждого типа платформы, которые мы объявили. Тут содержится информация для конкретного типа. Пример для Word:
- В последней части, мы описываем информационный блок ресурсов:
Детальную информацию по созданию файла манифеста можно прочитать в официальной документации.
Написание веб-приложения
Для разработки веб-приложения нам понадобится API JavaScript для Office. Библиотека API JavaScript для Office состоит из файла Office.js и связанных JS-файлов. Простейший способ сослаться на API — использовать сеть доставки содержимого (CDN), добавив следующий код <script> в тег <head> страницы:
<script src="https://appsforoffice.microsoft.com/lib/1/hosted/Office.js" type="text/javascript"></script>
Начать работу с библиотекой необходимо с инициализации библиотеки Office, для этого предусмотрен метод Office.onReady() — это асинхронный метод, который возвращает объект Promise во время проверки загрузки библиотеки Office.js. Когда библиотека будет загружена, объект Promise сопоставляется в качестве объекта, определяющего приложение Office, с числовым значением Office.HostType (Excel, Word и т. д.), а платформа — с числовым значением Office.PlatformType (PC, Mac, OfficeOnline и т. д.). Объект Promise сопоставляется незамедлительно, если библиотека уже загружена, когда вызывается Office.onReady().
Надстройки взаимодействует с объектами в Office с помощью двух типов объектных моделей JavaScript:
Общий API JavaScript для Office используется, если вам нужно:
- создать надстройки для Word 2013;
- выполнить начальные действия для приложения;
- проверить поддерживаемый набор требований;
- получить доступ к метаданным документа, его параметрам и сведениям о среде;
- создать привязку к разделам документа и записать события;
- использовать пользовательские XML-части;
- открыть диалоговое окно.
API JavaScript для Excel, Word, PowerPoint предоставляют строго типизированные объекты, с помощью которых можно получать доступ к различным объектам рабочей области документов.
Например, для получения контента из рабочей области документа можно воспользоваться методом getSelectedDataAsync:
А для вставки контента в рабочую область, можем воспользоваться методом setSelectedDataAsync:
Также хотелось бы выделить использование Dialog API в надстройках Office. В настоящее время оно поддерживается для Word, Excel, PowerPoint и Outlook. Dialog API позволяет реализовать:
- Отобразить страницу входа, которую невозможно открыть непосредственно в области задач.
- Предоставить больше места на экране (или даже весь экран) для некоторых задач в надстройке.
- Разместить видео, которое будет слишком маленьким в области задач.
Важно отметить, что страница веб-приложения и ресурсы диалоговых окон должны иметь одинаковые полные доменные имена.
В целом, для создания веб-приложения можно использовать любые веб-технологии и фреймворки. Так как я разрабатывал надстройку для уже готового веб-сайта, то в качестве клиентского фреймворка я выбрал React, как и в основном сайте, также использовал API уже готового бэкенда написанного на Ruby. В итоге у меня получилась вот такая надстройка, которую можно найти в общем доступе, правда она вам пригодится, если вы являетесь пользователем платформы ProjectX.
На данный момент AppSource содержит около 6,5 тысяч готовых приложений разделенные на определенные категории и отрасли. Майкрософт продолжает развивать и поддерживать данное направление, облегчая процесс создания надстроек и расширяя возможности интерфейсов API JavaScript Office.js. На сайте Майкрософта можно найти много полезных ресурсов для разработки. В конечном счете, перед тем как надстройка окажется в общем доступе, она должна пройти этап тестирования, а также должна соответствовать всем требованиям для запуска надстроек Office от Microsoft.
5К открытий5К показов
GitHub Copilot обвинили в невозможности ограничить передачу конфиденциальных данных в облако, создавая угрозу безопасности пользователей
Узнайте, правда ли, что свободная Linux предлагает своим пользователям больше свободы и гибкости по сравнению с Microsoft Windows
Яндекс запускает Yandex Code Assistant — аналог GitHub Copilot для российских разработчиков. Этот ИИ-ассистент помогает генерировать продолжение кода на популярных языках, таких как C++, Go, Java и Python
Microsoft, в своих лучших традициях, перестала спрашивать пользователей, хотят ли они включить бэкап своих файлов через OneDrive