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

Реализация активации на основе событий в надстройках Excel, PowerPoint и Word

Активация на основе событий автоматически запускает централизованно развернутую надстройку Word, Excel или PowerPoint при создании или открытии документа. Это позволяет надстройке проверять, вставлять или обновлять критически важное содержимое без каких-либо операций вручную. Надстройка открывается в фоновом режиме, чтобы избежать нарушения работы пользователя.

Примечание.

Сведения о том, как реализовать активацию на основе событий для надстроек Outlook, см. в статье Настройка надстройки Outlook для активации на основе событий.

Поддерживаемые события и клиенты

Имя события Описание Поддерживаемые клиенты и каналы
OnDocumentOpened Происходит, когда пользователь открывает документ или создает новый документ, электронную таблицу или презентацию.
  • Windows (сборка >= 16.0.18324.20032)
  • Office в Интернете
  • Office на Mac будет доступен позже

Поведение и ограничения

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

  • Office на Mac не поддерживается.
  • Унифицированный манифест не поддерживается.
  • Надстройки на основе событий работают только при развертывании администратором. Если пользователи устанавливают их непосредственно из AppSource или Магазина Office, они не запускаются автоматически. Администратор развертывания выполняются путем отправки манифеста в Центр администрирования Microsoft 365.
  • Если пользователь устанавливает несколько надстроек, обрабатывающих одно и то же событие активации, будет активирована только одна надстройка. Детерминированного способа узнать, какая надстройка будет активирована, не существует. Например, если несколько надстроек, обрабатывающих OnDocumentOpened, будет запущен только один из этих обработчиков.
  • ИНТЕРФЕЙСы API, взаимодействующие с пользовательским интерфейсом или отображаемыми элементами пользовательского интерфейса, не поддерживаются для Word, PowerPoint и Excel в Windows. Это связано с тем, что обработчик событий выполняется в среде выполнения, доступной только для JavaScript. Дополнительные сведения см. в разделе Среды выполнения в надстройках Office.

Пошаговое руководство. Автоматическое действие при открытии документа

В следующих разделах показано, как разработать надстройку Word, которая автоматически изменяет заголовок документа при открытии нового или существующего документа. Хотя этот конкретный пример предназначен для Word, конфигурация манифеста одинакова для Excel и PowerPoint.

Важно!

Для этого примера требуется подписка Microsoft 365 с поддерживаемой версией Word.

Создание надстройки

Создайте надстройку, выполнив Word краткое руководство. Вы получите рабочую надстройку Office, в которую можно добавить код активации на основе событий.

Настройка манифеста

Чтобы включить надстройку на основе событий, необходимо настроить следующие элементы в VersionOverridesV1_0 узле манифеста.

  • В элементе Runtimes создайте новый элемент Override для среды выполнения. Переопределите тип javascript и сослаться на файл JavaScript, содержащий функцию, которую нужно активировать с событием.
  • В элементе DesktopFormFactor добавьте элемент FunctionFile для файла JavaScript с обработчиком событий.
  • В элементе ExtensionPoint задайте для xsi:typeLaunchEvent. Это включает функцию активации на основе событий в надстройке.
  • В элементе LaunchEvent задайте для TypeOnDocumentOpened и укажите имя функции JavaScript обработчика событий в атрибуте FunctionName .

