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

Указание приложений Office и требований API

  • Статья

Надстройка Office может зависеть от определенного приложения Office (также называемого узлом Office) или от определенных членов API 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 для надстроек Office .

Совет

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

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

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

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

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

По умолчанию надстройка устанавливается во всех приложениях Office, поддерживаемых указанным типом надстройки (то есть почта, область задач или содержимое). Например, надстройка области задач устанавливается по умолчанию в Access, Excel, OneNote, PowerPoint, Project и Word.

Чтобы убедиться, что надстройка доступна для установки в подмножестве приложений Office, используйте элементы Hosts и Host в манифесте.

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

<Hosts>
  <Host Name="Workbook" />
</Hosts>

Элемент <Hosts> может содержать один или несколько <элементов Host> . Для каждого приложения Office должен быть отдельный <элемент Host> , в котором должна быть установлена надстройка. Атрибут Name является обязательным и может иметь одно из следующих значений.

Имя Клиентские приложения Office Доступные типы надстроек
Документ Word в Интернете, Windows, Mac, iPad Область задач
Mailbox Outlook в Интернете, Windows (новая и классическая версия), Mac, Android, iOS Почта
Notebook OneNote в Интернете Область задач, содержимое
Презентация PowerPoint в Интернете, Windows, Mac, iPad Область задач, содержимое
Проект Project для Windows Область задач
Книга Excel в Интернете, Windows, Mac, iPad Область задач, содержимое
База данных Доступ (устаревший) Область задач

Примечание.

Приложения Office поддерживаются на разных платформах и работают на настольных компьютерах, веб-браузерах, планшетах и мобильных устройствах. Обычно нельзя указать, какую платформу можно использовать для запуска надстройки. Например, если указать Workbook, для запуска надстройки можно использовать Excel как в Интернете, так и в Windows. Однако если указать Mailbox, надстройка не будет работать на мобильных клиентах Outlook, если вы не определите точку расширения для мобильных устройств.

Примечание.

Манифест надстройки не может применяться к нескольким типам: "Почта", "Область задач" или "Содержимое". Это означает, что если вы хотите установить надстройку в Outlook и в одном из других приложений Office, необходимо создать две надстройки: одну с манифестом типа "Почта", а другую с манифестом "Задача" или "Тип контента".

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

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

Важно!

Используйте только базовый манифест, чтобы указать члены API, которые должны иметь какая-либо важная ценность для вашей надстройки. Если надстройка использует API для некоторых функций, но имеет другие полезные функции, которым не нужен API, следует разработать надстройку таким образом, чтобы она была установлена на сочетаниях версий платформы и 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, поэтому всегда следует указывать в манифесте минимальную версию каждого набора требований, который требуется надстройке. Сведения о том, как это сделать, см. далее в этой статье.

Совет

Дополнительные сведения об управлении версиями наборов обязательных элементов см. в статье Доступность наборов обязательных элементов Office, а полные списки наборов требований и сведения о API в каждом из них начните с наборов требований надстроек Office. В справочных разделах по большинству API-интерфейсов Office.js также указывается набор требований, к которому они относятся (если таковые есть).

Примечание.

С некоторыми наборами требований также связаны элементы манифеста. Сведения о том, когда этот факт имеет отношение к структуре надстройки, см. в разделе Указание требований в элементе VersionOverrides .

API- интерфейсы, не в наборе требований

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

Элемент Requirements

Используйте элемент Requirements и его дочерние элементы Set and Methods , чтобы указать минимальные наборы требований или члены API, которые должны поддерживаться приложением Office для установки надстройки.

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

Примечание.

Элемент <Requirements> является необязательным для всех надстроек, за исключением надстроек Outlook. xsi:type Если атрибут корневого OfficeApp элемента имеет значение MailApp, должен быть элемент Requirements>, указывающий минимальную< версию набора обязательных для почтового ящика, требуемую надстройке. Дополнительные сведения см. в разделе Наборы обязательных элементов API JavaScript для Outlook.

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

  • TableBindings набор обязательных требований, который имеет минимальную версию "1.1".
  • OOXML набор обязательных требований, который имеет минимальную версию "1.1".
  • Document.getSelectedDataAsync метод.
<OfficeApp ... >
  ...
  <Requirements>
     <Sets DefaultMinVersion="1.1">
        <Set Name="TableBindings" MinVersion="1.1"/>
        <Set Name="OOXML" MinVersion="1.1"/>
     </Sets>
     <Methods>
        <Method Name="Document.getSelectedDataAsync"/>
     </Methods>
  </Requirements>
    ...
</OfficeApp>

Обратите внимание на следующие сведения об этом примере.

  • Элемент <Requirements> содержит дочерние <элементы Sets> и <Methods> .
  • Элемент <Sets> может содержать один или несколько <элементов Set> . DefaultMinVersion задает значение по умолчанию MinVersion для всех дочерних <элементов Set> .
  • Элемент Set указывает набор требований, который приложение Office должно поддерживать, чтобы сделать надстройку устанавливаемой. Атрибут Name задает имя набора требований. Указывает MinVersion минимальную версию набора требований. MinVersion переопределяет значение атрибута DefaultMinVersion в родительском <наборе Sets>.
  • Элемент <Methods> может содержать один или несколько элементов Method . Элемент Methods> нельзя использовать< с надстройками Outlook.
  • Элемент <Method> указывает отдельный метод, который приложение Office должно поддерживать, чтобы сделать надстройку устанавливаемой. Атрибут Name является обязательным и указывает имя метода, соответствующего родительскому объекту.

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

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

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

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

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

Среда выполнения проверяет поддержку методов и наборов требований

