Páginas, elementos de página y propiedades

Para usar la API de Presentaciones de manera eficaz, debes comprender la arquitectura de las presentaciones y sus componentes, así como las interacciones entre estos componentes. En esta página, se proporciona una descripción general detallada de estos temas:

• Modelo conceptual de los componentes de presentación
• Cómo la API representa estos componentes
• Propiedades de estilo de los componentes

Leer esta y las otras descripciones generales de los conceptos facilitará la comprensión y el uso de las guías prácticas, la documentación de referencia y las muestras de código.

Presentaciones, páginas y elementos de página

El elemento contenedor más externo en Presentaciones de Google es una presentación. Esta es la unidad que se puede guardar en Google Drive, compartir con otros usuarios, etcétera.

Cada presentación contiene varios tipos de páginas. Un tipo de página es una diapositiva, que son las páginas que los usuarios ven y entre las que se desplazan cuando la presentación se renderiza en una pantalla.

Cada página contiene una cantidad de elementos de página, que juntos conforman el contenido de la página, como se muestra en el siguiente diagrama:

Además de las diapositivas, hay otros tipos de páginas que te permiten aplicar el diseño a muchas diapositivas diferentes, lo que crea una apariencia coherente. Estos otros tipos de páginas son diapositivas maestras y diseños, y sus propiedades determinan la forma en que se renderizan las diapositivas, como se muestra en el siguiente diagrama:

Páginas maestras: La página maestra tiene dos propósitos. Los marcadores de posición de la diapositiva principal contienen los valores predeterminados de los estilos de texto que se usan en toda la presentación. El fondo y cualquier otra forma de la diapositiva de diseño conforman el fondo predeterminado de todas las diapositivas basadas en ese diseño. Si tienes un logotipo de la empresa que quieres que aparezca en todas las diapositivas de tu presentación, colócalo en la diapositiva maestra.

Diseños: Las plantillas de diseño determinan cómo se organiza el contenido en cada tipo de diapositiva. Por ejemplo, si quieres que todas tus diapositivas de título tengan un aspecto determinado, puedes editar la plantilla de diseño de título.

Hay otros dos tipos de páginas, las páginas de notas y los patrones de notas, que son más relevantes para trabajar con las notas del orador.

Tipos y estructura de representación de la API

En esta sección, se describe cómo se representa en la API de Slides el modelo conceptual de Presentaciones de Google, como se describió anteriormente.

En el siguiente diagrama, se muestra la relación entre las presentaciones, las páginas y los elementos de página como tipos en la API de Presentaciones:

En las siguientes secciones, se muestra cómo se representan estos tipos en JSON.

Presentaciones

Una presentación incluye una cantidad de propiedades y contiene las páginas que se encuentran en ella:

{
  "presentationId": string,
  "pageSize": { object(Size) },
  "slides": [ { object(Page) } ],
  "title": string,
  "masters": [ { object(Page) } ],
  "layouts": [ { object(Page) } ],
  "notesMaster": object(Page),
  "locale": string,
}

Páginas

Una página incluye un conjunto de propiedades y contiene los elementos de página que se encuentran en ella:

{
  "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

Los elementos de página son los componentes visuales que se colocan en las páginas. Un elemento de página en la API contiene varias propiedades, incluido un campo que varía según el 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.
}

Existen varios tipos de elementos de página, como se define en el campo de unión element_kind de la definición anterior. Estos tipos de elementos de página se describen en la siguiente tabla:

Tipo de elemento	Descripción
Grupo	Es un conjunto de elementos de página que se tratan como una unidad individual. Se pueden mover, escalar y rotar juntos.
Forma	Un objeto visual simple, como rectángulos, elipses y cuadros de texto. Las formas pueden contener texto, por lo que son los elementos de página más comunes para crear diapositivas.
Imagen	Un gráfico importado a Presentaciones.
Video	Un video importado a Presentaciones
Línea	Una línea, curva o conector visual.
Tabla	Una cuadrícula de contenido
WordArt	Es un elemento de texto visual que se comporta más como una forma.
SheetsChart	Un gráfico importado a Presentaciones desde Hojas de cálculo de Google

