Автоматическое открытие области задач с документомAutomatically open a task pane with a document

Команды в надстройке Office позволяют расширить возможности пользовательского интерфейса Office, добавляя кнопки в ленту Office. Когда пользователи нажимают кнопки, выполняются различные операции (например, открывается область задач).You can use add-in commands in your Office Add-in to extend the Office UI by adding buttons to the Office ribbon. When users click your command button, an action occurs, such as opening a task pane.

В некоторых сценариях требуется, чтобы область задач открывалась автоматически вместе с документом без явного взаимодействия с пользователем.Some scenarios require that a task pane open automatically when a document opens, without explicit user interaction. Функция автоматического открытия области задач, представленная в наборе требований AddInCommands 1.1, позволяет автоматически открывать область задач, если это требуется в вашем сценарии.You can use the autoopen task pane feature, introduced in the AddInCommands 1.1 requirement set, to automatically open a task pane when your scenario requires it.

Чем функция автоматического открытия отличается от вставки области задач?How is the autoopen feature different from inserting a task pane?

Если пользователь запускает надстройки, которые не используют команды надстроек (например, в Office 2013), они вставляются в документ и сохраняются в нем. Таким образом, при открытии этого документа другими пользователями, им будет предложено установить надстройку и откроется область задач. Недостатки этой модели часто связаны с тем, что пользователи не хотят сохранять надстройку для документа. Например, учащийся, который использует надстройку словаря в документе Word, может не захотеть, чтобы его преподаватели или одноклассники получили запрос на установку этой надстройки при открытии документа.When a user launches add-ins that don't use add-in commands - for example, add-ins that run in Office 2013 - they are inserted into the document, and persist in that document. As a result, when other users open the document, they are prompted to install the add-in, and the task pane opens. The challenge with this model is that in many cases, users don’t want the add-in to persist in the document. For example, a student who uses a dictionary add-in in a Word document might not want their classmates or teachers to be prompted to install that add-in when they open the document.

Функция автоматического открытия позволяет явно определить или дать разрешение пользователю определять необходимость в сохранении конкретной надстройки области задач в конкретном документе.With the autoopen feature, you can explicitly define or allow the user to define whether a specific task pane add-in persists in a specific document.

Поддержка и доступностьSupport and availability

Функция автоматического открытияThe autoopen feature is currently поддерживается в продуктах и платформах, перечисленных ниже.supported in the following products and platforms.

ПродуктыProducts ПлатформыPlatforms
  • WordWord
  • ExcelExcel
  • PowerPointPowerPoint
Поддерживаемые платформы для всех продуктов:Supported platforms for all products:
  • Office для настольных компьютеров с Windows (сборки 16.0.8121.1000 или более поздней)Office on Windows Desktop. Build 16.0.8121.1000+
  • Office для Mac, сборка 15.34.17051500 или вышеOffice for Mac. Build 15.34.17051500+
  • Office в ИнтернетеOffice on the web

РекомендацииBest practices

При использовании функции автоматического открытия придерживайтесь указанных рекомендаций.Apply the following best practices when you use the autoopen feature:

  • Используйте функцию автоматического открытия, если она повысит эффективность работы пользователей в подобных случаях:Use the autoopen feature when it will help make your add-in users more efficient, such as:

    • Если надстройка требуется для правильной работы документа. Например, для электронной таблицы, содержащей стоимость запасов, которая периодически обновляется с помощью надстройки. Надстройка должна открываться автоматически вместе с электронной таблицей, чтобы значения своевременно обновлялись.When the document needs the add-in in order to function properly. For example, a spreadsheet that includes stock values that are periodically refreshed by an add-in. The add-in should open automatically when the spreadsheet is opened to keep the values up to date.
    • Если пользователь с большой вероятностью всегда будет использовать эту надстройку при работе с определенным документом. Пример: надстройка, которая помогает пользователям добавлять данные в документы или вносить изменения, извлекая информацию из серверной системы.When the user will most likely always use the add-in with a particular document. For example, an add-in that helps users fill in or change data in a document by pulling information from a backend system.
  • Разрешите пользователям включать и выключать функцию автоматического открытия. Добавьте параметр в интерфейс для пользователей, чтобы автоматическое открытие области задач надстройки можно было отключить.Allow users to turn on or turn off the autoopen feature. Include an option in your UI for users to choose to no longer automatically open the add-in task pane.

  • Используйте средство обнаружения набора требований, чтобы определять доступность функции автоматического открытия, и предоставить отработку отказа при ее отсутствии.Use requirement set detection to determine whether the autoopen feature is available, and provide a fallback behavior if it isn’t.

  • Не используйте функцию автоматического открытия, чтобы искусственно увеличивать показатели использования надстройки. Если автоматическое открытие надстройки нецелесообразно для определенных документов, эта функция может раздражать пользователей.Don't use the autoopen feature to artificially increase usage of your add-in. If it doesn’t make sense for your add-in to open automatically with certain documents, this feature can annoy users.

    Примечание

    Если корпорация Майкрософт обнаружит, что функция автоматического открытия применяется не по назначению, возможно исключение вашей надстройки из AppSource.If Microsoft detects abuse of the autoopen feature, your add-in might be rejected from AppSource.

  • Не используйте эту функцию, чтобы закрепить несколько областей задач. Можно задать только одну область вашей надстройки для автоматического открытия вместе с документом.Don't use this feature to pin multiple task panes. You can only set one pane of your add-in to open automatically with a document.

