Руководство по созданию надстройки области задач PowerPoint с помощью Visual Studio

В этом руководстве вы создадите надстройку области задач PowerPoint, которая:

Предварительные условия

• Visual Studio 2019 или более поздней версии с установленной рабочей нагрузкой разработки Office/SharePoint .

  Примечание.

  Если вы уже установили Visual Studio, используйте установщик Visual Studio, чтобы убедиться, что также установлена рабочая нагрузка Разработка надстроек для Office и SharePoint.

• Пакет Office, подключенный к подписке Microsoft 365 (включая Office в Интернете).

  Примечание.

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

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

Выполните указанные ниже действия, чтобы создать проект надстройки PowerPoint с помощью Visual Studio.

1. Выберите Создание нового проекта.

2. Используя поле поиска, введите надстройка. Выберите вариант Веб-надстройка PowerPoint и нажмите кнопку Далее.

3. Назовите проект HelloWorld и нажмите кнопку Создать.

4. В диалоговом окне Создание надстройки Office выберите Добавить новые функции в PowerPoint, а затем нажмите кнопку Готово, чтобы создать проект.

5. Visual Studio создаст решение, и в обозревателе решений появятся два соответствующих проекта. В Visual Studio откроется файл Home.html.

   

6. Необходимо установить следующие пакеты NuGet. Установите их в проекте HelloWorldWeb с помощью диспетчера пакетов NuGet в Visual Studio. Инструкции см. в справке Visual Studio. Второй из этих пакетов может быть установлен автоматически при установке первого.

   • Microsoft.AspNet.WebApi.WebHost
   • Microsoft.AspNet.WebApi.Core

   Важно!

   При использовании диспетчера пакетов NuGet для установки этих пакетов не устанавливайте рекомендуемое обновление для jQuery. Версия jQuery, установленная вместе с решением Visual Studio, соответствует вызову jQuery в файлах решения.

7. Используйте диспетчер пакетов NuGet , чтобы обновить пакет Newtonsoft.Json до версии 13.0.3 или более поздней. Затем удалите файл app.config , если он был добавлен в проект HelloWorld .

Обзор решения Visual Studio

После завершения работы мастера Visual Studio создает решение, которое содержит два проекта.

Обновление кода

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

1. Файл Home.html содержит HTML-контент, который будет отображаться в области задач надстройки. В файле Home.html найдите раздел div с id="content-main", замените весь этот раздел приведенным ниже кодом и сохраните файл.

   <!-- TODO2: Create the content-header div. -->
   <div id="content-main">
       <div class="padding">
           <!-- TODO1: Create the insert-image button. -->
           <!-- TODO3: Create the insert-text button. -->
           <!-- TODO4: Create the get-slide-metadata button. -->
           <!-- TODO5: Create the add-slides and go-to-slide buttons. -->
       </div>
   </div>
   

2. Откройте файл Home.js в корневой папке проекта веб-приложения. Этот файл содержит скрипт надстройки. Замените все его содержимое указанным ниже кодом и сохраните файл.

   (function () {
       "use strict";
   
       let messageBanner;
   
       Office.onReady(function () {
           $(document).ready(function () {
               // Initialize the FabricUI notification mechanism and hide it.
               const element = document.querySelector('.MessageBanner');
               messageBanner = new components.MessageBanner(element);
               messageBanner.hideBanner();
   
               // TODO1: Assign event handler for insert-image button.
               // TODO4: Assign event handler for insert-text button.
               // TODO6: Assign event handler for get-slide-metadata button.
               // TODO8: Assign event handlers for add-slides and the four navigation buttons.
           });
       });
   
       // TODO2: Define the insertImage function.
   
       // TODO3: Define the insertImageFromBase64String function.
   
       // TODO5: Define the insertText function.
   
       // TODO7: Define the getSlideMetadata function.
   
       // TODO9: Define the addSlides and navigation functions.
   
       // Helper function for displaying notifications.
       function showNotification(header, content) {
           $("#notification-header").text(header);
           $("#notification-body").text(content);
           messageBanner.showBanner();
           messageBanner.toggleExpansion();
       }
   })();
   

