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

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

  • работать в одном (например, Word или Excel) или нескольких приложениях Office;

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

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

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

Примечание

Для представления на высоком уровне о том, Office в настоящее время поддерживаются надстройки, см. в Office клиентского приложения и доступности платформы для Office надстройки.

В таблице ниже перечислены основные понятия, рассматриваемые в этой статье.

Концепция Описание
Office, Office клиентского приложения Приложение Office, используемое для запуска надстройки, например Word, Excel и т. д.
Платформа Где Office приложение, например в браузере или iPad.
Набор обязательных элементов Именованная группа связанных элементов API. Надстройки используют наборы требований, чтобы определить, поддерживает ли приложение Office API-членов, используемых вашей надстройки. Проще проверять поддержку набора требований, а не отдельных элементов API. Поддержка набора требований зависит Office приложения и версии Office приложения.
Наборы обязательных элементов указываются в файле манифеста. При указании наборов требований в манифесте устанавливается минимальный уровень поддержки API, который Office приложение для запуска надстройки. Office приложения, которые не поддерживают наборы требований, указанные в манифесте, не могут запустить надстройку, и ваша надстройка не будет отображаться в моихнадстройких. Это ограничивает доступ к надстройки. в коде с помощью проверок в среде выполнения. Полный список наборов требований см. в статье Наборы обязательных элементов для надстроек Office.
Проверка в среде выполнения Тест, выполняемый во время выполнения, чтобы определить, поддерживает ли Office приложение, которое выполняет надстройку, наборы требований или методы, используемые вашей надстройки. Для выполнения проверки времени выполнения используется утверждение if с методом, наборами требований или именами методов, которые не являются isSetSupported частью набора требований. Проверки в среде выполнения позволяют максимально расширить аудиторию надстройки. В отличие от наборов требований, проверки времени запуска не указывают минимальный уровень поддержки API, который Office приложение должно предоставить для запуска надстройки. Вместо этого вы используете утверждение if, чтобы определить, поддерживается ли член API. и если это так, добавляете в надстройку дополнительные функции. Если вы используете проверки в среде выполнения, ваша надстройка всегда будет отображаться в разделе Мои надстройки.

Подготовка

Надстройка должна использовать последнюю версию схемы манифеста надстройки. Если вы используете проверки времени работы в надстройки, убедитесь, что вы используете последнюю Office API JavaScript (office.js) библиотеку.

Выбор последней версии схема манифестов надстроек

Ваша надстройка должна использовать схему манифеста 1.1. Установите элемент OfficeApp в манифесте надстройки следующим образом. В этом примере показан TaskPaneApp тип.

<OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="TaskPaneApp">

Укажите последнюю Office API JavaScript

Если вы используете проверки времени запуска, ссылайся на наиболее текущую версию библиотеки 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 приложений или требований API

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

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

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

  • Чтобы установить минимальный набор требований или членов API, которые Office приложение должно поддерживать для запуска надстройки, установите элемент Requirements манифеста. Дополнительные сведения см. в элементе Set the Requirements in the manifest.

  • Если вы хотите предоставить дополнительные функции, если в приложении Office доступны определенные наборы требований или члены API, выполните проверку времени выполнения в коде JavaScript надстройки. Например, если надстройка выполняется в Excel 2016, используйте элементы нового API JavaScript для Excel, чтобы предоставить дополнительные функции. Дополнительные сведения см. в разделе Использование проверок в среде выполнения в коде JavaScript.

Задание элемента Hosts

Чтобы выполнить надстройку в Office клиентского приложения, используйте элементы и элементы Hosts Host манифеста. Если элемент не указан, надстройка будет работать во всех Office приложениях, поддерживаемых указанным типом Hosts OfficeApp (например, Mail, Task pane или Content).

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

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

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

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

Примечание

Атрибут Name указывает Office клиентского приложения, которое может запустить надстройку. Office поддерживаются на разных платформах и запускаются на настольных компьютерах, веб-браузерах, планшетах и мобильных устройствах. Вам не удастся указать, какую платформу можно использовать для запуска надстройки. Например, если указать, Outlook в Интернете и Windows можно использовать для запуска Mailbox надстройки.