РеализацияImplementation

Выполните следующие действия, чтобы использовать функцию автоматического открытия.To implement the autoopen feature:

  • Укажите область задач, которую необходимо открывать автоматически.Specify the task pane to be opened automatically.
  • Отметьте документ, в котором будет автоматически открываться эта область задач.Tag the document to automatically open the task pane.

Важно!

Область, отмеченная для автоматического открытия, будет открываться, только если необходимая надстройка уже есть на устройстве пользователя. Если она там не установлена, функция автоматического открытия не сработает при открытии документа, а параметр будет проигнорирован. Чтобы надстройка распространялась вместе с документом, задайте для свойства visibility значение 1. Это можно сделать только с помощью OpenXML. Соответствующий пример приведен ниже.The pane that you designate to open automatically will only open if the add-in is already installed on the user's device. If the user does not have the add-in installed when they open a document, the autoopen feature will not work and the setting will be ignored. If you also require the add-in to be distributed with the document you need to set the visibility property to 1; this can only be done using OpenXML, an example is provided later in this article.

Этап 1. Указание области задач, которую необходимо открыватьStep 1: Specify the task pane to open

Чтобы указать область задач, которую необходимо открывать автоматически, задайте для TaskpaneId значение Office.AutoShowTaskpaneWithDocument. Это значение можно установить только в одной области задач. Если установить это значение для нескольких областей задач, распознается только первый случай его использования, а все остальные будут игнорироваться.To specify the task pane to open automatically, set the TaskpaneId value to Office.AutoShowTaskpaneWithDocument. You can only set this value on one task pane. If you set this value on multiple task panes, the first occurrence of the value will be recognized and the others will be ignored.

Ниже представлен пример, где для TaskPaneId задано значение Office.AutoShowTaskpaneWithDocument.The following example shows the TaskPaneId value set to Office.AutoShowTaskpaneWithDocument.

<Action xsi:type="ShowTaskpane">
    <TaskpaneId>Office.AutoShowTaskpaneWithDocument</TaskpaneId>
    <SourceLocation resid="Contoso.Taskpane.Url" />
</Action>

Этап 2. Установка отметки для документа, вместе с которым будет автоматически открываться область задачStep 2: Tag the document to automatically open the task pane

Вы можете отметить документ для запуска функции автоматического открытия одним из двух способов. Выберите вариант, который лучше всего подходит для вашего сценария.You can tag the document to trigger the autoopen feature in one of two ways. Pick the alternative that works best for your scenario.

Установка отметки для документа на стороне клиентаTag the document on the client side

Используйте метод Office.js settings.set, чтобы установить для Office.AutoShowTaskpaneWithDocument значение true, как показано в следующем примере.Use the Office.js settings.set method to set Office.AutoShowTaskpaneWithDocument to true, as shown in the following example.

Office.context.document.settings.set("Office.AutoShowTaskpaneWithDocument", true);
Office.context.document.settings.saveAsync();

Используйте этот метод, если нужно отметить документ в рамках взаимодействия с надстройкой (например, после создания пользователем привязки или выбора параметра, он сможет указать необходимость в автоматическом открытии области).Use this method if you need to tag the document as part of your add-in interaction (for example, as soon as the user creates a binding, or chooses an option to indicate that they want the pane to open automatically).

Установка отметки для документа с помощью Open XMLUse Open XML to tag the document

С помощью Open XML можно создать документ и вносить в него изменения, а также добавлять соответствующие исправления в Open Office XML для запуска функции автоматического открытия. Пример с иллюстрацией того, как это можно сделать, см. в статье Office-OOXML-EmbedAddin.You can use Open XML to create or modify a document and add the appropriate Open Office XML markup to trigger the autoopen feature. For a sample that shows you how to do this, see Office-OOXML-EmbedAddin.

