Inserir slides de outra apresentação do PowerPoint

Saiba como criar suplementos do PowerPoint que inserem programaticamente slides de uma apresentação em outra, oferecendo aos usuários recursos personalizados de gerenciamento de slides diretamente no PowerPoint.

Visão Geral

Os suplementos do PowerPoint podem inserir slides de uma apresentação na apresentação atual usando a biblioteca JavaScript específica do aplicativo do PowerPoint. Você tem controle sobre quais slides inserir, onde colocá-los e se os slides inseridos manterão a formatação da apresentação de origem ou adotarão o tema da apresentação de destino.

Esse recurso é particularmente valioso para:

  • Modelos de apresentação: Crie suplementos que permitem aos usuários montar rapidamente apresentações de bibliotecas de slides pré-aprovadas.
  • Reutilização de conteúdo: permita que as equipes compartilhem e reutilizem slides em várias apresentações.
  • Fluxos de trabalho automatizados: crie soluções que combinam slides dinamicamente com base na lógica de negócios.

Pré-requisitos

Antes de começar, verifique se você tem:

As APIs de inserção de slides são usadas principalmente em cenários de modelo de apresentação em que, por exemplo, há um pequeno número de apresentações conhecidas que servem como pools de slides que podem ser inseridos pelo suplemento. Nesse cenário, você ou o cliente devem criar e manter uma fonte de dados que correlacione o critério de seleção (como títulos de slide ou imagens) com IDs de slide. As APIs também podem ser usadas em cenários em que o usuário pode inserir slides de qualquer apresentação arbitrária, mas, nesse cenário, o usuário fica efetivamente limitado a inserir todos os slides da apresentação de origem. Consulte Selecionando quais slides inserir para obter mais informações sobre isso.

Como inserir slides: processo passo a passo

A inserção de slides de uma apresentação em outra envolve duas etapas principais:

  1. Converta o arquivo de apresentação de origem (.pptx) em uma cadeia de caracteres no formato Base64.
  2. Use o insertSlidesFromBase64 método para inserir um ou mais slides do arquivo codificado em Base64 na apresentação atual.

Etapa 1: Converter a apresentação de origem para a codificação Base64

Há muitas maneiras de converter um arquivo para a codificação Base64. A linguagem de programação e a biblioteca que você usa e se a conversão deve ser convertida no lado do servidor do suplemento ou no lado do cliente são determinados pelo cenário. Normalmente, você fará a conversão em JavaScript no lado do cliente usando um objeto FileReader . O exemplo a seguir mostra essa prática.

  1. Para começar, obtenha uma referência ao arquivo de origem do PowerPoint. Neste exemplo, usaremos um <input> controle de tipo file para solicitar que o usuário escolha um arquivo. Adicione a seguinte marcação à página do suplemento.

    <section>
    <p>Select a PowerPoint presentation from which to insert slides</p>
    <form>
        <input type="file" id="file" />
    </form>
</section>

    Essa marcação adiciona a interface do usuário na captura de tela a seguir à página.

    Um controle de entrada de tipo de arquivo HTML precedido por uma frase instrucional que diz 'Selecione uma apresentação do PowerPoint da qual inserir slides'. O controle consiste em um botão denominado 'Escolher arquivo' seguido pela frase 'Nenhum arquivo escolhido'.

    Observação

    Existem muitas outras maneiras de obter um arquivo do PowerPoint. Por exemplo, se o arquivo estiver armazenado no OneDrive ou no SharePoint, você poderá usar o Microsoft Graph para baixá-lo. Para obter mais informações, consulte Trabalhando com arquivos no Microsoft Graph e Access Files com o Microsoft Graph.

  2. Adicione o código a seguir ao JavaScript do suplemento para atribuir uma função ao evento do controle de change entrada. (Você criará a storeFileAsBase64 função na próxima etapa.)

    $("#file").on("change", storeFileAsBase64);

  3. Adicione o código a seguir. Observe o seguinte sobre este código.

    • O reader.readAsDataURL método converte o arquivo em codificação Base64 e o armazena na reader.result propriedade. Quando o método é concluído, ele dispara o onload manipulador de eventos.
    • O onload manipulador de eventos corta metadados do arquivo codificado e armazena a cadeia de caracteres codificada em uma variável global.
    • A cadeia de caracteres codificada em Base64 é armazenada globalmente porque será lida por outra função criada em uma etapa posterior.
    let chosenFileBase64;

async function storeFileAsBase64() {
    const reader = new FileReader();

    reader.onload = async (event) => {
        const startIndex = reader.result.toString().indexOf("base64,");
        const copyBase64 = reader.result.toString().substr(startIndex + 7);

        chosenFileBase64 = copyBase64;
    };

    const myFile = document.getElementById("file") as HTMLInputElement;
    reader.readAsDataURL(myFile.files[0]);
}

Etapa 2: Inserir slides com insertSlidesFromBase64

Seu suplemento insere slides de outra apresentação do PowerPoint na apresentação atual com o método Presentation.insertSlidesFromBase64 . A seguir, um exemplo simples em que todos os slides da apresentação de origem são inseridos no início da apresentação atual e os slides inseridos mantêm a formatação do arquivo de origem. Observe que chosenFileBase64 é uma variável global que contém uma versão codificada em Base64 de um arquivo de apresentação do PowerPoint.

async function insertAllSlides() {
  await PowerPoint.run(async function(context) {
    context.presentation.insertSlidesFromBase64(chosenFileBase64);
    await context.sync();
  });
}