Используйте следующий пример кода манифеста, чтобы обновить проект.

  1. В редакторе кода откройте созданный проект быстрого запуска.

  2. Откройте файлmanifest.xml , расположенный в корне проекта.

  3. Выберите весь <узел VersionOverrides> (включая открытые и закрытые теги) и замените его следующим XML-кодом.

      <VersionOverrides xmlns="http://schemas.microsoft.com/office/taskpaneappversionoverrides" xsi:type="VersionOverridesV1_0">
    <Hosts>
      <Host xsi:type="Document">
        <Runtimes>
          <Runtime resid="Taskpane.Url" lifetime="long" />
          <Runtime resid="WebViewRuntime.Url">
            <Override type="javascript" resid="JsRuntimeWord.Url"/>
          </Runtime>
        </Runtimes>
        <DesktopFormFactor>
          <GetStarted>
            <Title resid="GetStarted.Title"/>
            <Description resid="GetStarted.Description"/>
            <LearnMoreUrl resid="GetStarted.LearnMoreUrl"/>
          </GetStarted>
          <FunctionFile resid="Commands.Url"/>
          <ExtensionPoint xsi:type="LaunchEvent">
            <LaunchEvents>
              <LaunchEvent Type="OnDocumentOpened" FunctionName="changeHeader"></LaunchEvent>
            </LaunchEvents>
            <SourceLocation resid="WebViewRuntime.Url"/>
          </ExtensionPoint>
          <ExtensionPoint xsi:type="PrimaryCommandSurface">
            <OfficeTab id="TabHome">
              <Group id="CommandsGroup">
                <Label resid="CommandsGroup.Label"/>
                <Icon>
                  <bt:Image size="16" resid="Icon.16x16"/>
                  <bt:Image size="32" resid="Icon.32x32"/>
                  <bt:Image size="80" resid="Icon.80x80"/>
                </Icon>
                <Control xsi:type="Button" id="TaskpaneButton">
                  <Label resid="TaskpaneButton.Label"/>
                  <Supertip>
                    <Title resid="TaskpaneButton.Label"/>
                    <Description resid="TaskpaneButton.Tooltip"/>
                  </Supertip>
                  <Icon>
                    <bt:Image size="16" resid="Icon.16x16"/>
                    <bt:Image size="32" resid="Icon.32x32"/>
                    <bt:Image size="80" resid="Icon.80x80"/>
                  </Icon>
                  <Action xsi:type="ShowTaskpane">
                    <TaskpaneId>ButtonId1</TaskpaneId>
                    <SourceLocation resid="Taskpane.Url"/>
                  </Action>
                </Control>
              </Group>
            </OfficeTab>
          </ExtensionPoint>
        </DesktopFormFactor>
      </Host>
    </Hosts>
    <Resources>
      <bt:Images>
        <bt:Image id="Icon.16x16" DefaultValue="https://localhost:3000/assets/icon-16.png"/>
        <bt:Image id="Icon.32x32" DefaultValue="https://localhost:3000/assets/icon-32.png"/>
        <bt:Image id="Icon.80x80" DefaultValue="https://localhost:3000/assets/icon-80.png"/>
      </bt:Images>
      <bt:Urls>
        <bt:Url id="GetStarted.LearnMoreUrl" DefaultValue="https://go.microsoft.com/fwlink/?LinkId=276812"/>
        <bt:Url id="Commands.Url" DefaultValue="https://localhost:3000/commands.html"/>
        <bt:Url id="Taskpane.Url" DefaultValue="https://localhost:3000/taskpane.html"/>
        <bt:Url id="WebViewRuntime.Url" DefaultValue="https://localhost:3000/commands.html"/>
        <bt:Url id="JsRuntimeWord.Url" DefaultValue="https://localhost:3000/commands.js"/>
      </bt:Urls>
      <bt:ShortStrings>
        <bt:String id="GetStarted.Title" DefaultValue="Get started with your sample add-in!"/>
        <bt:String id="CommandsGroup.Label" DefaultValue="Event-based add-in activation"/>
        <bt:String id="TaskpaneButton.Label" DefaultValue="My add-in"/>
      </bt:ShortStrings>
      <bt:LongStrings>
        <bt:String id="GetStarted.Description" DefaultValue="Your sample add-in loaded successfully. Go to the HOME tab and click the 'Show Task Pane' button to get started."/>
        <bt:String id="TaskpaneButton.Tooltip" DefaultValue="Click to show the task pane"/>
      </bt:LongStrings>
    </Resources>
  </VersionOverrides>

  4. Сохраните изменения.

Реализация обработчика событий