Добавьте в документ две части Open XML:Add two Open XML parts to the document:

  • часть webextension;A webextension part
  • часть taskpane.A taskpane part

В примере ниже показано, как добавить часть webextension.The following example shows how to add the webextension part.

<we:webextension xmlns:we="http://schemas.microsoft.com/office/webextensions/webextension/2010/11" id="[ADD-IN ID PER MANIFEST]">
  <we:reference id="[GUID or AppSource asset ID]" version="[your add-in version]" store="[Pointer to store or catalog]" storeType="[Store or catalog type]"/>
  <we:alternateReferences/>
  <we:properties>
   <we:property name="Office.AutoShowTaskpaneWithDocument" value="true"/>
  </we:properties>
  <we:bindings/>
  <we:snapshot xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships"/>
</we:webextension>

Часть webextension содержит контейнер свойств, а также свойство под названием Office.AutoShowTaskpaneWithDocument, для которого необходимо установить значение true.The webextension part includes a property bag and a property named Office.AutoShowTaskpaneWithDocument that must be set to true.

Часть webextension также содержит ссылку на магазин или каталог с атрибутами для id, storeType, store и version.The webextension part also includes a reference to the store or catalog with attributes for id, storeType, store, and version. Только четыре значения storeType относятся к функции автоматического открытия.Of the storeType values, only four are relevant to the autoopen feature. Значения остальных трех атрибутов зависят от значения для storeType, как показано в таблице ниже.The values for the other three attributes depend on the value for storeType, as shown in the following table.

Значение storeTypestoreType value Значение idid value Значение storestore value Значение versionversion value
OMEX (AppSource)OMEX (AppSource) ИД ресурса AppSource для надстройки (см. примечание)The AppSource asset ID of the add-in (see Note) Код языка для AppSource (например, "ru-ru").The locale of AppSource; for example, "en-us". Версия каталога AppSource (см. примечание)The version in the AppSource catalog (see Note)
FileSystem (сетевая папка)FileSystem (a network share) GUID надстройки в ее манифесте.The GUID of the add-in in the add-in manifest. Путь к сетевой папке (например, "\\MyComputer\MySharedFolder").The path of the network share; for example, "\\MyComputer\MySharedFolder". Версия в манифесте надстройки.The version in the add-in manifest.
EXCatalog (развертывание через Exchange Server)EXCatalog (deployment via the Exchange server) GUID надстройки в ее манифесте.The GUID of the add-in in the add-in manifest. EXCatalog."EXCatalog". Строка EXCatalog — это строка, которая будет использоваться с надстройками, использующими централизованное развертывание в Центре администрирования Office 365.EXCatalog row is the row to use with add-ins that use Centralized Deployment in the Office 365 admin center. Версия в манифесте надстройки.The version in the add-in manifest.
Registry (реестр системы)Registry (System registry) GUID надстройки в ее манифесте.The GUID of the add-in in the add-in manifest. "developer""developer" Версия в манифесте надстройки.The version in the add-in manifest.

Примечание

Для поиска ИД ресурса и версии надстройки в AppSource перейдите на целевую страницу AppSource для соответствующей надстройки. ИД ресурса отображается в адресной строке браузера. Версия указана в разделе Сведения на этой странице.To find the asset ID and version of an add-in in AppSource, go to the AppSource landing page for the add-in. The asset ID appears in the address bar in the browser. The version is listed in the Details section of the page.

Дополнительные сведения об исправлении webextension см. в документе [MS-OWEXML] 2.2.5. WebExtensionReference.For more information about the webextension markup, see [MS-OWEXML] 2.2.5. WebExtensionReference.

В примере ниже показано, как добавить часть taskpane.The following example shows how to add the taskpane part.

<wetp:taskpane dockstate="right" visibility="0" width="350" row="4" xmlns:wetp="http://schemas.microsoft.com/office/webextensions/taskpanes/2010/11">
  <wetp:webextensionref xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships" r:id="rId1" />
</wetp:taskpane>