Você pode controlar alguns aspectos do resultado da inserção, incluindo onde os slides são inseridos e se eles obtêm a formatação de origem ou de destino, passando um objeto InsertSlideOptions como um segundo parâmetro para insertSlidesFromBase64. Apresentamos um exemplo a seguir. Sobre este código, observe:

  • Há dois valores possíveis para a formatting propriedade: "UseDestinationTheme" e "KeepSourceFormatting". Opcionalmente, você pode usar a enumeração InsertSlideFormatting (por exemplo, PowerPoint.InsertSlideFormatting.useDestinationTheme).
  • A função inserirá os slides da apresentação de origem imediatamente após o slide especificado pela targetSlideId propriedade. O valor dessa propriedade é uma cadeia de caracteres de uma das três formas possíveis: nnn#, #mmmmmmmmm ou nnn#mmmmmmmmm, em que nnn é a ID do slide (normalmente 3 dígitos) e mmmmmmmmm é a ID de criação do slide (normalmente 9 dígitos). Alguns exemplos são 267#763315295, 267#, e #763315295.
async function insertSlidesDestinationFormatting() {
  await PowerPoint.run(async function(context) {
    const insertSlideOptions: PowerPoint.InsertSlideOptions = {
                                formatting: "UseDestinationTheme",
                                targetSlideId: "267#"
    };
    context.presentation.insertSlidesFromBase64(chosenFileBase64, insertSlideOptions);
    await context.sync();
  });
}

É claro que, normalmente, você não saberá, no momento da codificação, a ID ou a ID de criação do slide de destino. Mais comumente, um suplemento solicitará que os usuários selecionem o slide de destino. As etapas a seguir mostram como obter a ID nnn# do slide selecionado no momento e usá-la como o slide de destino.

  1. Crie uma função que obtenha a ID do slide selecionado no momento usando o método Office.context.document.getSelectedDataAsync das APIs JavaScript comuns. Apresentamos um exemplo a seguir. Observe que a chamada para getSelectedDataAsync está incorporada em uma função de retorno de promessa. Para obter mais informações sobre por que e como fazer isso, consulte Encapsular Common-APIs em funções de retorno de promessa.

    function getSelectedSlideID() {
  return new OfficeExtension.Promise<string>(function (resolve, reject) {
    Office.context.document.getSelectedDataAsync(Office.CoercionType.SlideRange, function (asyncResult) {
      try {
        if (asyncResult.status === Office.AsyncResultStatus.Failed) {
          reject(console.error(asyncResult.error.message));
        } else {
          resolve(asyncResult.value.slides[0].id);
        }
      }
      catch (error) {
        reject(console.log(error));
      }
    });
  })
}

  2. Chame sua nova função dentro do PowerPoint.run() da função principal e passe o ID que ela retorna (concatenado com o targetSlideId símbolo "#") como o valor da propriedade do InsertSlideOptions parâmetro. Apresentamos um exemplo a seguir.

    async function insertAfterSelectedSlide() {
    await PowerPoint.run(async function(context) {

        const selectedSlideID = await getSelectedSlideID();
        const insertSlideOptions: PowerPoint.InsertSlideOptions = {
            formatting: "UseDestinationTheme",
            targetSlideId: selectedSlideID + "#"
        };

        context.presentation.insertSlidesFromBase64(chosenFileBase64, insertSlideOptions);

        await context.sync();
    });
}

Selecionando os slides a serem inseridos

Você também pode usar o parâmetro InsertSlideOptions para controlar quais slides da apresentação de origem são inseridos. Para fazer isso, atribua uma matriz de IDs de slide da apresentação de origem à sourceSlideIds propriedade. Veja a seguir um exemplo que insere quatro slides. Observe que cada cadeia de caracteres na matriz deve seguir um ou outro dos padrões usados para a targetSlideId propriedade.

async function insertAfterSelectedSlide() {
    await PowerPoint.run(async function(context) {
        const selectedSlideID = await getSelectedSlideID();
        const insertSlideOptions: PowerPoint.InsertSlideOptions = {
            formatting: "UseDestinationTheme",
            targetSlideId: selectedSlideID + "#",
            sourceSlideIds: ["267#763315295", "256#", "#926310875", "1270#"]
        };
        context.presentation.insertSlidesFromBase64(chosenFileBase64, insertSlideOptions);

        await context.sync();
    });
}

Observação

Os slides serão inseridos na mesma ordem relativa em que aparecem na apresentação de origem, independentemente da ordem em que aparecem na matriz.

Não há nenhuma maneira prática para que os usuários descubram a ID ou a ID de criação de um slide na apresentação de origem. Por esse motivo, você só poderá usar a sourceSlideIds propriedade quando souber as IDs de origem no momento da codificação ou quando o suplemento puder recuperá-las em runtime de alguma fonte de dados. Como não é possível esperar que os usuários memorizem IDs de slide, você também precisa de uma maneira de permitir que o usuário selecione slides, talvez por título ou por uma imagem, e correlacione cada título ou imagem com a ID do slide.

Assim, a sourceSlideIds propriedade é usada principalmente em cenários de modelo de apresentação: O suplemento foi projetado para funcionar com um conjunto específico de apresentações que servem como pools de slides que podem ser inseridos. Nesse cenário, você ou o cliente devem criar e manter uma fonte de dados que correlacione um critério de seleção (como títulos ou imagens) com IDs de slide ou IDs de criação de slide que foram criadas a partir do conjunto de possíveis apresentações de origem.

Experimente

Experimente o seguinte exemplo interativo usando o suplemento do Script Lab.

  • Inserir slides de outra apresentação

Para saber mais sobre o Script Lab, consulte Explorar a API JavaScript do Office usando o Script Lab.

Confira também

  • Last updated on