Вставка изображения

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

1. Используя обозреватель решений, добавьте новую папку Controllers в проект HelloWorldWeb.

   

2. Щелкните правой кнопкой мыши (или выберите и удерживайте ) папку Контроллеры и выберите Добавить>новый шаблонный элемент....

3. В диалоговом окне Добавление шаблона выберите Контроллер Web API 2 — пустой и нажмите кнопку Добавить.

4. В диалоговом окне Добавление контроллера введите имя PhotoController и нажмите кнопку Добавить. Visual Studio создаст и откроет файл PhotoController.cs.

   Важно!

   Процесс формирования шаблонов завершается неправильно в некоторых версиях Visual Studio после версии 16.10.3. Если у вас есть файлы Global.asax и ./App_Start/WebApiConfig.cs , перейдите к шагу 6.

   

5. Если в проекте HelloWorldWeb отсутствуют файлы формирования шаблонов, добавьте их следующим образом.

   1. С помощью Обозреватель решений добавьте новую папку с именем App_Start в проект HelloWorldWeb.

   2. Щелкните правой кнопкой мыши (или выберите и удерживайте) папку App_Start и выберите Добавить>класс....

   3. В диалоговом окне Добавление нового элемента присвойте файлу имя WebApiConfig.cs затем нажмите кнопку Добавить .

   4. Замените все содержимое файла WebApiConfig.cs следующим кодом.

      using System;
      using System.Collections.Generic;
      using System.Linq;
      using System.Web;
      using System.Web.Http;
      
      namespace HelloWorldWeb.App_Start
      {
          public static class WebApiConfig
          {
              public static void Register(HttpConfiguration config)
              {
                  config.MapHttpAttributeRoutes();
      
                  config.Routes.MapHttpRoute(
                      name: "DefaultApi",
                      routeTemplate: "api/{controller}/{id}",
                      defaults: new { id = RouteParameter.Optional }
                  );
              }
          }
      }
      

   5. В Обозреватель решений щелкните правой кнопкой мыши (или выберите и удерживайте) проект HelloWorldWeb и выберите Добавить>новый элемент....

   6. В диалоговом окне Добавление нового элемента найдите "global", выберите Глобальный класс приложения, а затем нажмите кнопку Добавить . По умолчанию файл называется Global.asax.

   7. Замените все содержимое файла Global.asax.cs следующим кодом.

      using HelloWorldWeb.App_Start;
      using System;
      using System.Collections.Generic;
      using System.Linq;
      using System.Web;
      using System.Web.Http;
      using System.Web.Security;
      using System.Web.SessionState;
      
      namespace HelloWorldWeb
      {
          public class WebApiApplication : System.Web.HttpApplication
          {
              protected void Application_Start()
              {
                  GlobalConfiguration.Configure(WebApiConfig.Register);
              }
          }
      }
      

   8. В Обозреватель решений щелкните правой кнопкой мыши (или выберите и удерживайте) файл Global.asax и выберите пункт Просмотреть разметку.

   9. Замените все содержимое файла Global.asax следующим кодом.

      <%@ Application Codebehind="Global.asax.cs" Inherits="HelloWorldWeb.WebApiApplication" Language="C#" %>
      