Обратите внимание, что в этом примере для атрибута visibility установлено значение "0".Note that in this example, the visibility attribute is set to "0". Это означает, что после добавления частей webextension и taskpane при первом открытии документа пользователю необходимо будет установить надстройку, нажав кнопку Надстройка на ленте.This means that after the webextension and taskpane parts are added, the first time the document is opened, the user has to install the add-in from the Add-in button on the ribbon. После этого область задач надстройки будет открываться автоматически вместе с файлом.Thereafter, the add-in task pane opens automatically when the file is opened. Кроме того, если установить для visibility значение "0", можно с помощью Office.js предоставить пользователям возможность включать и выключать функцию автоматического открытия.Also, when you set visibility to "0", you can use Office.js to enable users to turn on or turn off the autoopen feature. В частности, ваш скрипт устанавливает для параметра документа Office.AutoShowTaskpaneWithDocument значение true или false.Specifically, your script sets the Office.AutoShowTaskpaneWithDocument document setting to true or false. (Дополнительные сведения см. в разделе Установка отметки для документа на стороне клиента.)(For details, see Tag the document on the client side.)

Если для visibility установлено значение "1", область задач откроется автоматически при первом открытии документа. Пользователю будет предложено доверять надстройке. В случае предоставления доверия надстройка откроется. После этого область задач надстройки будет открываться автоматически вместе с файлом. Однако если установить для visibility значение "1", можно с помощью Office.js предоставить пользователям возможность включать и выключать функцию автоматического открытия.If visibility is set to "1", the task pane opens automatically the first time the document is opened. The user is prompted to trust the add-in, and when trust is granted, the add-in opens. Thereafter, the add-in task pane opens automatically when the file is opened. However, when visibility is set to "1", you can't use Office.js to enable users to turn on or turn off the autoopen feature.

Значение "1" отлично подходит для свойства visibility, если надстройка и шаблон или содержимое документа интегрированы настолько тесно, что пользователь не откажется от использования функции автоматического открытия.Setting visibility to "1" is a good choice when the add-in and the template or content of the document are so closely integrated that the user would not opt out of the autoopen feature.

Примечание

Если вы хотите распространять надстройку вместе с документом, чтобы пользователям предлагалось установить ее, необходимо задать для свойства visibility значение 1. Это можно сделать только через Open XML.If you want to distribute your add-in with the document, so that users are prompted to install it, you must set the visibility property to 1. You can only do this via Open XML.

Самый простой способ записи XML — сначала запустить надстройку и отметить документ на стороне клиента, чтобы записать значение, а затем сохранить документ и проверить созданный XML. Office обнаружит и укажет соответствующие значения атрибута. Инструмент Open XML SDK 2.5 Productivity Tool также можно использовать для создания кода на языке C#, чтобы программным способом добавить исправление на основе создаваемого XML.An easy way to write the XML is to first run your add-in and tag the document on the client side to write the value, and then save the document and inspect the XML that is generated. Office will detect and provide the appropriate attribute values. You can also use the Open XML SDK 2.5 Productivity Tool tool to generate C# code to programmatically add the markup based on the XML you generate.

Тестирование и проверка открытия областей задачTest and verify opening task panes

Вы можете развернуть тестовую версию своей надстройки, которая автоматически откроет область задач с использованием централизованного развертывания через Центр администрирования Office 365.You can deploy a test version of your add-in that will automatically open a task pane using Centralized Deployment via the Office 365 admin center. В примере ниже показано, как надстройки вставляются в каталог централизованного развертывания при помощи EXCatalog (версии из магазина).The following example shows how add-ins are inserted from the Centralized Deployment catalog using the EXCatalog store version.

<we:webextension xmlns:we="http://schemas.microsoft.com/office/webextensions/webextension/2010/11" id="{52811C31-4593-43B8-A697-EB873422D156}">
    <we:reference id="af8fa5ba-4010-4bcc-9e03-a91ddadf6dd3" version="1.0.0.0" store="EXCatalog" storeType="EXCatalog"/>
    <we:alternateReferences/>
    <we:properties/>
    <we:bindings/>
    <we:snapshot xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships"/>
</we:webextension>

Чтобы протестировать предыдущий пример, рассмотрите возможность присоединения к программе для разработчиков Office 365 и подписки на учетную запись разработчика Office 365, если у вас еще нет этой подписки.To test the previous example, please consider joining the Office 365 Developer Program and signing up for an Office 365 developer account if you don't already own an Office 365 subscription. Вы можете в реальных условиях протестировать централизованное развертывание и убедиться, что ваша надстройка работает должным образом.You can actually test drive Centralized Deployment and verify that your add-in works as expected.

См. такжеSee also

Пример использования функции автоматического открытия см. на странице с примерами команд для надстройки Office.For a sample that shows you how to use the autoopen feature, see Office Add-in commands samples. Присоединитесь к программе для разработчиков Office 365.Join the Office 365 developer program.