Uma aplicação útil da API Google Slides é mesclar informações de uma ou mais fontes de dados em um modelo de apresentação de slides.
Nesta página, descrevemos como extrair dados de uma fonte externa e inseri-los em um modelo de apresentação. O conceito é semelhante ao de uma mala direta usando um processador de texto e uma planilha.
Essa abordagem é útil por vários motivos:
É fácil para os designers ajustar o design de uma apresentação usando o editor do Apresentações Google. É muito mais fácil do que ajustar parâmetros no app para definir o design do slide renderizado.
Separar conteúdo da apresentação é um princípio de design bem conhecido com muitos benefícios.
Um roteiro básico
Veja um exemplo de como você pode usar a Slides API para mesclar dados em uma apresentação:
Crie sua apresentação como quiser usando conteúdo marcador de posição para ajudar no design.
Para cada elemento de conteúdo que você inserir, substitua o conteúdo do marcador por uma tag. Tags são caixas de texto ou formas com uma string exclusiva. Use strings que provavelmente não ocorrerão normalmente. Por exemplo,
{{account-holder-name}}
pode ser uma boa tag.No seu código, use a API Google Drive para fazer uma cópia da apresentação.
No código, use o método
batchUpdate
da API Slides com um conjunto de solicitaçõesreplaceAllText
para realizar todas as substituições de texto durante a apresentação. Use as solicitaçõesreplaceAllShapesWithImage
para substituir imagens ao longo da apresentação.
Depois de criar uma apresentação com tags, faça uma cópia e use a API Slides para manipulá-la. Não use a API Slides para manipular o texto do "modelo" principal.
As seções a seguir incluem snippets de código que ilustram parte desse processo. Você também pode assistir ao vídeo acima para ver um exemplo completo (Python) combinando vários conceitos das seções individuais abaixo.
Mesclar texto
Você pode usar uma solicitação replaceAllText
para substituir todas as instâncias de uma determinada string de texto em uma
apresentação por texto novo. Para mesclagens, isso é mais simples do que
encontrar e substituir cada instância de texto individualmente. Uma razão pela qual essa é a abordagem mais sofisticada é que os IDs de elementos de página são difíceis de prever, especialmente quando os colaboradores refinam e mantêm a apresentação do modelo.
Exemplo
Este exemplo usa a API Drive para copiar um modelo de apresentação, criando uma nova instância da apresentação. Em seguida, ele usa a API Google Sheets para ler os dados de uma planilha do Planilhas e, por fim, usa a API Slides para atualizar a nova apresentação.
O exemplo usa dados de três células em uma linha de um intervalo nomeado na planilha. Em seguida, ele substitui esses dados na apresentação sempre que
as strings {{customer-name}}
, {{case-description}}
ou
{{total-portfolio}}
ocorrem.
Apps Script
Go
Java
JavaScript
Node.js
PHP
Python
Ruby
Mesclar imagens
Também é possível mesclar imagens na apresentação usando uma
solicitação
replaceAllShapesWithImage
. Essa solicitação substitui todas as instâncias de formas que contêm a string de texto fornecida pela imagem fornecida. A solicitação posiciona e dimensiona a imagem automaticamente para caber nos limites da forma da tag, preservando a proporção da imagem.
Exemplo
Este exemplo usa a API Google Drive para copiar um modelo de apresentação, criando uma nova instância da apresentação. Em seguida, ela usa a API Slides para encontrar
qualquer forma com o texto {{company-logo}}
e a substituir pela imagem do logotipo da empresa. A solicitação também substitui qualquer forma pelo texto {{customer-graphic}}
por uma imagem diferente.
Apps Script
Go
Java
JavaScript
Node.js
PHP
Python
Ruby
Substituir a caixa de texto ou instâncias de imagem específicas
As solicitações replaceAllText
e replaceAllShapesWithImage
são úteis para substituir tags em uma apresentação, mas
às vezes você só precisa substituir elementos de acordo com outros critérios, como
a localização em um slide específico.
Nesses casos, é necessário recuperar os IDs das formas de tag que você quer substituir. Para substituições de texto, exclua o texto existente nessas formas e, em seguida, insira o novo texto. Consulte o exemplo Editar texto em uma forma especificada.
Substituir imagens é mais complexo. Para mesclar uma imagem, você precisa:
- Consiga o ID da forma com a tag.
- Copie as informações de tamanho e transformação da tag.
- Adicione a imagem à página usando as informações de tamanho e transformação.
- Exclua a forma da tag.
Preservar a proporção da imagem enquanto ela é redimensionada para o tamanho pretendido pode exigir certo cuidado, conforme descrito na próxima seção. Veja também este exemplo: Substituir uma tag de forma por uma imagem.
Preservar a proporção
Quando você cria imagens usando a API Slides, o ajuste da proporção é baseado apenas no tamanho da imagem, não nos dados de tamanho e transformação. Os dados de tamanho fornecidos
na solicitação createImage
são considerados o tamanho pretendido da imagem. A API ajusta a proporção da imagem a esse tamanho desejado e aplica a transformação fornecida.
Ao substituir uma tag por uma imagem, você preserva a proporção dela definindo o tamanho e o dimensionamento dela da seguinte maneira:
- width: defina como o produto de
width
escaleX
da tag. - height: definido como o produto dos
height
escaleY
da tag. - scale_x: definida como
1
- scale_y: definido como
1
Isso faz com que a API Slides se ajuste à imagem de acordo com o tamanho visual da tag, e não com o tamanho não dimensionado. Consulte Substituir uma tag de forma por uma imagem.
Definir os parâmetros de escalonamento como 1
impede que a imagem seja escalonada
duas vezes.
Essa organização garante que a proporção da imagem seja preservada e impede que ela exceda o tamanho da forma da tag. A imagem tem o mesmo ponto central que a forma da tag.
Gerenciar modelos
Para apresentações de modelo que o aplicativo define e possui, crie o modelo usando uma conta dedicada que represente o aplicativo. As contas de serviço são uma boa opção e evitam complicações com as políticas do Google Workspace que restringem o compartilhamento.
Ao criar instâncias de apresentações com base em modelos, sempre use credenciais de usuário final. Isso dá aos usuários controle total sobre a apresentação resultante e evita problemas de escalonamento relacionados aos limites por usuário no Google Drive.
Para criar um modelo usando uma conta de serviço, siga estas etapas com as credenciais do aplicativo:
- Crie uma apresentação usando presentations.create na API Slides.
- Atualize as permissões para autorizar que os destinatários da apresentação leiam o arquivo usando permissions.create na API Drive.
- Atualize as permissões para permitir que os autores do modelo gravem nele usando permissions.create na API Drive.
- Edite o modelo conforme necessário.
Para criar uma instância da apresentação, siga estas etapas com as credenciais de usuário:
- Crie uma cópia do modelo usando files.copy na API Drive.
- Substitua os valores usando presentation.batchUpdate na API Slides.