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

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

  • Статья

Примечание.

Сведения об указании требований с помощью унифицированного манифеста для Microsoft 365 см. в статье Указание узлов Office и требований API с помощью унифицированного манифеста.

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

  • Запуск в одном приложении Office (например, Word или Excel) или нескольких приложениях.
  • Используйте 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.1/ в URL-адресе сети доставки содержимого.

<script src="https://appsforoffice.microsoft.com/lib/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 .

Элемент Requirements

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

Все API в моделях для конкретных приложений находятся в наборах требований, но некоторые из них в модели Common API — нет. Используйте методы , чтобы указать не заданные члены API, необходимые надстройке. Элемент Methods> нельзя использовать< с надстройками Outlook.

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

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

Указание требований в элементе 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 не поддерживается, на ленте не будет отображаться ни кнопка . Более лучшая стратегия в этом сценарии заключается в использовании метода, описанного в разделе Проверка доступности API во время выполнения. Код, вызываемый второй кнопкой, сначала используется isSetSupported для проверка для поддержки ExcelApi 1.9. Если она не поддерживается, код предоставляет пользователю сообщение о том, что эта функция надстройки недоступна в его версии Office.

Совет

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

См. также