Чтобы надстройка могла действовать при возникновении OnDocumentOpened события, необходимо реализовать обработчик событий JavaScript. В этом разделе вы создадите changeHeader функцию, которая добавляет заголовок "Public" в новые документы или заголовок "Строго конфиденциальный" в существующие документы, у которых уже есть содержимое.

  1. В папке ./src/commands откройте файл с именемcommands.js.

  2. Замените все содержимое commands.js следующим кодом JavaScript.

      /*
  * Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
  * See LICENSE in the project root for license information.
  */
  /* global global, Office, self, window */

  Office.onReady(() => {
    // If needed, Office.js is ready to be called
  });

  async function changeHeader(event) {
    Word.run(async (context) => {
      const body = context.document.body;
      body.load("text");
      await context.sync();

      if (body.text.length == 0) {
      // For new or empty documents, make a "Public" header. 
        const header = context.document.sections.getFirst().getHeader(Word.HeaderFooterType.primary);
        const firstPageHeader = context.document.sections.getFirst().getHeader(Word.HeaderFooterType.firstPage);
        header.clear();
        firstPageHeader.clear();

        header.insertParagraph("Public - The data is for the public and shareable externally", "Start");
        firstPageHeader.insertParagraph("Public - The data is for the public and shareable externally", "Start");
        header.font.color = "#07641d";
        firstPageHeader.font.color = "#07641d";
        await context.sync();
      } else {
        // For existing documents, make a "Highly Confidential" header.
        const header = context.document.sections.getFirst().getHeader(Word.HeaderFooterType.primary);
        const firstPageHeader = context.document.sections.getFirst().getHeader(Word.HeaderFooterType.firstPage);
        header.clear();
        firstPageHeader.clear();
        header.insertParagraph("Highly Confidential - The data must be secret or in some way highly critical", "Start");
        firstPageHeader.insertParagraph("Highly Confidential - The data must be secret or in some way highly critical", "Start");
        header.font.color = "#f8334d";
        firstPageHeader.font.color = "#f8334d";
        await context.sync();
      }
    });

    // Calling event.completed is required. event.completed lets the platform know that processing has completed.
    event.completed();
  }

  async function paragraphChanged() {
    await Word.run(async (context) => {
      const results = context.document.body.search("110");
      results.load("length");
      await context.sync();
      if (results.items.length == 0) {
        const header = context.document.sections.getFirst().getHeader(Word.HeaderFooterType.primary);
        header.clear();
        header.insertParagraph("Public - The data is for the public and shareable externally", "Start");
        const font = header.font;
        font.color = "#07641d";

        await context.sync();
      } else {
        const header = context.document.sections.getFirst().getHeader(Word.HeaderFooterType.primary);
        header.clear();
        header.insertParagraph("Highly Confidential - The data must be secret or in some way highly critical", "Start");
        const font = header.font;
        font.color = "#f8334d";

        await context.sync();
      }
    });
  }

  async function registerOnParagraphChanged(event) {
    Word.run(async (context) => {
      let eventContext = context.document.onParagraphChanged.add(paragraphChanged);
      await context.sync();
    });
    // Calling event.completed is required. event.completed lets the platform know that processing has completed.
    event.completed();
  }


  Office.actions.associate("changeHeader", changeHeader);
  Office.actions.associate("registerOnParagraphChanged", registerOnParagraphChanged);

  3. Сохраните изменения.

Тестирование и проверка надстройки

  1. Запустите npm start , чтобы создать проект и запустить веб-сервер. Игнорируйте открытый документ Word.
  2. Вручную загрузите неопубликованные Word надстройки в Интернете, следуя инструкциям в разделе Загрузка неопубликованных надстроек Office для Office в Интернете. Используйте manifest.xml в корне проекта.
  3. Попробуйте открыть как новые, так и существующие документы Word в Word в Интернете. Заголовки должны автоматически добавляться при открытии.

Развертывание надстройки

Надстройки на основе событий работают только при развертывании администратором. Если пользователи устанавливают их непосредственно из AppSource или Магазина Office, они не запускаются автоматически. Чтобы выполнить развертывание администратора, отправьте манифест в Центр администрирования Microsoft 365, выполнив следующие действия.

  1. На портале администрирования разверните раздел Параметры в области навигации и выберите Интегрированные приложения.
  2. На странице Интегрированные приложения выберите действие Отправить пользовательские приложения .

Дополнительные сведения о развертывании надстройки см. в статье Развертывание и публикация надстроек Office в Центр администрирования Microsoft 365.