Propiedades de la página y de los elementos de página

La API de Presentaciones te permite leer y actualizar la apariencia de las páginas y los elementos de página de tu presentación. Los diferentes elementos de página admiten distintas propiedades que controlan cómo se renderiza el elemento de página.

Cada tipo de elemento de página tiene un elemento de propiedades correspondiente y un mensaje de actualización de propiedades, por ejemplo:

• Hay un tipo de elemento de página Forma.
• Su campo de propiedad es shapeProperties.
• La solicitud para actualizar estas propiedades es UpdateShapePropertiesRequest.

Existe el mismo conjunto de elementos, propiedades y solicitudes de actualización para cada tipo de elemento de página: Image/imageProperties/UpdateImageProperties, etcétera.

Puedes leer el atributo de propiedades dondequiera que lo encuentres cuando leas un elemento. Para cambiar los valores que contiene, úsalo con el tipo de solicitud coincidente como la carga útil del método batchUpdate, lo que te permitirá cambiar estos valores en la presentación.

Tipos de propiedades

Existen algunas propiedades que son comunes entre varios tipos de objetos en la API de Presentaciones:

Propiedad	Descripción
Color	Los colores en la API de Presentaciones pueden ser un valor RGB o una referencia a un color del tema. Se hace referencia a los colores del tema por nombre (por ejemplo, "DARK1") y se pueden asignar a valores RGB con un esquema de colores de la página. Este esquema de colores se suele actualizar cuando se cambia el tema de la presentación en el editor de Presentaciones.
Relleno	El relleno representa la renderización del espacio vacío dentro de un objeto. El relleno más común en Presentaciones es el relleno sólido, en el que el interior de un objeto se rellena con un solo color sólido. Los rellenos también se pueden usar para los fondos de las páginas.
Contorno	El contorno representa el conjunto de líneas que rodean el elemento de página. El color de las líneas se controla con un relleno. Los emisores también pueden ajustar el ancho y el estilo de guion de los contornos.
Sombra	La sombra representa un efecto visual que imita la sombra física que proyecta el objeto. Actualmente, las sombras en la API de Presentaciones son de solo lectura.

Actualiza propiedades

Para actualizar una propiedad, usa la solicitud Update...Properties adecuada en una llamada batchUpdate, por ejemplo, UpdateShapeProperties para las formas. Estas solicitudes aceptan un mensaje de propiedades completo y pueden usar máscaras de campo para determinar qué campos del mensaje de propiedades se deben actualizar.

Una máscara de campo de * se trata como un comodín y es una forma abreviada de especificar cada campo de un mensaje. La sintaxis de comodín puede producir resultados no deseados si la API se actualiza en el futuro, ya que los campos de solo lectura y los campos agregados recientemente pueden causar errores. Para las aplicaciones de producción, enumera siempre los campos específicos que se actualizan en las máscaras de campo y evita usar comodines *.

Herencia de la propiedad

Una página o un elemento de página puede heredar propiedades de sus objetos superiores. Las propiedades de un objeto, incluidas las que define y las que hereda, determinan su apariencia visual final.

• Propiedades de la página: Una página hereda las propiedades que no define, pero que se definen en el diseño o la página principal en la que se basa.
• Propiedades de la forma: Una forma se puede marcar como un marcador de posición, lo que te permite hacer referencia de manera explícita a otra forma de marcador de posición (en el diseño de nivel superior o la diapositiva maestra de la página) de la que se heredarán las propiedades.

Estas ideas se explican con más detalle en los siguientes párrafos.

Herencia de propiedades de página

La estructura de las diapositivas, los diseños y las diapositivas maestras definen una jerarquía de herencia dentro de la presentación: las diapositivas heredan de los diseños, y los diseños heredan de las diapositivas maestras. El diseño de nivel superior y la diapositiva maestra de una diapositiva se especifican en el campo slideProperties de la diapositiva.

