Указание ведущих приложений Office и требований к APISpecify Office hosts and API requirements

Работа надстройки Office может зависеть от ведущего приложения Office, набора обязательных элементов, элемента или версии API. Например, надстройка может:Your Office Add-in might depend on a specific Office host, a requirement set, an API member, or a version of the API in order to work as expected. For example, your add-in might:

  • работать в одном (например, Word или Excel) или нескольких приложениях Office;Run in a single Office application (e.g., Word or Excel), or several applications.

  • использовать API JavaScript, доступные только в некоторых версиях Office. Например, можно создать надстройку Excel 2016 на базе новых API JavaScript для Excel;Make use of JavaScript APIs that are only available in some versions of Office. For example, you might use the Excel JavaScript APIs in an add-in that runs in Excel 2016.

  • работать только в версиях Office, которые поддерживают элементы API, используемые вашей надстройкой.Run only in versions of Office that support API members that your add-in uses.

Эта статья поможет вам разобраться, какие параметры следует выбрать для правильной работы надстройки и максимального охвата аудитории.This article helps you understand which options you should choose to ensure that your add-in works as expected and reaches the broadest audience possible.

Примечание

Общие сведения о том, на каких платформах поддерживаются надстройки Office, см. в этой статье.For a high-level view of where Office Add-ins are currently supported, see the Office Add-in host and platform availability page.

В таблице ниже перечислены основные понятия, рассматриваемые в этой статье.The following table lists core concepts discussed throughout this article.

КонцепцияConcept ОписаниеDescription
Приложение Office, ведущее приложение Office или ведущее приложениеOffice application, Office host application, Office host, or host Приложение Office, используемое для запуска надстройки, например Word, Excel и т. д.The Office application used to run your add-in. For example, Word, Excel, and so on.
ПлатформаPlatform Среда выполнения ведущего приложения Office, например браузер или iPad.Where the Office host runs, such as in a browser or on an iPad.
Набор обязательных элементовRequirement set Именованная группа связанных элементов API. С помощью наборов обязательных элементов надстройка определяет, поддерживает ли ведущее приложение Office элементы API, которые она использует. Проще проверять поддержку набора обязательных элементов, а не отдельных элементов API. Поддержка набора обязательных элементов зависит от ведущего приложения Office и его версии. A named group of related API members. Add-ins use requirement sets to determine whether the Office host supports API members used by your add-in. It's easier to test for the support of a requirement set than for the support of individual API members. Requirement set support varies by Office host and the version of the Office host.
Наборы обязательных элементов указываются в файле манифеста.Requirement sets are specified in the manifest file. Задавая наборы обязательных элементов в манифесте, вы указываете, какой минимальный уровень поддержки API должно обеспечить ведущее приложение Office, чтобы можно было запустить надстройку.When you specify requirement sets in the manifest, you set the minimum level of API support that the Office host must provide in order to run your add-in. Надстройка не будет работать в ведущих приложениях Office, которые не поддерживают наборы обязательных элементов, указанные в манифесте, и не будет отображаться в разделе Мои надстройки. Это ограничивает доступность надстройкиOffice hosts that don't support requirement sets specified in the manifest can't run your add-in, and your add-in won't display in My Add-ins. This restricts where your add-in is available. в коде с помощью проверок в среде выполнения.In code using runtime checks. Полный список наборов требований см. в статье Наборы обязательных элементов для надстроек Office.For the complete list of requirement sets, see Office Add-in requirement sets.
Проверка в среде выполненияRuntime check Проверка в среде выполнения, которая позволяет определить, поддерживает ли ведущее приложение Office наборы требований или методы, которые использует надстройка.A test that is performed at runtime to determine whether the Office host running your add-in supports requirement sets or methods used by your add-in. Чтобы запустить такую проверку, используйте оператор if с методом isSetSupported, наборами требований или именами методов, которые не входят в набор требований.To perform a runtime check, you use an if statement with the isSetSupported method, the requirement sets, or the method names that aren't part of a requirement set. Проверки в среде выполнения позволяют максимально расширить аудиторию надстройки.Use runtime checks to ensure that your add-in reaches the broadest number of customers. В отличие от наборов требований, такие проверки не позволяют задать минимальный уровень поддержки API, который требуется для запуска надстройки.Unlike requirement sets, runtime checks don't specify the minimum level of API support that the Office host must provide for your add-in to run. Вместо этого с помощью оператора if вы определяете, поддерживается ли элемент API,Instead, you use the if statement to determine whether an API member is supported. и если это так, добавляете в надстройку дополнительные функции.If it is, you can provide additional functionality in your add-in. Если вы используете проверки в среде выполнения, ваша надстройка всегда будет отображаться в разделе Мои надстройки.Your add-in will always display in My Add-ins when you use runtime checks.