Во время выполнения вы проверяете, поддерживает ли Office пользователя набор обязательных элементов с помощью метода isSetSupported . Передайте имя набора требований и минимальную версию в качестве параметров. Если набор требований поддерживается, isSetSupported возвращается true. Ниже приводится пример кода.

if (Office.context.requirements.isSetSupported('WordApi', '1.2'))
{
   // Code that uses API members from the WordApi 1.2 requirement set.
} else {
   // Provide diminished experience here. E.g., run alternate code when the user's Word is volume-licensed perpetual Word 2016 (which doesn't support WordApi 1.2).
}

Вот что нужно знать об этом коде:

  • Первый параметр является обязательным. Это строка, представляющая имя набора требований. Дополнительные сведения о доступных наборах обязательных элементов см. в статье Наборы обязательных элементов для надстроек Office.
  • Второй параметр является необязательным. Это строка, указывающая минимальную версию набора требований, которую приложение Office должно поддерживать для выполнения кода в if инструкции (например, "1.9"). Если не используется, предполагается версия "1.1".

Предупреждение

При вызове isSetSupported метода значение второго параметра (если указано) должно быть строкой, а не числом. Средство синтаксического анализа JavaScript не может различать числовые значения, такие как 1.1 и 1.10, в то время как он может использовать для строковых значений, таких как "1.1" и "1.10".

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

Приложение Office RequirementSetName
Excel ExcelApi
OneNote OneNoteApi
Outlook Mailbox
PowerPoint PowerPointApi
Word WordApi

Ниже приведен пример использования метода с одним из наборов требований модели Common API.

if (Office.context.requirements.isSetSupported('CustomXmlParts'))
{
    // Run code that uses API members from the CustomXmlParts requirement set.
}
else
{
    // Run alternate code when the user's Office application doesn't support the CustomXmlParts requirement set.
}

Примечание.

Метод isSetSupported и наборы требований для этих приложений доступны в последнем файле Office.js в CDN. Если вы не используете Office.js из СЕТИ CDN, надстройка может создать исключения, если используется старая версия библиотеки, в которой isSetSupported не определен. Дополнительные сведения см. в статье Использование последней библиотеки API JavaScript для Office.

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

Примечание.

Рекомендуем ограничить использование этого типа проверки в среде выполнения в коде надстройки.

В следующем примере кода проверяется, поддерживает document.setSelectedDataAsyncли приложение Office .

if (Office.context.document.setSelectedDataAsync)
{
    // Run code that uses `document.setSelectedDataAsync`.
}

Указание требований в элементе VersionOverrides

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

Предположим, что ваша надстройка использует одну из этих функций, но она полезна и должна быть установлена даже в версиях Office, которые не поддерживают эту функцию. В этом сценарии определите функцию с помощью элемента Requirements (и его дочерних элементов Sets и Methods ), который вы включаете как дочерний <элемент элемента VersionOverrides> , а не как дочерний элемент базового OfficeApp элемента. Результатом этого является то, что Office позволит установить надстройку, но Office будет игнорировать некоторые дочерние элементы <элемента VersionOverrides> в версиях Office, где эта функция не поддерживается.

В частности, дочерние элементы <VersionOverrides> , которые переопределяют элементы в базовом <манифесте, такие как элемент Hosts> , игнорируются, а вместо них используются соответствующие элементы базового манифеста. Однако в <VersionOverrides> могут быть дочерние элементы, которые фактически реализуют дополнительные функции, а не переопределяют параметры в базовом манифесте. Двумя примерами являются WebApplicationInfo и EquivalentAddins. Эти части <VersionOverrides>не будут игнорироваться, если платформа и версия Office поддерживают соответствующую функцию.

Сведения об элементах-потомков <элемента Requirements> см. в разделе Элемент Requirements ранее в этой статье.

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

<VersionOverrides ... >
   ...
   <Requirements>
      <Sets DefaultMinVersion="1.1">
         <Set Name="WordApi" MinVersion="1.2"/>
      </Sets>
   </Requirements>
   <Hosts>

      <!-- ALL MARKUP INSIDE THE HOSTS ELEMENT IS IGNORED WHEREVER WordApi 1.2 IS NOT SUPPORTED -->

      <Host xsi:type="Workbook">
         <!-- markup for custom add-in commands -->
      </Host>
   </Hosts>
</VersionOverrides>

Предупреждение

Будьте внимательны перед включением <элемента Requirements> в <VersionOverrides>, так как в сочетаниях платформ и версий, которые не поддерживают требование, ни одна из команд надстроек не будет установлена, даже те, которые вызывают функции, для которых не требуется требование. Рассмотрим, например, надстройку с двумя настраиваемыми кнопками ленты. Один из них вызывает API JavaScript для Office, доступные в наборе требований ExcelApi 1.4 (и более поздних версий). Другие вызывают API, доступные только в ExcelApi 1.9 (и более поздних версиях). Если вставить требование для ExcelApi 1.9 в <versionOverrides>, то если версия 1.9 не поддерживается, на ленте не появится ни кнопка. Лучшей стратегией в этом сценарии было бы использование метода, описанного в разделе Проверка среды выполнения для поддержки метода и набора требований. Код, вызываемый второй кнопкой, сначала используется isSetSupported для проверки поддержки ExcelApi 1.9. Если она не поддерживается, код предоставляет пользователю сообщение о том, что эта функция надстройки недоступна в его версии Office.

Совет

Нет смысла повторять элемент Requirements в <VersionOverrides> , который уже отображается в базовом манифесте. Если требование указано в базовом манифесте, надстройка не может установить там, где это требование не поддерживается, поэтому Office даже не анализирует <элемент VersionOverrides> .

См. также