6. Замените все содержимое файла PhotoController.cs следующим кодом, который вызывает службу Bing для получения фотографии дня в виде строки в кодировке Base64. При использовании API JavaScript для Office для вставки изображения в документ данные изображения должны быть указаны в виде строки в кодировке Base64.

   using System;
   using System.IO;
   using System.Net;
   using System.Text;
   using System.Web.Http;
   using System.Xml;
   
   namespace HelloWorldWeb.Controllers
   {
       public class PhotoController : ApiController
       {
           public string Get()
           {
               string url = "http://www.bing.com/HPImageArchive.aspx?format=xml&idx=0&n=1";
   
               // Create the request.
               HttpWebRequest request = (HttpWebRequest)WebRequest.Create(url);
               WebResponse response = request.GetResponse();
   
               using (Stream responseStream = response.GetResponseStream())
               {
                   // Process the result.
                   StreamReader reader = new StreamReader(responseStream, Encoding.UTF8);
                   string result = reader.ReadToEnd();
   
                   // Parse the XML response and get the URL.
                   XmlDocument doc = new XmlDocument();
                   doc.LoadXml(result);
                   string photoURL = "http://bing.com" + doc.SelectSingleNode("/images/image/url").InnerText;
   
                   // Fetch the photo and return it as a Base64-encoded string.
                   return getPhotoFromURL(photoURL);
               }
           }
   
           private string getPhotoFromURL(string imageURL)
           {
               var webClient = new WebClient();
               byte[] imageBytes = webClient.DownloadData(imageURL);
               return Convert.ToBase64String(imageBytes);
           }
       }
   }
   

7. В файле Home.html замените TODO1 приведенным ниже кодом. Этот код определяет кнопку Insert Image (Вставить изображение), которая появится в области задач надстройки.

   <button class="Button Button--primary" id="insert-image">
       <span class="Button-icon"><i class="ms-Icon ms-Icon--plus"></i></span>
       <span class="Button-label">Insert Image</span>
       <span class="Button-description">Gets the photo of the day that shows on the Bing home page and adds it to the slide.</span>
   </button>
   

8. В файле Home.js замените TODO1 приведенным ниже кодом, чтобы назначить обработчик событий для кнопки Insert Image (Вставить изображение).

   $('#insert-image').on("click", insertImage);
   

9. В файле Home.js замените TODO2 приведенным ниже кодом, чтобы определить функцию insertImage. Эта функция извлекает изображение из веб-службы Bing, а затем вызывает функцию insertImageFromBase64String, чтобы вставить его в документ.

   function insertImage() {
       // Get image from web service (as a Base64-encoded string).
       $.ajax({
           url: "/api/photo/",
           dataType: "text",
           success: function (result) {
               insertImageFromBase64String(result);
           }, error: function (xhr, status, error) {
               showNotification("Error", "Oops, something went wrong.");
           }
       });
   }
   

10. В файле Home.js замените TODO3 приведенным ниже кодом, чтобы определить функцию insertImageFromBase64String. Эта функция использует API JavaScript для Office, чтобы вставить изображение в документ. Примечание.

    • coercionType, второй параметр запроса setSelectedDataAsync, определяет тип вставляемых данных.

    • Объект asyncResult инкапсулирует результат запроса setSelectedDataAsync, включая сведения о состоянии и ошибке, если запрос завершился ошибкой.

    function insertImageFromBase64String(image) {
        // Call Office.js to insert the image into the document.
        Office.context.document.setSelectedDataAsync(image, {
            coercionType: Office.CoercionType.Image
        },
            function (asyncResult) {
                if (asyncResult.status === Office.AsyncResultStatus.Failed) {
                    showNotification("Error", asyncResult.error.message);
                }
            });
    }
    

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

1. С помощью Visual Studio протестируйте созданную надстройку PowerPoint, нажав клавишу F5 или нажав кнопку Пуск , чтобы запустить PowerPoint с кнопкой Показать область задач на ленте. Надстройка будет размещена на локальном сервере IIS.

   

2. Если область задач надстройки еще не открыта в PowerPoint, нажмите кнопку Показать область задач на ленте, чтобы открыть ее.

   

