Para usar a API Slides de maneira eficaz, é necessário entender a arquitetura das apresentações e seus componentes, bem como as interações entre eles. Nesta página, você encontra uma visão geral detalhada dos seguintes tópicos:
- Modelo conceitual dos componentes de apresentação
- Como a API representa esses componentes
- Propriedades de estilo dos componentes
Ler esta e as outras visões gerais de conceitos vai facilitar a compreensão e o uso dos guias de instruções, da documentação de referência e dos exemplos de receitas.
Apresentações, páginas e elementos de página
O elemento de contêiner mais externo no Google Slides é uma apresentação. Essa é a unidade que 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 tipo de página é um slide, que são as páginas que os usuários veem e alternam quando a apresentação é renderizada em uma tela.
Cada página contém vários elementos, que juntos formam 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 design a vários slides diferentes, criando uma aparência consistente. Esses outros tipos de página são modelos e layouts, e as propriedades deles determinam a forma como os slides são renderizados, conforme mostrado no diagrama a seguir:
Modelos: a página principal tem duas finalidades. Os marcadores de posição no modelo contêm os padrões para estilos de texto usados em toda a apresentação. O plano de fundo e todas as outras formas no slide mestre compõem o plano de fundo padrão de todos os slides com base nesse modelo. Se você tiver um logotipo da empresa que quer que apareça em todos os slides da apresentação, coloque-o no modelo.
Layouts: os modelos de layout determinam como o conteúdo é organizado em cada tipo de slide. Se quiser que todos os slides de título tenham uma aparência específica, por exemplo, edite o modelo de layout de título.
Há mais dois tipos de páginas, as de observações e os modelos de observações, que são mais relevantes para trabalhar com observações do apresentador.
Tipos e estrutura de representação de API
Esta seção descreve como o modelo conceitual do Google Slides, 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 a seguir mostram como esses tipos são representados em JSON.
Apresentações
Uma apresentação inclui várias propriedades e contém as páginas que estão nela:
{
"presentationId": string,
"pageSize": { object(Size) },
"slides": [ { object(Page) } ],
"title": string,
"masters": [ { object(Page) } ],
"layouts": [ { object(Page) } ],
"notesMaster": object(Page),
"locale": string,
}
Páginas
Uma página inclui um conjunto de propriedades e contém os elementos da página:
{
"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 que são 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 da página que são 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 e são os elementos de página mais comuns para criar slides. |
| Imagem | Um gráfico importado para o Google Slides. |
| Vídeo | Um vídeo importado para o app Apresentações. |
| Linha | Uma linha, curva ou conector visual. |
| Tabela | Uma grade de conteúdo. |
| WordArt | Um elemento do texto visual que se comporta mais como uma forma. |
| SheetsChart | Um gráfico importado para o Apresentações Google do Google Planilhas. |
Propriedades de página e elementos da página
Com a API Slides, é possível ler e atualizar a aparência de páginas e elementos de página na sua apresentação. Elementos de página diferentes oferecem suporte a propriedades diferentes 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 Forma
- O campo de propriedade é 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 "properties" sempre que ele aparecer ao ler um elemento. Para mudar os valores dele, use-o com o tipo de solicitação correspondente como o payload do método batchUpdate, permitindo que você mude esses valores na apresentação.
Tipos de propriedades
Há algumas propriedades comuns entre vários tipos de objetos na API Slides:
| Propriedade | Descrição |
|---|---|
| Cor | As cores na API Apresentações podem ser um valor RGB ou uma referência a uma cor do tema. As cores do tema são referidas por nome (por exemplo, "DARK1") e podem ser mapeadas para valores RGB usando um esquema de cores da página. Esse esquema de cores é atualizado com frequência quando o tema da apresentação é alterado no editor do Apresentações. |
| Preenchimento | O preenchimento representa a renderização do espaço vazio dentro de um objeto. O preenchimento mais usado 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 os planos de fundo das páginas. |
| Contorno | O contorno representa o conjunto de linhas que envolvem o 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 imita 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 formas. Essas solicitações
aceitam uma mensagem de propriedades completa e podem usar
máscaras de campo para determinar quais campos na
mensagem de propriedades precisam ser atualizados.
Herança da propriedade
Uma página ou um elemento de página pode herdar propriedades dos objetos pai. As propriedades de um objeto, incluindo as que ele define e as que herda, determinam a aparência visual final.
- Propriedades da página: uma página herda todas as propriedades que não define, mas que são definidas no layout ou no modelo em que ela se baseia.
- Propriedades de forma: uma forma pode ser marcada como um marcador de posição, permitindo que você faça referência explícita a outra forma de marcador de posição (no layout principal ou mestre da página) para herdar propriedades.
Essas ideias são explicadas com mais detalhes nos parágrafos a seguir.
Herança de propriedades da página
A estrutura de slides, layouts e modelos define uma hierarquia de herança na apresentação: os slides herdam dos layouts, e os layouts herdam dos modelos. O layout pai e o modelo principal de um slide são especificados no campo slideProperties do slide.
Uma página pode herdar propriedades, como segundo plano 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 essa propriedade na mensagem PageProperties. Ao não "substituir" o valor definido pelo elemento pai, a página aceita o valor herdado.
O diagrama a seguir mostra um slide que herda propriedades de um layout, que herda de um modelo:
As propriedades usadas para renderizar um slide são uma combinação das que ele define e das que herda. Neste exemplo, os valores resolvidos usados para renderizar o slide 1 são os seguintes:
- PropertyA é "Red".
- PropertyB é "Laranja".
Herança de propriedades de forma
As formas podem herdar propriedades, como preenchimento, contorno ou sombra, de outras formas. Uma forma é um marcador de posição se o campo
Shape.placeholder
estiver definido. O campo Shape.placeholder.parentObjectId do marcador de posição filho
identifica o marcador de posição pai. Quando você cria um slide com base em um layout, todos os marcadores de posição desse layout aparecem como formas secundárias no novo slide.
Da mesma forma, os marcadores de posição nas páginas principais podem atuar como principais dos marcadores de posição 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 elemento pai, a forma filha aceita o valor herdado.
O diagrama a seguir mostra a herança de propriedades entre três espaços reservados contidos em um slide, um layout e um modelo:
As propriedades usadas para renderizar uma forma de marcador de posição são uma combinação das que ela define e das que herda. Neste exemplo, os valores resolvidos para essas formas são os seguintes:
- Placeholder1: propertyA é renderizada como "Yellow", propertyB como "Green".
- Placeholder2: propertyA é renderizada como "Amarelo", propertyB como "Roxo".
- Placeholder3: propertyA é renderizada como "Amarelo", propertyB como "Roxo".
As formas são o único tipo de elemento de página que pode ter elementos pai. Outros tipos, como imagens, tabelas e gráficos, não podem ser marcadores de posição nem ter elementos pai.
"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 secundárias. Uma propriedade com o estado NOT_RENDERED não será usada ao renderizar a forma na página dela. No entanto, os filhos que têm um estado de propriedade correspondente de RENDERED ainda podem herdar essa propriedade.
O diagrama a seguir mostra a herança de propriedades entre três placeholders que manipulam o campo PropertyState:
A renderização das propriedades de forma pode ser afetada pelo campo "PropertyState". Neste exemplo, os valores resolvidos para essas formas são os seguintes:
- Placeholder1: propertyA é renderizado como "Red".
- Placeholder2: propertyA não é renderizado. Se essa fosse a propriedade de contorno, o Placeholder2 não teria contorno.
- Placeholder3: propertyA não é renderizada.
Há mais um valor possível da enumeração PropertyState: o estado da propriedade INHERIT significa que o estado da propriedade em si é herdado, e o valor do elemento pai deve ser usado. Formas sem elementos principais não podem ter um estado de propriedade INHERIT.