Suplementos do PowerPointPowerPoint add-ins

Você pode usar suplementos do PowerPoint na criação de soluções envolventes para as apresentações de seus usuários em todas as plataformas, incluindo Windows, iPad, Mac e em um navegador.You can use PowerPoint add-ins to build engaging solutions for your users' presentations across platforms including Windows, iOS, Mac, and in a browser. Você pode criar dois tipos de comandos de suplementos do PowerPoint:You can create two types of PowerPoint add-ins:

  • Use suplementos de conteúdo para adicionar conteúdo dinâmico do HTML5 às suas apresentações. Por exemplo, confira o suplemento LucidChart Diagrams for PowerPoint que pode ser usado para inserir um diagrama interativo do LucidChart para seu conjunto.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 suplementos do painel de tarefas para exibir as informações de referência ou inserir dados na apresentação através de um serviço.Use task pane add-ins to bring in reference information or insert data into the presentation via a service. Por exemplo, confira o suplemento Pixton Comic Characters, que você pode usar para adicionar fotos profissionais à sua apresentação.For example, see the Pixton Comic Characters add-in, which you can use to add professional photos to your presentation.

Cenários de suplemento do PowerPointPowerPoint add-in scenarios

Os exemplos de código no artigo mostram algumas tarefas básicas para desenvolver suplementos para o PowerPoint.The code examples in this article demonstrate some basic tasks for developing add-ins for PowerPoint. Além disso, observe o seguinte:Please note the following:

  • Para exibir as informações, esses exemplos dependem da função app.showNotification, incluída em modelos de projeto de Suplementos do Office do Visual Studio.To display information, these examples use the app.showNotification function, which is included in the Visual Studio Office Add-ins project templates. Se você não estiver usando o Visual Studio para desenvolver seu suplemento, será necessário substituir a função showNotification por seu próprio código.If you aren't using Visual Studio to develop your add-in, you'll need replace the showNotification function with your own code.

  • Vários desses exemplos também usam um objeto Globals que é declarado fora do âmbito destas funções como: 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};

  • Para usar esses exemplos, seu suplemento de projeto deverá referenciar a biblioteca do Office.js 1.1 ou posterior.To use these examples, your add-in project must reference Office.js v1.1 library or later.

Detecte a exibição ativa da apresentação e manipule o evento ActiveViewChangedDetect the presentation's active view and handle the ActiveViewChanged event

Se você estiver criando um suplemento de conteúdo, será necessário obter o modo de exibição ativo da apresentação e manipular o ActiveViewChanged evento, como parte do seu Office.Initialize manipulador.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.

Observação

No PowerPoint Online na Web, o evento Document.ActiveViewChanged nunca será acionado porque o modo de Apresentação de Slides é tratado como uma nova sessão.In PowerPoint on the web, the Document.ActiveViewChanged event will never fire as Slide Show mode is treated as a new session. Nesse caso, o suplemento deve obter o modo de exibição ativo ao carregar, conforme observado abaixo.In this case, the add-in must fetch the active view on load, as shown in the following code sample.

No seguinte exemplo de código:In the following code sample:

  • A função getActiveFileView chama o método Document.getActiveViewAsync para retornar se o modo de exibição atual da apresentação for "edição" (qualquer um dos modos de exibição em que é possível editar slides, como Normal ou Modo de Exibição de Estrutura de Tópicos) ou "leitura" ( Apresentação de Slides ou Modo de Exibição de Leitura).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).

  • A função registerActiveViewChanged chama o método addHandlerAsync para registrar um manipulador para o evento 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);
            }
        });
}

No seguinte exemplo de código, o método getSelectedRange função chamadas do Document.getSelectedDataAsync para acessar o objeto JSON retornado pela asyncResult.value, que contém uma matriz chamada 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. A matriz slides contém índices, ids e títulos do intervalo selecionado slides (ou do slide atual, se vários slides não forem selecionados).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). Ela também salva a id do primeiro slide no intervalo selecionado em uma variável global.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));
        }
    });
}

No seguinte exemplo de código, o método goToFirstSlide função chamadas a Document.goToByIdAsync para navegar até o primeiro slide identificado pela getSelectedRange função mostrada anteriormente.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");
        }
    });
}

No seguinte exemplo de código, o método goToSlideByIndex função chamadas a Document.goToByIdAsync para navegar até o próximo slide na apresentação.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");
        }
    });
}

Obtenha a URL da apresentaçãoGet the URL of the presentation

No seguinte exemplo de código, o método getFileUrl função chamadas a Document.getFileProperties para obter a URL do arquivo da apresentação.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);
        }
    });
}

Criar uma apresentaçãoCreate a presentation

O suplemento pode criar uma nova apresentação separada da instância do PowerPoint, na qual o suplemento está sendo executado atualmente.Your add-in can create a new presentation, separate from the PowerPoint instance in which the add-in is currently running. O namespace do PowerPoint tem o método createPresentation para essa finalidade.The PowerPoint namespace has the createPresentation method for this purpose. Quando esse método é chamado, a nova apresentação é aberta imediatamente e exibida em uma nova instância do PowerPoint.When this method is called, the new presentation is immediately opened and displayed in a new instance of PowerPoint. O suplemento permanece aberto e em execução com a apresentação anterior.Your add-in remains open and running with the previous presentation.

PowerPoint.createPresentation();

O método createPresentation também cria uma cópia de uma apresentação existente.The createPresentation method can also create a copy of an existing presentation. O método aceita uma representação de cadeia de caracteres codificada em Base64 de um arquivo .pptx como parâmetro opcional.The method accepts a base64-encoded string representation of an .pptx file as an optional parameter. A apresentação resultante será uma cópia desse arquivo, supondo que o argumento da cadeia de caracteres seja um arquivo .pptx válido.The resulting presentation will be a copy of that file, assuming the string argument is a valid .pptx file. A classe FileReader pode ser usada para converter um arquivo em uma cadeia de caracteres codificada com Base64, como demonstrado no exemplo a seguir.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]);

Confira tambémSee also