3. В области задач нажмите кнопку Insert Image (Вставить изображение), чтобы добавить фотографию дня Bing на текущий слайд.

   

   Примечание.

   Если появляется сообщение об ошибке "Не удалось найти файл [...]\bin\roslyn\csc.exe", а затем сделайте следующее:

   1. Откройте \Web.config-файл .
   2. Найдите узел компилятора<> для .cs extension, а затем удалите type атрибут и его значение.
   3. Сохраните файл.

4. В Visual Studio остановите надстройку, нажав клавиши SHIFT+F5 или нажав кнопку Остановить . PowerPoint автоматически закроется при остановке надстройки.

   

Настройка элементов пользовательского интерфейса

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

1. В файле Home.html замените TODO2 приведенным ниже кодом, чтобы добавить раздел верхнего колонтитула и заголовок в область задач. Примечание.

   • Стили, названия которых начинаются с ms-, определены в Fabric Core для надстроек Office — интерфейсной платформе JavaScript для создания пользовательских интерфейсов для Office. Файл Home.html включает ссылку на таблицу стилей Fabric Core.

   <div id="content-header">
       <div class="ms-Grid ms-bgColor-neutralPrimary">
           <div class="ms-Grid-row">
               <div class="padding ms-Grid-col ms-u-sm12 ms-u-md12 ms-u-lg12"> <div class="ms-font-xl ms-fontColor-white ms-fontWeight-semibold">My PowerPoint add-in</div></div>
           </div>
       </div>
   </div>
   

2. В файле Home.html найдите раздел div с class="footer" и удалите весь раздел div, чтобы удалить раздел нижнего колонтитула из области задач.

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

1. В Visual Studio протестируйте надстройку PowerPoint, нажав клавишу F5 или нажав кнопку Пуск , чтобы запустить PowerPoint с кнопкой Показать область задач на ленте. Надстройка будет размещена на локальном сервере IIS.

   

2. Если область задач надстройки еще не открыта в PowerPoint, нажмите кнопку Показать область задач на ленте, чтобы открыть ее.

   

3. Обратите внимание на то, что область задач теперь содержит раздел верхнего колонтитула и заголовок и больше не содержит раздел нижнего колонтитула.

   

4. В Visual Studio остановите надстройку, нажав клавиши SHIFT+F5 или нажав кнопку Остановить . PowerPoint автоматически закроется при остановке надстройки.

   

Вставка текста

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

1. В файле Home.html замените TODO3 приведенным ниже кодом. Этот код определяет кнопку Insert Text (Вставить текст), которая появится в области задач надстройки.

       <br /><br />
       <button class="Button Button--primary" id="insert-text">
           <span class="Button-icon"><i class="ms-Icon ms-Icon--plus"></i></span>
           <span class="Button-label">Insert Text</span>
           <span class="Button-description">Inserts text into the slide.</span>
       </button>
   

2. В файле Home.js замените TODO4 приведенным ниже кодом, чтобы назначить обработчик событий для кнопки Insert Text (Вставить текст).

   $('#insert-text').on("click", insertText);
   

3. В файле Home.js замените TODO5 приведенным ниже кодом, чтобы определить функцию insertText. Эта функция вставляет текст в текущий слайд.

   function insertText() {
       Office.context.document.setSelectedDataAsync('Hello World!',
           function (asyncResult) {
               if (asyncResult.status === Office.AsyncResultStatus.Failed) {
                   showNotification("Error", asyncResult.error.message);
               }
           });
   }
   

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

1. В Visual Studio протестируйте надстройку, нажав клавишу F5 или нажав кнопку Пуск , чтобы запустить PowerPoint с кнопкой Показать область задач на ленте. Надстройка будет размещена на локальном сервере IIS.

   

2. Если область задач надстройки еще не открыта в PowerPoint, нажмите кнопку Показать область задач на ленте, чтобы открыть ее.

   

3. В области задач нажмите кнопку Insert Image (Вставить изображение), чтобы добавить фотографию дня Bing на текущий слайд, и выберите макет слайда с текстовым полем для заголовка.

   

