Share via

Adicionar e excluir slides no PowerPoint

  • Artigo

Um suplemento do PowerPoint pode adicionar slides à apresentação e, opcionalmente, especificar qual mestre de slides e qual layout do mestre é usado para o novo slide. O suplemento também pode excluir slides.

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

Adicionar um slide com SlideCollection.add

Adicione slides com o método SlideCollection.add . Veja a seguir um exemplo simples no qual um slide que usa o mestre de slides padrão da apresentação e o primeiro layout desse mestre é adicionado. O método sempre adiciona novos slides ao final da apresentação. Apresentamos um exemplo a seguir.

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

    await context.sync();
  });
}

Selecione qual mestre de slides e layout usar

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

  • Você pode incluir ou ambas as propriedades do AddSlideOptions objeto.
  • Se ambas as propriedades forem usadas, o layout especificado deverá pertencer ao mestre especificado ou um erro será gerado.
  • Se a masterId propriedade não estiver presente (ou seu valor for uma cadeia de caracteres vazia), o mestre de slides padrão será usado e o layoutId deve ser um layout desse mestre de slides.
  • O mestre de slides padrão é o mestre de slides usado pelo último slide na apresentação. (No caso incomum em que atualmente não há slides na apresentação, o mestre de slides padrão é o primeiro mestre de slides na apresentação.)
  • Se a layoutId propriedade não estiver presente (ou seu valor for uma cadeia de caracteres vazia), o primeiro layout do mestre especificado pelo masterId é usado.
  • Ambas as propriedades são cadeias de caracteres de uma das três formas possíveis: nnnnnnnnnnnn#, #mmmmmmmmm ou nnnnnnnnmmmmmmmmm#, onde nnnnnnnnnnnn é a ID do mestre ou do layout (normalmente 10 dígitos) e mmmmmmmmmmmmm é a ID de criação do mestre ou 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á nenhuma maneira prática de que os usuários possam descobrir a ID ou a ID de criação de um mestre de slides ou layout. Por esse motivo, você só pode usar o AddSlideOptions parâmetro quando souber que as IDs na hora da codificação ou seu suplemento podem descobri-las em runtime. Como os usuários não podem ser esperados para memorizar as IDs, você também precisa de uma maneira de permitir que o usuário selecione slides, talvez pelo nome ou por uma imagem, e correlacionar cada título ou imagem com a ID do slide.

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

Fazer com que o usuário escolha 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 mestre e layout que é usado por um slide existente , o suplemento poderá (1) solicitar que o usuário selecione um slide e (2) leia as IDs do mestre e layout do slide. As etapas a seguir mostram como ler as IDs e adicionar um slide com um mestre 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 a ser getSelectedDataAsync inserida 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 promessas.
    • getSelectedDataAsync retorna uma matriz porque vários slides podem ser selecionados. Nesse cenário, o usuário selecionou apenas um, portanto, o código obtém o primeiro slide (0º), 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 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 chame o Slide.delete método. Veja a seguir um exemplo no qual 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();
    });
}