Inserir diapositivos de outra apresentação do PowerPoint

Saiba como criar suplementos do PowerPoint que inserem diapositivos através de programação de uma apresentação noutra, proporcionando aos utilizadores capacidades de gestão de diapositivos personalizadas diretamente no PowerPoint.

Visão Geral

Os suplementos do PowerPoint podem inserir diapositivos de uma apresentação na apresentação atual com a biblioteca de JavaScript específica da aplicação do PowerPoint. Tem controlo sobre os diapositivos a inserir, onde colocá-los e se os diapositivos inseridos mantêm a formatação da apresentação de origem ou adotam o tema da apresentação de destino.

Esta capacidade é particularmente valiosa para:

Modelos de apresentação: crie suplementos que permitam aos utilizadores montar rapidamente apresentações a partir de bibliotecas de diapositivos pré-aprovadas.
Reutilização de conteúdo: permita que as equipas partilhem e reutilizem diapositivos em várias apresentações.
Fluxos de trabalho automatizados: crie soluções que combinem dinamicamente diapositivos com base na lógica de negócio.

Pré-requisitos

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

Uma compreensão básica do desenvolvimento de Suplementos do Office.
Estar familiarizado com a API javaScript do PowerPoint.
Conhecimentos sobre padrões de programação JavaScript/TypeScript e assíncrono.

As APIs de inserção de diapositivos são utilizadas principalmente em cenários de modelo de apresentação onde, por exemplo, existe um pequeno número de apresentações conhecidas que servem como conjuntos de diapositivos que podem ser inseridos pelo suplemento. Nesse cenário, o utilizador ou o cliente têm de criar e manter uma origem de dados que correlacione o critério de seleção (como títulos de diapositivos ou imagens) com os IDs dos diapositivos. As APIs também podem ser utilizadas em cenários em que o utilizador pode inserir diapositivos a partir de qualquer apresentação arbitrária, mas nesse cenário o utilizador está efetivamente limitado à inserção de todos os diapositivos da apresentação de origem. Consulte Selecionar os diapositivos a inserir para obter mais informações sobre isto.

Como inserir diapositivos: processo passo a passo

Inserir diapositivos de uma apresentação noutra envolve dois passos principais:

Converta o ficheiro de apresentação de origem (.pptx) numa cadeia formatada em Base64.
Utilize o insertSlidesFromBase64 método para inserir um ou mais diapositivos do ficheiro codificado em Base64 na apresentação atual.

Passo 1: Converter a apresentação de origem em codificação Base64

Existem várias formas de converter um ficheiro para codificação Base64. A linguagem e biblioteca de programação que utiliza e se pretende converter no lado do servidor do suplemento ou do lado do cliente é determinada pelo seu cenário. Normalmente, irá efetuar a conversão em JavaScript no lado do cliente com um objeto FileReader . O exemplo seguinte mostra esta prática.

Comece por obter uma referência ao ficheiro do PowerPoint de origem. Neste exemplo, vamos utilizar um <input> controlo do tipo file para pedir ao utilizador para escolher um ficheiro. Adicione a seguinte marcação à página de suplementos.
```
<section>
    <p>Select a PowerPoint presentation from which to insert slides</p>
    <form>
        <input type="file" id="file" />
    </form>
</section>
```
Esta marcação adiciona a IU na seguinte captura de ecrã à página.

Observação

