Páginas, elementos de página y propiedades

Para usar la Slides API de manera eficiente, debes comprender la arquitectura de las presentaciones y sus componentes, y también las interacciones entre estos componentes. En esta página se proporciona información detallada sobre los siguientes temas:

  • Modelo conceptual de los componentes de presentaciones.
  • Representación de estos componentes a través de la API.
  • Propiedades de ajuste de estilo de los componentes.

La lectura de la información general sobre estos y otros conceptos facilitará la comprensión y el uso de las guías instructivas, la documentación de referencia y los ejemplos de recetas.

Presentaciones, páginas y elementos de página

Una presentación es el elemento contenedor más periférico de Google Slides. Se trata de la unidad que puede guardarse en Google Drive y compartirse con otros usuarios, entre otras posibilidades.

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 cuales alternan cuando la presentación se representa en una pantalla.

Cada una de las páginas contiene varios elementos de página, los cuales integran el contenido de estas, como se muestra en el siguiente diagrama:

diagrama de arquitectura de diapositivas

Además de las diapositivas, existen otros tipos de páginas que te permiten aplicar diseño a muchas diapositivas diferentes y así lograr un aspecto uniforme. Estos otros tipos de páginas son patrones y diseños, y sus propiedades determinan la forma en que se representan las diapositivas, como se muestra en el siguiente diagrama:

diagrama de arquitectura de temas

Patrones: la página patrón cumple dos funciones. Los marcadores de posición de la página patrón contienen los valores predeterminados de los estilos de texto empleados en toda tu presentación. El fondo y todas las demás formas de la diapositiva patrón componen el fondo predeterminado para todas las diapositivas basadas en esa diapositiva patrón. Si dispones de un logotipo empresarial que deseas mostrar en cada diapositiva de tu presentación, ubícalo en la diapositiva patrón.

Diseños: las plantillas de diseño determinan la disposición del contenido en cada tipo de diapositiva. Si deseas que todas tus diapositivas de título tengan un aspecto determinado, por ejemplo, puedes editar la plantilla de diseño de título.

Tipos de representación y estructura de la API

En esta sección se describe la forma en que el modelo conceptual de Google Slides, mencionado previamente, se representa en la Slides API.

En el siguiente diagrama se representa la relación entre presentaciones, páginas y elementos de página como tipos de la Slides API:

diagrama tipo der

En las siguientes secciones se muestra la forma en que estos tipos se representan en JSON.

Presentaciones

Una presentación incluye varias 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) } ],
  "locale": string,
}

Páginas

Una página, así sea una diapositiva, un diseño o una diapositiva patrón, 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) },
  // 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 disponen en las páginas. Un elemento de página de la API contiene varias propiedades, incluido un campo que varía según la clase 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 varias clases de elementos de página, según lo determina el campo de unión element_kind en la definición anterior. Estas clases de elementos de página se describen en la siguiente tabla:

Clase de elemento Descripción
Grupo Conjunto de elementos de página que reciben tratamiento como una unidad separada. Pueden moverse, recibir ajustes de tamaño y girarse en conjunto.
Forma Objeto visible simple, como rectángulos, elipses y cuadros de texto. Las formas pueden contener texto. Por lo tanto, son los elementos de página más comunes a la hora de crear diapositivas.
Imagen Elemento gráfico importado a Slides.
Video Secuencia de video importada a Slides.
Línea Línea, curva o conector visible.
Tabla Cuadrícula de contenido.
WordArt Elemento de texto visible cuyo comportamiento responde más al de una forma.
SheetsChart Gráfico importado a Slides desde Google Sheets.

Propiedades de páginas y elementos de página

La Slides API te permite leer y actualizar el aspecto 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 la forma en que estos se representan.

Cada clase de elemento de página tiene un elemento de propiedades y un mensaje de actualización de propiedades que le corresponden. Por ejemplo:

La misma solicitud de elemento, propiedades y actualización existe para cada tipo de elemento de página: Image, imagePropertiesy UpdateImageProperties, entre otras.

Puedes leer el atributo de propiedades donde lo encuentres al leer un elemento; para modificar sus valores, úsalo con el tipo de solicitud coincidente como carga para el método batchUpdate, lo cual te permitirá modificar estos valores en la presentación.

Clases de propiedades

Existen algunas propiedades que son comunes entre varias clases de objetos de la Slides API:

