Páginas, elementos de página e propriedades

Para usar a API Slides de maneira eficaz, é preciso entender a arquitetura das apresentações e os componentes delas, além das interações entre esses componentes. Nesta página, você encontra uma visão geral detalhada destes 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 o entendimento 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 Google Slides é uma apresentação. Essa é a unidade que pode ser salva no Google Drive, compartilhada com outros usuários etc.

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 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 modelos e layouts, e as propriedades deles determinam como os slides são renderizados, conforme mostrado no diagrama a seguir:

Páginas mestras: a página mestra tem duas finalidades. Os marcadores de posição no slide mestre contêm os padrões para estilos de texto usados em toda a apresentação. O plano de fundo e outras formas no slide mestre compõem o plano de fundo padrão para todos os slides baseados nele. Se você tiver um logotipo da empresa que queira que apareça em todos os slides da apresentação, coloque-o no slide 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 de título.

Há mais dois tipos de páginas: páginas de anotações e matrizes de anotações, que são relevantes principalmente para trabalhar com anotações do apresentador.

Tipos e estrutura de representação de API

Nesta seção, descrevemos 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 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

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:

Propriedades da página e do elemento de página

A API Slides permite ler e atualizar a aparência de páginas e elementos de página na sua apresentação. Elementos de página diferentes são compatíveis com 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:

• 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 solicitações de elemento/propriedades/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 dele, use-o com o tipo de solicitação atendida 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:

Como atualizar propriedades

Para atualizar uma propriedade, use a solicitação Update...Properties adequada 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 elemento de página pode herdar propriedades dos objetos pai. As propriedades de um objeto, incluindo as que ele define e as que ele 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 mestre 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 pai ou mestre da página) de onde as propriedades serão herdadas.

Essas ideias são explicadas em mais detalhes nos parágrafos a seguir.

Herança de propriedades da página

A estrutura de slides, layouts e mestres define uma hierarquia de herança na apresentação: os slides herdam dos layouts, e os layouts herdam dos mestres. O layout pai e o slide mestre 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 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 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 mestre:

As propriedades usadas para renderizar um slide são uma combinação das que ele define e das que ele herda. Neste exemplo, os valores resolvidos usados para renderizar o slide 1 são os seguintes:

• PropertyA é "Red".
• PropertyB é "Orange".

Herança de propriedades de forma

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 de posição filho identifica o marcador de posição pai. 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 mestras 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 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 slide mestre:

As propriedades usadas para renderizar uma forma de marcador de posição são uma combinação das que ela define e das que ela herda. Neste exemplo, os valores resolvidos para essas formas são os seguintes:

• Marcador de posição 1: propertyA é renderizada como "Yellow", propertyB como "Green".
• Marcador de posição 2: propertyA é renderizada como "Yellow", propertyB como "Purple".
• Marcador de posição 3: propertyA é renderizada como "Amarelo", propertyB 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 nem ter pais.

"Ocultar" propriedades usando PropertyState

A enumeração PropertyState controla se uma propriedade de 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:

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 é renderizada. 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 de propriedade INHERIT significa que o próprio estado de propriedade é herdado e que o valor do pai precisa ser usado. As formas sem pais não podem ter um estado de propriedade de INHERIT.