Автоматическое открытие области задач с документом

  • Статья

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

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

Примечание.

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

Чем функция автоматического открытия отличается от вставки области задач?

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

Функция автоматического открытия позволяет явно определить или дать разрешение пользователю определять необходимость в сохранении конкретной надстройки области задач в конкретном документе.

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

Функция автоподкрыти в настоящее время поддерживается в следующих продуктах и платформах.

Продукты Платформы
  • Word
  • Excel
  • PowerPoint
 Поддерживаемые платформы для всех поддерживаемых продуктов:
  • Office в Интернете
  • Office в Windows (сборка 16.0.8121.1000 или более поздняя версия)
  • Office для Mac (сборка 15.34.17051500 или более поздняя версия)

Лучшие методики

При использовании функции автоматического обновления используйте следующие рекомендации.

  • Используйте функцию автоматического открытия, если она повысит эффективность работы пользователей в подобных случаях:

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

  • Разрешите пользователям включать и выключать функцию автоматического открытия. Добавьте параметр в интерфейс для пользователей, чтобы автоматическое открытие области задач надстройки можно было отключить.

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

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

    Примечание.

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

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

Реализация функции автоподбора

  • Укажите область задач, которую необходимо открывать автоматически.
  • Отметьте документ, в котором будет автоматически открываться эта область задач.

Важно!

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

Этап 1. Указание области задач, которую необходимо открывать

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

Ниже представлен пример, где для TaskPaneId задано значение Office.AutoShowTaskpaneWithDocument.

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

Этап 2. Установка отметки для документа, вместе с которым будет автоматически открываться область задач

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

Установка отметки для документа на стороне клиента

Используйте метод Office.js settings.set , чтобы задать для Office.AutoShowTaskpaneWithDocument значение true, как показано в следующем примере.

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

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

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

Вы можете использовать Open XML для создания или изменения документа и добавления соответствующей разметки Open Office XML для активации функции автоподключа. Пример, показывающий, как это сделать, см. в разделе Office-OOXML-EmbedAddin.

Добавьте в документ две части Open XML.

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

В примере ниже показано, как добавить часть webextension.

<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.

Часть webextension также содержит ссылку на магазин или каталог с атрибутами для id, storeType, store и version. Только четыре значения storeType относятся к функции автоматического открытия. Значения остальных трех атрибутов зависят от значения для storeType, как показано в таблице ниже.

значение storeType значение id значение store значение version
OMEX (AppSource) Идентификатор ресурса AppSource надстройки (см. примечание). Код языка для AppSource (например, "ru-ru"). Версия в каталоге AppSource (см. примечание).
WOPICatalog (партнерские узлы WOPI ) Идентификатор ресурса AppSource надстройки (см. примечание). "wopicatalog". Используйте это значение для надстроек, опубликованных в источнике приложений и установленных на узлах WOPI. Дополнительные сведения см. в статье Интеграция с Office Online. Версия в манифесте надстройки.
FileSystem (сетевая папка) GUID надстройки в ее манифесте. Путь к общей сетевой папке; например, "\\MyComputer\MySharedFolder". Версия в манифесте надстройки.
EXCatalog (развертывание через Exchange Server) GUID надстройки в ее манифесте. EXCatalog. Строка EXCatalog — это строка, используемая для надстроек, использующих централизованное развертывание в Центр администрирования Microsoft 365. Версия в манифесте надстройки.
Registry (реестр системы) GUID надстройки в ее манифесте. "developer" Версия в манифесте надстройки.

Примечание.

Для поиска ИД ресурса и версии надстройки в AppSource перейдите на целевую страницу AppSource для соответствующей надстройки. ИД ресурса отображается в адресной строке браузера. Версия указана в разделе Сведения на этой странице.

Дополнительные сведения об исправлении webextension см. в документе [MS-OWEXML] 2.2.5. WebExtensionReference.

В примере ниже показано, как добавить часть taskpane.

<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". Это означает, что после добавления частей webextension и taskpane при первом открытии документа пользователю необходимо будет установить надстройку, нажав кнопку Надстройка на ленте. После этого область задач надстройки будет открываться автоматически вместе с файлом. Кроме того, если установить для visibility значение "0", можно с помощью Office.js предоставить пользователям возможность включать и выключать функцию автоматического открытия. В частности, ваш скрипт устанавливает для параметра документа Office.AutoShowTaskpaneWithDocument значение true или false. (Дополнительные сведения см. в разделе Установка отметки для документа на стороне клиента.)

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

Значение "1" отлично подходит для свойства visibility, если надстройка и шаблон или содержимое документа интегрированы настолько тесно, что пользователь не откажется от использования функции автоматического открытия.

Примечание.

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

Простой способ написать XML-код — сначала запустить надстройку и отметить документ на стороне клиента , чтобы записать значение, а затем сохранить документ и проверить созданный XML-код. Office обнаружит и предоставит соответствующие значения атрибутов. Вы также можете использовать средство повышения производительности пакета SDK Open XML для создания кода C#, чтобы программно добавить разметку на основе xml, который вы создаете.

Тестирование и проверка открытия областей задач

Вы можете развернуть тестовую версию надстройки, которая автоматически откроет область задач с помощью централизованного развертывания через Центр администрирования Microsoft 365. В примере ниже показано, как надстройки вставляются в каталог централизованного развертывания при помощи EXCatalog (версии из магазина).

<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>

Вы можете протестировать предыдущий пример, используя подписку Microsoft 365, чтобы опробовать централизованное развертывание и убедиться, что надстройка работает должным образом. Если у вас еще нет подписки на Microsoft 365, вы можете получить право на Microsoft 365 E5 подписку разработчика в рамках программы microsoft 365 для разработчиков. Дополнительные сведения см. в разделе Вопросы и ответы. Кроме того, вы можете зарегистрироваться для получения бесплатной пробной версии на 1 месяц или приобрести план Microsoft 365.

См. также