Надстройки PowerPointPowerPoint add-ins

С помощью надстроек PowerPoint можно создавать удобные решения, подходящие для использования в презентациях на различных платформах, таких как Windows, iOS, Mac и браузеры.You can use PowerPoint add-ins to build engaging solutions for your users' presentations across platforms including Windows, iOS, Office Online, and Mac. Можно создать два типа надстроек PowerPoint:You can create two types of PowerPoint add-ins:

  • Контентные надстройки позволяют добавлять динамический контент HTML5 в презентации. Например, ознакомьтесь с надстройкой LucidChart Diagrams for PowerPoint, с помощью которой можно добавить интерактивные схемы LucidChart в набор слайдов.Use content add-ins to add dynamic HTML5 content to your presentations. For example, see the LucidChart Diagrams for PowerPoint add-in, which you can use to inject an interactive diagram from LucidChart into your deck.

  • Надстройки области задач позволяют добавлять справочные сведения или данные в презентацию с помощью службы.Use task pane add-ins to bring in reference information or insert data into the presentation via a service. Например, используя надстройку Pixton Comic Characters, вы можете вставить профессиональные фотографии в свою презентацию.For example, see the Pixton Comic Characters add-in, which you can use to add professional photos to your presentation.

Сценарии надстроек PowerPointPowerPoint add-in scenarios

В приведенных в этой статье примерах кода показаны основные задачи по разработке надстроек для PowerPoint.The code examples in this article demonstrate some basic tasks for developing add-ins for PowerPoint. Обратите внимание на следующее:Please note the following:

  • При отображении сведений эти примеры используют функцию app.showNotification, включенную в шаблоны проектов надстроек Office в Visual Studio.To display information, these examples use the app.showNotification function, which is included in the Visual Studio Office Add-ins project templates. Если для разработки надстройки вы не используете Visual Studio, замените функцию showNotification собственным кодом.If you aren't using Visual Studio to develop your add-in, you'll need replace the showNotification function with your own code.

  • Некоторые из этих примеров также используют объект Globals, объявленный за пределами указанных функций как var Globals = {activeViewHandler:0, firstSlideId:0};.Several of these examples also use a Globals object that is declared beyond the scope of these functions as: var Globals = {activeViewHandler:0, firstSlideId:0};

  • Для использования этих примеров необходимо, чтобы проект надстройки ссылался на библиотеку Office.js 1.1 или более поздней версии.To use these examples, your add-in project must reference Office.js v1.1 library or later.

Определение активного представления презентации и обработка события ActiveViewChangedDetect the presentation's active view and handle the ActiveViewChanged event

При создании контентной надстройки вам понадобится получить активное представление презентации, а также обработать событие ActiveViewChanged в рамках обработчика событий Office.Initialize.If you are building a content add-in, you will need to get the presentation's active view and handle the ActiveViewChanged event, as part of your Office.Initialize handler.

Примечание

В PowerPoint в Интернете не удастся запустить событие Document.ActiveViewChanged, поскольку режим показа слайдов обрабатывается как новый сеанс.In PowerPoint Online, the Document.ActiveViewChanged event will never fire as Slide Show mode is treated as a new session. В этом случае надстройке необходимо получить активное представление по загрузке, как показано в примере кода ниже.In this case, the add-in must fetch the active view on load, as shown in the following code sample.

В представленном ниже примере кода:In the following code sample:

  • Функция getActiveFileView вызывает метод Document.getActiveViewAsync, который возвращает текущее представление презентации: "edit" (представления, в которых можно редактировать слайды, например Обычный режим или Режим структуры) или "read" (Показ слайдов или Режим чтения).The getActiveFileView function calls the Document.getActiveViewAsync method to return whether the presentation's current view is "edit" (any of the views in which you can edit slides, such as Normal or Outline View) or "read" (Slide Show or Reading View).

  • Функция registerActiveViewChanged вызывает метод addHandlerAsync для регистрации обработчика для события Document.ActiveViewChanged.The registerActiveViewChanged function calls the addHandlerAsync method to register a handler for the Document.ActiveViewChanged event.

//general Office.initialize function. Fires on load of the add-in.
Office.initialize = function(){

    //Gets whether the current view is edit or read.
    var currentView = getActiveFileView();

    //register for the active view changed handler
    registerActiveViewChanged();

    //render the content based off of the currentView
    //....
}

function getActiveFileView()
{
    Office.context.document.getActiveViewAsync(function (asyncResult) {
        if (asyncResult.status == "failed") {
            app.showNotification("Action failed with error: " + asyncResult.error.message);
        }
        else {
            app.showNotification(asyncResult.value);
        }
    });

}

function registerActiveViewChanged() {
    Globals.activeViewHandler = function (args) {
        app.showNotification(JSON.stringify(args));
    }

    Office.context.document.addHandlerAsync(Office.EventType.ActiveViewChanged, Globals.activeViewHandler,
        function (asyncResult) {
            if (asyncResult.status == "failed") {
                app.showNotification("Action failed with error: " + asyncResult.error.message);
            }
            else {
                app.showNotification(asyncResult.status);
            }
        });
}