Важно!

Больше не рекомендуется создавать и использовать веб-приложения и базы данных Access в SharePoint. В качестве альтернативы рекомендуем использовать Microsoft PowerApps для создания бизнес-решений для Интернета и мобильных устройств без написания кода.

Указание элемента Requirements в манифесте

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

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

Только используйте элемент для указания критически важных наборов требований или Requirements членов API, которые должна использовать ваша надстройка. Если Office или платформа не поддерживает наборы требований или членов API, указанных в элементе, надстройка не будет работать в этом приложении или платформе и не будет отображаться в моих надстройки. Requirements Вместо этого рекомендуется сделать надстройки доступными на всех платформах приложения Office, таких как Excel в Интернете, Windows и iPad. Чтобы сделать надстройку доступной для всех Office приложений и платформ, используйте проверки времени работы вместо Requirements элемента.

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

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

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

  • Document.getSelectedDataAsync метод.

<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>
  • Элемент Requirements содержит и Sets Methods детские элементы.

  • Элемент Sets может содержать один или несколько Set элементов. DefaultMinVersion указывает значение MinVersion по умолчанию для всех Set детских элементов.

  • Элемент указывает наборы требований, которые Office приложение должно поддерживать для Set запуска надстройки. Атрибут Name указывает имя набора требований. Указывает MinVersion минимальную версию набора требований. MinVersionпереопределяет значение Дополнительные сведения о наборах требований и версиях набора требований, к которые принадлежат члены API, см. в Office наборов DefaultMinVersion требований к надстройки.

  • Элемент Methods может содержать один или несколько Method элементов. Нельзя использовать элемент с Outlook Methods надстройки.

  • Элемент указывает отдельный метод, который должен поддерживаться в приложении Office, где выполняется Method надстройка. Атрибут необходим и указывает имя метода, квалифицированного с Name родительским объектом.

Использование проверок в среде выполнения в коде JavaScript

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

if (Office.context.requirements.isSetSupported(RequirementSetName, MinimumVersion))
{
   // Code that uses API members from RequirementSetName.
}

  • RequirementSetName (обязательный параметр) — это строка, представляющая имя набора обязательных элементов (например, "ExcelApi", "Mailbox" и т. д.). Дополнительные сведения о доступных наборах обязательных элементов см. в статье Наборы обязательных элементов для надстроек Office.
  • MinimumVersion (необязательный) — это строка, которая указывает минимальную версию набора требований, которую необходимо поддерживать приложению Office для запуска кода в заявлении if (например,"1.9").

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

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

Используйте isSetSupported с связанным с RequirementSetName приложением Office следующим образом.

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

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

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

if (Office.context.requirements.isSetSupported('WordApi', '1.1'))
{
    // Run code that provides additional functionality using the Word JavaScript API when the add-in runs in Word 2016 or later.
}
else if (Office.context.requirements.isSetSupported('CustomXmlParts'))
{
    // Run code that uses API members from the CustomXmlParts requirement set.
}
else
{
    // Run additional code when the Office application is not Word 2016 or later and does not support the CustomXmlParts requirement set.
}

Проверки в среде выполнения с использованием методов, не входящих в набор обязательных элементов

Некоторые элементы API не входят в наборы обязательных элементов. Это относится только к членам API, которые являются частью пространства имен API Office JavaScript (все, кроме API Outlook почтовых ящиков), но не являются членами Office. API Word JavaScript (все в), Excel API JavaScript (все в ), или OneNote Word. Excel. API JavaScript (все в ) OneNote. пространствах имен. Если надстройка зависит от метода, который не входит в набор требований, вы можете использовать проверку времени работы, чтобы определить, поддерживается ли метод приложением Office, как показано в следующем примере кода. Список всех методов, не входящих в набор обязательных элементов, см. в статье Наборы обязательных элементов для надстроек Office.

Примечание

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

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

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

См. также