ПодготовкаBefore you begin

Надстройка должна использовать последнюю версию схемы манифеста надстройки. Если вы используете проверки в среде выполнения, используйте последнюю версию библиотеки API JavaScript для Office (office.js).Your add-in must use the most current version of the add-in manifest schema. If you use runtime checks in your add-in, ensure that you use the latest JavaScript API for Office (office.js) library.

Выбор последней версии схема манифестов надстроекSpecify the latest add-in manifest schema

Ваша надстройка должна использовать схему манифеста 1.1. Настройте элемент OfficeApp в манифесте надстройки указанным ниже образом.Your add-in's manifest must use version 1.1 of the add-in manifest schema. Set the OfficeApp element in your add-in manifest as follows.

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

Выбор последней версии библиотеки API JavaScript для OfficeSpecify the latest JavaScript API for Office library

Если вы используете проверки в среде выполнения, то вам необходимо ссылаться на последнюю версию библиотеки API JavaScript для Office из сети доставки содержимого. Для этого добавьте указанный ниже тег script в HTML-код. Чтобы всегда ссылаться на последнюю версию файла Office.js, используйте /1/ в URL-адресе сети доставки содержимого.If you use runtime checks, reference the most current version of the JavaScript API for Office library from the content delivery network (CDN). To do this, add the following script tag to your HTML. Using /1/ in the CDN URL ensures that you reference the most recent version of Office.js.

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

Параметры для задания ведущих приложений Office или требований к APIOptions to specify Office hosts or API requirements

При указании ведущих приложений Office и требований к API необходимо учитывать несколько факторов. На следующей схеме показано, как выбрать правильный метод для надстройки.When you specify Office hosts or API requirements, there are several factors to consider. The following diagram shows how to decide which technique to use in your add-in.

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

  • Если ваша надстройка работает в одном приложении Office, укажите элемент Hosts в манифесте. Дополнительные сведения см. в разделе Задание элемента Hosts.If your add-in runs in one Office host, set the Hosts element in the manifest. For more information, see Set the Hosts element.

  • Чтобы задать минимальный набор обязательных элементов или элементы API, которые должно поддерживать ведущее приложение Office для запуска надстройки, задайте элемент Requirements в манифесте. Дополнительные сведения см. в разделе Задание элемента Requirements в манифесте.To set the minimum requirement set or API members that an Office host must support to run your add-in, set the Requirements element in the manifest. For more information, see Set the Requirements element in the manifest.

  • Чтобы предоставить дополнительные функции, если определенные наборы обязательных элементов или элементы API доступны в ведущем приложении Office, выполните проверку в среде выполнения для кода JavaScript надстройки.If you would like to provide additional functionality if specific requirement sets or API members are available in the Office host, perform a runtime check in your add-in's JavaScript code. Например, если надстройка выполняется в Excel 2016, используйте элементы нового API JavaScript для Excel, чтобы предоставить дополнительные функции.For example, if your add-in runs in Excel 2016, use API members from the Excel JavaScript API to provide additional functionality. Дополнительные сведения см. в разделе Использование проверок в среде выполнения в коде JavaScript.For more information, see Use runtime checks in your JavaScript code.

Задание элемента HostsSet the Hosts element

Чтобы надстройка работала в одном ведущем приложении Office, используйте элементы Hosts и Host в манифесте. Если элемент Hosts не указан, надстройка будет работать во всех ведущих приложениях.To make your add-in run in one Office host application, use the Hosts and Host elements in the manifest. If you don't specify the Hosts element, your add-in will run in all hosts.

