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 coletar 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:
Os designers podem facilmente ajustar o design de uma apresentação usando o editor do Apresentações Google. Isso é muito mais fácil do que ajustar parâmetros no seu app para definir o design do slide renderizado.
Separar o conteúdo da apresentação é um princípio de design bem conhecido com muitos benefícios.
Uma receita básica
Veja um exemplo de como você pode usar a API Slides para mesclar dados em uma apresentação:
Crie sua apresentação como quiser usando conteúdo marcador de posição para ajudar com o design.
Para cada elemento de conteúdo que você inserir, substitua o conteúdo do marcador de posição 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 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 fazer todas as substituições de texto ao longo da apresentação. Use as solicitaçõesreplaceAllShapesWithImage
para realizar substituições de imagens durante a apresentação.
Depois de criar uma apresentação com tags, faça uma cópia dela e use a API Slides para manipulá-la. Não use a API Slides para manipular a cópia principal do "modelo".
As seções abaixo 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 dos 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 um novo texto. Para mesclas, 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 à medida que os colaboradores refinam e mantêm o modelo de apresentação.
Exemplo
Este exemplo usa a API Drive para copiar um modelo de apresentação, criando uma nova instância da apresentação. Depois, ele usa a API Google Sheets para ler 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 sua apresentação usando uma
solicitação
replaceAllShapesWithImage
. Essa solicitação substitui todas as instâncias de formas que contêm a string de texto informada com a imagem fornecida. A solicitação posiciona e dimensiona automaticamente a imagem para que ela se ajuste aos limites da forma da tag, preservando a proporção dela.
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, ele usa a API Slides para encontrar
qualquer forma com o texto {{company-logo}}
e substituí-la por uma 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 instâncias de caixa de texto ou imagem específicas
As solicitações replaceAllText
e replaceAllShapesWithImage
são úteis para substituir tags em toda a 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, você precisa recuperar os IDs das formas de tag que 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.
A substituição de imagens é mais complexa. Para mesclar uma imagem, você precisa:
- Acessa o ID do formato da tag.
- Copie as informações de tamanho e transformação da tag.
- Adicione sua imagem à página usando as informações de tamanho e transformação.
- Exclua a forma da tag.
Preservar a proporção da imagem ao redimensioná-la para o tamanho desejado pode exigir algum cuidado, conforme descrito na próxima seção. Confira 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 desejado 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, a proporção dela é mantida configurando o tamanho e o dimensionamento dela da seguinte maneira:
- width: definido como o produto de
width
escaleX
da tag - height: definida como o produto de
height
escaleY
da tag. - scale_x: defina como
1
. - scale_y: defina 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 dimensionamento como 1
impede que a imagem seja dimensionada
duas vezes.
Isso garante que a proporção da imagem seja preservada e evita que ela exceda o tamanho do formato 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 a partir de modelos, use sempre credenciais de usuário final. Isso dá aos usuários controle total sobre a apresentação resultante e evita problemas de escalonamento relacionados ao limite por usuário no Google Drive.
Para criar um modelo usando uma conta de serviço, execute as etapas a seguir com as credenciais do aplicativo:
- Crie uma apresentação usando presentations.create na API Slides.
- Atualize as permissões para permitir que os destinatários da apresentação leiam a apresentação usando permissions.create na API Drive.
- Atualize as permissões para 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 as etapas a seguir 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.