Указание приложений Office и требований к API с помощью унифицированного манифеста

Надстройка Office может зависеть от определенного приложения Office (также называемого узлом Office) или от определенных элементов библиотеки JavaScript для Office (office.js). Например, надстройка может:

• работать в одном (например, Word или Excel) или нескольких приложениях Office;
• Используйте API JavaScript для Office, доступные только в некоторых версиях Office. Например, корпоративная бессрочная версия Excel 2016 не поддерживает все API,связанные с Excel, в библиотеке Office JavaScript.
• Предназначены для использования только в мобильном форм-факторе.

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

Существуют также сценарии, в которых вы хотите контролировать, какие функции надстройки видны пользователям на основе их приложения Office и версии Office. Ниже приведены три примера.

• Ваша надстройка имеет функции, полезные как в Word, так и в PowerPoint, такие как управление текстом, но в ней есть некоторые дополнительные функции, которые имеют смысл только в PowerPoint, например функции управления слайдами. Если надстройка запущена в Word, необходимо скрыть функции, доступные только для PowerPoint.
• В вашей надстройке есть функция, которая требует использования метода API JavaScript для Office, который поддерживается в некоторых версиях приложения Office, таких как Excel по подписке на Microsoft 365, но не поддерживается в других, например в корпоративных бессрочных Excel 2016. Но в вашей надстройке есть и другие функции, для которых требуются только методы API JavaScript для Office, которые поддерживаются в корпоративной лицензированной бессрочной Excel 2016. В этом сценарии надстройка должна быть установлена в этой версии Excel 2016, но функция, требующая неподдерживаемого метода, должна быть скрыта от этих пользователей.
• Ваша надстройка имеет функции, которые поддерживаются в классическом Office, но не в мобильном Office.

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

Использование последней библиотеки API JavaScript для Office

Ваша надстройка должна загружать самую последнюю версию библиотеки API JavaScript для Office из сети доставки содержимого (CDN). Для этого убедитесь, что у вас есть следующий <script> тег в первом HTML-файле, открываемом надстройкой. Чтобы всегда ссылаться на последнюю версию файла Office.js, используйте /1/ в URL-адресе сети доставки содержимого.

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

Укажите, в каких приложениях Office может размещаться надстройка

Чтобы указать приложения Office, в которых можно установить надстройку, используйте массив extensions.requirements.scopes. Укажите любое подмножество "mail", "workbook", "document" и "presentation". В следующей таблице показано, какие сочетания приложений и платформ Office соответствуют этим значениям. Здесь также показано, какой тип надстройки можно установить для каждой область.

Например, следующий код JSON указывает, что надстройка может устанавливаться в любом выпуске Excel, который включает в себя Excel в Интернете, Windows и iPad, но не может быть установлен в любом другом приложении Office.

"extensions": [
    {
        "requirements": {
            "scopes": [ "workbook" ],
        },
        ...
    }
]

Укажите, какие API Office нужны надстройке

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

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

Чтобы упростить процесс указания ИНТЕРФЕЙСов API, необходимых надстройке, Office объединяет большинство API в наборы требований. API в общей объектной модели API группируются по поддерживаемой функции разработки. Например, все API, подключенные к табличным привязкам, находятся в наборе требований с именем TableBindings 1.1. API-интерфейсы в объектных моделях приложений группируются по времени их выпуска для использования в рабочих надстройках.

Наборы обязательных элементов имеют версию. Например, API- интерфейсы, поддерживающие диалоговые окна , находятся в наборе обязательных элементов DialogApi 1.1. При выпуске дополнительных API- интерфейсов, которые обеспечивают обмен сообщениями из области задач в диалог, они были сгруппированы в DialogApi 1.2, а также все API в DialogApi 1.1. Каждая версия набора требований является надмножеством всех предыдущих версий.

Поддержка набора требований зависит от приложения Office, версии приложения Office и платформы, на которой оно выполняется. Например, DialogApi 1.2 не поддерживается в корпоративных бессрочных версиях Office до Office 2021, но DialogApi 1.1 поддерживается во всех бессрочных версиях Office 2016. Вы хотите, чтобы надстройка была установлена на каждой комбинации платформы и версии Office, которая поддерживает используемые в ней API, поэтому всегда следует указывать в манифесте минимальную версию каждого набора требований, который требуется надстройке. Сведения о том, как это сделать, см. далее в этой статье.

свойство extensions.requirements.capabilities

Используйте свойство requirements.capabilities, чтобы указать минимальные наборы требований, которые должны поддерживаться приложением Office для установки надстройки. Если приложение или платформа Office не поддерживают наборы требований или члены API, указанные в свойстве requirements.capabilities, надстройка не будет запускаться в этом приложении или платформе и не будет отображаться в разделе "Мои надстройки".

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

• TableBindings набор обязательных требований, который имеет минимальную версию "1.1".
• OOXML набор обязательных требований, который имеет минимальную версию "1.1".

"extensions": [
    {
        "requirements": {
            "capabilities": [ 
                {
                    "name": "TableBindings",
                    "minVersion": "1.1"
                },
                {
                    "name": "OOXML",
                    "minVersion": "1.1"
                }
            ],
        },
        ...
    }
]

Укажите форм-факторы, на которых можно установить надстройку

Для надстройки Outlook можно указать, должна ли надстройка устанавливаться на настольных компьютерах (включая планшеты) или мобильных форм-факторах. Чтобы настроить эту настройку, используйте свойство extensions.requirements.formFactors. В следующем примере показано, как сделать надстройку Outlook устанавливаемой в обоих форм-факторах.

"extensions": [
    {
        "requirements": {
            ...
            "formFactors": [
                "desktop",
                "mobile"
            ]
        },
        ...
    }
]

Проектирование для альтернативных интерфейсов

Функции расширяемости, предоставляемые платформой надстроек Office, можно разделить на три типа:

• Функции расширения, доступные сразу после установки надстройки. Примером такой функции являются команды надстройки, которые представляют собой настраиваемые кнопки и меню ленты.
• Функции расширяемости, доступные только при выполнении надстройки и реализованные с Office.js API JavaScript; например, Диалоговые окна.
• Функции расширяемости, доступные только во время выполнения, но реализованные с сочетанием Office.js JavaScript и конфигурации манифеста. Примерами являются пользовательские функции Excel, единый вход и настраиваемые контекстные вкладки.

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

Эта конструкция реализуется по-разному в зависимости от того, как реализована функция расширяемости:

• Сведения о функциях, реализованных полностью с помощью JavaScript, см. в разделе Проверка доступности API во время выполнения.
• Сведения о функциях, требующих настройки манифеста, см. в разделе "Фильтрация функций" статьи Указание требований к надстройке Office в унифицированном манифесте для Microsoft 365.

См. также

• Манифест надстроек Office
• Наборы обязательных элементов для надстроек Office
• Указание требований к надстройке Office в унифицированном манифесте для Microsoft 365