4. Установите курсор в текстовом поле на заглавном слайде и нажмите кнопку Insert Text (Вставить текст) в области задач, чтобы добавить текст.

   

5. В Visual Studio остановите надстройку, нажав клавиши SHIFT+F5 или нажав кнопку Остановить . PowerPoint автоматически закроется при остановке надстройки.

   

Получение метаданных слайда

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

1. В файле Home.html замените TODO4 приведенным ниже кодом. Этот код определяет кнопку Get Slide Metadata (Получить метаданные слайда), которая появится в области задач надстройки.

   <br /><br />
   <button class="Button Button--primary" id="get-slide-metadata">
       <span class="Button-icon"><i class="ms-Icon ms-Icon--plus"></i></span>
       <span class="Button-label">Get Slide Metadata</span>
       <span class="Button-description">Gets metadata for the selected slides.</span>
   </button>
   

2. В файле Home.js замените TODO6 приведенным ниже кодом, чтобы назначить обработчик событий для кнопки Get Slide Metadata (Получить метаданные слайда).

   $('#get-slide-metadata').on("click", getSlideMetadata);
   

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

   function getSlideMetadata() {
       Office.context.document.getSelectedDataAsync(Office.CoercionType.SlideRange,
           function (asyncResult) {
               if (asyncResult.status === Office.AsyncResultStatus.Failed) {
                   showNotification("Error", asyncResult.error.message);
               } else {
                   showNotification("Metadata for selected slides:", JSON.stringify(asyncResult.value), null, 2);
               }
           }
       );
   }
   

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

1. В Visual Studio протестируйте надстройку, нажав клавишу F5 или нажав кнопку Пуск , чтобы запустить PowerPoint с кнопкой Показать область задач на ленте. Надстройка будет размещена на локальном сервере IIS.

   

2. Если область задач надстройки еще не открыта в PowerPoint, нажмите кнопку Показать область задач на ленте, чтобы открыть ее.

   

3. В области задач нажмите кнопку Get Slide Metadata (Получить метаданные слайда), чтобы получить метаданные выбранного слайда. Метаданные слайда записываются во всплывающее диалоговое окно в нижней части области задач. В этом случае массив slides в метаданных JSON содержит один объект, в котором указаны свойства id, title и index выбранного слайда. Если при извлечении метаданных будет выбрано несколько слайдов, массив slides в метаданных JSON будет содержать один объект для каждого выбранного слайда.

   

4. В Visual Studio остановите надстройку, нажав клавиши SHIFT+F5 или нажав кнопку Остановить . PowerPoint автоматически закроется при остановке надстройки.

   

Переход между слайдами

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

1. В файле Home.html замените TODO5 приведенным ниже кодом. Этот код определяет четыре кнопки навигации, которые появятся в области задач надстройки.

   <br /><br />
   <button class="Button Button--primary" id="add-slides">
       <span class="Button-icon"><i class="ms-Icon ms-Icon--plus"></i></span>
       <span class="Button-label">Add Slides</span>
       <span class="Button-description">Adds 2 slides.</span>
   </button>
   <br /><br />
   <button class="Button Button--primary" id="go-to-first-slide">
       <span class="Button-icon"><i class="ms-Icon ms-Icon--plus"></i></span>
       <span class="Button-label">Go to First Slide</span>
       <span class="Button-description">Go to the first slide.</span>
   </button>
   <br /><br />
   <button class="Button Button--primary" id="go-to-next-slide">
       <span class="Button-icon"><i class="ms-Icon ms-Icon--plus"></i></span>
       <span class="Button-label">Go to Next Slide</span>
       <span class="Button-description">Go to the next slide.</span>
   </button>
   <br /><br />
   <button class="Button Button--primary" id="go-to-previous-slide">
       <span class="Button-icon"><i class="ms-Icon ms-Icon--plus"></i></span>
       <span class="Button-label">Go to Previous Slide</span>
       <span class="Button-description">Go to the previous slide.</span>
   </button>
   <br /><br />
   <button class="Button Button--primary" id="go-to-last-slide">
       <span class="Button-icon"><i class="ms-Icon ms-Icon--plus"></i></span>
       <span class="Button-label">Go to Last Slide</span>
       <span class="Button-description">Go to the last slide.</span>
   </button>
   

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

   $('#add-slides').on("click", addSlides);
   $('#go-to-first-slide').on("click", goToFirstSlide);
   $('#go-to-next-slide').on("click", goToNextSlide);
   $('#go-to-previous-slide').on("click", goToPreviousSlide);
   $('#go-to-last-slide').on("click", goToLastSlide);
   