Например, указанное ниже объявление Hosts и Host указывает, что надстройка будет работать с любым выпуском Excel, включая Excel в Интернете, Excel для Windows и для iPad.For example, the following Hosts and Host declaration specifies that the add-in will work with any release of Excel, which includes Excel on the web, Windows, and iPad.

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

Элемент Hosts может содержать один или несколько элементов Host. Элемент Host указывает ведущее приложение Office, в котором может работать ваша надстройка. Обязательному атрибуту Name можно присвоить одно из указанных ниже значений.The Hosts element can contain one or more Host elements. The Host element specifies the Office host your add-in requires. The Name attribute is required and can be set to one of the following values.

ИмяName Ведущие приложения OfficeOffice host applications
DatabaseDatabase Веб-приложения AccessAccess web apps
ДокументDocument Word для Windows, Word для Mac, Word для iPad, Word в ИнтернетеWord on Windows, Word on Mac, Word on iPad, Word on the web
Почтовый ящикMailbox Outlook для Windows, Outlook для Mac, Outlook в Интернете, Outlook для Android, Outlook для iOSOutlook on Windows, Outlook on Mac, Outlook on the web, Outlook on Android, Outlook on iOS
ПрезентацияPresentation PowerPoint для Windows, PowerPoint для Mac, PowerPoint для iPad, PowerPoint в ИнтернетеPowerPoint on Windows, PowerPoint on Mac, PowerPoint on iPad, PowerPoint on the web
ПроектProject Project для WindowsProject on Windows
Рабочая книгаWorkbook Excel для Windows, Excel для Mac, Excel для iPad, Excel в ИнтернетеExcel on Windows, Excel on Mac, Excel on iPad, Excel on the web

Примечание

Атрибут Name указывает приложение Office, в котором может запускаться ваша надстройка.The Name attribute specifies the Office host application that can run your add-in. Приложения Office поддерживаются на разных платформах и работают на настольных ПК, в веб-браузерах, на планшетах и мобильных устройствах.Office hosts are supported on different platforms and run on desktops, web browsers, tablets, and mobile devices. Вам не удастся указать, какую платформу можно использовать для запуска надстройки.You can't specify which platform can be used to run your add-in. Например, если указать Mailbox, то для запуска надстройки можно будет использовать и Outlook для Windows, и Outlook в Интернете.For example, if you specify Mailbox, both Outlook on Windows and on the web can be used to run your add-in.

Важно!

Больше не рекомендуется создавать и использовать веб-приложения и базы данных Access в SharePoint.We no longer recommend that you create and use Access web apps and databases in SharePoint. В качестве альтернативы рекомендуем использовать Microsoft PowerApps для создания бизнес-решений для Интернета и мобильных устройств без написания кода.As an alternative, we recommend that you use Microsoft PowerApps to build no-code business solutions for web and mobile devices.

Указание элемента Requirements в манифестеSet the Requirements element in the manifest

С помощью элемента Requirements можно задать минимальные наборы обязательных элементов или элементы API, которые должно поддерживать ведущее приложение Office для запуска надстройки. В элементе Requirements можно указать как наборы обязательных элементов, так и отдельные методы, используемые в надстройке. В версии 1.1 схемы манифестов надстроек элемент Requirements необязателен для всех надстроек, кроме надстроек Outlook.The Requirements element specifies the minimum requirement sets or API members that must be supported by the Office host to run your add-in. The Requirements element can specify both requirement sets and individual methods used in your add-in. In version 1.1 of the add-in manifest schema, the Requirements element is optional for all add-ins, except for Outlook add-ins.

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

Используйте элемент Requirements, только чтобы указать ключевые наборы требований или элементы API, которые должна использовать надстройка.Only use the Requirements element to specify critical requirement sets or API members that your add-in must use. Если платформа или ведущее приложение Office не поддерживает наборы требований или элементы API, указанные в элементе Requirements, надстройка не будет работать в этом ведущем приложении или на этой платформе, а также не будет отображаться в разделе Мои надстройки. Вместо этого рекомендуем сделать надстройку доступной на всех платформах ведущего приложения Office, таких как Excel в Интернете, Excel для Windows и для iPad.If the Office host or platform doesn't support the requirement sets or API members specified in the Requirements element, the add-in won't run in that host or platform, and won't display in My Add-ins. Instead, we recommend that you make your add-in available on all platforms of an Office host, such as Excel on the web, Windows, and iPad. Чтобы надстройка была доступной во всех приложениях Office и на всех платформах, используйте проверки в среде выполнения, а не элемент Requirements.To make your add-in available on all Office hosts and platforms, use runtime checks instead of the Requirements element.