Propiedad Descripción
Color Los colores en la Slides API pueden representar un valor RGB o una referencia a un color de tema. La referencia a colores de tema se hacen por nombre (por ejemplo, “DARK1”) y pueden asignarse a valores RGB usando el esquema de colores de una página. Este esquema de colores comúnmente se actualiza al cambiar el tema de la presentación en el editor de Slides.
Fill El relleno implica la representación de espacio vacío dentro de un objeto. El que se admite con mayor frecuencia en Slides es un relleno sólido, con el cual el interior de un objeto se rellena con un único color sólido. Los rellenos también pueden usarse para los fondos de las páginas.
Outline 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.
Shadow La sombra representa un efecto visual pensado para imitar una sombra real proyectada por el objeto. Actualmente, las sombras de la Slides API son de solo lectura.

Actualización de propiedades

Para actualizar una propiedad, usa la solicitud Update...Properties correspondiente en una llamada al método batchUpdate; por ejemplo, UpdateShapeProperties para formas. Estas solicitudes aceptan un mensaje de propiedades completo y pueden usar máscaras de campo para determinar los campos del mensaje de propiedades que deben actualizarse.

Una máscara de campo * recibe el mismo tratamiento que un comodín y representa un atajo para especificar todos los campos de un mensaje.

No apliques una máscara de campo * a código de producción, ya que los campos de solo lectura y los campos nuevos pueden producir errores en el futuro.

Herencia de propiedades

Las páginas o los elementos de página pueden heredar propiedades de sus objetos primarios. Las propiedades de un objeto, incluidas las que define y las que hereda, determinan su aspecto visual final.

  • Propiedades de página: una página hereda las propiedades que no define, pero que al mismo tiempo se definen en el diseño o el patrón en los cuales se basa.
  • Propiedades de forma: una forma puede marcarse como un marcador de posición, lo cual te permite hacer referencia de manera explícita a otra forma de marcador de posición (en el diseño primario o patrón de la página) de la cual se heredarán propiedades.

Estas ideas se explican en mayor profundidad en los párrafos siguientes.

Herencia de propiedades de página

La estructura de las diapositivas, los diseños y los patrones definen una jerarquía de herencia dentro de la presentación: las diapositivas heredan elementos de los diseños y estos heredan elementos de los patrones. El diseño primario y el patrón de una diapositiva se especifican en el campo slideProperties.

Una página puede heredar propiedades, como el fondo y el esquema de colores, de una página primaria. Para heredar una propiedad, la página secundaria simplemente no fija un valor para la propiedad en cuestión en su mensaje PageProperties. Al no “anular” el valor definido por la página primaria, la página acepta el valor heredado.

En el siguiente diagrama se muestra una diapositiva que hereda propiedades de un diseño, que a su vez hereda elementos de un patrón:

herencia de propiedades de diapositiva

Las propiedades empleadas para representar una diapositiva son una combinación de las que esta define y hereda. En este ejemplo, los valores resueltos usados para representar la diapositiva 1 son los siguientes:

  • La propiedad A es “Rojo”.
  • La propiedad B es “Naranja”.

Herencia de propiedades de 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 configura su campo Shape.placeholder. El campo Shape.placeholder.parentObjectId del marcador de posición secundario identifica su marcador de posición primario. Cuando creas una nueva diapositiva basada en un diseño, los marcadores de posición de este aparecen como formas secundarias en la nueva diapositiva. De manera similar, los marcadores de posición de las páginas patrón pueden funcionar como marcadores de posición primarios de los marcadores de posición del diseño.

Con esta jerarquía de herencia definida, la página secundaria hereda una propiedad sin fijar ese valor en su mensaje de ShapeProperties. Al no “anular” el valor definido por la página primaria, la forma secundaria acepta el valor heredado.

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

herencia de propiedades de forma

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

  • Marcador de posición 1: la propiedad A se representa como “Amarillo” y la B como “Verde”.
  • Marcador de posición 2: la propiedad A se representa como “Amarillo” y la B como “Púrpura”.
  • Marcador de posición 3: la propiedad A se representa como “Amarillo” y la B como “Púrpura”.

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

“Ocultamiento” de propiedades con PropertyState

La enumeración de PropertyState determina si la propiedad de una forma se usa para representación o si el valor se usa únicamente para herencia aplicada a formas secundarias. Una propiedad con el estado NOT_RENDERED no se usará al representar la forma en su página. Sin embargo, los elementos secundarios con el estado de propiedad correspondiente RENDERED pueden heredar su propiedad de todos modos.

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

estado y herencia de propiedades

La representación de propiedades de 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: la propiedad A se representa como “Rojo”.
  • Marcador de posición 2: la propiedad A no se representa. Si esta fuera la propiedad de contorno, el marcador de posición 2 no tendría contorno.
  • Marcador de posición 3: la propiedad A no se representa.

Existe otro valor posible para la enumeración de PropertyState: el estado de propiedad INHERIT implica que el propio estado es heredado, y debe usarse el valor del elemento primario. El estado de propiedad de las formas sin elementos primarios no puede ser INHERIT.

Enviar comentarios sobre…