Una página puede heredar propiedades, como background y color scheme, de una página superior. Para heredar una propiedad, la página secundaria simplemente no establece un valor para esa propiedad en su mensaje PageProperties. Al no "anular" el valor definido por el elemento superior, la página acepta el valor heredado.

En el siguiente diagrama, se muestra una diapositiva que hereda propiedades de un diseño, que hereda de una diapositiva maestra:

Las propiedades que se usan para renderizar una diapositiva son una combinación de las que define y las que hereda. En este ejemplo, los valores resueltos que se usan para renderizar la diapositiva 1 son los siguientes:

• PropertyA es "Red".
• PropertyB es "Orange".

Una página que no tiene un elemento superior hereda los valores predeterminados de Presentaciones de Google para las propiedades que no define.

Herencia de las propiedades de las formas

Las formas pueden heredar propiedades, como el relleno, el contorno o la sombra, de otras formas. Una forma es un marcador de posición si se establece su campo Shape.placeholder. El campo Shape.placeholder.parentObjectId del marcador de posición secundario identifica su marcador de posición superior. Cuando creas una diapositiva nueva basada en un diseño, los marcadores de posición de ese diseño aparecen como formas secundarias en la diapositiva nueva. Del mismo modo, los marcadores de posición de las páginas maestras pueden actuar como elementos superiores de los marcadores de posición de los diseños.

Puedes crear marcadores de posición con el editor de Presentaciones, pero no con la API de Presentaciones.

Con esta jerarquía de herencia definida, la página secundaria hereda una propiedad si no se establece ese valor en su mensaje ShapeProperties. Si no se anula el valor definido por el elemento superior, la forma secundaria acepta el valor heredado.

En el siguiente diagrama, se muestra la herencia de propiedades entre tres marcadores de posición que se encuentran en una diapositiva, un diseño y una diapositiva maestra:

Las propiedades que se usan para renderizar una forma de marcador de posición son una combinación de las que define y las que hereda. En este ejemplo, los valores resueltos para estas formas son los siguientes:

• Marcador de posición 1: propertyA se renderiza como "Yellow" y propertyB como "Green".
• Marcador de posición 2: propertyA se renderiza como "Yellow" y propertyB como "Purple".
• Marcador de posición 3: propertyA se renderiza como "Yellow" y propertyB, como "Purple".

Las formas son el único tipo de elemento de página que puede tener elementos superiores. Otros tipos, como imágenes, tablas y gráficos, no pueden ser marcadores de posición ni tener elementos superiores.

Cuando una forma no tiene un elemento superior, los valores que no se establecen se completan automáticamente con los valores predeterminados de la aplicación.

"Oculta" propiedades con PropertyState

La enumeración PropertyState controla si una propiedad de una forma se usa realmente para la renderización o si el valor solo se usa para la herencia de las formas secundarias. No se usará una propiedad con el estado de propiedad NOT_RENDERED cuando se renderice la forma en su página. Sin embargo, los elementos secundarios que tengan un estado de propiedad correspondiente de RENDERED podrán heredar esta propiedad.

Cuando actualizas una propiedad, se establece de forma implícita su estado como `RENDERED`, a menos que establezcas el estado en algún otro valor en la misma solicitud.

En el siguiente diagrama, se muestra la herencia de propiedades entre tres marcadores de posición que manipulan el campo PropertyState:

La renderización de las propiedades de las formas puede verse afectada por el campo PropertyState. En este ejemplo, los valores resueltos para estas formas son los siguientes:

• Marcador de posición 1: propertyA se renderiza como "Red".
• Marcador de posición 2: No se renderiza la propiedad A. Si esta fuera la propiedad de contorno, Placeholder2 no tendría contorno.
• Placeholder3: propertyA is not rendered.

Hay un valor más posible de la enumeración PropertyState: el estado de la propiedad INHERIT significa que el estado de la propiedad se hereda y se debe usar el valor del elemento superior. Las formas sin elementos superiores no pueden tener un estado de propiedad de INHERIT.