Para usar a API Slides de forma eficaz, você precisa entender a arquitetura das apresentações e os componentes delas, bem como as interações entre eles. Esta página oferece uma visão geral detalhada desses tópicos:
- Modelo conceitual dos componentes da apresentação
- Como a API representa esses componentes
- Propriedades de estilo dos componentes
Com a leitura desta e das outras visões gerais dos conceitos, fica mais fácil entender e usar os guias de instruções, a documentação de referência e os exemplos de receitas.
Apresentações, páginas e elementos de página
O elemento do contêiner mais externo no Apresentações Google é uma apresentação. Essa unidade pode ser salva no Google Drive, compartilhada com outros usuários e assim por diante.
Cada apresentação contém vários tipos de páginas. Um slide é um tipo de página que os usuários veem e alternam quando a apresentação é renderizada em uma tela.
Cada página contém vários elementos de página que, juntos, compõem o conteúdo da página, conforme mostrado no diagrama a seguir:
Além dos slides, há outros tipos de páginas que permitem aplicar o design a vários slides diferentes, criando uma aparência consistente. Esses outros tipos de página são mestres e layouts, e as propriedades deles determinam como os slides são renderizados, como mostrado no diagrama a seguir:
Master: a página mestre tem duas finalidades. Os marcadores de posição no mestre contêm os padrões de estilos de texto usados em toda a apresentação. O plano de fundo e quaisquer outras formas no slide mestre compõem o plano de fundo padrão de todos os slides baseados nesse mestre. Se você tem um logotipo de empresa que quer aparecer em todos os slides da apresentação, coloque-o no mestre.
Layouts: os modelos de layout determinam como o conteúdo é organizado em cada tipo de slide. Se você quiser que todos os slides de título tenham uma determinada aparência, por exemplo, edite o modelo de layout do título.
Há outros dois tipos de páginas: de notas e mestres de notas, que são mais relevantes para trabalhar com as notas do apresentador.
Tipos e estrutura de representação da API
Esta seção descreve como o modelo conceitual do Apresentações Google, conforme descrito acima, é representado na API Slides.
O diagrama a seguir mostra a relação entre apresentações, páginas e elementos de página como tipos na API Slides:
As seções abaixo mostram como esses tipos são representados em JSON.
Apresentações
Uma apresentação inclui várias propriedades e as páginas dela:
{
"presentationId": string,
"pageSize": { object(Size) },
"slides": [ { object(Page) } ],
"title": string,
"masters": [ { object(Page) } ],
"layouts": [ { object(Page) } ],
"notesMaster": object(Page),
"locale": string,
}
Pages
Uma página inclui um conjunto de propriedades e os elementos da página que estão nela:
{
"objectId": string,
"pageType": enum(PageType),
"pageElements": [ { object(PageElement) } ],
"pageProperties": { object(PageProperties) },
// Union field properties can be only one of the following:
"slideProperties": { object(SlideProperties) },
"layoutProperties": { object(LayoutProperties) },
"notesProperties": { object(NotesProperties) },
// End of list of possible types for union field properties.
}
Elementos de página
Elementos de página são os componentes visuais colocados nas páginas. Um elemento de página na API contém várias propriedades, incluindo um campo que varia de acordo com o tipo de elemento de página:
{
"objectId": string,
"size": { object(Size) },
"transform": { object(AffineTransform) },
"title": string,
"description": string,
// Union field element_kind can be only one of the following:
"elementGroup": { object(Group) },
"shape": { object(Shape) },
"image": { object(Image) },
"video": { object(Video) },
"line": { object(Line) },
"table": { object(Table) },
"wordArt": { object(WordArt) },
"sheetsChart": { object(SheetsChart) },
// End of list of possible types for union field element_kind.
}
Há vários tipos de elementos de página, conforme definido pelo campo de união
element_kind na definição acima. Esses tipos de elementos de página são
descritos na tabela a seguir:
| Tipo de elemento | Descrição |
|---|---|
| Grupo | Um conjunto de elementos de página tratados como uma unidade individual. Eles podem ser movidos, dimensionados e girados juntos. |
| Forma | Um objeto visual simples, como retângulos, elipses e caixas de texto. As formas podem conter texto, por isso são os elementos de página mais comuns na criação de slides. |
| Imagem | Uma imagem importada para o Apresentações. |
| Video | Um vídeo importado para as Apresentações. |
| Linhas | Linha, curva ou conector visual. |
| Tabela | Uma grade de conteúdo. |
| WordArt | Um elemento de texto visual que se comporta mais como uma forma. |
| SheetsChart | Um gráfico do Planilhas Google importado para o Apresentações. |
Propriedades de página e elemento de página
A API Slides permite ler e atualizar a aparência das páginas e dos elementos de página de uma apresentação. Diferentes elementos de página são compatíveis com propriedades distintas que controlam como o elemento é renderizado.
Cada tipo de elemento de página tem um elemento de propriedades correspondente e uma mensagem de atualização de propriedades, por exemplo:
- Há um tipo de elemento de página Shape.
- O campo de propriedade dele é shapeProperties.
- A solicitação para atualizar essas propriedades é UpdateShapePropertiesRequest.
O mesmo conjunto de elemento/propriedades/solicitação de atualização existe para cada tipo de elemento de página: Image/imageProperties/UpdateImageProperties e assim por diante.
É possível ler o atributo de propriedades onde quer que você o encontre na leitura de um elemento. Para alterar os valores, use-o com o tipo de solicitação correspondente como o payload para o método batchUpdate, permitindo que você altere esses valores na apresentação.
Tipos de propriedade
Há algumas propriedades comuns entre vários tipos de objetos na API Slides:
| Propriedade | Descrição |
|---|---|
| Cor | As cores na API Slides podem ser um valor RGB ou uma referência à cor de um tema. As cores de tema são chamadas de nome (por exemplo, "DARK1") e podem ser mapeadas para os valores RGB usando o esquema de cores de uma página. Esse esquema de cores costuma ser atualizado quando o tema da apresentação no editor do Apresentações é alterado. |
| Preenchimento | O preenchimento representa a renderização de espaço vazio dentro de um objeto. O preenchimento mais comumente aceito no Apresentações é o sólido, em que o interior de um objeto é preenchido com uma única cor sólida. Os preenchimentos também podem ser usados para o plano de fundo de Páginas. |
| Contorno | O contorno representa o conjunto de linhas ao redor do elemento de página. A cor das linhas é controlada com um preenchimento. Os autores da chamada também podem ajustar a largura e o estilo de traço dos contornos. |
| Sombra | A sombra representa um efeito visual que visa imitar uma sombra física projetada pelo objeto. No momento, as sombras na API Slides são somente leitura. |
Como atualizar propriedades
Para atualizar uma propriedade, use a solicitação Update...Properties apropriada em uma chamada batchUpdate, por exemplo, UpdateShapeProperties para Shapes. Essas solicitações aceitam uma mensagem de propriedades completa e podem usar máscaras de campo para determinar quais campos da mensagem de propriedades precisam ser atualizados.
Herança da propriedade
Uma página ou um elemento de página pode herdar propriedades de seus objetos pais. As propriedades de um objeto, incluindo aquelas que ele define e que ele herda, determinam a aparência final dele.
- Propriedades de página: uma página herda as propriedades que não define, mas que são definidas no layout ou no mestre em que ela se baseia.
- Propriedades de forma: uma forma pode ser marcada como um marcador, permitindo que você faça referência explícita a outra forma de marcador (no layout principal ou mestre da página) de onde as propriedades serão herdadas.
Essas ideias são explicadas com mais detalhes nos parágrafos a seguir.
Herança de propriedades de páginas
A estrutura de slides, layouts e mestres define uma hierarquia de herança dentro da apresentação: slides herdam de layouts, e layouts herdam de mestres. O layout principal e o mestre de um slide são especificados no campo slideProperties dele.
Uma página pode herdar propriedades, como plano de fundo e esquema de cores, de uma página mãe. Para herdar uma propriedade, a página filha simplesmente não define um valor para ela na mensagem PageProperties. Ao não "substituir" o valor definido pelo pai, a página aceita o valor herdado.
O diagrama a seguir mostra um slide que herda propriedades de um layout, que é herdada de um mestre:
As propriedades usadas para renderizar um slide são uma combinação das que ele define com as herdadas. Neste exemplo, os valores resolvidos usados para renderizar o slide 1 são os seguintes:
- A propriedadeA está em "vermelho".
- A propriedade B é "laranja".
Herança de propriedades de formas
As formas podem herdar propriedades, como preenchimento, contorno ou sombra, de outras
formas. Uma forma será um marcador de posição se o campo Shape.placeholder estiver definido. O campo Shape.placeholder.parentObjectId do marcador filho
identifica o marcador pai. Quando você cria um novo slide com base em um
layout, todos os marcadores de posição aparecem como formas filhas no novo slide.
Da mesma forma, os marcadores de páginas mestres podem atuar como principais dos marcadores
dos layouts.
Com essa hierarquia de herança definida, a página filha herda uma propriedade ao não definir esse valor na mensagem ShapeProperties. Ao não substituir o valor definido pelo pai, a forma filha aceita o valor herdado.
O diagrama a seguir mostra a herança de propriedades entre três marcadores de posição contidos em um slide, um layout e um mestre:
As propriedades usadas para renderizar uma forma de marcador são uma combinação das que ela define com as herdadas. Neste exemplo, os valores resolvidos dessas formas são os seguintes:
- Placeholder1: propriedadeA é renderizada como "amarelo" e propriedadeB como "verde".
- Placeholder2: propriedadeA é renderizada como "amarelo" e propriedadeB como "roxo".
- Placeholder3: propriedadeA é renderizada como "amarelo" e propriedadeB como "roxo".
As formas são o único tipo de elemento de página que pode ter pais. Outros tipos, como imagens, tabelas e gráficos, não podem ser marcadores de posição e não podem ter pais.
Como "ocultar" propriedades usando PropertyState
A enumeração PropertyState controla se a propriedade de uma forma é realmente usada para renderização ou se o valor é usado apenas para herança por formas filhas. Uma propriedade com
o estado de propriedade NOT_RENDERED não será usada ao renderizar a forma na
página. No entanto, as filhas com um estado de propriedade RENDERED
correspondente ainda podem herdar essa propriedade.
O diagrama a seguir mostra a herança de propriedades entre três marcadores que manipulam o campo PropertyState:
A renderização das propriedades da forma pode ser afetada pelo campo PropertyState. Neste exemplo, os valores resolvidos dessas formas são os seguintes:
- Placeholder1: propriedadeA é renderizada como "vermelho".
- Placeholder2: propriedadeA não é renderizada. Se essa fosse a propriedade "outline", Placeholder2 não teria contorno.
- Placeholder3: propriedadeA não foi renderizada.
Há mais um valor possível da enumeração PropertyState: o estado da propriedade INHERIT significa que o próprio estado da propriedade é herdado, e o valor do pai precisa ser usado. Formas sem
pais não podem ter o estado de propriedade INHERIT.