В примере кода ниже показана надстройка, которая загружается во всех ведущих приложениях Office, поддерживающих указанные ниже элементы.The following code example shows an add-in that loads in all Office host applications that support the following:

  • Набор обязательных элементов TableBindings 1.1 или более поздней версии.TableBindings requirement set, which has a minimum version of "1.1".

  • Набор обязательных элементов OOXML 1.1 или более поздней версии.OOXML requirement set, which has a minimum version of "1.1".

  • Метод Document.getSelectedDataAsync.Document.getSelectedDataAsync method.

<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.The Requirements element contains the Sets and Methods child elements.

  • Элемент Sets может содержать один или несколько элементов Set. Параметр DefaultMinVersion задает значение MinVersion по умолчанию для всех дочерних элементов Set.The Sets element can contain one or more Set elements. DefaultMinVersion specifies the default MinVersion value of all child Set elements.

  • Элемент Set указывает наборы обязательных элементов, которые ведущее приложение Office должно поддерживать для запуска надстройки.The Set element specifies requirement sets that the Office host must support to run the add-in. Атрибут Name указывает имя набора обязательных элементов.The Name attribute specifies the name of the requirement set. Атрибут MinVersion указывает минимальную версию набора обязательных элементов.The MinVersion specifies the minimum version of the requirement set. MinVersion переопределяет значение DefaultMinVersion.MinVersion overrides the value of DefaultMinVersion. Дополнительные сведения о наборах обязательных элементов и их версиях, к которым принадлежат элементы API, см. в статье Наборы обязательных элементов для надстроек Office.For more information about requirement sets and requirement set versions that your API members belong to, see Office Add-in requirement sets.

  • Элемент Methods может содержать один или несколько элементов Method. Элемент Methods не следует использовать с надстройками Outlook.The Methods element can contain one or more Method elements. You can't use the Methods element with Outlook add-ins.

  • Элемент Method задает отдельный метод, который должно поддерживать ведущее приложение Office, в котором работает надстройка. Атрибут Name обязателен и указывает имя метода с его родительским объектом.The Method element specifies an individual method that must be supported in the Office host where your add-in runs. The Name attribute is required and specifies the name of the method qualified with its parent object.

Использование проверок в среде выполнения в коде JavaScriptUse runtime checks in your JavaScript code

Если ведущее приложение Office поддерживает определенные наборы требований, вы можете добавить в надстройку дополнительные функции.You might want to provide additional functionality in your add-in if certain requirement sets are supported by the Office host. Например, если надстройка работает в Word 2016, вы можете использовать в ней API JavaScript для Word.For example, you might want to use the Word JavaScript APIs in your existing add-in if your add-in runs in Word 2016. Для этого используйте метод isSetSupported с именем набора обязательных элементов.To do this, you use the isSetSupported method with the name of the requirement set. В среде выполнения метод isSetSupported определяет, поддерживает ли приложение Office, в котором запускается надстройка, этот набор требований.isSetSupported determines, at runtime, whether the Office host running the add-in supports the requirement set. Если он поддерживается, то метод isSetSupported возвращает значение true и запускает дополнительный код, который использует элементы API из этого набора.If the requirement set is supported, isSetSupported returns true and runs the additional code that uses the API members from that requirement set. Если приложение Office не поддерживает набор требований, метод isSetSupported возвращает значение false, и дополнительный код не запускается.If the Office host doesn't support the requirement set, isSetSupported returns false and the additional code won't run. В коде ниже показан синтаксис, который необходимо использовать с методом isSetSupported.The following code shows the syntax to use with isSetSupported.

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

  • RequirementSetName (обязательный параметр) — это строка, представляющая имя набора обязательных элементов (например, "ExcelApi", "Mailbox" и т. д.).RequirementSetName (required) is a string that represents the name of the requirement set (e.g., "ExcelApi", "Mailbox", etc.). Дополнительные сведения о доступных наборах обязательных элементов см. в статье Наборы обязательных элементов для надстроек Office.For more information about available requirement sets, see Office Add-in requirement sets.
  • MinimumVersion (необязательный параметр) — это строка, указывающая минимальную версию набора обязательных элементов, которая должна поддерживаться ведущим приложением, чтобы выполнять код в операторе if (например, "1.9").MinimumVersion (optional) is a string that specifies the minimum requirement set version that the host must support in order for the code within the if statement to run (e.g., "1.9").

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