Existem muitas outras formas de obter um ficheiro do PowerPoint. Por exemplo, se o ficheiro estiver armazenado no OneDrive ou no SharePoint, pode utilizar o Microsoft Graph para o transferir. Para obter mais informações, consulte Trabalhar com ficheiros no Microsoft Graph e Ficheiros do Access com o Microsoft Graph.
Adicione o seguinte código ao JavaScript do suplemento para atribuir uma função ao evento do controlo de change entrada. (Vai criar a storeFileAsBase64 função no passo seguinte.)
```
$("#file").on("change", storeFileAsBase64);
```
Adicione o código a seguir. Observe o seguinte sobre este código.
- O reader.readAsDataURL método converte o ficheiro em codificação Base64 e armazena-o na reader.result propriedade . Quando o método for concluído, aciona o onload processador de eventos.
- O onload processador de eventos corta os metadados do ficheiro codificado e armazena a cadeia codificada numa variável global.
- A cadeia codificada com Base64 é armazenada globalmente porque será lida por outra função que criar num passo 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]);
}
```

Passo 2: Inserir diapositivos com insertSlidesFromBase64

O suplemento insere diapositivos de outra apresentação do PowerPoint na apresentação atual com o método Presentation.insertSlidesFromBase64 . Segue-se um exemplo simples no qual todos os diapositivos da apresentação de origem são inseridos no início da apresentação atual e os diapositivos inseridos mantêm a formatação do ficheiro de origem. Tenha em atenção que chosenFileBase64 é uma variável global que contém uma versão codificada em Base64 de um ficheiro de apresentação do PowerPoint.

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

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

Existem dois valores possíveis para a formatting propriedade: "UseDestinationTheme" e "KeepSourceFormatting". Opcionalmente, pode utilizar a InsertSlideFormatting enumeração (por exemplo, PowerPoint.InsertSlideFormatting.useDestinationTheme).
A função irá inserir os diapositivos da apresentação de origem imediatamente após o diapositivo especificado pela targetSlideId propriedade . O valor desta propriedade é uma cadeia de uma das três formas possíveis: nnn#, #mmmmmmmmm ou nnn#mmmmmmmmm, em que nnn é o ID do diapositivo (normalmente 3 dígitos) e mmmmmmmmm é o ID de criação do diapositivo (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 não saberá no momento da codificação o ID ou o ID de criação do diapositivo de destino. Mais frequentemente, um suplemento irá pedir aos utilizadores para selecionarem o diapositivo de destino. Os passos seguintes mostram como obter o ID nnn# do diapositivo atualmente selecionado e utilizá-lo como o diapositivo de destino.

Crie uma função que obtenha o ID do diapositivo atualmente selecionado com o método Office.context.document.getSelectedDataAsync das APIs JavaScript Comuns. Apresentamos um exemplo a seguir. Tenha em atenção que a chamada para getSelectedDataAsync está incorporada numa função promise-returning. Para obter mais informações sobre o porquê e como fazê-lo, consulte Encapsular Common-APIs em funções que devolvem promessas.

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));
      }
    });
  })
}

Chame a sua nova função dentro de PowerPoint.run() da função principal e transmita o ID que devolve (concatenado com o símbolo "#") como o valor da targetSlideId 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();
    });
}

Selecionar os diapositivos a inserir

Também pode utilizar o parâmetro InsertSlideOptions para controlar que diapositivos da apresentação de origem são inseridos. Pode fazê-lo ao atribuir uma matriz dos IDs de diapositivos da apresentação de origem à sourceSlideIds propriedade . Segue-se um exemplo que insere quatro diapositivos. Tenha em atenção que cada cadeia na matriz tem de seguir um ou outro dos padrões utilizados 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 diapositivos serão inseridos pela mesma ordem relativa em que aparecem na apresentação de origem, independentemente da ordem pela qual aparecem na matriz.

Não existe uma forma prática de os utilizadores detetarem o ID ou o ID de criação de um diapositivo na apresentação de origem. Por este motivo, só pode utilizar a sourceSlideIds propriedade quando conhece os IDs de origem no momento da codificação ou o suplemento pode obtê-los no runtime a partir de alguma origem de dados. Uma vez que não é possível esperar que os utilizadores memorizem os IDs dos diapositivos, também precisa de uma forma de permitir que o utilizador selecione diapositivos, talvez por título ou por uma imagem, e, em seguida, correlacione cada título ou imagem com o ID do diapositivo.

Assim, a sourceSlideIds propriedade é utilizada principalmente em cenários de modelos de apresentação: o suplemento foi concebido para funcionar com um conjunto específico de apresentações que servem como conjuntos de diapositivos que podem ser inseridos. Neste cenário, o utilizador ou o cliente têm de criar e manter uma origem de dados que correlacione um critério de seleção (como títulos ou imagens) com IDs de diapositivos ou IDs de criação de diapositivos que foram construídos a partir do conjunto de possíveis apresentações de origem.

Experimente

Experimente o seguinte exemplo interativo com o suplemento Script Lab.

Inserir diapositivos 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

Comentários

Esta página foi útil?

Last updated on 2025-12-19