В приведенном ниже примере кода функция getSelectedRange вызывает метод Document.getSelectedDataAsync, чтобы получить возвращаемый свойством asyncResult.value объект JSON, содержащий массив с именем slides.In the following code sample, the getSelectedRange function calls the Document.getSelectedDataAsync method to get the JSON object returned by asyncResult.value, which contains an array named slides. Массив slides содержит идентификаторы, заголовки и индексы выбранного диапазона слайдов (или текущего слайда, если не выбрано несколько слайдов).The slides array contains the ids, titles, and indexes of selected range of slides (or of the current slide, if multiple slides are not selected). Кроме того, он сохраняет идентификатор первого слайда в выбранном диапазоне в глобальной переменной.It also saves the id of the first slide in the selected range to a global variable.

function getSelectedRange() {
    // Get the id, title, and index of the current slide (or selected slides) and store the first slide id */
    Globals.firstSlideId = 0;

    Office.context.document.getSelectedDataAsync(Office.CoercionType.SlideRange, function (asyncResult) {
        if (asyncResult.status == "failed") {
            app.showNotification("Action failed with error: " + asyncResult.error.message);
        }
        else {
            Globals.firstSlideId = asyncResult.value.slides[0].id;
            app.showNotification(JSON.stringify(asyncResult.value));
        }
    });
}

В приведенном ниже примере кода функция goToFirstSlide вызывает метод Document.goToByIdAsync для перехода к первому слайду, который был определен показанной ранее функцией getSelectedRange.In the following code sample, the goToFirstSlide function calls the Document.goToByIdAsync method to navigate to the first slide that was identified by the getSelectedRange function shown previously.

function goToFirstSlide() {
    Office.context.document.goToByIdAsync(Globals.firstSlideId, Office.GoToType.Slide, function (asyncResult) {
        if (asyncResult.status == "failed") {
            app.showNotification("Action failed with error: " + asyncResult.error.message);
        }
        else {
            app.showNotification("Navigation successful");
        }
    });
}

В приведенном ниже примере кода функция goToSlideByIndex вызывает метод Document.goToByIdAsync для перехода к следующему слайду в презентации.In the following code sample, the goToSlideByIndex function calls the Document.goToByIdAsync method to navigate to the next slide in the presentation.

function goToSlideByIndex() {
    var goToFirst = Office.Index.First;
    var goToLast = Office.Index.Last;
    var goToPrevious = Office.Index.Previous;
    var goToNext = Office.Index.Next;

    Office.context.document.goToByIdAsync(goToNext, Office.GoToType.Index, function (asyncResult) {
        if (asyncResult.status == "failed") {
            app.showNotification("Action failed with error: " + asyncResult.error.message);
        }
        else {
            app.showNotification("Navigation successful");
        }
    });
}

Получение URL-адреса презентацииGet the URL of the presentation

В приведенном ниже примере кода функция getFileUrl вызывает метод Document.getFileProperties, чтобы получить URL-адрес файла презентации.In the following code sample, the getFileUrl function calls the Document.getFileProperties method to get the URL of the presentation file.

function getFileUrl() {
    //Get the URL of the current file.
    Office.context.document.getFilePropertiesAsync(function (asyncResult) {
        var fileUrl = asyncResult.value.url;
        if (fileUrl == "") {
            app.showNotification("The file hasn't been saved yet. Save the file and try again");
        }
        else {
            app.showNotification(fileUrl);
        }
    });
}

Создание презентацииCreate a presentation

Ваша надстройка может создать новую презентацию, отдельную от экземпляра PowerPoint, в котором в настоящее время работает надстройка.Your add-in can create a new presentation, separate from the PowerPoint instance in which the add-in is currently running. Для этой цели в пространстве имен PowerPoint есть метод createPresentation.The PowerPoint namespace has the createPresentation method for this purpose. При вызове этого метода сразу открывается и отображается новая презентация в новом экземпляре программы PowerPoint.When this method is called, the new presentation is immediately opened and displayed in a new instance of PowerPoint. Ваша надстройка остается открытой и запущенной в предыдущей презентации.Your add-in remains open and running with the previous presentation.

PowerPoint.createPresentation();

С помощью метода createPresentation также можно создать копию существующей презентации.The createPresentation method can also create a copy of an existing presentation. Метод принимает в качестве необязательного параметра строковое представление PPTX-файла в кодировке base64.The method accepts a base64-encoded string representation of an .pptx file as an optional parameter. Полученная презентация будет копией этого файла, предполагая, что строковый аргумент является допустимым PPTX-файлом.The resulting presentation will be a copy of that file, assuming the string argument is a valid .pptx file. Преобразование файла в нужную строку в кодировке base64 можно выполнить с помощью класса FileReader, как показано в приведенном ниже примере.The FileReader class can be used to convert a file into the required base64-encoded string, as demonstrated in the following example.

var myFile = document.getElementById("file");
var reader = new FileReader();

reader.onload = function (event) {
    // strip off the metadata before the base64-encoded string
    var startIndex = reader.result.toString().indexOf("base64,");
    var copyBase64 = reader.result.toString().substr(startIndex + 7);

    PowerPoint.createPresentation(copyBase64);
};

// read in the file as a data URL so we can parse the base64-encoded string
reader.readAsDataURL(myFile.files[0]);

См. такжеSee also