При вызове метода isSetSupported значение параметра MinimumVersion (если указано) должно быть строковым.When calling the isSetSupported method, the value of the MinimumVersion parameter (if specified) should be a string. Это обусловлено тем, что средство синтаксического анализа JavaScript не может различить числовые значения, например 1.1 и 1.10, но может различать строковые значения, например "1.1" и "1.10".This is because the JavaScript parser cannot differentiate between numeric values such as 1.1 and 1.10, where as it can for string values such as "1.1" and "1.10". Перегрузка оператора number не рекомендуется.The number overload is deprecated.

Используйте метод isSetSupported с параметром RequirementSetName, связанным с ведущим приложением Office, как показано ниже.Use isSetSupported with the RequirementSetName associated with the Office host as follows.

Ведущее приложение OfficeOffice host RequirementSetNameRequirementSetName
ExcelExcel ExcelApiExcelApi
OneNoteOneNote OneNoteApiOneNoteApi
OutlookOutlook MailboxMailbox
WordWord WordApiWordApi

Метод isSetSupported и наборы обязательных элементов для этих ведущих приложений доступны в последней версии файла Office.js, размещенного в сети доставки содержимого.The isSetSupported method and the requirement sets for these hosts are available in the latest Office.js file on the CDN. Если вы не используете файл Office.js из CDN, надстройка может создавать исключения, так как метод isSetSupported не будет определен.If you don't use Office.js from the CDN, your add-in might generate exceptions because isSetSupported will be undefined. Дополнительные сведения см. в статье Выбор последней версии библиотеки API JavaScript для Office.For more information, see Specify the latest JavaScript API for Office library.

В приведенном ниже примере кода показано, как функциональность надстройки может отличаться в ведущих приложениях Office, поддерживающих разные наборы обязательных элементов или элементы API.The following code example shows how an add-in can provide different functionality for different Office hosts that might support different requirement sets or API members.

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 host is not Word 2016 or later and does not support the CustomXmlParts requirement set.
}

Проверки в среде выполнения с использованием методов, не входящих в набор обязательных элементовRuntime checks using methods not in a requirement set

Некоторые элементы API не входят в наборы обязательных элементов.Some API members don't belong to requirement sets. Это относится только к тем элементам API, которые входят в пространства имен API JavaScript для Office (все элементы в Office., кроме API почтовых ящиков для Outlook), но не относится к элементам API, принадлежащим к пространствам имен API JavaScript для Word (все элементы в Word.), API JavaScript для Excel (все элементы в Excel.) или API JavaScript для OneNote (все элементы в OneNote.).This only applies to API members that are part of the JavaScript API for Office namespace (anything under Office. except Outlook Mailbox APIs), but not API members that belong to the Word JavaScript API (anything in Word.), Excel JavaScript API (anything in Excel.), or OneNote JavaScript API (anything in OneNote.) namespaces. Если надстройка зависит от метода, не входящего в набор обязательных элементов, вы можете использовать проверку в среде выполнения, чтобы определить, поддерживается ли метод ведущим приложением Office, как показано в примере кода ниже.When your add-in depends on a method that is not part of a requirement set, you can use the runtime check to determine whether the method is supported by the Office host, as shown in the following code example. Список всех методов, не входящих в набор обязательных элементов, см. в статье Наборы обязательных элементов для надстроек Office.For a complete list of methods that don't belong to a requirement set, see Office Add-in requirement sets.

Примечание

Рекомендуем ограничить использование этого типа проверки в среде выполнения в коде надстройки.We recommend that you limit the use of this type of runtime check in your add-in's code.

В примере кода ниже показано, как проверить, поддерживает ли ведущее приложение метод document.setSelectedDataAsync.The following code example checks whether the host supports document.setSelectedDataAsync.

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

См. такжеSee also