Para usar la API de Slides 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 los siguientes temas:
- Modelo conceptual de los componentes de la presentación
- Cómo representa la API estos componentes
- Propiedades de diseño 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 los ejemplos de recetas.
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 pueden cambiar cuando la presentación se renderiza en una pantalla.
Cada página contiene una cantidad de elementos de página, que, en conjunto, conforman el contenido de la página, como se muestra en el siguiente diagrama:
Además de las diapositivas, existen otros tipos de páginas que te permiten aplicar diseños a muchas diapositivas diferentes, lo que crea una apariencia coherente. Estos otros tipos de páginas son patrones y diseños, y sus propiedades determinan la forma en que se renderizan las diapositivas, como se muestra en el siguiente diagrama:
Páginas principales: La página principal tiene dos propósitos. Los marcadores de posición de la diapositiva principal contienen los valores predeterminados para los estilos de texto que se usan en toda la presentación. El fondo y cualquier otra forma de la diapositiva principal componen el fondo predeterminado de todas las diapositivas basadas en esa principal. Si tienes un logotipo de la empresa que deseas que aparezca en todas las diapositivas de la presentación, colócalo en el diseño maestro.
Diseños: Las plantillas de diseño determinan cómo se organiza el contenido en cada tipo de diapositiva. Si quieres que todas tus diapositivas de título se vean de una manera determinada, por ejemplo, puedes editar la plantilla de diseño de título.
Existen otros dos tipos de páginas: las páginas de notas y las notas maestras, que son más relevantes para trabajar con notas del orador.
Tipos y estructura de representación de la API
En esta sección, se describe cómo se representa el modelo conceptual de Presentaciones de Google, como se explicó anteriormente, en la API de Slides.
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 Slides:
En las siguientes secciones, se muestra cómo se representan estos tipos en JSON.
Presentaciones
Una presentación incluye varias propiedades y contiene las páginas que la componen:
{
"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 la 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 la 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.
}
Hay varios tipos de elementos de página, según se definen en el campo de unión element_kind de la definición anterior. En la siguiente tabla, se describen estos tipos de elementos de la página:
| Tipo de elemento | Descripción |
|---|---|
| Grupo | Es un conjunto de elementos de la página que se consideran 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 en Presentaciones. |
| Video | Un video importado a Presentaciones. |
| Línea | Línea, curva o conector visual. |
| Tabla | Es 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 la página
La API de Slides te permite leer y actualizar la apariencia de las páginas y los elementos de página en tu presentación. Los diferentes elementos de la página admiten diferentes propiedades que controlan cómo se renderiza el elemento de la página.
Cada tipo de elemento de la 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 Shape.
- 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 la página: Image/imageProperties/UpdateImageProperties, y así sucesivamente.
Puedes leer el atributo properties dondequiera que lo encuentres al leer 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 permite 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 Slides:
| Propiedad | Descripción |
|---|---|
| Color | Los colores en la API de Slides pueden ser un valor RGB o una referencia a un color del tema. Los colores del tema se conocen por su nombre (por ejemplo, "DARK1") y se pueden asignar a valores RGB con el esquema de color de una página. Este esquema de color se actualiza con frecuencia 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 que se admite 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 la página. El color de las líneas se controla con un relleno. Los usuarios que llaman también pueden ajustar el ancho y el estilo de guion de los contornos. |
| Sombra | La sombra representa un efecto visual que imita una sombra física proyectada por el objeto. Actualmente, las sombras en la API de Slides son de solo lectura. |
Actualiza propiedades
Para actualizar una propiedad, usa la solicitud Update...Properties adecuada en una llamada a batchUpdate, por ejemplo, UpdateShapeProperties para Shapes. 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.
Herencia de la propiedad
Una página o un elemento de página pueden heredar propiedades de sus objetos principales. 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 forma: Una forma se puede marcar como marcador de posición, lo que te permite hacer referencia explícitamente a otra forma de marcador de posición (en el diseño principal o superior 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 las propiedades de la página
La estructura de las diapositivas, los diseños y los patrones define una jerarquía de herencia dentro de la presentación: las diapositivas heredan de los diseños, y los diseños heredan de los patrones. El diseño principal y el diseño principal de una diapositiva se especifican en el campo slideProperties de la diapositiva.
Una página puede heredar propiedades, como el fondo y el esquema de color, de una página principal. 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, a su vez, hereda de un patrón:
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 "Rojo".
- La propiedadB es "Naranja".
Herencia de propiedades de forma
Las formas pueden heredar propiedades, como relleno, contorno o sombra, de otras formas. Una forma es un marcador de posición si su campo Shape.placeholder está establecido. El campo Shape.placeholder.parentObjectId del marcador de posición secundario identifica su marcador de posición principal. Cuando creas una nueva diapositiva basada en un diseño, todos los marcadores de posición de ese diseño aparecen como formas secundarias en la nueva diapositiva.
Del mismo modo, los marcadores de posición en las páginas principales pueden actuar como elementos superiores de los marcadores de posición de los diseños.
Con esta jerarquía de herencia definida, la página secundaria hereda una propiedad sin establecer ese valor en su mensaje ShapeProperties. Si no 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 un patrón:
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: La propiedadA se renderiza como "Amarillo" y la propiedadB como "Verde".
- Marcador de posición 2: propertyA se renderiza como "Amarillo" y propertyB como "Púrpura".
- Marcador de posición 3: La propiedadA se renderiza como "Amarillo" y la propiedadB como "Púrpura".
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.
Ocultar propiedades con PropertyState
La enumeración PropertyState controla si la propiedad de una forma se usa realmente para la renderización o si el valor solo se usa para la herencia por parte de las formas secundarias. Una propiedad con el estado de propiedad NOT_RENDERED no se usará cuando se renderice la forma en su página. Sin embargo, los elementos secundarios que tengan un estado de propiedad correspondiente de RENDERED pueden heredar esta propiedad.
En el siguiente diagrama, se muestra la herencia de propiedades entre tres marcadores de posición que manipulan el campo PropertyState:
El campo PropertyState puede afectar la renderización de las propiedades de la forma. En este ejemplo, los valores resueltos para estas formas son los siguientes:
- Comodín 1: propertyA se renderiza como "Rojo".
- Placeholder2: No se renderiza propertyA. Si esta fuera la propiedad de esquema, Placeholder2 no tendría esquema.
- Marcador de posición 3: No se renderiza propertyA.
Hay un valor más posible de la enumeración PropertyState: El estado de propiedad INHERIT significa que el estado de la propiedad en sí se hereda y se debe usar el valor de la propiedad principal. Las formas sin elementos superiores no pueden tener un estado de propiedad de INHERIT.