3. В файлеHome.js замените TODO9 приведенным ниже кодом, чтобы определить функции навигации addSlides и . Каждая из этих функций использует метод goToByIdAsync для выбора слайда с учетом его позиции в документе (первый, последний, предыдущий, следующий).

   async function addSlides() {
       await PowerPoint.run(async function (context) {
           context.presentation.slides.add();
           context.presentation.slides.add();
   
           await context.sync();
   
           showNotification("Success", "Slides added.");
           goToLastSlide();
       });
   }
   
   function goToFirstSlide() {
       Office.context.document.goToByIdAsync(Office.Index.First, Office.GoToType.Index,
           function (asyncResult) {
               if (asyncResult.status == "failed") {
                   showNotification("Error", asyncResult.error.message);
               }
           });
   }
   
   function goToLastSlide() {
       Office.context.document.goToByIdAsync(Office.Index.Last, Office.GoToType.Index,
           function (asyncResult) {
               if (asyncResult.status == "failed") {
                   showNotification("Error", asyncResult.error.message);
               }
           });
   }
   
   function goToPreviousSlide() {
       Office.context.document.goToByIdAsync(Office.Index.Previous, Office.GoToType.Index,
           function (asyncResult) {
               if (asyncResult.status == "failed") {
                   showNotification("Error", asyncResult.error.message);
               }
           });
   }
   
   function goToNextSlide() {
       Office.context.document.goToByIdAsync(Office.Index.Next, Office.GoToType.Index,
           function (asyncResult) {
               if (asyncResult.status == "failed") {
                   showNotification("Error", asyncResult.error.message);
               }
           });
   }
   

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

1. В Visual Studio протестируйте надстройку, нажав клавишу F5 или нажав кнопку Пуск , чтобы запустить PowerPoint с кнопкой Показать область задач на ленте. Надстройка будет размещена на локальном сервере IIS.

   

2. Если область задач надстройки еще не открыта в PowerPoint, нажмите кнопку Показать область задач на ленте, чтобы открыть ее.

   

3. В области задач нажмите кнопку Добавить слайды . В документ добавляются два новых слайда, а последний слайд в документе выбирается и отображается.

   

4. В области задач нажмите кнопку Go to First Slide (Перейти к первому слайду). Будет выбран и показан первый слайд в документе.

   

5. В области задач нажмите кнопку Go to Next Slide (Перейти к следующему слайду). Будет выбран и показан следующий слайд в документе.

   

6. В области задач нажмите кнопку Go to Previous Slide (Перейти к предыдущему слайду). Будет выбран и показан предыдущий слайд в документе.

   

7. В области задач нажмите кнопку Go to Last Slide (Перейти к последнему слайду). Будет выбран и показан последний слайд в документе.

   

8. В Visual Studio остановите надстройку, нажав клавиши SHIFT+F5 или нажав кнопку Остановить . PowerPoint автоматически закроется при остановке надстройки.

   

Примеры кода

• Руководство по надстройкам PowerPoint. Результат работы с этим руководством.

Дальнейшие действия

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

См. также

• Обзор платформы надстроек Office
• Разработка надстроек Office