Páginas, elementos de página e propriedades

Para usar a API Slides de maneira eficaz, é necessário entender a arquitetura das apresentações e dos componentes delas, bem como as interações entre esses componentes. 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
  • Como definir o estilo das propriedades dos componentes

A leitura desta e das 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 código.

Apresentações, páginas e elementos de página

O elemento de contêiner mais externo no Apresentações Google é 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 a 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 de página, que juntos compõem o conteúdo da página, conforme mostrado no diagrama a seguir:

diagrama de arquitetura de slides

Além dos slides, há outros tipos de páginas que permitem aplicar o design a muitos slides diferentes, criando uma aparência consistente. Esses outros tipos de página são masters e layouts, e as propriedades deles determinam a forma como os slides são renderizados, conforme mostrado no diagrama a seguir:

diagrama de arquitetura de temas

Masters : a página master tem duas finalidades. Os marcadores de posição no master contêm os padrões para estilos de texto usados em toda a apresentação. O plano de fundo e outras formas no slide master compõem o plano de fundo padrão de todos os slides com base nesse master. Se você tiver um logotipo da empresa que quer que apareça em todos os slides da apresentação, coloque-o no master.

Layouts : os modelos de layout determinam como o conteúdo é organizado em cada tipo de slide. Por exemplo, se você quiser que todos os slides de título tenham uma determinada aparência, edite o modelo de layout de título.

Há mais dois tipos de páginas (páginas de notas e notes masters), que são mais relevantes para trabalhar com 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:

diagrama no estilo ERD

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 de 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

Os 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 de 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, então são os elementos de página mais comuns para criar slides.
Imagem Um gráfico importado para o Apresentações.
Vídeo Um vídeo importado para o 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 do Planilhas Google.

Propriedades de página e elemento de página

A API Slides permite ler e atualizar a aparência de páginas e elementos de página na apresentação. Diferentes elementos de página oferecem suporte a propriedades diferentes que controlam como o elemento de página é renderizado.

Cada tipo de elemento de página tem um elemento de propriedades correspondente e uma mensagem de atualização de propriedades. Por exemplo:

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 sempre que ele for encontrado ao ler um elemento. Para mudar os valores nele, use-o com o tipo de solicitação correspondente como o payload do batchUpdate, permitindo que você mude esses valores na apresentação.

Tipos de propriedades

Há algumas propriedades que são 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 a uma cor do tema. As cores do tema são referenciadas por nome (por exemplo, "DARK1") e podem ser mapeadas para valores RGB usando o esquema de cores de uma página. Esse esquema de cores é atualizado com frequência ao mudar o tema da apresentação no editor do Apresentações.
Preenchimento O preenchimento representa a renderização do espaço vazio dentro de um objeto. O preenchimento mais comum no Apresentações é um preenchimento 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 destinado a 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 apropriada Update...Properties em uma batchUpdate chamada. 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 elemento de página pode herdar propriedades dos objetos principais. As propriedades de um objeto, incluindo aquelas 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 master 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 da página ou master) da qual 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 masters define uma hierarquia de herança na apresentação: os slides herdam dos layouts, e os layouts herdam dos masters. O layout pai e o master de um slide são especificados no campo slideProperties do slide.

Uma página pode herdar propriedades, como plano de fundo e esquema de cores, de uma página principal. Para herdar uma propriedade, a página filha simplesmente não define um valor para essa propriedade na sua PageProperties PageProperties. Ao não "substituir" o valor definido pelo pai, a página aceita o valor herdado.

O diagrama a seguir mostra um slide herdando propriedades de um layout, que herda de um master:

herança de propriedades de slides

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:

  • A propriedade A é "Vermelho".
  • A propriedade B é "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 seu Shape.placeholder campo estiver definido. O campo Shape.placeholder.parentObjectId do marcador de posição filho identifica o marcador de posição principal. Quando você cria um novo slide com base em um layout, todos os marcadores de posição nesse layout aparecem como formas filhas no novo slide. Da mesma forma, os marcadores de posição nas páginas master podem atuar como pais 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 sua ShapeProperties mensagem. 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 master:

herança de propriedades de forma

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:

  • Marcador de posição 1: a propriedade A é renderizada como "Amarelo", a propriedade B como "Verde".
  • Marcador de posição 2: a propriedade A é renderizada como "Amarelo", a propriedade B como "Roxo".
  • Marcador de posição 3: a propriedade A é renderizada como "Amarelo", a propriedade B 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 PropertyState 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 NOT_RENDERED não será usada ao renderizar a forma na página. 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 marcadores de posição que manipulam o campo PropertyState:

estado e herança da propriedade

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:

  • Marcador de posição 1: a propriedade A é renderizada como "Vermelho".
  • Marcador de posição 2: a propriedade A não é renderizada. Se essa fosse a propriedade de contorno, o marcador de posição 2 não teria contorno.
  • Marcador de posição 3: a propriedade A 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 pai precisa ser usado. As formas sem pais não podem ter um estado de propriedade de INHERIT.