Adicionar e excluir slides do PowerPoint programaticamente

Adicione e remova rapidamente slides de uma apresentação do PowerPoint usando um suplemento.

  • Adicione slides programaticamente com SlideCollection.add() e controle o master e o layout quando necessário.
  • Corresponda ao master ou layout de um slide existente ou escolha específico slideMasterId e layoutId em tempo de execução.
  • Excluir slides por referência ou índice; Sempre inclua await context.sync() após as alterações.
  • Tempo estimado: Experimente os exemplos curtos em ~2–5 minutos.

As APIs para adicionar slides são usadas principalmente em cenários em que as IDs dos slides mestres e layouts na apresentação são conhecidas no momento da codificação ou podem ser encontradas em uma fonte de dados em tempo de execução. Em tal cenário, você ou o cliente devem criar e manter uma fonte de dados que correlacione o critério de seleção (como os nomes ou imagens de slides mestres e layouts) com as IDs dos slides mestres e layouts. As APIs também podem ser usadas em cenários em que o usuário pode inserir slides que usam o slide master padrão e o layout padrão do master, e em cenários em que o usuário pode selecionar um slide existente e criar um novo com o mesmo slide master e layout (mas não o mesmo conteúdo). Consulte Seleção de qual slide master e layout usar para obter mais informações sobre isso.

Adicionar um slide com SlideCollection.add

Adicione slides com o método SlideCollection.add . A seguir, um exemplo em que um slide que usa o master de slides padrão da apresentação e o primeiro layout desse master é adicionado. O método sempre adiciona novos slides ao final da apresentação.

async function addSlide() {
  await PowerPoint.run(async function(context) {
    context.presentation.slides.add();

    await context.sync();
  });
}

Selecione qual master de slide e layout usar

Use o parâmetro AddSlideOptions para controlar qual slide mestre é usado para o novo slide e qual layout dentro do master é usado. Apresentamos um exemplo a seguir. Sobre este código, observe:

  • Você pode incluir uma ou ambas as propriedades do AddSlideOptions objeto.
  • Se ambas as propriedades forem usadas, o layout especificado deverá pertencer ao master especificado ou um erro será gerado.
  • Se a masterId propriedade não estiver presente (ou seu valor for uma cadeia de caracteres vazia), o slide master padrão será usado e layoutId deverá ser um layout desse slide master.
  • O slide master padrão é o slide master usado pelo último slide da apresentação. (No caso incomum em que atualmente não há slides na apresentação, o slide master padrão é o primeiro slide master na apresentação.)
  • Se a layoutId propriedade não estiver presente (ou seu valor for uma cadeia de caracteres vazia), o primeiro layout do master especificado pela masterId será usado.
  • Ambas as propriedades são cadeias de caracteres de uma das três formas possíveis: nnnnnnnnnn#, #mmmmmmmmm ou nnnnnnnnnn#mmmmmmmmm, em que nnnnnnnnnn é a ID do master ou do layout (normalmente 10 dígitos) e mmmmmmmmm é a ID de criação do master ou do layout (normalmente 6 a 10 dígitos). Alguns exemplos são 2147483690#2908289500, 2147483690#, e #2908289500.
async function addSlide() {
    await PowerPoint.run(async function(context) {
        context.presentation.slides.add({
            slideMasterId: "2147483690#2908289500",
            layoutId: "2147483691#2499880"
        });
    
        await context.sync();
    });
}

Não há uma maneira prática para os usuários descobrirem a ID ou a ID de criação de um slide master ou layout. Por esse motivo, você só poderá usar o AddSlideOptions parâmetro quando souber as IDs no momento da codificação ou se o suplemento puder descobri-las em tempo de execução. Como não é possível esperar que os usuários memorizem as IDs, você também precisa de uma maneira de permitir que o usuário selecione slides, talvez por nome ou por uma imagem, e correlacione cada título ou imagem com a ID do slide.

Assim, o AddSlideOptions parâmetro é usado principalmente em cenários nos quais o suplemento foi projetado para trabalhar com um conjunto específico de slides mestres e layouts cujas IDs são conhecidas. Nesse cenário, você ou o cliente devem criar e manter uma fonte de dados que correlacione um critério de seleção (como nomes ou imagens de slide master e layout) com as IDs ou IDs de criação correspondentes.

Peça ao usuário para escolher um slide correspondente

Se o suplemento puder ser usado em cenários em que o novo slide deve usar a mesma combinação de slide master e layout usada por um slide existente, o suplemento poderá (1) solicitar que o usuário selecione um slide e (2) ler as IDs do slide mestre e do layout. As etapas a seguir mostram como ler as IDs e adicionar um slide com um master e layout correspondentes.

  1. Crie uma função para obter o índice do slide selecionado. Apresentamos um exemplo a seguir. Sobre este código, observe:

    • Ele usa o método Office.context.document.getSelectedDataAsync das APIs JavaScript comuns.
    • 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 APIs comuns em funções de retorno de promessa.
    • getSelectedDataAsync Retorna uma matriz porque vários slides podem ser selecionados. Nesse cenário, o usuário selecionou apenas um, de modo que o código obtém o primeiro (0º) slide, que é o único selecionado.
    • O index valor do slide é o valor baseado em 1 que o usuário vê ao lado do slide no painel de miniaturas.
    function getSelectedSlideIndex() {
    return new OfficeExtension.Promise<number>(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].index);
                }
            } 
            catch (error) {
                reject(console.log(error));
            }
        });
    });
}

  2. Chame sua nova função dentro do PowerPoint.run() da função principal que adiciona o slide. Apresentamos um exemplo a seguir.

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

        let selectedSlideIndex = await getSelectedSlideIndex();

        // Decrement the index because the value returned by getSelectedSlideIndex()
        // is 1-based, but SlideCollection.getItemAt() is 0-based.
        const realSlideIndex = selectedSlideIndex - 1;
        const selectedSlide = context.presentation.slides.getItemAt(realSlideIndex).load("slideMaster/id, layout/id");

        await context.sync();

        context.presentation.slides.add({
            slideMasterId: selectedSlide.slideMaster.id,
            layoutId: selectedSlide.layout.id
        });

        await context.sync();
    });
}

Excluir slides

Exclua um slide obtendo uma referência ao objeto Slide que representa o slide e, em seguida, chamando o método Slide.delete . Veja a seguir um exemplo em que o 4º slide é excluído.

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

        // The slide index is zero-based. 
        const slide = context.presentation.slides.getItemAt(3);
        slide.delete();

        await context.sync();
    });
}

Considerações

  • IDs mestre/layout são opacas: slideMasterId e layoutId são cadeias de caracteres de ID (geralmente tokens numéricos longos). Não há nenhuma interface do usuário para os usuários descobri-los, portanto, seu suplemento deve mapear nomes amigáveis ou miniaturas para IDs em tempo de execução.
  • Diferenças de índice: Office.context.document.getSelectedDataAsync(Office.CoercionType.SlideRange) retorna índices de slide baseados em 1. slides.getItemAt(...) é baseado em 0 — subtraia 1 ao usar o valor.
  • Chamada context.sync() após mutações: a adição ou exclusão de slides tem efeito no documento; sempre inclua await context.sync() após a chamada add() ou delete() para garantir que as alterações sejam aplicadas.
  • O layout deve pertencer ao master: Se você fornecer ambos slideMasterId e layoutId, o layout deve pertencer a esse master ou um erro será gerado.
  • Trabalhe em cópias para alterações em massa: a exclusão de slides é imediata. Considere avisar os usuários ou operar em uma cópia ao executar exclusões em lote.
  • Last updated on